normalizr

What is normalizr?

Normalizr is a powerful library for normalizing nested JSON data. It helps in transforming complex nested data structures into a flat structure, making it easier to manage and work with in applications, especially in state management scenarios.

What are normalizr's main functionalities?

Define Schemas

Normalizr allows you to define schemas for your data. In this example, we define schemas for users, comments, and articles, where comments have a relationship with users, and articles have relationships with both users and comments.

const { schema } = require('normalizr');

const user = new schema.Entity('users');
const comment = new schema.Entity('comments', {
  commenter: user
});
const article = new schema.Entity('articles', {
  author: user,
  comments: [comment]
});

Normalize Data

Once schemas are defined, you can use the `normalize` function to transform your nested data into a normalized form. This example shows how to normalize a nested JSON object representing an article with an author and comments.

const { normalize } = require('normalizr');

const originalData = {
  id: '123',
  author: {
    id: '1',
    name: 'Paul'
  },
  title: 'My awesome blog post',
  comments: [
    {
      id: '324',
      commenter: {
        id: '2',
        name: 'Nicole'
      }
    }
  ]
};

const normalizedData = normalize(originalData, article);
console.log(JSON.stringify(normalizedData, null, 2));

Denormalize Data

Normalizr also provides a `denormalize` function to convert normalized data back into its original nested form. This example demonstrates how to denormalize data using the previously defined schemas.

const { denormalize } = require('normalizr');

const normalizedData = {
  result: '123',
  entities: {
    articles: {
      '123': { id: '123', author: '1', title: 'My awesome blog post', comments: ['324'] }
    },
    users: {
      '1': { id: '1', name: 'Paul' },
      '2': { id: '2', name: 'Nicole' }
    },
    comments: {
      '324': { id: '324', commenter: '2' }
    }
  }
};

const denormalizedData = denormalize('123', article, normalizedData.entities);
console.log(JSON.stringify(denormalizedData, null, 2));

Other packages similar to normalizr

normalizr-immutable

normalizr-immutable is a fork of normalizr that works with Immutable.js data structures. It provides similar functionality to normalizr but is designed to work seamlessly with Immutable.js, making it a good choice for applications that use Immutable.js for state management.

redux-orm

redux-orm is a library for managing relational data in Redux. It provides an ORM-like interface for defining models and relationships, and it integrates with Redux to manage normalized data. Unlike normalizr, which focuses on normalization and denormalization, redux-orm provides a more comprehensive solution for managing relational data in Redux applications.

README

normalizr

Install

Install from the NPM repository using yarn or npm:

yarn add normalizr

npm install 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
  • Build Files
• Quick Start
• API
  • normalize
  • denormalize
  • schema
• Using with JSONAPI

Examples

• Normalizing GitHub Issues
• Relational Data
• Interactive Redux

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",
      "commenter": {
        "id": "2",
        "name": "Nicole"
      }
    }
  ]
}

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

import { normalize, schema } from 'normalizr';

// Define a users schema
const user = new schema.Entity('users');

// Define your comments schema
const comment = new schema.Entity('comments', {
  commenter: user
});

// Define your article
const article = new schema.Entity('articles', {
  author: user,
  comments: [comment]
});

const normalizedData = normalize(originalData, article);

Now, normalizedData will be:

{
  result: "123",
  entities: {
    "articles": {
      "123": {
        id: "123",
        author: "1",
        title: "My awesome blog post",
        comments: [ "324" ]
      }
    },
    "users": {
      "1": { "id": "1", "name": "Paul" },
      "2": { "id": "2", "name": "Nicole" }
    },
    "comments": {
      "324": { id: "324", "commenter": "2" }
    }
  }
}

Dependencies

None.

Credits

Normalizr was originally created by Dan Abramov and inspired by a conversation with Jing Chen. Since v3, it was completely rewritten and maintained by Paul Armstrong. It has also received much help, enthusiasm, and contributions from community members.

Changelog

v3.4.0

• Changed Now built with Babel 7
• Added Support for circular references (gh-335)
• Added Symbols are valid keys for Entity keys (gh-369)
• Added/Changed Typescript definitions include generics for normalize (gh-363)
• Fixed denormalization skipping of falsy valued ids used in Object schemas (gh-345)
• Chore Update dev dependencies
• Chore Added Greenkeeper