@rebolon/json-reviver NPM

Json Reviver

When you work on a Frontend application with an API, you usually receive JSON string in HTTP. This is a pain to get back this JSON into real entities. And it's a worst pain when this JSON contain nested entities. This happens also when you try to restore JSON from LocalStorage !

So if you want to restore entities, with all their prototype, there is a lot to do. This is where this package can help you.

HowTo

Install the package npm install @rebolon/json-reviver --save For all required entities, just implements EntityInterface from this package (this is just for typings). Then write a Reviver for all required entities. This reviver must extends ItemAbstractReviver or ListAbstractReviver (for entities that are just an association between different entities).

eg:

// json object restored from localStorage or received from API call
{
    "book": {
        "title": "Zombies in western culture",
        "editors": [{
            "publicationDate": "1519664915",
            "collection": "printed version",
            "isbn": "9781783743230",
            "editor": {
                "name": "Open Book Publishers"
            }
        }, {
            "publicationDate": "1519747464",
            "collection": "ebooks",
            "isbn": "9791036500824",
            "editor": {
                "name": "Open Book Publishers"
            }
        }]
        "serie": {
            "name": "Open Reports Series"
        }
    }
}

// entities that represents a Book (for other entities look at tests/fixtures/entities folder
class Book implements EntityInterface {
    id: number
    title: string = ''
    description?: string = ''
    indexInSerie?: number

    editors: Array<Editors>
    serie?: Serie

    addEdition(edition: Editors) {
        if (typeof this.editors == 'undefined') {
            this.editors = []
        }

        this.editors.push(edition)
    }

    setEdition(edition: Editors) {
        this.editors = []

        this.editors.push(edition)
    }
}

// the reviver for the book
class BookReviver extends ItemAbstractReviver
{
    protected editorsReviver

    protected serieReviver

    constructor (
        editorsReviver: EditorsReviver,
        serieReviver: SerieReviver
    ) {
        super()

        this.editorsReviver = editorsReviver
        this.serieReviver = serieReviver
    }

    // The name of the node in the json string/object
    getNodeName(): string {
        return 'book'
    }

    // The entity for which the reviver works
    getNewEntity(): Object {
        return new Book()
    }

    // List of props (int, string, date, bool) of the entity
    public getEzPropsName()
    {
        return ['id', 'title', 'description', 'indexInSerie', ]
    }

    // List of props that links to other entities (relations Many To Many)
    // And configuration of how to restore them
    public getManyRelPropsName(): Object
    {
        return {
            'editors': {
                'reviver': this.editorsReviver,
                'setter': 'addEdition',
                'cb': function (relation, entity) {
                    Accessor('book', relation, entity)
                },
            },
        }
    }

    // List of props that links to other entities (relations Many To One)
    public getOneRelPropsName(): Object
    {
        return {
            'serie': {
                'reviver': this.serieReviver,
                'registryKey': 'serie',
            },
        }
    }
}

// In your application you just have to do this to restore the entities:
// those 3 are mandatory for nested entities: Book constructor require SerieReviver and EditorsReviver, and the EditorsReviver nees EditorReviver to restore its own editor sub entity (have a look at tests/fixtures/reviver/library)
const editorReviver = new EditorReviver()
const serieReviver = new SerieReviver()
const editorsReviver = new EditorsReviver(editorReviver)

const bookReviver = new BookReviver(editorsReviver, serieReviver)
const bookReviver = new BookReviver()
const book = bookReviver.main(myJsonStringOrObject)

// you can now use all feature of Book entity from your `book`  constant

You can also restore array of object like this (root node book is not mandatory):

[{
    "book": {
        "title": "Zombies in western culture"
    }
},
{   "book": {
         "title": "Another book with Zombies in western culture"
     }
 ]

Running unit tests

Run npm run test to execute the unit tests via Karma.

Npm publication

With typescript package it appears that .ts files should not be published (more info here:https://ljn.io/posts/publishing-typescript-projects-with-npm/). In fact we have to transpile .ts into javascript files. During this process we also need to generate module files (the famous .d.ts). Those files will be published and it will allow typescript compiler to use the .js file finely.

To do this:

in tsconfig.json: set the following compilerOptions
- "declaration": true
- "declarationDir": "./dist"
in package.json: add "prepublishOnly": "node_modules/.bin/tsc -p ./"
then, just run npm publish

Todo

For sub-entities that are represented only by an ID or an IRI, we should be able to retreive the full entity by calling back the API (maybe use rxjs to return a subscription, and let the developper do what he wants)