maykinmedia/consumerjs

Consumerjs simplifies REST with an ORM like approach. Built on top of Axios.

ConsumerJS

Consumerjs simplifies REST with an ORM like approach. Built on top of Axios.

Consumerjs is an ORM-like repository/entity mapper that aims to make using RESTful JSON API's simple and DRY. It supports basic CRUD operations on remote resources and can easiy be extended with custom behaviour.

ConsumerJS out of the box supports (Django) CSRF protection.

Installation

Install with npm.

$ npm i consumerjs --save

As of 2.0.0: @babel/polyfill needs to be installed in your project in order to support older browsers like Internet Explorer 11.

Usage

See doc for full API documentation.

Example:

data/post.js

import { CrudConsumer, CrudConsumerObject } from 'consumerjs';


class Post extends CrudConsumerObject {}


class PostConsumer extends CrudConsumer {
    constructor(endpoint='http://example.com/api/v1/posts/', objectClass=Post) {
        super(endpoint, objectClass);
    }
;}


export default PostConsumer;

examples/my-app.js

import PostConsumer from '../data/post.js';


let postConsumer = new PostConsumer();
postConsumer.create()
    .then(someFunction)  // When promise resolves, call someFunction with new Post object
    .catch(errorFunction);  // When promise rejects, call errorFunction

    
//
// When a consumer receives a JSON array as result, an array of consumer objects is returned.
//

    
postConsumer.read()
    .then(someFunction)  // When promise resolves, call someFunction with all resolved Post objects
    .catch(errorFunction);  // When promise rejects, call errorFunction
    
    
let id = 1;
postConsumer.read(id)
    .then(someFunction)  // When promise resolves, call someFunction with resolved Post (with id 1)
    .catch(errorFunction);  // When promise rejects, call errorFunction

examples/my-app2.js

// Internally, id is resolved using either "pk" or "id" field

post.title = 'some new title';
post.update()  // Saves changed fields to API using partial PATCH request
post.save()  // Save all fields to API using full PUT request
post.delete()  // Deletes this post using DELETE request

Pagination

TODO: Document the usage of various List types and pagination. For now please see the tests for examples.

Concepts

ConsumerJS defines a few built-in classes, all of those should preferably be extended by a custom class implementing domain specific behaviour (if any):

• Consumer
• CrudConsumer
• ConsumerObject
• CrudConsumerObject

Consumers (Consumer, CrudConsumer):

"Consumers" are classes that define how to perform operations on the remote API. It converts the results to "Consumer object" which contains a statefull representation of the API result.

A consumer:

• Acts a data store fore fetching remote data.
• Can be used to convert human readable methods into DELETE, GET, PATCH POST and PUT requests.
• All requests return promises.
• Successfull API requests return promises for either an array (list) or a single consumer object (scalar).
• Failed API requests cause the promise to reject.
• Objects are cast to instances of a configurable consumer object class referenced by the consumers "objectClass" key.

Consumers should be preferably be extended, configured and optionally, methods can be overwritten to change default behaviour. Configuration should preferably be done in de constructor method:

/**
 * Configures Consumer instance
 * @param {string} endpoint Base endpoint for this API
 * @param {AbstractConsumerObject} objectClass Class to cast results to
 * @param {Object} [options] Additional configuration
 */
constructor(endpoint='http://example.com/api/v1/posts/', objectClass=Post, options=null) {
    super(endpoint, objectClass);
}

• Consumer: Simple "bare" consumer intended for use with custom methods.
• CrudConsumer: "Consumer with base methods for common CRUD operations.
  • create([object]), creates objecs.
  • read([id]), fetches all objects or a single object by id.

Consumer objects (ConsumerObject, CrudConsumerObject):

"Consumer objects" are classes that define how to perform object specific operations on the remote API. Consumer objects should be extended, configured and optionally methods can be overwritten to change default behaviour.

A consumer object:

• Is the result of a resolved promise, gets passed to the promise's then() method.
• If the API returns an array (list), an array of object classes is returned.
• If the API returns a single object (scalar), a single object is returned.
• The consumer object class can have methods.
• The consumer object class keeps a reference to it's consumer using the "_consumer_" key, this allows methods to talk back to the API.

A reference to the consumer is kept using the __consumer__ property, (custom) methods can use this to communicate with the API.

customMethod(data) {
    return this.__consumer.__.post('/path/', data);  // CrudConsumerObject instances can use this.getPath() as path.
}

• ConsumerObject: Simple "bare" consumer object intended for use with custom methods.
• CrudConsumerObject: "Consumer object with base methods for common CRUD operations.
  • update(), persists changes made to object.
  • save(), fully saves object.
  • delete(), deletes this object.