@contactlab/appy

@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>.

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

interface Req<A> extends RTE.ReaderTaskEither<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).

type ReqInput = RequestInfo | RequestInfoInit;

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

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

interface Resp<A> {
  response: Response;
  data: A;
}

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

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

ResponseError represents a response error. It carriess the generated Error and the original Response object.

type Err = RequestError | ResponseError;

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

interface ResponseError {
  type: 'ResponseError';
  error: Error;
  response: Response;
}

Examples

import {get} from '@contactlab/appy';
import {fold} from 'fp-ts/lib/Either';

const users = 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

In order to make extending the library functionalities easier, any other feature should then be expressed as 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/lib/pipeable';

interface User {
  id: number;
  email: string;
  first_name: string;
  last_name: string;
  avatar: string;
}

declare const userDec: Decoder<User>;

const getUser = pipe(get, withDecoder(userDec));

const singleUser = 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';

const asJson = pipe(get, withHeaders({'Content-Type': 'application/json'}));

const users = 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/lib/pipeable';

const send = pipe(
  post,
  withBody({email: '[e-mail]', first_name: 'Foo', last_name: 'Bar'})
);

const addUser = send('https://reqres.in/api/users');

io-ts integration

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

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

import * as t from 'io-ts';
import {failure} from 'io-ts/lib/PathReporter';
import {Decoder, toDecoder} from '@contactlab/appy/combinators/decoder';

export const fromIots = <A>(d: t.Decoder<unknown, A>): Decoder<A> =>
  toDecoder(d.decode, e => new Error(failure(e).join('\n')));

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.

Contributing

Opening issues is always welcome.

Then, fork the repository or create a new branch, write your code and send a pull request.

This project uses Prettier (automatically applied as pre-commit hook), ESLint (with TypeScript integration) and Jest.

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.