restful-fetch

0.6.4 • Public • Published

restful-fetch

NPM License Downloads

A RESTful library based on isomorphic-fetch.

Installation

$ npm i restful-fetch

Quick start

import Restful from 'restful-fetch';

const restful = new Restful();

const Foo = restful.model('foo');
Foo.get().then(data => console.log(data));    // GET /foo

Foo.Single = Foo.model(':id');
Foo.Single.fill({id: 1}).get().then(data => console.log(data));   // GET /foo/1

Foo.Bar = Foo.Single.model('bar');
Foo.Bar.fill({id: 1}).get().then(data => console.log(data));      // GET /foo/1/bar

Documents

Overview

Everything is a model, derives from models and derives models.

restful-fetch

Restful

A Restful instance is the root model, which has a few properties to be shared by all its derivatives. The properties are:

  • prehandlers
  • posthandlers
  • errhandlers

The handlers will be discussed more as interceptors.

Parameters

  • options: (Optional) Object

    • root: (Optional) String

      Base address for all requests, default as ''.

    • headers: (Optional) Object

      Default request headers.

    • config: (Optional) Object

      Extra config to be passed to fetch.

    • methods: (Optional) Object

      Custom methods to be bound to models. The object are composed of methodName: methodInfo pairs. methodInfo may have following properties:

      • method

        The HTTP method to be used for requests, default as GET.

      • args

        The argument name list. Names may be url, params, body and headers.

    const restful = new Restful({
      root: '/api',
      headers: {
        'X-From': 'restful-fetch',
      },
      methods: {
        foo: {
          method: 'GET',
          args: ['url', 'params']
        }
      }
    });
    
    // restful.foo(url, params)

Methods

An Restful instance has all methods that a derived model has, except for fill, which should only work in abstract models.

const restful = new Restful(options);
// or
const restful = Restful(options);

Model

A Model instance is an object derived from a Restful instance or another model.

A model instance has following properties:

  • prehandlers
  • posthandlers
  • overrides

The handlers will be discussed more as interceptors.

Methods

  • model(...args: []String)

    Derive a submodel.

    A model is always generated by instance.model(...args). Each argument is a part of URL and will be joined with / as the submodel's relative path.

    If a part of URL starts with :, it will be marked as a placeholder. Models with placeholders are abstract models, and can not make requests directly. Abstract models have to be filled with data to get non-abstract models before making requests. This is designed to share properties between different model instances.

  • fill(data: Object)

    Derive a new Model instance with placeholders filled with data. data is an object with keys as the placeholder names and values to be filled with.

  • request(options: Object)

    A low-level request method called by get, post, put, etc. options may have following properties:

    • url: String, default as ''
    • method: String, default as GET
    • headers: Object, default as null
    • params: Object, default as null
    • body: Any, default as null
  • post(url: String, data: Any, params: (Optional) Object)

    POST request.

  • get(url: String, params: (Optional) Object)

    GET request.

  • put(url: String, data: Any, params: (Optional) Object)

    PUT request.

  • patch(url: String, data: Any, params: (Optional) Object)

    PATCH request.

  • delete(url: String, params: (Optional) Object)

    DELETE request.

const Cars = restful.model('cars');

const AbstractCar = restful.model('cars', ':id');
// or
const AbstractCar = Cars.model(':id');

AbstractCar.prehandlers.push(function () {
  console.log('Get a car!');
});

const car1 = AbstractCar.fill({id: 1});
const car2 = AbstractCar.fill({id: 2});

const seats = car1.model('seats');
seats.get().then(data => console.log(data));

Interceptors

Restful and Model instances have a several handler properties, which contains lists of interceptors. Those on Restful instances are global interceptors and those on Model instances are model specific interceptors.

  • prehandlers (present on Restful and Model)

    Process order: Model::prehandlers -> Restful::prehandlers.

    Each prehandler is called with one parameter: the request options. Returned value will be merged into it, so only the changed attributes need to be returned.

  • posthandlers (present on Restful and Model)

    Process order: Restful::posthandlers -> Model::posthandlers.

    Each posthandler is called with two parameters: data, options. data is the current data object and can be modified by returning a new one. options contains all information of the request, including method, url (full url), relative (url relative to current model).

    There are two default posthandlers on a Restful object so that you may either resolve the response data or reject an object with the response object and its data:

    • response => ({response, data})
    • ({response, data}) => response.ok ? data : reject({response, data})
  • errhandlers (present on Restful)

    Each errhandler is called with the error captured. The last errhandler should throw the error to make a rejection to the promise.

  • overrides (present on Model)

    Overrides global handlers on Restful object for current model.

const restful = new Restful();
const model = restful.model('/cars/1');

// Global interceptors will be processed for all requests
restful.prehandlers.push(options => {
  return {
    params: Object.assign({}, options.params, {hello: 'world'}),
  };
});
restful.posthandlers.push(res => {
  console.log('Intercepted:', res);
  return res;
});

// Model interceptors will be processed only for the model itself
// Model prehandlers will execute BEFORE global prehandlers
model.prehandlers.push(options => {
  return {
    headers: {
      'X-From-Model': true,
    },
  };
});
// Model posthandlers will be processed AFTER global posthandlers
model.posthandlers.push(data => {
  return data || 'empty';
});

model.overrides = {
  posthandlers: [],   // disable global posthandlers
};

Readme

Keywords

Package Sidebar

Install

npm i restful-fetch

Weekly Downloads

1

Version

0.6.4

License

MIT

Last publish

Collaborators

  • gera2ld