@sweepbright/margaret-fetcher
v1.6.2
Published
Request classes for fetch
Downloads
144
Readme
Margaret Fetcher
Dead simple request classes for fetch.
Usage
To use it simply create a class that extends JsonRequest
(or AbstractRequest
) and define requests as methods on it.
The AbstractRequest
class comes with a method per HTTP verb (this.get
, this.post
etc.).
import {JsonRequest} from 'margaret-fetcher';
export default class UserRequests extends JsonRequest
{
query = {
include: 'articles',
};
show(user) {
return this.get(`users/${user}`);
}
update(user, attributes) {
return this.put(`users/${user}`, attributes);
}
uploadImage(image) {
const body = new FormData();
body.append('image', image);
return this.make('images', {
method: 'PUT',
body,
});
}
}
To then use those methods simply call the class anywhere:
import UserRequests from './UserRequests';
const user = new UserRequests().show(3);
You can also use the CrudRequest
class which already comes with methods for CRUD endpoints:
import {CrudRequest} from 'margaret-fetcher';
export default class UserRequests extends CrudRequest
{
resource = 'users';
query = {include: 'articles'};
}
const requests = new UserRequests();
requests.show(3);
requests.update(3, {foo: 'bar'});
requests.delete(3);
Advanced usage
Configuring options
You can configure options passed with all requests either as one time thing:
// Merge options with the defaults
UserRequests.withOptions({headers: {Authorization: 'Bearer FOOBAR'}}).show(3)
// Override default options
UserRequests.setOptions({headers: {Authorization: 'Bearer FOOBAR'}}).show(3)
Or through the class itself:
class UserRequests extends CrudRequest {
constructor() {
super();
this.withOptions({
headers: {
Authorization: `Bearer ${access_token}`,
}
});
}
}
You can also pass callables as any option, and it will only get resolved before each request. Useful if you need to pass options that need to be always up to date:
UserRequests.withOptions({
headers: {
Authorization: () => `Bearer ${AuthManager.getToken()}`,
}
})
Configuring query parameters
You can configure query parameters with the same ease through these provided methods:
// Override all query parameters
UserRequests.setQueryParameters({foo: 'bar'});
// Append new query parameters
UserRequests
.withQueryParameter('foo', 'bar')
.withQueryParameter('baz', 'qux');
UserRequests.withQueryParameters({foo: 'bar', baz: 'qux'});
You can also pass arrays to these methods:
UserRequests.withQueryParameter('foo', ['bar', 'baz']); // ?foo[]=bar&foo[]=baz
Configuring middlewares
The promise returned by fetch
will be passed through a list of middlewares
.
By default it will return an object of the data contained in the response. But you can add your own middlewares to perform specific logic.
import {CrudRequest, parseJson, extractData} from 'margaret-fetcher';
class MyRequest extends CrudRequest {
constructor() {
super();
this.setMiddlewares([
parseJson, // Parses a JSON response
::this.extractAuthorizationHeader,
extractData, // Returns the data contained in a Response object
]);
}
extractAuthorizationHeader(response) {
const authorizationHeader = response.headers.get('Authorization');
// Store it somewhere.
return response;
}
}
You can disable all middlewares for a given request using the withoutMiddlewares
method:
const users = new UserRequests()
.withoutMiddlewares()
.show(3);
Extra helpers
The package also comes with some helper methods for common options:
UserRequests.withBearerToken('FOOBAR').show(3)
You can use a function as well, like for other options:
UserRequests.withBearerToken(::AuthManager.getToken).show(3)
Subrequests
Request classes can be nested at will to build more complex paths.
Imagine you have an UserRequests
and an ArticleRequests
, and that an user can have articles, you can do this:
// GET /users/1/articles/2
new UserRequests()
.getSubrequest(new ArticleRequests(), 1)
.show(2);
You can also predefine subrequests through the subrequests
property on a request class:
class UserRequests extends AbstractRequest
{
subrequests = {
articles: new ArticlesRequests(),
};
}
And then retrieve it anytime:
new UserRequests().getSubrequest('articles', 1).update(2, attributes);
Raw fetch requests
Sometimes you just need to bypass everything and do a raw fetch request, you can do that through the fetch
method:
class UserRequests extends AbstractRequest
{
uploadSomething(image) {
const body = new FormData();
body.append('image', image);
return this.fetch('images', {
method: 'PUT',
body,
});
}
}
Testing
$ npm test
$ npm test:watch