graphql-normalizr

library2.10.3jsnpmunverified

A lightweight library that normalizes GraphQL responses into a flat, entity-based structure (e.g., { EntityType: { id: entity } }) suitable for client-side caching in Flux/Redux stores or local state management. As of v2.10.3, it supports any GraphQL version from 0.11 to 15.x and works in both Node.js and browser environments. Unlike normalizr (which is schema-based), graphql-normalizr leverages the `__typename` field and `id` field automatically, simplifying integration with GraphQL clients. It is unopinionated about caching strategies and does not require defining schemas upfront. It is actively maintained with regular releases.

database

npm install graphql-normalizr

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRAPHQL-NORMALIZR

graphql-normalizr

databasejavascriptv2.10.3

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

normalize

✓ import { normalize } from 'graphql-normalizr'

✗ import normalize from 'graphql-normalizr'

The library exports `normalize` as a named export, not a default export.

denormalize

✓ import { denormalize } from 'graphql-normalizr'

✗ import { normalizr } from 'graphql-normalizr'

The correct function name is `denormalize`, not `normalizr`.

isEntity

✓ import { isEntity } from 'graphql-normalizr'

A helper to check if an object has __typename and id. Useful for custom logic.

Shows how to use normalize and denormalize with a typical GraphQL query result.

import { normalize, denormalize } from 'graphql-normalizr'; const queryResult = { data: { findUser: [ { __typename: 'User', id: '1', name: 'Alice', posts: [ { __typename: 'Post', id: '10', title: 'GraphQL Rocks' } ] } ] } }; const schema = queryResult.data; // The data object itself const normalized = normalize(schema); console.log(JSON.stringify(normalized, null, 2)); // Output: // { // "User": { // "1": { // "id": "1", // "name": "Alice", // "posts": ["10"] // } // }, // "Post": { // "10": { // "id": "10", // "title": "GraphQL Rocks" // } // } // } // Denormalize back to original structure const entityType = 'User'; const entityId = '1'; const denormalized = denormalize(entityType, entityId, normalized, schema); console.log(JSON.stringify(denormalized, null, 2)); // Output matches the original findUser[0] object with nested posts populated.

Debug

Known issues

gotchaThe library expects every entity object to have a `__typename` and an `id` field. If your schema uses a different ID field (e.g., `_id` or `uuid`), normalization will not detect entities correctly.

fix

Ensure all entity types have an `id` field and `__typename` in the GraphQL response, or use a wrapper to map fields before passing to normalize.

affects: >=1.0.0

gotchaArrays of scalars (e.g., [String]) will be treated as entity arrays and may cause unexpected behavior if those scalars have no `id`.

fix

Avoid passing scalar arrays directly; use a wrapper or filter them out before normalization.

affects: >=1.0.0

gotchaDenormalize requires the original schema (the query result structure) to reconstruct nested objects. If the schema is missing, denormalize may omit relationships.

fix

Always pass the original `data` object (or the portion of the result that matches the query) as the fourth argument to denormalize.

affects: >=1.0.0

deprecatedThe `normalizr` export (lowercase) was used in early v1 but removed in v2. Using it will throw a runtime error.

fix

Use `normalize` (capital 'N' i.e., the Node.js style) instead.

affects: >=2.0.0

Errors

Common errors & fixes

TypeError: __typename is not defined

Missing `__typename` field on an entity in the GraphQL response (likely introspected).

fix

Ensure your GraphQL query includes `__typename` on all nested objects, or add a custom resolver.

TypeError: Cannot read properties of undefined (reading 'id')

Entity object is missing an `id` field; library expects every entity to have an `id`.

fix

Add an `id` field to your GraphQL schema/query for each type that should be normalized.

Uncaught ReferenceError: require is not defined

Using CommonJS require() in an ESM environment (e.g., React with Vite).

fix

Use ES module import: `import { normalize } from 'graphql-normalizr'`.

Upgrade

Version history

2.10.3latest on npm

Audit

Dependencies

graphqloptionalPeer dependency required for GraphQL type handling; v0.11 to v15 supported.

Agent activity

9 hits · last 30 days

node

Resources

githubhttps://github.com/monojack/graphql-normalizr ↗

packagegraphql-normalizr ↗

homepagehttps://github.com/monojack/graphql-normalizr#readme ↗