JSON API Normalizer

1.0.4 · abandoned · verified Sun Apr 19

The `json-api-normalizer` package provides a utility to transform JSON:API compliant response data into a normalized, Redux-friendly format. Unlike general-purpose normalization libraries such as Normalizr, this package directly interprets the JSON:API specification, eliminating the need for manual schema definitions. It converts collections of resources into key-value maps, where keys are resource IDs, making it highly suitable for efficient state management within Redux applications. The current stable version is 1.0.4. Development appears to be largely inactive since 2017, with the last commit on GitHub approximately five years ago, suggesting a potentially abandoned status. Its primary differentiator is its direct, schema-less adherence to the JSON:API specification, providing a simpler setup for compliant APIs.

Common errors

```
TypeError: json_api_normalizer__WEBPACK_IMPORTED_MODULE_0__.normalize is not a function
```
cause Attempting to import `normalize` as a named export (`import { normalize } from '...'`) when it is a default export.

fix Change the import statement to `import normalize from 'json-api-normalizer';`
```
TypeError: Cannot read properties of undefined (reading 'meta') when trying to access normalized output with meta data
```
cause The 'endpoint' option was not provided to the `normalize` function, which is necessary for the library to generate the `meta` object in the output.

fix Ensure the `endpoint` option is passed to the `normalize` function with a string value representing the request endpoint, e.g., `normalize(json, { endpoint: '/api/resource' })`.

Warnings

breaking The `json-api-normalizer` package is effectively abandoned, with its last commit on GitHub occurring approximately five years ago. This means it has not been updated since 2017 and may have significant compatibility issues with modern JavaScript environments, newer Redux versions, or evolving JSON:API specifications.
Fix: Consider migrating to a more actively maintained JSON:API client or normalization library, or fork the project for custom maintenance. Thorough testing is required if used in a modern stack.
gotcha The library processes JSON:API responses according to the specification prevalent around 2017. Later revisions or extensions to the JSON:API spec (e.g., more complex relationship types, meta object placement) might not be fully supported or normalized as expected.
Fix: Manually verify normalization behavior against your specific JSON:API server's response format, especially if your API uses newer JSON:API features or custom extensions.
gotcha By default, query options in the endpoint URL are ignored when storing metadata unless the 'filterEndpoint' option is explicitly set to `false`. This can lead to overwriting cached data if different queries to the same base endpoint return distinct datasets.
Fix: Set `filterEndpoint: false` in the options object if you need distinct metadata entries for different query parameters (e.g., `normalize(json, { endpoint: '/posts?page=1', filterEndpoint: false })`).

Install

npm install json-api-normalizer npm
yarn add json-api-normalizer yarn
pnpm add json-api-normalizer pnpm

Imports

normalize
wrong:
```
import { normalize } from 'json-api-normalizer';
```
correct:
```
import normalize from 'json-api-normalizer';
```
The primary normalization function is a default export. Attempting to destructure it will result in 'undefined'.
normalize (CommonJS)
wrong:
```
import normalize from 'json-api-normalizer';
```
correct:
```
const normalize = require('json-api-normalizer');
```
For CommonJS environments, use `require`. The package provides both ESM and CJS entry points for compatibility.

Quickstart

This example demonstrates how to normalize a JSON:API response, including related 'included' data, and how to use the `endpoint` option to store request-specific metadata.

import normalize from 'json-api-normalizer';

const json = {
  data: [{
    "type": "post-block",
    "relationships": {
      "question": {
        "data": {
          "type": "question",
          "id": "295"
        }
      }
    },
    "id": "2620",
    "attributes": {
      "text": "I am great!",
      "id": 2620
    }
  }],
  included: [{
    "type": "question",
    "id": "295",
    "attributes": {
      "text": "How are you?",
      id: 295
    }
  }]
};

console.log(normalize(json));
/* Expected Output:
{
  question: {
    "295": {
      id: 295,
      type: "question"
      attributes: {
        text: "How are you?"
      }
    }
  },
  postBlock: {
    "2620": {
      id: 2620,
      type: "postBlock",
      attributes: {
        text: "I am great!"
      },
      relationships: {
        question: {
          type: "question",
          id: "295"
        }
      }
    }
  }
}
*/

const normalizedWithEndpoint = normalize(json, { endpoint: '/post-block/2620' });
console.log(normalizedWithEndpoint.meta);

view raw JSON →