@data-client/normalizr

Normalizr Client

Install

Install from the NPM repository using yarn or npm:

yarn add @data-client/normalizr

npm install --save @data-client/normalizr

Motivation

Many APIs, public or not, return JSON data that has deeply nested objects. Using data in this kind of structure is often very difficult for JavaScript applications, especially those using Flux or Redux.

Solution

Normalizr is a small, but powerful utility for taking JSON with a schema definition and returning nested entities with their IDs, gathered in dictionaries.

Documentation

• Introduction
• Quick Start
• API
  • normalize
  • denormalize
  • schema

Examples

• Normalizing GitHub Issues
• Relational Data
• Interactive Redux
• Benchmarks
  • Charts

React Demos

• Todo Demo
• Github Demo
• NextJS SSR Demo

Quick Start

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"
      }
    }
  ]
}

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

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

// Define a users schema
class User extends Entity {}

// Define your comments schema
class Comment extends Entity {
  static schema = {
    commenter: User,
    createdAt: Temporal.Instant.from,
  };
}

// Define your article
class Article extends Entity {
  static schema = {
    author: User,
    comments: [Comment],
  };
}

Normalize

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

const args = [{ id: '123' }];
const normalizedData = normalize(Article, originalData, 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"
      }
    }
  },
}

normalizedData can be placed in any flux store as the single source of truth for this data.

Denormalize

Accessing the store can then be done using flux selectors by denormalizing:

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

const denormalizedData = denormalize(
  Article,
  normalizedData.result,
  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%. All three methods are memoized.

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(schema, input, state.entities, args);

const data = memo.query(schema, args, state.entities, state.indexes);

function query(schema, args, state, key) {
  const queryKey = memo.buildQueryKey(
    schema,
    args,
    state.entities,
    state.indexes,
    key,
  );
  const { data } = this.denormalize(schema, queryKey, state.entities, args);
  return typeof data === 'symbol' ? undefined : (data as any);
}

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() allows denormalizing without a normalized input. See Queryable for more info.

memo.buildQueryKey() builds the input used to denormalize for query(). This is exposed to allow greater flexibility in its usage.

Schemas

Available from @data-client/endpoint

Data Type	Mutable	Schema	Description	Queryable
Object	✅	Entity, EntityMixin	single unique object	✅
✅	Union(Entity)	polymorphic objects (A | B)	✅
🛑	Object	statically known keys	🛑
	Invalidate(Entity)	delete an entity	🛑
List	✅	Collection(Array)	growable lists	✅
🛑	Array	immutable lists	🛑
✅	All	list of all entities of a kind	✅
Map	✅	Collection(Values)	growable maps	✅
🛑	Values	immutable maps	🛑
any		Query(Queryable)	memoized custom transforms	✅

Benchmarks

Performance compared to normalizr package (higher is better):

	no cache	with cache
normalize (long)	121%	121%
denormalize (long)	158%	1,262%
denormalize (short)	676%	2,367%

View benchmark

Credits

Normalizr Client is based on Normalizr - originally created by Dan Abramov and inspired by a conversation with Jing Chen. Since v3, it was completely rewritten and maintained by Paul Armstrong.

Normalizr Client was rewritten and maintained by Normalizr contributor Nathaniel Tucker. It has also received much help, enthusiasm, and contributions from community members.