@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` (a.k.a. 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 posts = get('http://jsonplaceholder.typicode.com/posts');

posts().then(
  fold(
    err => console.error(err),
    data => console.log(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 Post {
  id: number;
  userId: number;
  title: string;
  body: string;
}

declare const decoder: Decoder<Post>;

const getPost = pipe(withDecoder(decoder), get);

const singlePost = getPost('http://jsonplaceholder.typicode.com/posts/1');

or adding headers to the request:

import {get} from '@contactlab/appy';
import {withHeaders} from '@contactlab/appy/combinators/headers';

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

const posts = asJson('http://jsonplaceholder.typicode.com/posts');

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(
  withBody({userId: 1234, title: 'My post title', body: 'My post body'}),
  post
);

const addPost = send('http://jsonplaceholder.typicode.com/posts');

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.

License

Released under the Apache 2.0 license.