Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

jsona

Package Overview
Dependencies
Maintainers
2
Versions
59
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

jsona

Provide data formatters (data model builder & json builder) to work with JSON API specification v1.0 in your JavaScript / TypeScript code

  • 1.8.0
  • Source
  • npm
  • Socket score

Version published
Weekly downloads
34K
decreased by-4.11%
Maintainers
2
Weekly downloads
 
Created
Source

Jsona

Framework agnostic, customizable library that provide data formatters to simplify work with JSON API v1.0 specification.

NPM Build Status dependencies downloads

What problem does it solve?

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:

  • How to get necessary entity from included array many times more inconvenient and optimal?
  • How to describe data from server, working with typings (TypeScript, Flow)?
  • How to send JSON to the server without manually assembling JSON in accordance with specification?

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 (reduxObject is 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

Installation

npm install jsona

or

yarn add jsona

How to use

You need to instantiate Jsona ones, then use it's public methods to convert data.

import Jsona from 'jsona';
const dataFormatter = new Jsona();
deserialize - creates simplified object(s) from json
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']
} */
serialize - creates json from simplified object(s)
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',
        }
    }]
}*/
denormalizeReduxObject - creates simplified object(s) from reduxObject

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

Customize

Build process and property names

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:

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.

Cache

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:

import Jsona from 'jsona';
import {MyOwnDeserializeCache} from './index';

export default const dataFormatter = new Jsona({
    DeserializeCache: MyOwnDeserializeCache
});

License

Jsona, examples provided in this repository and in the documentation are MIT licensed.

Keywords

FAQs

Package last updated on 22 Jul 2020

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc