carlobeltrame/hal-json-normalizer

Normalizes responses from HAL JSON APIs for use in Vuex, redux and similar state stores.

hal-json-normalizer

Utility to normalize HAL JSON data for Vuex applications.

Description

hal-json-normalizer helps HAL JSON APIs and Vuex work together. Unlike normalizr, hal-json-normalizer supports the HAL+JSON specification, which means that you don't have to care about schemas. This library also supports templated links.

Install

$ npm install hal-json-normalizer

Example

import normalize from 'hal-json-normalizer';

const json = {
  id: 2620,
  text: 'I am great!',
  _embedded: {
    question: {
      id: 295,
      text: 'How are you?',
      _links: {
        self: {
          href: 'https://my.api.com/questions/295',
        },
      },
    },
  },
  _links: {
    self: {
      href: 'https://my.api.com/answers/2620',
    },
    author: {
      href: 'https://my.api.com/users/1024',
    },
    questions: {
      href: 'https://my.api.com/questions{/id}',
      templated: true,
    },
  },
};

console.log(normalize(json));
/* Output:
{
  'https://my.api.com/answers/2620': {
    id: 2620,
    text: 'I am great!'
    question: {
      href: 'https://my.api.com/questions/295',
    },
    author: {
      href: 'https://my.api.com/users/1024',
    },
    questions: {
      href: 'https://my.api.com/questions{/id}',
      templated: true,
    },
    _meta: {
      self: 'https://my.api.com/answers/2620',
    },
  },
  'https://my.api.com/questions/295': {
    id: 295,
    text: 'How are you?',
    _meta: {
      self: 'https://my.api.com/questions/295',
    },
  },
}
*/

Options

Camelize Keys

By default all object keys are converted to camel case, however, you can disable this with camelizeKeys option.

const json = {
  'camel-me': 1,
  _links: {
    self: {
      href: 'https://my.api.com/someEntity/1',
    },
  },
};

console.log(normalize(json));
/* Output:
{
  'https://my.api.com/someEntity/1': {
    camelMe: 1,
    _meta: {
      self: 'https://my.api.com/someEntity/1',
    },
  },
}
*/

console.log(normalize(json, { camelizeKeys: false }));
/* Output:
{
  'https://my.api.com/someEntity/1': {
    'camel-me': 1,
    _meta: {
      self: 'https://my.api.com/someEntity/1',
    },
  },
}
*/

Normalizing URIs

In many cases, all API URIs will start with the same prefix, or you may want to treat different orderings of query parameters as the same endpoint, etc. You can specify a normalization strategy for all identifiers by passing a function to the normalizeUri option.

Note: Templated links are excluded from normalization, because the URIs inside are actually URI templates, not normal URIs. Templated links look like this: { href: 'https://so.me/where{/id}', templated: true }

const json = {
  id: 1,
  _links: {
    self: {
      href: 'https://my.api.com/api/v2/someEntity/1',
    },
    someApiInternalLink: {
      href: 'https://my.api.com/api/v2/related/20',
    },
    someExternalLink: {
      href: 'test.com/not-starting-with-the-same-prefix',
    },
  },
};

console.log(normalize(json));
/* Output:
{
  'https://my.api.com/api/v2/someEntity/1': {
    id: 1,
    someApiInternalLink: {
      href: 'https://my.api.com/api/v2/related/20',
    },
    someExternalLink: {
      href: 'test.com/not-starting-with-the-same-prefix',
    },
    _meta: {
      self: 'https://my.api.com/someEntity/1',
    },
  },
}
*/

console.log(normalize(json, { normalizeUri: (uri) => uri.replace(/^https:\/\/my.api.com\/api\/v2/, '') }));
/* Output:
{
  '/someEntity/1: {
    id: 1,
    someApiInternalLink: {
      href: '/related/20',
    },
    someExternalLink: {
      href: 'test.com/not-starting-with-the-same-prefix',
    },
    _meta: {
      self: '/someEntity/1',
    },
  },
}
*/

Custom _meta key

This library adds the self link as a string property self to the _meta property of each resource. Depending on your API server framework, you might want to use a different key than _meta. You can change this using the metaKey option.

const json = {
  id: 1,
  _meta: {
    expiresAt: 1513868982,
  },
  _links: {
    self: {
      href: 'https://my.api.com/someEntity/1',
    },
  },
};

console.log(normalize(json));
/* Output:
{
  'https://my.api.com/someEntity/1': {
    id: 1,
    _meta: {
      expiresAt: 1513868982,
      self: 'https://my.api.com/someEntity/1',
    },
  },
}
*/

console.log(normalize(json, { metaKey: '__metadata' }));
/* Output:
{
  'https://my.api.com/someEntity/1': {
    id: 1,
    // CAUTION: this key is now now special anymore and therefore is camelized by default
    meta: {
      expiresAt: 1513868982,
    },
    __metadata: {
      self: 'https://my.api.com/someEntity/1',
    },
  },
}
*/

Embedded lists with a self link

In some cases your API might need to embed a list (for performance reasons), but still communicate a self link under which the list can be separately re-fetched. This is supported by doing the following:

