@volst/mobx-spine

mobx-spine

A frontend package built upon MobX to add models and collections. It has first-class support for relations and can communicate to a backend.

By default it comes with a "communication layer" for Django Binder, which is Code Yellow's Python backend framework. It is easy to add support for another backend.

yarn add @volst/mobx-spine lodash mobx moment
npm install @volst/mobx-spine lodash mobx moment

Work In Progress.

mobx-spine is highly inspired by Backbone and by the package we built on top of Backbone, Backbone Relation.

Design differences with Backbone

Since mobx-spine uses MobX, it does not need to have an event system like Backbone has. This means that there are no this.listenTo()'s. If you need something like that, look for autorun() or add a @computed property.

Another difference is that in mobx-spine, all properties of a model must be defined beforehand. So if a model has the props id and name defined, it's not possible to suddenly add a slug property unless you define it on the model itself. Not allowing this helps with keeping overview of the props there are.

mobx-spine has support for relations and pagination built-in, in contrast to Backbone.

A model or collection can only do requests to an API if you add an api instance to it. This allows for easy mocking of the API, and makes mobx-spine not coupled to Binder, our Python framework. It would be easy to make a package or just a separate file with a custom backend.

Usage

A basic example of mobx-spine:

import { observable } from 'mobx';
import { Model, Store, BinderApi } from '@volst/mobx-spine';

class Animal extends Model {
    @observable id = null;
    @observable name = '';
}

const animal = new Animal();
animal.name = 'Lion';
animal.color = 'green' // `color` is not defined, so this does not trigger a re-render if used in a component.

An example with relations:

const api = new BinderApi();

class Breed extends Model {
    @observable id = null;
    @observable name = '';
}

class Animal extends Model {
    api = api;
    urlRoot = '/api/animal/';
    @observable id = null;
    @observable name = '';

    relations() {
        return {
            breed: Breed,
        };
    }
}

class animal = new Animal({ id: 2 }, { relations: ['breed'] });
animal.fetch(); // Performs a request: GET api/animal/2?with=breed
console.log(animal.breed.name);

An example with a Store (called a Collection in Backbone):

class AnimalStore extends Store {
    api = api;
    url = '/api/animal/';
    Model = Animal;
}

class animalStore = new AnimalStore(null, { relations: ['breed'] });
animalStore.fetch(); // Performs a request: GET api/animal/?with=breed

An example of saving data:

class Animal extends Model {
    api = api;
    urlRoot = '/api/animal/';
    @observable id = null;
    @observable name = '';
    @observable _errors = {};
}

const animal = new Animal({ id: 1, name: 'King' });
animal.save(); // Performs a request: POST api/animal
// Note that the `_errors` prop will not be included in the request;
// props starting with an underscore are frontend-only.