@contactlab/appy

A functional wrapper around Fetch API.

Install

$ npm install @contactlab/appy fp-ts
# --- or ---
$ yarn add @contactlab/appy fp-ts

Motivation

appy tries to offer a better model for fetching resources, using the standard global fetch() function as a "backbone" and some principles from Functional Programming paradigm.

The model is built around the concepts of:

• a function with some configurable options (Reader)
• that runs asynchronous operations (Task)
• which can fail for some reason (Either)

In order to achieve this, appy intensely uses:

• Typescript >= v3.2.2
• fp-ts

API

appy exposes a simple core API that can be extended with "combinators".

It encodes through the Req<A> type a resource's request, or rather, an async operation that can fail or return a Resp<A>.

For better composability, the request is expressed in terms of ReaderTaskEither - a function that takes a ReqInput as parameter and returns a TaskEither: we can act on both side of operation (input and output) with the tools provided by fp-ts.

interfaceReq<A>extendsReaderTaskEither<ReqInput,Err,Resp<A>>{}

ReqInput encodes the fetch() parameters: a single RequestInfo (simple string or Request object) or a tuple of RequestInfo and RequestInit (the object containing request's options, that it's optional in the original fetch() API).

typeReqInput=RequestInfo|RequestInfoInit;// Just an alias for a tuple of `RequesInfo` and `RequestInit` (namely the `fetch()` parameters)typeRequestInfoInit=[RequestInfo,RequestInit];

Resp<A> is an object that carries the original Response from a fetch() call, the actual retrieved data (of type A) and the request's input (optional).

interfaceResp<A>{response: Response;data: A;input?: RequestInfoInit;}

Err encodes (as tagged union) the two kind of error that can be generated by Req: a RequestError or a ResponseError.

typeErr=RequestError|ResponseError;

RequestError represents a request error. It carries the generated Error and the input of the request (RequestInfoInit tuple).

interfaceRequestError{type: 'RequestError';error: Error;input: RequestInfoInit;}

ResponseError represents a response error. It carries the generated Error, the original Response object and the request's input (optional).

interfaceResponseError{type: 'ResponseError';error: Error;response: Response;input?: RequestInfoInit;}

Examples

import{get}from'@contactlab/appy';import{fold}from'fp-ts/Either';constusers=get('https://reqres.in/api/users');users().then(fold(err=>console.error(err),resp=>console.log(resp.data)));

You can find other examples here.

Combinators

To make easier extending the library functionalities, any other feature should then be expressed as a simple combinator Req<A> => Req<A>.

So, for example, decoding the response body as JSON:

import{get}from'@contactlab/appy';import{withDecoder,Decoder}from'@contactlab/appy/combinators/decoder';import{pipe}from'fp-ts/function';interfaceUser{id: number;email: string;first_name: string;last_name: string;avatar: string;}declareconstuserDec: Decoder<User>;constgetUser=pipe(get,withDecoder(userDec));constsingleUser=getUser('https://reqres.in/api/users/1');

or adding headers to the request:

import{get}from'@contactlab/appy';import{withHeaders}from'@contactlab/appy/combinators/headers';constasJson=pipe(get,withHeaders({'Content-Type': 'application/json'}));constusers=asJson('https://reqres.in/api/users');

or setting request's body (for POSTs or PUTs):

import{post}from'@contactlab/appy';import{withBody}from'@contactlab/appy/combinators/body';import{pipe}from'fp-ts/function';constsend=pipe(post,withBody({email: 'foo.bar@mail.com',first_name: 'Foo',last_name: 'Bar'}));constaddUser=send('https://reqres.in/api/users');

io-ts integration

io-ts is recommended but not automatically installed as dependency.

In order to use it with the Decoder combinator you can write a simple helper like:

import*astfrom'io-ts';import{failure}from'io-ts/PathReporter';import{Decoder,toDecoder}from'@contactlab/appy/combinators/decoder';exportconstfromIots=<A>(d: t.Decoder<unknown,A>): Decoder<A>=>toDecoder(d.decode,e=>newError(failure(e).join('\n')));

Or, with the Decoder module:

import*asDfrom'io-ts/Decoder';import{Decoder,toDecoder}from'@contactlab/appy/combinators/decoder';exportconstfromIots=<A>(d: D.Decoder<unknown,A>): Decoder<A>=>toDecoder(d.decode,e=>newError(D.draw(e)));

About fetch() compatibility

The Fetch API is available only on "modern" browsers: if you need to support legacy browsers (e.g. Internet Explorer 11 or older) or you want to use it in a Nodejs script we recommend you the excellent cross-fetch package.

Be aware that Nodejs lacks of some classes and directives which have to be exposed to the global scope (check out the tests setup file).

Publish a new version

In order to keep the package's file structure as flat as possible, the "usual" npm publish command was disabled (via a prepublishOnly script) in favour of a release script:

$ npm run release

This command will execute npm publish directly in the /dist folder, where the postbuild script previously copied the package.json and other usefull files (LICENSE, CHANGELOG.md, etc...).

License

Released under the Apache 2.0 license.