• In the API, embed the list normally under some relation key (e.g. comments) and also add a link with the same relation key to _links
• Set the embeddedStandaloneListKey option to some string, e.g. 'items'

The list will then be normalized as a separate (standalone) object, containing just the list under the key from the option (items).

Note: If you don't specify the embeddedStandaloneListKey option and the API sends the same relation key in _embedded and in _links, the data from _embedded will take preference, since that can potentially contain more information.

const json = {
  id: 1,
  _embedded: {
    comments: [
      {
        text: 'Hello World!',
        author: 'James',
        _links: {
          self: {
            href: 'https://my.api.com/comments/53204',
          },
        },
      },
      {
        text: 'Hi there',
        author: 'Joana',
        _links: {
          self: {
            href: 'https://my.api.com/comments/1395',
          },
        },
      },
    ],
  },
  _links: {
    comments: {
      href: 'https://my.api.com/comments?someEntity=1',
    },
    self: {
      href: 'https://my.api.com/someEntity/1',
    },
  },
};

console.log(normalize(json));
/* Output:
{
  'https://my.api.com/someEntity/1': {
    id: 1,
    comments: [
      {
        href: 'https://my.api.com/comments/53204',
      },
      {
        href: 'https://my.api.com/comments/1395',
      },
    ],
    _meta: {
      self: 'https://my.api.com/someEntity/1',
    },
  },
  'https://my.api.com/comments/53204': {
    text: 'Hello World!',
    author: 'James',
    _meta: {
      self: 'https://my.api.com/comments/53204'
    },
  }
  'https://my.api.com/comments/1395': {
    text: 'Hi there',
    author: 'Joana',
    _meta: {
      self: 'https://my.api.com/comments/1395'
    },
  },
}
*/

console.log(normalize(json, { embeddedStandaloneListKey: 'items' }));
/* Output:
{
  'https://my.api.com/someEntity/1': {
    id: 1,
    comments: {
      href: 'https://my.api.com/comments?someEntity=1',
    },
    _meta: {
      self: 'https://my.api.com/someEntity/1',
    },
  },
  'https://my.api.com/comments?someEntity=1': {
    items: [
      {
        href: 'https://my.api.com/comments/53204',
      },
      {
        href: 'https://my.api.com/comments/1395',
      },
    ],
    _meta: {
      self: 'https://my.api.com/comments?someEntity=1',
    },
  },
  'https://my.api.com/comments/53204': {
    text: 'Hello World!',
    author: 'James',
    _meta: {
      self: 'https://my.api.com/comments/53204'
    },
  }
  'https://my.api.com/comments/1395': {
    text: 'Hi there',
    author: 'Joana',
    _meta: {
      self: 'https://my.api.com/comments/1395'
    },
  },
}
*/

Virtual self link for embedded collections without link

For consistency, you might want to always have related collections referenceable, even if the API does not provide any single link under which the collection could be accessed in isolation. This library gives you the option to generate virtual keys (virtual URIs, virtual self links) for all embedded and linked arrays that don't already have a self link. To activate, set virtualSelfLinks to true.

Note: If the API also sends a single link for an embedded collection, this single link will be used instead of any virtual (generated) key, since that link will be more accurate and more useful to e.g. reload the collection from the API in isolation.

The generated links are always marked with the virtual: true flag, so you can distinguish them from "normal" self links when doing further processing.

const json = {
  id: 1,
  _embedded: {
    comments: [
      {
        text: 'Hello World!',
        author: 'James',
        _links: {
          self: {
            href: 'https://my.api.com/comments/53204',
          },
        },
      },
      {
        text: 'Hi there',
        author: 'Joana',
        _links: {
          self: {
            href: 'https://my.api.com/comments/1395',
          },
        },
      },
    ],
  },
  _links: {
    users: [{
      href: 'https://my.api.com/users/123',
    }, {
      href: 'https://my.api.com/users/324',
    }],
    self: {
      href: 'https://my.api.com/someEntity/1',
    },
  },
};

console.log(normalize(json, { embeddedStandaloneListKey: 'items', virtualSelfLinks: true }));
/* Output:
{
  'https://my.api.com/someEntity/1': {
    id: 1,
    comments: {
      href: 'https://my.api.com/someEntity/1#comments',
      virtual: true,
    },
    users: {
      href: 'https://my.api.com/someEntity/1#users',
      virtual: true,
    },
    _meta: {
      self: 'https://my.api.com/someEntity/1',
    },
  },
  'https://my.api.com/someEntity/1#comments': {
    items: [
      {
        href: 'https://my.api.com/comments/53204',
      },
      {
        href: 'https://my.api.com/comments/1395',
      },
    ],
    _meta: {
      self: 'https://my.api.com/someEntity/1#comments',
      virtual: true,
      owningResource: 'https://my.api.com/someEntity/1',
      owningRelation: 'comments',
    },
  },
  'https://my.api.com/someEntity/1#users': {
    items: [
      {
        href: 'https://my.api.com/users/123',
      },
      {
        href: 'https://my.api.com/users/324',
      },
    ],
    _meta: {
      self: 'https://my.api.com/someEntity/1#users',
      virtual: true,
      owningResource: 'https://my.api.com/someEntity/1',
      owningRelation: 'comments',
    },
  },
  'https://my.api.com/comments/53204': {
    text: 'Hello World!',
    author: 'James',
    _meta: {
      self: 'https://my.api.com/comments/53204'
    },
  }
  'https://my.api.com/comments/1395': {
    text: 'Hi there',
    author: 'Joana',
    _meta: {
      self: 'https://my.api.com/comments/1395'
    },
  },
}
*/

