HTTP Client in JavaScript using Fetch API
- to avoid hard-coding urls when doing ajax.
- to assert the structure of the request parameter object.
- to assert the structure of the response JSON.
npm i --save alize
- whatwg-fetch
- to use Fetch API in browser environment (you can use another polyfill)
const alize = require('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
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|
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.
name | type | description | required |
---|---|---|---|
url | string | Url path. If the url has dynamic values, then use colon. e.g. /foo/:id/bar | true |
method | string | The same parameter as the fetch API's method. e.g. get, post, delete, put... | or template |
template | string | Template method. You can generate multiple methods with this | or method |
only | Array(string) | When you use template, alize generates methods which is only specified here | false |
path | string | access path to the generated method | false |
headers | object | The same parameter as the fetch API's headers. e.g. { 'Content-Type': 'application/json' } | false |
credentials | string | The same parameter as the fetch API's credentials. e.g. 'same-origin' | false |
assert | object | Used to validate post parameters and the returned JSON | false |
process | object | Used to process parameter object before fetching or the returned JSON after fetching | false |
logMode | string | Specify log level. the default value is 'silent' e.g. 'error', 'warn', 'info', 'log', 'debug' | false |
The access path to the method is determined as below.
- If the path is specified, then the value is that.
- e.g. 'foo.bar'
- If the path is /, then the access path will be 'root'
- 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
Alize has two default template
methods.
Generates methods below. This crresponds to the Rails' resources.
method | WebAPI | url |
---|---|---|
index | GET | {path} |
show | GET | {path}/:id |
create | POST | {path} |
edit | GET | {path}/:id/edit |
update | PUT | {path}/:id |
destroy | DELETE | {path}/:id |
Generates methods below.
method | WebAPI | url |
---|---|---|
get | GET | {path} |
put | PUT | {path} |
post | PUT | {path} |
patch | PUT | {path} |
delete | PUT | {path} |
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
You can validate the parameters before fetching, and also the returned JSON (when content-type is 'application/json') after fetching.
name | type | description |
---|---|---|
pre | object | Used to validate the parameters before fetching |
post | object | Used to validate the returned JSON |
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.
},
},
},
},
};
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 } }],
});
You can convert parameters or returned JSON before or after fetching.
name | type | description |
---|---|---|
pre | function | Used to process the parameters before fetching |
post | function | Used to process the returned JSON |
const process = {
pre(param) {
return param;
},
post(json) {
return json;
},
};
const alizeBuilder = alize.setup({
urls: [{ url: '/foo', method: 'get', option: { process } }],
});
Please refer to the configuration details.
const alizeBuilder = alize.setup();
let alizeClient = alizeBuilder.getClient();
// This is the same as above.
alizeClient = alize.build();
const alizeBuilder = alize.setup();
const alizeClient = alizeBuilder.getClient();
const alizeBuilder = alize.setup();
alizeBuilder.add({ url: '/foo', method: 'get' })
.add({ url: 'bar', method: 'post' });
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 has the generated metods.
receives post parameter and fetch remote data.
name | type | description |
---|---|---|
urlParam | object | When the url has parameters, then the value is specified here |
data | object | The same parameter as the fetch API's data |
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.
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' });