alize v0.0.5

Alize.js

HTTP Client in JavaScript using Fetch API

Why Alize.js?

1. to avoid hard-coding urls when doing ajax.
2. to assert the structure of the request parameter object.
3. to assert the structure of the response JSON.

Requirements

• whatwg-fetch
  • to use Fetch API in browser environment (you can use another polyfill)

Examples

import alize from 'alize';

const alizeBuilder = alize.setup({
  urls: [
    {
      url: '/foo',
      method: 'get',
    },
    {
      url: '/foo/:id',
      method: 'post',
      assert: {
        pre: {
          {
            x: {
              require: true,
            },
          },
        },
        post: {
          {
            message: {
              require: true,
            },
          },
        },
      },
    },
    {
      url: '/bar',
      template: 'resources',
      only: ['show', 'new', 'destroy'],
    },
  ],
  option: {
    logMode: 'error',
    headers: {
      'Content-Type': 'application/json',
    },
  },
});

const client = alizeBuilder.getClient();

client.foo.get(); // GET /foo
client.foo.post({ urlParam: { id: 1 }, data: { x: 'x' } }); // POST /foo/:id
client.bar.destroy({ urlParam: { id: 1 } }); // DELETE /bar/:id

This example generate a object (Alize object), which has methods to fetch remote data, and validate the parameter object and the returned JSON.

You can also add such a method after initializing.

const alizeBuilder = alize.setup();

// You can now access .foo.get
alizeBuilder.add({ url: '/foo', method: 'get' });

const client = alizeBuilder.getClient();
client.foo.get(); // GET /foo

Configuration

Alize's setup method receives an object which has properties below.

|name|type|description| |urls|Array(object)|Used to initialize UrlConfig object| |template|object|Used to generate template functions| |option|object|Set common options. You can set such values as the log level, headers, and so on|

UrlConfig

Alize generates methods as specified in a UrlConfig object. You can initialize a UrlConfig object through alize.setup method or Alize.add method.

For example,

const param = {
  urls: [
    { url: '/foo', method: 'get' }, // This is used to initialize UrlConfig object.
  ],
};
const alizeBuilder = alize.setup(param);

// alize.setup returns Alize object. You can call add method to generate another method.
alizeBuilder.add({ url: '/foo:id', method: 'delete' });

The UrlConfig constructor receives such a object as specified below.

Property

Path

The access path to the method is determined as below.

1. If the path is specified, then the value is that.

• e.g. 'foo.bar'

1. If the path is /, then the access path will be 'root'
2. Thrashes in the path is replaced by dots, and the dynamic parameters and superfluous dots are removed

• e.g. '/foo/:id/bar' -> 'foo.bar'

const alizeBuilder = alize.setup();
alizeBuilder
  .add({ url: 'foo', method: 'get' })
  .add({ url: 'foo/:id/bar', template: 'resources', only: ['index'] });

const client = alizeBuilder.getClient();
client.foo.get(); // When the method is specified, method name will be the value
clinet.foo.bar.index(); // When the template is specified, methods' name will be the template methods' name

Template

Alize has two default template methods.

resources

Generates methods below. This crresponds to the Rails' resources.

rest

Generates methods below.

Example

const alizeBuilder = alize.setup({
  urls: [{ url: 'foo', template: 'resources' }],
});

const client = alizeBuilder.getClient();
client.foo.index(); // GET /foo

// You can call a template method directly.
alizeBuilder.resources('/bar');
client.bar.show({ urlParam: { id: 1 } }); // GET /bar/1

You can also add your original template methods.

const alizeBuilder = alize.setup({
  template: {
    original: function (baseUrl) { // receives url path string
      'methodName': {
        url: `${baseUrl}/:id`,
        method: 'get',
      },
    },
  },
});

// Now you can use 'original' template.
alizeBuilder.original('/foo');

const client = alizeBuilder.getClient();
client.foo.methodName({ urlParam: { id: 1 } }); // GET /foo/1

Assert

You can validate the parameters before fetching, and also the returned JSON (when content-type is 'application/json') after fetching.

Assert Property

pre and post's object has such a structure as

const pre = {
  [property]: {
    type: [type value], // this is the returned value of typeof operator.
    checks: {
      'enum': { // Specified when the value is limited.
        array: [array of values],
      },
      'require': { // If always required, then you can also set true.
        when: {
          present: [Array of property names],
          // When some of the specified properties are present in the object, then the object must have the property.
          absent: [Array of property names]
          // When some the specified properties are not present in the object, then the object must have the property.
        },
      },
      'forbid': {
        when: {
          present: [Array of property names],
          // When some of the specified properties are present in the object, then the object mustn't have the property.
          absent: [Array of property names]
          // When some the specified properties are not present in the object, then the object mustn't have the property.
        },
      },
    },
  },
};

Examples

const assert = {
  pre: {
    x: {
      type: 'string',  // x's type is string,
      checks: {
        require: true, // and post parameter must include 'x'.
      },
    },
    y: {
      type: 'number',
      checkes: {
        require: {
          when: {
            absent: ['z'], // y is required when the parameter doesn't have the property 'z',
          },
        },
        forbid: {
          when: {
            present: ['z'], // and y is forbidden when the parameter has the property 'z'.
          },
        },
      },
    },
  },
};

const alizeBuilder = alize.setup({
  urls: [{ url: '/foo', method: 'get', option: { assert } }],
});

Process

You can convert parameters or returned JSON before or after fetching.

Property

Examples

const process = {
  pre(param) {
    return param;
  },
  post(json) {
    return json;
  },
};

const alizeBuilder = alize.setup({
  urls: [{ url: '/foo', method: 'get', option: { process } }],
});

API

setup (object) => Alize

Please refer to the configuration details.

build (object) => AlizeClient

const alizeBuilder = alize.setup();
let alizeClient = alizeBuilder.getClient();

// This is the same as above.
alizeClient = alize.build();

Alize

getClient (void) => AlizeClient

const alizeBuilder = alize.setup();
const alizeClient = alizeBuilder.getClient();

add (object) => Alize(this)

const alizeBuilder = alize.setup();
alizeBuilder.add({ url: '/foo', method: 'get' })
  .add({ url: 'bar', method: 'post' });

template method (string, object) => Alize(this)

receives url path string and fetch option object, then generate methods to fetch.

const alizeBuilder = alize.setup();
alizeBuilder
  .resources('bar')
  .get('foo', {
    headers: {
      'Content-Type': 'text/html'
    },
    credentials: 'same-origin',
    process: {
      post(json) {
        return json.message;
      },
    },
  });

const alizeClient = alizeBuilder.getClient();
alizeClient.bar.show({ urlParam: { id : 1 }); // GET /bar/:id
alizeClient.foo.get(); // GET /foo

The default template methods are below. Please also refer to the template details

• resources
• rest
• get
• post
• delete
• put
• patch
• head
• options

AlizeClient

AlizeClient has the generated metods.

Generated method

receives post parameter and fetch remote data.

Parameter Property

const client = alize.build({ urls: [{ url: 'foo/:id', method: 'get' }] });
client.foo.get({ urlParam: { id: 1 }, data: { x: 2 } }); // GET /foo/1?x=2

You can't set other fetch options here. If you'd like to set options dynamically, then use the next Fetch API wrapper method.

Fetch API wrapper

AlizeClient has the methods which wrap fetch API, other than the generated methods. You can fetch data with calling such methods as get, post, and so on.

const client = alize.setup().getClient();

// GET /foo?id=1
client.get('/foo', { id: 1 }, { 'Content-Type': 'application/json' });