Filtering references

Even if the HAL JSON standard does not define it this way, some API server frameworks (like apigility in the Zend Framework 2) can sometimes send stripped down versions of deeply nested embedded resources. As you can see below (the author of the comment resource), such references contain nothing but a self link. You can prevent these incomplete resource representations from polluting your store using the filterReferences option.

const json = {
  id: 1,
  text: 'hello, world!',
  _embedded: {
    comments: [
      {
        id: 203,
        text: 'good post!',
        _embedded: {
          // This is a reference: an embedded resource with nothing but a self link
          author: {
            _links: {
              self: {
                href: 'https://my.api.com/users/124',
              },
            },
          },
        },
        _links: {
          self: {
            href: 'https://my.api.com/comments/203',
          },
        },
      },
    ],
  },
  _links: {
    self: {
      href: 'https://my.api.com/posts/1',
    },
  },
};

console.log(normalize(json));
/* Output:
{
  'https://my.api.com/posts/1': {
    id: 1,
    text: 'hello, world!',
    comments: [
      {
        href: 'https://my.api.com/comments/203',
      },
    ],
    _meta: {
      self: 'https://my.api.com/posts/1',
    },
  },
  'https://my.api.com/comments/203': {
    id: 203,
    text: 'good post!',
    author: 'https://my.api.com/users/124',
    _meta: {
      self: 'https://my.api.com/comments/203',
    },
  },
  // This is an incomplete representation of the user, use filterResources: true if you don't want this:
  'https://my.api.com/users/124': {
    _meta: {
      self: 'https://my.api.com/users/124',
    },
  },
}
*/

console.log(normalize(json, { filterReferences: true }));
/* Output:
{
  'https://my.api.com/posts/1': {
    id: 1,
    text: 'hello, world!',
    comments: [
      {
        href: 'https://my.api.com/comments/203',
      },
    ],
    _meta: {
      self: 'https://my.api.com/posts/1',
    },
  },
  'https://my.api.com/comments/203': {
    id: 203,
    text: 'good post!',
    author: 'https://my.api.com/users/124',
    _meta: {
      self: 'https://my.api.com/comments/203',
    },
  },
}
*/

hal-json-normalizer's Issues

Normalizer breaks on null values when filterReferences is enabled

Hi,
Nice project! I was taking it for a spin and found that on the API I was dealing with that the normalizer throws an exception on null values.

The exception is thrown in hasSingleKey as Object.keys is called on null.

I can create a pull request if you like. Let me know. My proposal would be to check for null values in isReference.

const json = {
  id: 2620,
  text: 'hello',
  _embedded: {
    question: null,
  },
  _links: {
    prev: {
      href: null,
    },
    self: {
      href: 'http://example.com/entity/1',
    },
  },
};

const result = normalize(json, {
  filterReferences: true,
});

Action Required: Fix Renovate Configuration

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Error type: undefined. Note: this is a nested preset so please contact the preset author if you are unable to fix it yourself.

Dependency Dashboard

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Rate-Limited

These updates are currently rate-limited. Click on a checkbox below to force their creation now.

• chore(deps): update babel monorepo to v7.24.5 (@babel/core, @babel/preset-env)

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• chore(deps): replace dependency babel-eslint with @babel/eslint-parser 7.11.0
• chore(deps): update actions/cache action to v4
• chore(deps): update actions/checkout action to v4
• chore(deps): update actions/setup-node action to v4
• chore(deps): update dependency babel-loader to v9
• chore(deps): update dependency chai to v5
• chore(deps): update dependency eslint to v9
• chore(deps): update dependency mocha to v10
• chore(deps): update dependency rimraf to v5
• chore(deps): update dependency webpack-cli to v5
• Click on this checkbox to rebase all open PRs at once

Detected dependencies

github-actions

.github/workflows/ci.yml

• actions/checkout v2
• actions/setup-node v2
• actions/cache v3
• actions/checkout v2
• actions/setup-node v2
• actions/cache v3

npm

package.json

• lodash ^4.17.15
• @babel/core 7.24.4
• @babel/preset-env 7.24.4
• @babel/register 7.23.7
• babel-eslint 10.1.0
• babel-loader 8.3.0
• chai 4.4.1
• eslint 7.32.0
• eslint-config-airbnb-base 15.0.0
• eslint-loader 4.0.2
• eslint-plugin-import 2.29.1
• mocha 9.2.2
• nyc 15.1.0
• rimraf 3.0.2
• webpack 5.91.0
• webpack-cli 4.10.0
• webpack-node-externals 3.0.0
• node >= 10.13.0

---

• Check this box to trigger a request for Renovate to run again on this repository