Data formatter that creates simplified objects from JSON or stored reduxObject, creates JSON from the same simplified objects (in according with JSON API specification)
Framework agnostic, customizable library that provide data formatters to simplify work with JSON API v1.0 specification.
When you work with API standardized to json:api specification, you're dealing with a special and optimized JSON data format in the request and response body. You can get data of several entities that are related to each other, but you'll receive it in array (included). You may need to send modified back to server (or new data) in accordance with specification.
This may puzzle you with the following questions:
includedarray many times more inconvenient and optimal?
Jsona solves this problems by providing: * converter from JSON to simplified objects (some denormalized structure, wich is easy to typify) * converter from simplified objects to JSON (in according with json:api specification) * converter from "reduxObject" to simplified objects (
reduxObjectis a result object of json-api-normalizer)
NOTE: This README describes latest stable version. You can read README for old versions 0.2.x here
npm install jsona
or
yarn add jsona
You need to instantiate Jsona once, then use its public methods to convert data.
javascript import Jsona from 'jsona'; const dataFormatter = new Jsona();
const json = { data: { type: 'town', id: '123', attributes: { name: 'Barcelona' }, relationships: { country: { data: { type: 'country', id: '32' } } } }, included: [{ type: 'country', id: '32', attributes: { name: 'Spain' } }] };const town = dataFormatter.deserialize(json); console.log(town); // will output: /* { type: 'town', id: '123', name: 'Barcelona', country: { type: 'country', id: '32', name: 'Spain' }, relationshipNames: ['country'] } */
const user = { type: 'user', id: 1, categories: [{ type: 'category', id: '1', name: 'First category' }], town: { type: 'town', id: '123', name: 'Barcelona', country: { type: 'country', id: '32', name: 'Spain' }, relationshipNames: ['country'] }, relationshipNames: ['categories', 'town'] };const newJson = dataFormatter.serialize({ stuff: user, // can handle array includeNames: ['categories', 'town.country'] // can include deep relations via dot });
console.log(newJson); // will output: /* { data: { type: 'user', id: 1, relationships: { categories: { data: [{ type: 'category', id: '1' }] }, town: { data: { type: 'town', id: '123' } } } }, included: [{ type: 'category', id: '1', attributes: { name: 'First category', } }, { type: 'town', id: '123', attributes: { name: 'Barcelona', }, relationships: { country: { data: { type: 'country', id: '32', } } } }, { type: 'country', id: '32', attributes: { name: 'Spain', } }] }*/
"reduxObject" - result object of json-api-normalizer
const reduxObject = reduxStore.entities; // depends on where you store it const town = dataFormatter.denormalizeReduxObject({reduxObject, entityType: 'town', entityIds: '123'}); console.log(town); // if there is such town and country in reduxObject, it will output: /* { type: 'town', id: '123', name: 'Barcelona', country: { type: 'country', id: '34', name: 'Spain' }, relationshipNames: ['country'] } */
You can control process of building simplified objects, just use your own propertyMappers when Jsona instantiates.
With IJsonPropertiesMapper you can implement your way of creation simplified objects (data models) from JSON, with IModelPropertiesMapper implement how to give back values from data model to JSON.
It gives unlimited possibilities to integrate Jsona with react, redux, angular2
Example of passing your own propertyMappers to Jsona: ```javascript import Jsona from 'jsona'; import {MyModelPropertiesMapper, MyJsonPropertiesMapper} from 'myPropertyMappers';
export default const dataFormatter = new Jsona({ modelPropertiesMapper: MyModelPropertiesMapper, jsonPropertiesMapper: MyJsonPropertiesMapper }); ``` Also, there is built-in switchCasePropertyMappers, that you can use if need to automatically transform property names from kebab, snake, camel case and back.
For faster creation of simplified objects from json, it uses a cache for already processed json-entity, see DeserializeCache that uses by default. It possible to provide your own IDeserializeCache manager: ```javascript import Jsona from 'jsona'; import {MyOwnDeserializeCache} from './index';
export default const dataFormatter = new Jsona({ DeserializeCache: MyOwnDeserializeCache }); ```
Jsona, examples provided in this repository and in the documentation are MIT licensed.