Models

Like any Backend ORM, models are the reprensentation of the data structure. They store a list of indexed entries, linked toguether using relations.

Overview

import { createModel } from 'dispersive';
import { withField } from 'dispersive/field';
import { withMany } from 'dispersive/relation';

const Book = createModel([
  withField('title'),
]);

const Author = createModel([
  withField('name'),
  withMany('books', Book),
]);

Out of the box

Models are generated using the createModel function.

import { createModel } from 'dispersive';

const Book = createModel();

In this example above, Book is already capable of storing entries. Its entries manager is Book.objects.

const firstBook = Book.objects.first();
const booksCount = Book.objects.count();

Each entry is a proxy to a values object. These values are Immutable.Map structures.

const book = Book.objects.first();
const bookTitle = book.values.get('title');

Model composition

To make a better the developer experience, a model is configured with a set of composers.

const Unicorn = createModel([
  lookingLikeAHorse(),
  withSpiralingHorn(),
  surfingOnRainbows(),
]);

Each composers is meant to improve and scale the basics of a model.

Fields

Dispersive has 3 native composers in its API, withField is one of them. The other will be seen in the relations paragraph below.

import { withField } from 'dispersive/field';

const Book = createModel([
  withField('title'),
]);

It's basically an set/get accessor to an entry values.

const book = Book.objects.first();
const bookTitle = book.title; // same as book.values.get('title');

book.title = 'Peter Pan'. // same as book.values = book.values.set('title', 'Peter Pan');

Relations

There are 2 composers for relations purpose : withOne and withMany.

Together, they fill these 4 relations types : one to one, many to one, one to many and many to many.

1. One to one relation

const Reader = createModel([
  withField('name'),
]);

const Book = createModel([
  withOne('owner', Reader),
]);

A book can have only one owner. So book.owner will return a Reader entry or null (if no owner has been attached).

2. Many to one relation

const Library = createModel([
  withMany('books', Book),
]);

A library can have several books. So library.books will return a filtered subset of Book.objects.

3. One to many relation

const Book = createModel([
  withOne('library', { model: Book, hasMany: true }),
]);

We have here the opposite of the "many to one" example. In this case, library can't access to its books list but each book knows in which library it is. They can both have accessors to the relation using : relatedName.

const Book = createModel([
  withOne('library', {
    model: Book,
    hasMany: true,
    relatedName: 'book',
  }),
]);

Now we can access book.library from a Book entry and library.books from a Library entry.

4. Many to many relation

As withOne, withMany can take the options hasMany and relatedName.

const Book = createModel([
  withMany('readers', {
    model: Reader,
    hasMany: true,
    relatedName: 'books',
  }),
]);

In this example book.readers from a Book entry and reader.books from a Reader entry.