normalizr-modern

A modern, maintained fork of Normalizr with TypeScript 5.x support, ESM/CJS dual package output, and improved developer experience.

What is Normalizr?

Normalizr is a library that normalizes nested JSON according to a schema. It responses to make them easier to work with.

Before:

{
 flattens API  "posts": [
    { "id": 1, "title": "Hello", "author": { "id": 1, "name": "Dan" }, "comments": [...] }
  ]
}

After:

{
  entities: {
    users: { 1: { id: 1, name: "Dan" } },
    posts: { 1: { id: 1, title: "Hello", author: 1 } },
    comments: { ... }
  },
  result: [1]
}

Installation

npm install normalizr-modern
# or
yarn add normalizr-modern
# or
pnpm add normalizr-modern

Quick Start

import { normalize, entity, array, object } from 'normalizr-modern';

// Define schemas
const user = entity({
  idAttribute: 'id'
});

const comment = entity({
  idAttribute: 'id',
  schema: {
    author: user
  }
});

const post = entity({
  idAttribute: 'id',
  schema: {
    author: user,
    comments: array({ schema: comment })
  }
});

// Normalize data
const data = {
  id: 1,
  title: 'My Post',
  author: { id: 1, name: 'Dan' },
  comments: [
    { id: 1, text: 'Great post!', author: { id: 1, name: 'Dan' } }
  ]
};

const { entities, result } = normalize(data, post);

API

normalize(input, schema)

Normalizes input data according to a schema.

const { entities, result } = normalize(apiResponse, postSchema);

denormalize(input, schema, entities)

Denormalizes normalized data back to original structure.

const original = denormalize(result, postSchema, entities);

entity(definition, options)

Creates an Entity schema for normalizing objects with IDs.

const user = entity({
  idAttribute: 'id',
  schema: {
    // nested schemas
  }
}, {
  processStrategy: (entity) => ({ ...entity, processed: true }),
  mergeStrategy: (existing, incoming) => ({ ...existing, ...incoming })
});

array(options)

Creates an Array schema for normalizing arrays.

const users = array({ schema: userSchema });
const posts = array(); // No schema - returns as-is

object(options)

Creates an Object schema for normalizing objects.

const metadata = object({
  schema: {
    settings: object(),
    tags: array()
  }
});

TypeScript

normalizr-modern is written in TypeScript 5.x with full strict mode support.

import { entity, array, normalize, Schema } from 'normalizr-modern';

interface User {
  id: number;
  name: string;
}

interface Post {
  id: number;
  title: string;
  author: User;
  comments: User[];
}

const userSchema = entity({
  idAttribute: 'id' as const
});

const postSchema = entity({
  idAttribute: 'id' as const,
  schema: {
    author: userSchema,
    comments: array({ schema: userSchema })
  }
});

// Type-safe normalization
const { result, entities } = normalize(apiData, postSchema);
// result is normalized Post, entities contains all entities

Migration from Original Normalizr

If you're migrating from the original Normalizr package:

- import { normalize, schema } from 'normalizr';
+ import { normalize, entity, array, object } from 'normalizr-modern';

- const { data, entities } = normalize(jsonResponse, [mySchema]);
+ const { result, entities } = normalize(jsonResponse, mySchema);

Key differences:

• Import named exports instead of schema namespace
• Use entity() instead of new schema.Entity()
• Use array() instead of new schema.Array()
• Use object() instead of new schema.Object()
• normalize returns { entities, result } instead of { entities, result }

Why a Fork?

The original Normalizr was archived in March 2022. This fork provides:

• ✅ TypeScript 5.x with strict mode
• ✅ ESM/CJS dual package
• ✅ Modern tooling (Vitest, es-toolkit)
• ✅ Active maintenance
• ✅ Better error messages
• ✅ Improved TypeScript inference

Contributing

Contributions are welcome! Please read our Contributing Guide for details.

License

MIT License - see LICENSE for details.