jsonapi-mergr v1.0.9

JSONAPI Mergr

JSON API Mergr is a framework agnostic library that makes it easier to deal with jsonapi responses.

It provides 2 methods:

• createDeepInclude
• createShallowInclude

createDeepInclude

createDeepInclude takes in the jsonapi response as an input and returns an object that has all of the included data in it making it easier to access the included data.

For example if you are fetching articles that has a relationship with authors and comments then the object returned by createDeepInclude will be as follows:

export function createDeepInclude (
  jsonApiResponse,
  key,
  includes,
  transformList,
  getFullTree
)

• jsonApiResponse: It is the response from jsonApi
• key: It is the data that was requested in the api
• includes: It is an array of the requested included data
• transformList: It specifies relationships. For example author has type people. This is added in the transformList.
• getFullTree: When it is set createDeepInclude returns back the entire state object. When getFullTree is false createDeepInclude returns back the only the detailed 'key'.

The response example is taken from the jsonapi Readme

Response

{
  "links": {
    "self": "http://example.com/articles",
    "next": "http://example.com/articles?page[offset]=2",
    "last": "http://example.com/articles?page[offset]=10"
  },
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "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" }
        ]
      }
    },
    "links": {
      "self": "http://example.com/articles/1"
    }
  }],
  "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"
    }
  }]
}

Object returned by createDeepInclude

{                                            // object of articles with keys as the id
  "1": {                                     // article with id: 1
    "title": "JSON:API paints my bikeshed!",
    "author": [                              // in place details of the author within the articles object
      {
        "type": "people",
        "id": "9",
        "firstName": "Dan",
        "lastName": "Gebhardt",
        "twitter": "dgeb"
      }
    ],
    "comments": [                           // in place article comment details
      {
        "type": "comments",
        "id": "5",
        "body": "First!",
        "author": [                        // Since the data for people:id = 2 wasn't sent in the API response
          {                                // it remains as is with the type and id.
            "type": "people",
            "id": "2"
          }
        ]
      },
      {
        "type": "comments",
        "id": "12",
        "body": "I like XML better",
        "author": [                      // Since the data for people:id = 9 is sent in the API response
          {                              // it is concatenated to the object.
            "type": "people",
            "id": "9",
            "firstName": "Dan",
            "lastName": "Gebhardt",
            "twitter": "dgeb"
          }
        ]
      }
    ]
  }
}

Example Usage

createDeepInclude(
  apiResponse,
  'articles',
  ['people', 'comments', 'author'],
  {
    author: 'people'
  }
)

createShallowInclude

createShallowInclude takes in the jsonapi response as an input and returns a flat object that strips off the relationships and attributes keys. All of the included entities are individual keys in the newly returned object

For example if you are fetching articles that has a relationship with authors and comments then the object returned by createShallowInclude will be as follows:

export function createShallowInclude (
  jsonApiResponse,
  entities,
  transformList
)

• jsonApiResponse is the response from jsonApi
• all of the entities that should be properties in the returned object
• transformList specified relationships. For example author has type people. This is added in the transformList.

The response example is taken from the jsonapi Readme

Response

{
  "links": {
    "self": "http://example.com/articles",
    "next": "http://example.com/articles?page[offset]=2",
    "last": "http://example.com/articles?page[offset]=10"
  },
  "data": [{
    "type": "articles",
    "id": "1",
    "attributes": {
      "title": "JSON:API paints my bikeshed!"
    },
    "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" }
        ]
      }
    },
    "links": {
      "self": "http://example.com/articles/1"
    }
  }],
  "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"
    }
  }]
}

Object returned by createShallowInclude

{
  "people": {
    "9": {
      "firstName": "Dan",
      "lastName": "Gebhardt",
      "twitter": "dgeb"
    }
  },
  "comments": {
    "5": {
      "body": "First!",
      "author": [
        {
          "type": "people",
          "id": "2"
        }
      ]
    },
    "12": {
      "body": "I like XML better",
      "author": [
        {
          "type": "people",
          "id": "9"
        }
      ]
    }
  },
  "articles": {
    "1": {
      "title": "JSON:API paints my bikeshed!",
      "author": [
        {
          "type": "people",
          "id": "9"
        }
      ],
      "comments": [
        {
          "type": "comments",
          "id": "5"
        },
        {
          "type": "comments",
          "id": "12"
        }
      ]
    }
  }
}

Example Usage

createShallowInclude(apiResponse, ['people', 'comments', 'articles'], {
  author: 'people'
})

Example

Clone the repository and run the example using

npm run example

Example Usage

ES 6

import { createDeepInclude, createShallowInclude } from 'jsonapi-mergr'

...
...
const articles = createDeepInclude(apiResponse, 'articles', ['people', 'comments', 'author'], { author: 'people' })
const stateObject = createShallowInclude(apiResponse, ['people', 'comments', 'articles'], { author: 'people' })
...
...

Common JS

const { createDeepInclude, createShallowInclude } = require('jsonapi-mergr')

...
...
const articles = createDeepInclude(apiResponse, 'articles', ['people', 'comments', 'author'], { author: 'people' })
const stateObject = createShallowInclude(apiResponse, ['people', 'comments', 'articles'], { author: 'people' })
...
...