Javascript/Typescript library mapping objects and their interrelations to JSON API, with a clean, fluent ActiveRecord (e.g. similar to Laravel's Eloquent) syntax for creating, retrieving, updating and deleting model objects. For example:

Teacher
    .where('gender', 'm')                   // sets a filter
    .with('students')                       // eager loads related models
    .with('schools.address')                // eager loads directly and indirectly related models
    .get()                                  // submits the HTTP request, returns an ES6 Promise
    .then(coloquentResponse => {
        // do stuff with response of full-fledged, interrelated model objects
    });

To get started, see our more elaborate guide in our wiki! A short version is featured below.

Install

$ npm install coloquent

Requirements

• Use in a project of which the runtime code is Javascript ES6 or higher. If your compile target is ES5 or lower, you will run into this issue.
• The attribute

  jsonApiBaseUrl

  explained in the Setup section of this readme must point to an API implementing the JSON API specification.

Usage

Retrieving

To retrieve a single page of models of a certain type:

Artist.get();

To retrieve the second page

Artist.get(2);

The page size can be configured, this is covered the Setup section.

To add a filter, add a

where

javascript
Artist
    .where('country', 'US')
    .get();

with

javascript
Artist
    .with('songs')
    .get();

orderBy

javascript
Artist
    .orderBy('birthDate', 'desc')
    .get();

asc

desc

SortDirection.ASC

SortDirection.DESC

Artist

first

get

javascript
Artist
    .orderBy('birthDate', 'desc')
    .first();

javascript
Artist.find(324);

javascript
artist.albums()
    .orderBy('name', SortDirection.DESC)
    .get()

?_foo=somevalue

option

javascript
Artist
    .option('_foo', 'somevalue')
    .get();

All of the queries above return an ES6

Promise

SingularResponse

PluralResponse

var teacher = coloquentResponse.getData[0];
var schoolAddress = teacher.getSchools()[0].getAddress();
var student = teacher.getStudents()[0];

The variables

teacher

schoolAddress

student

Note for TypeScript users

You should specify model class as generic type of any static method invocation.

Artist.get().then((response) => {
    const data = response.getData();
    // data is now properly inferred as Artist[] instead of Model[]
    // You don't have to cast anything thanks to provided generic type.
})

Creating / updating

To save an instance of

Artist

artist.save();

If

artist

id

PATCH

POST

Deleting

To delete an instance of

Artist

artist.delete();

Setup

All you need to do is extend Coloquent's

Model

import {Model} from 'coloquent';

class Artist extends Model
{
    public getJsonApiBaseUrl(): string
    {
        return 'http://www.app.com/api/';
    }
protected jsonApiType = 'artists';

protected pageSize = 30;
}

If there are settings that you want the same for all your models, it is useful to make an intermediary class that extends Coloquent's

Model

Example setup

We are configuring 3 models:

Artist

Album

Song

: Artists[]

import {Model} from 'coloquent';

class AppModel extends Model
{
    getJsonApiBaseUrl(): string
    {
        return 'http://www.app.com/api/';
    }
}
class Artist extends AppModel
{
    jsonApiType = 'artists';
readOnlyAttributes = [
    'age'
];

albums(): ToManyRelation<album this>
{
    return this.hasMany(Album);
}

getAlbums(): Album[]
{
    return this.getRelation('albums');
}

getBirthDate(): string
{
    return this.getAttribute('birtDate');
}

getAge(): number
{
    return this.getAttribute('age');
}

getCountry(): string
{
    return this.getAttribute('country');
}

setCountry(country: string)
{
    this.setAttribute('country', country);
}
}
class Album extends AppModel
{
    jsonApiType = 'albums';
artist(): ToOneRelation<artist this>
{
    return this.hasOne(Artist);
}

songs(): ToManyRelation<song this>
{
    return this.hasMany(Song);
}

getArtist(): Artist
{
    return this.getRelation('artist');
}

getSongs(): Song[]
{
    return this.getRelation('songs');
}
}
class Song extends AppModel
{
    jsonApiType = 'songs';
album(): ToOneRelation<album this>
{
    return this.hasOne(Album);
}

getAlbum(): Album
{
    return this.getRelation('album');
}
}

Now we can query these models in the fashion shown in the Usage section of this readme. Note that the models contain getters, and that these getters get the values of relationships and attributes with

this.getRelation

this.getAttribute

this.setAttribute

Also note the methods that return an object of type

ToManyRelation

ToOneRelation

Finally, note that the

Artist

readOnlyAttributes

Artist

save()

Feedback

If something is missing from this library that makes it not fit your use case today, or if you find a bug that spoils it for you, don't hesitate to create an Issue or a Pull Request. Coloquent is in active development and all feedback and contributions are sincerely appreciated.

License

The content of this project is licensed under the MIT license.