Thinking in Schemas

Consider a typical blog post. The API response for a single post might look something like this:

{
  "id": "123",
  "author": {
    "id": "1",
    "name": "Paul"
  },
  "title": "My awesome blog post",
  "comments": [
    {
      "id": "324",
      "createdAt": "2013-05-29T00:00:00-04:00",
      "commenter": {
        "id": "2",
        "name": "Nicole"
      }
    },
    {
      "id": "544",
      "createdAt": "2013-05-30T00:00:00-04:00",
      "commenter": {
        "id": "1",
        "name": "Paul"
      }
    }
  ]
}

Declarative definitions

We have two nested entity types within our article: users and comments. Using various schema, we can normalize all three entity types down:

TypeScript

import { schema, Entity } from '@data-client/endpoint';
import { Temporal } from '@js-temporal/polyfill';

class User extends Entity {
  id = '';
  name = '';

  pk() {
    return this.id;
  }
}

class Comment extends Entity {
  id = '';
  createdAt = Temporal.Instant.fromEpochSeconds(0);
  commenter = User.fromJS();

  pk() {
    return this.id;
  }

  static schema = {
    commenter: User,
    createdAt: Temporal.Instant.from,
  };
}

class Article extends Entity {
  id = '';
  title = '';
  author = User.fromJS();
  comments: Comment[] = [];

  pk() {
    return this.id;
  }

  static schema = {
    author: User,
    comments: [Comment],
  };
}

JavaScript

import { schema, Entity } from '@data-client/endpoint';
import { Temporal } from '@js-temporal/polyfill';

class User extends Entity {
  pk() {
    return this.id;
  }
}

class Comment extends Entity {
  pk() {
    return this.id;
  }

  static schema = {
    commenter: User,
    createdAt: Temporal.Instant.from,
  };
}

class Article extends Entity {
  pk() {
    return this.id;
  }

  static schema = {
    author: User,
    comments: [Comment],
  };
}

Normalize

import { normalize } from '@data-client/normalizr';

const args = [{ id: '123' }];
const normalizedData = normalize(originalData, Article, args);

Now, normalizedData will create a single serializable source of truth for all entities:

{
  result: "123",
  entities: {
    articles: {
      "123": {
        id: "123",
        author: "1",
        title: "My awesome blog post",
        comments: [ "324", "544" ]
      }
    },
    users: {
      "1": { "id": "1", "name": "Paul" },
      "2": { "id": "2", "name": "Nicole" }
    },
    comments: {
      "324": {
        id: "324",
        createdAt: "2013-05-29T00:00:00-04:00",
        commenter: "2"
      },
      "544": {
        id: "544",
        createdAt: "2013-05-30T00:00:00-04:00",
        commenter: "1"
      }
    }
  },
  // contents excluded for brevity
  indexes,
  entityMeta,
}

Denormalize

import { denormalize } from '@data-client/normalizr';

const denormalizedData = denormalize(
  normalizedData.result,
  Article,
  normalizedData.entities,
  args,
);

Now, denormalizedData will instantiate the classes, ensuring all instances of the same member (like Paul) are referentially equal:

Article {
  id: '123',
  title: 'My awesome blog post',
  author: User { id: '1', name: 'Paul' },
  comments: [
    Comment {
      id: '324',
      createdAt: Instant [Temporal.Instant] {},
      commenter: [User { id: '2', name: 'Nicole' }]
    },
    Comment {
      id: '544',
      createdAt: Instant [Temporal.Instant] {},
      commenter: [User { id: '1', name: 'Paul' }]
    }
  ]
}

MemoCache

MemoCache is a singleton that can be used to maintain referential equality between calls as well as potentially improved performance by 2000%. Its methods are memoized.

memo.denormalize

import { MemoCache } from '@data-client/normalizr';

// you can construct a new memo anytime you want to reset the cache
const memo = new MemoCache();

const { data, paths } = memo.denormalize(
  normalizedData.result,
  Article,
  normalizedData.entities,
  args,
);
const { data: data2 } = memo.denormalize(
  normalizedData.result,
  Article,
  normalizedData.entities,
  args,
);

// referential equality maintained between calls
assert(data === data2);

memo.denormalize() is just like denormalize() above but includes paths as part of the return value. paths is an Array of paths of all entities included in the result.

memo.query

memo.query() allows denormalizing Queryable based on args alone, rather than a normalized input.

// key is just any serialization of args
const key = JSON.stringify(args);

const data = memo.query(
  key,
  Article,
  args,
  normalizedData.entities,
  normalizedData.indexes,
);

Queryable

Queryable Schemas allow store access without an endpoint. They achieve this using the queryKey method that produces the results normally stored in the endpoint cache.

This enables their use in these additional cases:

• useQuery() - Rendering in React
• schema.Query() - As input to produce a computed memoization.
• ctrl.get/snap.get
  • Managers
  • React with useController()
  • RestEndpoint.getOptimisticResponse
  • Unit testing hooks with renderDataClient()
• memo.query()
• Improve performance of useSuspense, useDLE by rendering before endpoint resolution

Querables include Entity, All, Collection, Query, and Union.

interface Queryable {
  queryKey(
    args: readonly any[],
    queryKey: (...args: any) => any,
    getEntity: GetEntity,
    getIndex: GetIndex,
    // `{}` means non-void
  ): {};
}

Schema Overview

Schema	Description	Data Type	Mutable	Queryable	Of A
Entity	single unique object	Object	✅	✅
Object	statically known keys	Object	🛑	🛑
Array	lists of any size	Array	🛑	🛑
Values	maps of any size	Object	🛑	🛑
All	list of all entities of a kind	Array	🛑	✅
Collection	enables adding new items	Object or Array	✅	✅
Query	memoized custom transforms	any	✅/🛑	✅	Queryable
Union	one of many different types (A | B)	Polymorphic Object	✅	✅	Entity
Invalidate	remove an entity	Object	✅	🛑	Entity