npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

jsona

v1.12.1

Published

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

Downloads

140,889

Readme

Jsona

JSON API v1.0 specification serializer and deserializer for use on the server and in the browser.

  • From JSON to simplified objects
  • Back from simplified objects to JSON (in according with json:api specification)
  • Also from "reduxObject" to simplified objects (reduxObject is a result object of json-api-normalizer)

NPM 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?

Installation

npm i jsona --save

or

yarn add jsona

How to use

You need to instantiate Jsona once, then use its 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 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 const dataFormatter = new Jsona({
    DeserializeCache: MyOwnDeserializeCache
});

License

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