Teacher// sets a filter// eager loads related models// eager loads directly and indirectly related models// submits the HTTP request, returns an ES6 Promise;
To get started, see our more elaborate guide in our wiki! A short version is featured below.
$ npm install coloquent
To retrieve a single page of models of a certain type:
To retrieve the second page
The page size can be configured, this is covered the Setup section.
To add a filter, add a
To eager load related models within the same HTTP request, add a
To sort the result set server-side (indispensible for pagination), add an
The second argument denoting the sorting direction is optional and is either
asc (default) or
If you are only interested in the youngest
Artist, it is more efficient to use
first instead of
This will retrieve only a single model from the server. To retrieve a single model by ID:
To query a relation of an object you've instantiated:
If, for some reason, you need to add a raw URL query parameter (e.g.
?_foo=somevalue) to the underlying endpoint, use
All of the queries above return an ES6
Promise to which an instance of -depending on whether a single or multiple
models were requested-
PluralResponse is passed. From these classes both requested models and
eagerly loaded models can be obtained, e.g.:
var teacher = coloquentResponsegetData0;var schoolAddress = teacher0;var student = teacher0;
student now all contain full-fledged model objects.
Creating / updating
To save an instance of
Artist to the server:
artist has the property
id set, Coloquent will attempt a
PATCH request to update an existing object; otherwise it will perform a
POST request, creating a new object server-side.
To delete an instance of
Artist from the server:
- The attribute
jsonApiBaseUrlexplained in the Setup section of this readme must point to an API implementing the JSON API standard.
All you need to do is extend Coloquent's
Model class with your own model:
;public : stringreturn '';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, and have your model classes extend that class. This is done in the following example.
We are configuring 3 models:
Song. In the following example, Typescript type assertions (e.g.
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
respectively. Attributes can conversely be set with a
Also note the methods that return an object of type
These are relationship declarations: they tell Coloquent what kind of relationship
there exists. It is required that they bear the same name as the cosponding relationship
in the underlying JSON API.
Finally, note that the
Artist class overrides an array called
This array is for attributes that should be excluded from the payload sent to the server
when saving an instance of
Artist (using the
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.
The content of this project is licensed under the MIT license.