Naan and Paneer Makhani

    json-api-merge
    TypeScript icon, indicating that this package has built-in type declarations

    1.1.3 • Public • Published

    Node CI

    JSON API Merge

    json-api-merge is a JSON:API specific redundant duplication algorithm for merging included resources into original data.

    Getting Started

    Installation

    npm i json-api-merge

    or

    yarn add json-api-merge

    Usage

    const jsonApiData = {
      data: {
        id: 1,
        type: 'resource',
        attributes: {
          name: 'Resource name',
        },
        relationships: {
          related: {
            data: {
              id: 2,
              type: 'related_resource',
            },
          },
        },
      },
      included: [
        {
          id: 2,
          type: 'related_resource',
          attributes: {
            name: 'Related resource name',
          },
        },
      ],
    };

    ES2O19

    import jsonApiMerge from 'json-api-merge'
    
    jsonApiMerge(jsonApiData.included, jsonApiData.data)

    Node

    const jsonApiMerge = require('json-api-merge');
    
    jsonApiMerge(jsonApiData.included, jsonApiData.data);

    Result would be following data structure.

    {
      id: 1,
      type: 'resource',
      attributes: {
       name: 'Resource name',
      },
      relationships: {
        related: {
          data: {
           id: 2,
           type: 'related_resource',
           attributes: {
             name: 'Related resource name',
           },
          },
        },
      },
    }

    The library can also process data in list format and can transform this:

    {
      data: [
        {
          id: 1,
          type: 'resource',
          attributes: {
            name: 'Resource name',
          },
          relationships: {
            related: {
              data: {
                id: 2,
                type: 'related_resource',
              },
            },
          },
        }
      ],
      included: [
        {
          id: 2,
          type: 'related_resource',
          attributes: {
            name: 'Related resource name',
          },
        },
      ],
    }

    into this:

    [
      {
        id: 1,
        type: 'resource',
        attributes: {
          name: 'Resource name',
        },
        relationships: {
          related: {
            data: {
              id: 2,
              type: 'related_resource',
              attributes: {
                name: 'Related resource name',
              },
            },
          },
        },
      }
    ]

    Compound document

    To reduce the number of HTTP requests, servers MAY allow responses that include related resources along with the requested primary resources. Such responses are called “compound documents”.

    const jsonApiData = {
      data: [
        {
          type: 'articles',
          id: '1',
          attributes: {
            title: 'JSON:API paints my bikeshed!',
          },
          links: {
            self: 'http://example.com/articles/1',
          },
          relationships: {
            author: {
              links: {
                self: 'http://example.com/articles/1/relationships/author',
                related: 'http://example.com/articles/1/author',
              },
              data: { type: 'people', id: '9' },
            },
            comments: {
              links: {
                self: 'http://example.com/articles/1/relationships/comments',
                related: 'http://example.com/articles/1/comments',
              },
              data: [
                { type: 'comments', id: '5' },
                { type: 'comments', id: '12' },
              ],
            },
          },
        },
      ],
      included: [
        {
          type: 'people',
          id: '9',
          attributes: {
            firstName: 'Dan',
            lastName: 'Gebhardt',
            twitter: 'dgeb',
          },
          links: {
            self: 'http://example.com/people/9',
          },
        },
        {
          type: 'comments',
          id: '5',
          attributes: {
            body: 'First!',
          },
          relationships: {
            author: {
              data: { type: 'people', id: '2' },
            },
          },
          links: {
            self: 'http://example.com/comments/5',
          },
        },
        {
          type: 'comments',
          id: '12',
          attributes: {
            body: 'I like XML better',
          },
          relationships: {
            author: {
              data: { type: 'people', id: '9' },
            },
          },
          links: {
            self: 'http://example.com/comments/12',
          },
        },
      ],
    };

    Compound documents can achieve full linkage with the following trick:

    const included = jsonApiMerge(jsonApiData.included, jsonApiData.included);
    jsonApiMerge(included, jsonApiData.data);

    This operation will generate following compound document with full linkage:

    [
      {
        type: 'articles',
        id: '1',
        attributes: {
          title: 'JSON:API paints my bikeshed!',
        },
        links: {
          self: 'http://example.com/articles/1',
        },
        relationships: {
          author: {
            links: {
              self: 'http://example.com/articles/1/relationships/author',
              related: 'http://example.com/articles/1/author',
            },
            data: {
              type: 'people',
              id: '9',
              attributes: {
                firstName: 'Dan',
                lastName: 'Gebhardt',
                twitter: 'dgeb',
              },
              links: {
                self: 'http://example.com/people/9',
              },
            },
          },
          comments: {
            links: {
              self: 'http://example.com/articles/1/relationships/comments',
              related: 'http://example.com/articles/1/comments',
            },
            data: [
              {
                type: 'comments',
                id: '5',
                attributes: {
                  body: 'First!',
                },
                relationships: {
                  author: {
                    data: {
                      type: 'people',
                      id: '2',
                    },
                  },
                },
                links: {
                  self: 'http://example.com/comments/5',
                },
              },
              {
                type: 'comments',
                id: '12',
                attributes: {
                  body: 'I like XML better',
                },
                relationships: {
                  author: {
                    data: {
                      type: 'people',
                      id: '9',
                      attributes: {
                        firstName: 'Dan',
                        lastName: 'Gebhardt',
                        twitter: 'dgeb',
                      },
                      links: {
                        self: 'http://example.com/people/9',
                      },
                    },
                  },
                },
                links: {
                  self: 'http://example.com/comments/12',
                },
              },
            ],
          },
        },
      },
    ];

    Motivation

    I was looking for a simple way how to merge the included into data without compromising data structures. All other libraries that I tested were opionated about how the resulting merge should look like. This library has no opinion and simply merged the included into data. It does nothing else.

    Contributing

    If you want to contribute to this project, please consult the CONTRIBUTING.md guidelines.

    Obtaining project copy

     $ git clone https://github.com/char0n/json-api-merge
     $ npm i

    Running tests

     $ npm run test

    Running tests in browser

     $ npm run test:web

    Running code coverage numbers

     $ npm run coverage

    Running linter

    We're using eslint and airbnb codestyle rules with prettier integrated as an eslint plugin.

     $ npm run lint

    Typescript support

    Although json-api-merge is written in ES2019, we also support Typescript. When json-api-merge gets imported into a Typescript project, typings are automatically imported and used.

    Author

    char0n (Vladimir Gorej)

    vladimir.gorej@gmail.com

    https://www.linkedin.com/in/vladimirgorej/

    Install

    npm i json-api-merge

    DownloadsWeekly Downloads

    15

    Version

    1.1.3

    License

    BSD-3-Clause

    Unpacked Size

    1.18 MB

    Total Files

    15

    Last publish

    Collaborators

    • char0n