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',
    },
  },
}
*/