json-api-models

A lightweight layer for working with JSON:API data.

Installation

npm install json-api-models --save

Usage

import { Store } from 'json-api-models';

const models = new Store();

// Sync a JSON:API response document to the store
models.sync({
    data: {
        type: 'humans',
        id: '1',
        attributes: { name: 'Toby' },
        relationships: {
            dog: { data: { type: 'dogs', id: '1' }}
        }
    },
    included: [{
        type: 'dogs',
        id: '1',
        attributes: { name: 'Rosie' }
    }]
});

// Resource data is transformed into easy-to-consume models
const human = models.find('humans', '1');
human.name // Toby
human.dog // { type: 'dogs', id: '1', name: 'Rosie' }

Syncing JSON:API Data

Use the sync method to load your JSON:API response document into the store. Both the primary data and any included resources will be synced. The return value will be a model, or an array of models, corresponding to the primary data.

const model = models.sync(document);

If any of the synced resources already exist within the store, the new data will be merged into the old model. The model instance will not change so references to it throughout your application will remain intact.

You can also sync an individual resource using the syncResource method:

const model = models.syncResource({
    type: 'users',
    id: '1',
    attributes: { name: 'Toby' }
});

Retrieving Models

Specific models can be retrieved from the store using the find method. Pass it a type and an ID, a resource identifier object, or an array of resource identifier objects:

const model = models.find('users', '1');
const model = models.find({ type: 'users', id: '1' });
const models = models.find([
    { type: 'users', id: '1' },
    { type: 'users', id: '2' }
]);

Retrieve all of the models of a given type using the findAll method:

const models = models.findAll('users');

Working with Models

Models are a superset of JSON:API resource objects, meaning they contain all of the members you would expect (type, id, attributes, relationships, meta, links) plus some additional functionality.

Getters are automatically defined for all fields, allowing you to easily access their contents. Relationship fields are automatically resolved to their related models (if present within the store):

model.name // => model.attributes.name
model.dog // => models.find(model.relationships.dog.data)

To easily retrieve a resource identifier object for the model, the identifier method is available. This is useful when constructing relationships in JSON:API request documents.

model.identifier() // { type: 'users', id: '1' }

Forgetting Models

Remove a model from the store using the forget method, which accepts a resource identifier object. This means you can pass a model directly into it:

models.forget(user);

Custom Models

You can define custom model classes to add your own functionality. Custom models must extend the Model base class. This is useful if you wish to add any custom getters or methods to models for a specific resource type, and also to define types for each resource field:

import { Model } from 'json-api-models';

class User extends Model<'users'> {
    public declare name: string;
    public declare age: number;
    
    get firstName() {
        return this.name.split(' ')[0];
    }
}

Register your custom models with the store during construction:

const models = new Store({
    users: User,
});

Attribute Casts

You can define typecasts for attributes on your custom models:

class User extends Model<'users'> {
    declare public name: string;
    declare public createdAt: Date;
    
    protected casts = {
        createdAt: Date,
    };
}

API Consumption Tips

This library is completely unopinionated about how you interact with your JSON:API server. It merely gives you an easy way to work with the resulting JSON:API data. An example integration with fetch is demonstrated below:

const models = new Store();

function api(url, options = {}) {
    options.headers = options.headers || {};
    options.headers['Accept'] = 'application/vnd.api+json';

    if (options.body) {
        options.body = JSON.stringify(options.body);
        options.headers['Content-Type'] = 'application/vnd.api+json';
    }

    return fetch('http://example.org/api/' + url, options)
    	.then(async response => {
        	if (response.status === 204) {
                return { response };
            } else {
                const document = await response.json();
                const data = models.sync(document);
                return { response, document, data };
            }
    	});
}

api('users/1').then(({ data }) => {
    console.log(data.name);
});

When constructing API requests, remember that JSON:API resource objects contain links that can be used instead of rebuilding the URL. Also, models contain an identifier method that can be used to spread the type and id members into the document data (required by the specification). Here is an example of a request to update a resource:

const user = models.find('users', '1');

api(user.links.self, {
    method: 'PATCH',
    body: {
        data: {
            ...user.identifier(),
            attributes: { name: 'Changed' }
        }
    }
});

Building Queries

Building query strings for your JSON:API requests can be tedious, and sometimes they may need to be constructed dynamically with merge logic for certain parameters. The Query class takes care of this:

import { Query } from 'json-api-models';

const query = new Query({
    'include': 'foo',
    'fields[users]': 'name',
});

query.append('include', 'bar');
query.append('fields[users]', 'age');

query.toString(); // include=foo,bar&fields[users]=name,age

query.delete('fields[users]');
query.set('include', 'replaced');

query.toString(); // include=replaced

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

License

MIT