jadocument v0.10.0

JSON Api Document

Installation

npm install --save jadocument

Structure

JADocument can be used on regular javascript objects, or used as containers with methods available directly.

Immutability

With JSON Api documents, it is not always given that you want the data to be immutable. Some times you need to mutate your data directly, some times you might want the data to be immutable, having the updated document as a clone of the original. JADocument have the option to clone documents and resources as part of the call chain.

Usage

Transform plain object to JSON Api object

import JADocument from "jadocument";

const plain = {
    id: "12345",
    manufacturer: "Volkswagen",
    type: "Passat",
    year: 2010
};

JADocument.fromPlain("cars", plain);

// Return value:
{
    data: {
        id: "12345",
        type: "cars",
        attributes: {
            manufacturer: "Volkswagen",
            type: "Passat",
            year: 2010
        }
    }
}

Transform JSON Api object to plain object

import JADocument from "jadocument";

const jao = {
    data: {
        id: "12345",
        type: "cars",
        attributes: {
            type: "Passat",
            year: 2010
        },
        relationships: {
            manufacturer: {
                data: {
                    id: "23456",
                    type: "companies"
                }
            }
        }
    },
    included: [
        {
            id: "23456",
            type: "companies",
            attributes: {
                name: "Volkswagen",
                country: "Germany"
            }
        }
    ]
};

JADocument.toPlain(jao);

// Return value:
{
    id: "12345",
    manufacturer: {
        id: "23456",
        name: "Volkswagen",
        country: "Germany"
    },
    type: "Passat",
    year: 2010
}

Documentation

Abbreviations

ja-object / jao: JSON Api object. Regular Javascript objects containing JSON Api document data.

ja-resource: JSON Api resource. Regular Javascript object containing JSON Api resource data.

ja-relationship: JSON Api relationship. Regular Javascript object containing JSON Api relationship data.

import {
    JADocument, // JSON Api document
    JAResource, // JSON Api resource-object
    JAResourceIdentifier, // JSON Api resource-identifier-object
    JARelationship // JSON Api relationship-object
} from "jadocument";

All methods are available both as static class methods for manipulation of JSON Api data in plain javascript objects, and on wrapper objects for use in call chains etc. All static methods have a first argument for providing the original JSON Api object in addition to the listed arguments.

Example:

// Manipulate plain javascript objects containing JSON Api data
const mutation = JADocument.clearPrimaryData({
    data: {
        id: "123",
        type: "users",
        attributes: {}
    }
});
// mutation => { data: null }

// Wrap JSON Api data in container objects and manipulate directly
const original = new JADocument({
    data: {
        id: "123",
        type: "users",
        attributes: {}
    }
});
const mutation = original.clearPrimaryData();
// mutation is cloned instance of JADocument containing structure { data: null }

// Call chain example
const data = {
    data: {
        id: "123",
        type: "users",
        attributes: {}
    }
};
const emptyArray = new JADocument(data)
    .makePlural()
    .clearPrimaryData();
    .toObject();
// emptyArray => []

JADocument

JSON Api document

.clone()

Clone the document (for immutability).

.toPlain()

Convert to plain key-value object or array of objects.

.toObject()

Convert to regular ja-object

.toJSON()

For JSON.stringify

.isValid()

Check if ja-object is valid JSON Api object structure, return true/false.

.assertValid()

Assert valid ja-object, throwing error if not valid.

.isPlural()

Is ja-object plural (primary data is an array)?

.getLength() / .length (static / method)

Get number of resources in ja-object.

.clearPrimaryData()

Clear primary data, levaing data: null for singular and data: [] for plural objects.

.makePlural()

Make ja-object plural (Array in primary data) if not allready.

.makeSingular()

Make ja-object singular (resource object or null in primary data), will throw error if the ja-object is plural with multiple resources.

.merge(jao, jao, [jao..])

Merge data from all argument ja-objects like resources and includes on to one ja-object.

.addResources(resource) (+ alias .addResource)

Add one or more resources from one ja-object (second argument) to another (first argument).

.hasResource(id, type)

Check if a given resource is part of primary data of ja-object.

.removeResource(id, type)

Remove resource from ja-object.

.getAttribute(name)

Get attribute. Will return attribute value for singular ja-objects, and array of values for plural.

.setAttribute(name, value)

Set attribute on all resources.

.hasAttribute(name)

Check if attribute is set for one or more resources.

.removeAttribute(name)

Remove a named attribute from all resources.

.get()

Alias for getAttribute.

.set()

Alias for setAttribute.

.has()

Alias for hasAttribute.

.forEach(callback)

forEach-function for resources, plural or singular. Similar to Array.prototype.forEach.

.map(callback)

map-function for resources, plural or singular. Similar to Array.prototype.map.

.filter(callback)

filter-function for resources, plural or singular. Similar to Array.prototype.filter.

.reduce(callback, [initialValue])

reduce-function for resources, plural or singular. Similar to Array.prototype.reduce.

.some(callback)

some-function for resources, plural or singular. Similar to Array.prototype.some.

.getRelationship(name)

Get a named relationship object. Will return array of objects for plural ja-object.

.setRelationship(name, relationship)

Set named relationship on all resources.

.hasRelationship(name)

Check if relationship is defined on one or more resources.

.removeRelationship(name)

Remove named relationship for all resources.

.addIncluded(resource)

Add included resource.

.hasIncluded(id, type)

Is target resource included?

.removeIncluded(id, type)

Remove included resource.

JAResource

JSON Api resource

.toPlain()

Convert to plain key-value object.

.toObject()

Convert to regular ja-object

.toJSON()

For JSON.stringify

.toRelationship()

Convert resource to relationship-object.

.toResourceIdentifier()

Convert resource to resource-identifier-object.

.getAttribute(name)

Get attribute value.

.setAttribute(name, value)

Set attribute on resource.

.hasAttribute(name)

Check if attribute is set.

.removeAttribute(name)

Remove a named attribute from resource.

.get()

Alias for getAttribute.

.set()

Alias for setAttribute.

.has()

Alias for hasAttribute.

Sources

JSON Api document schema from http://json-schema.org/draft-04/schema

License

MIT