Coolio is an environment-agnostic networking client for Node.js, React Native & browser web apps. The aim of Coolio is to abstract out the technical stuff and let developers query APIs in DRY manner. Usually such approach makes simple things easier while making complex use-cases impossible. Coolio gives users more control over networking, allowing to customize almost every step of it's networking pipeline:

• sending and handling requests,

• body normalization,

• pre and postprocessing.

This is achieved by using interceptors concept and providing pluggable interfaces whenever possible.

Packages

Coolio is broken down into several packages, allowing you to pick what's really needed.

Contributing

Most important yarn scripts during development:

• start - runs builds for all packages in watch mode

• verify - runs lint & tests

What is an Interceptor

Quite often we need to do something "in-between" while our API requests are running. This is why we have a built-in interceptors mechanism. Interceptors allow us to :

• perform actions before request happens,

• perform actions after request happens,

• retry the request multiple times,

• even totally ignore the request and serve content in a different way (i.e. serve content from in-memory cache).

Common use-cases for interceptors:

• throw errors if response status code indicates that request failed,

• automagically retry request up to X times if it failed,

• transparently reauthorize if your access token has been revoked

The concept of interceptors should sound familiar to you if you ever used Angular or OkHttp.

One can add interceptor to HttpClient using addInterceptor method. addInterceptor can be chained and it mutates the httpClient, so you can define a client as below.

import { httpClient } 

const httpClient = new HttpClient({ ... })
  .addInterceptor(createErrorInterceptor())
  .addInterceptor(createLoggingInterceptor());

Built-in interceptors

coolio offers some basic interceptors, which you probably want to add right away.

Creating your own interceptor

coolio supports two ways of creating interceptors. One is a function-based approach and second is a class-based approach. Both ways are correct, just use what fits your use-case best.

Interceptors accept two arguments:

• request: HttpFetch - a function that returns a Promise that performs http request. It allows to queue or delay multiple requests, retry them etc.

• options: NormalizedHttpOptions - options that can be modified before request is made, i.e. you can add Authorization header in your authInterceptor.

See the example of error interceptor created as a function:

const interceptor: HttpInterceptorFunction = (request, options) => {
  return async () => {
    const response = await request();
    if (response.status >= 400) {
      throw new HttpResponseError(response);
    }
    return response;
  };
};

Interceptor has to return async function that returns response. In other words, it can either:

• just return request, which is passed as a first argument to interceptor

• create an async function, which performs some operations and then returns response

In the above case, we create such function manually and check the response status code, throwing an error when something goes wrong.

If we'd like to create an interceptor as a class, it would look like that:

export class ErrorInterceptor implements HttpInterceptorInterface { 
  onIntercept(request, options) {
    return async () => {
      const response = await request();
      if (response.status >= 400) {
        throw new HttpResponseError(response);
      }
      return response;
    };
  }
}

By exploiting the fact, that we return a function in our interceptor, we can implement retry mechanism, embed a queue and more. You can see some examples in coolio's auth-interceptor source code.

Coolio is an environment-agnostic networking client for Node.js, React Native & browser web apps. The aim of Coolio is to abstract out the technical stuff and let developers query APIs in DRY manner. Usually such approach makes simple things easier while making complex use-cases impossible. Coolio gives users more control over networking, allowing to customize almost every step of it's networking pipeline:

• sending and handling requests,

• body normalization,

• pre and postprocessing.

This is achieved by using interceptors concept and providing pluggable interfaces whenever possible.

Packages

Coolio is broken down into several packages, allowing you to pick what's really needed.

Contributing

Most important yarn scripts during development:

• start - runs builds for all packages in watch mode

• verify - runs lint & tests

Coolio's HTTP Package

@coolio/http is a simple, yet extendable HTTP client for web apps. It features:

• body parsing and serialization, with case-conversion support

  • raw data (ArrayBuffer)

  • JSON

  • URL-encoded

  • plain text

  • multipart ()

• extensibility via , with built-ins such as:

  • logger

  • error handler

  • redirection interceptor

• configurable requestHandler layer, which let's you choose the underlaying mechanism used for HTTP communication

Quick start

Installation

Install @coolio/http package using npm or yarn.

Creating a client

You may create multiple HttpClient instances, as your application connects to various APIs and each API probably has slightly different conventions. You can initialize a HttpClient and configure it as below:

In the example above, we create HttpClient instance which will route all paths to api.example.com/v1 address:

• if you request /users, the request will go to api.example.com/v1/users

• if you request https://google.com, the request will go to google.com, as you specified full URL and baseUrl is not applied in such case.

Requests

Repositories

You may use the repository pattern to separate API requests from other code. You can use previously defined HttpClient as below:

After doing the following, you can simply call UserRepository.getProfile() to receive the Promise returning User object.

Another way of dealing with repositories is to use class-based approach:

Advanced Use Cases

If you happen to use JSON API, you may benefit from using a wrapper library that handles most of it's specs:

Change Log

All notable changes to this project will be documented in this file. See for commit guidelines.

(2020-03-03)

Bug Fixes

• case-conversion: incorrect name formats are handled gracefully ()

• headers: preserve header casing ()

Features

• case-conversion: screaming snake case support ()

(2020-02-26)

Bug Fixes

• headers: explicitly passed nil value removes existing header ()

(2020-02-25)

Bug Fixes

Bug Fixes

BREAKING CHANGES

• headers: removed deprecated headers options

Bug Fixes

Features

Note: Version bump only for package coolio

Note: Version bump only for package coolio

Features

Note: Version bump only for package coolio

Features

Bug Fixes

Bug Fixes

Bug Fixes

Bug Fixes

Features

BREAKING CHANGES

• url-encoding: url string has now bigger priority than query passed in object, which results in better composability (parameters from url are always merged into object)

Bug Fixes

Features

Bug Fixes

Bug Fixes

Bug Fixes

Features

Features

Bug Fixes

Note: Version bump only for package coolio

Bug Fixes

Bug Fixes

Bug Fixes

Note: Version bump only for package coolio

Bug Fixes

Bug Fixes

Bug Fixes

Bug Fixes

Bug Fixes

0.1.0 (2019-03-30)

Create readable "multipart/form-data" streams. Can be used to submit forms and file uploads to other web applications.

Hierarchy

• CFormData

Index

Constructors

Properties

Methods

Constructors

constructor

Parameters:

Properties

Static DEFAULT_CONTENT_TYPE

▪ DEFAULT_CONTENT_TYPE: string = "application/octet-stream"

Static LINE_BREAK

▪ LINE_BREAK: string = " "

Methods

append

Parameters:

Returns: void

delete

▸ delete(name: string): void

Parameters:

Returns: void

forEach

▸ forEach(callbackfn: function): void

Parameters:

▪ callbackfn: function

Parameters:

Returns: void

get

Parameters:

getAll

Parameters:

getBoundary

▸ getBoundary(): string

Returns: string

getBuffer

▸ getBuffer(): Promise‹Buffer›

Returns: Promise‹Buffer›

getHeaders

▸ getHeaders(): object

Returns: object

• content-type: string = 'multipart/form-data; boundary=' + this.getBoundary()

has

▸ has(name: string): boolean

Parameters:

Returns: boolean

pipe

▸ pipe(writable: Writable): void

Parameters:

Returns: void

set

Parameters:

Returns: void

toString

▸ toString(): string

Returns: string

Static from

Parameters:

▪ data: any

▪Default value __namedParameters: object= {}

Static isFormData

▸ isFormData(data: any): data is FormData | CFormData

Parameters:

Returns: data is FormData | CFormData

Type parameters

▪ T

Hierarchy

• ↳ HttpRequestError

Index

Constructors

Properties

Constructors

constructor

Parameters:

Properties

message

• message: string

name

• name: string

options

Optional stack

• stack? : undefined | string

Static Error

▪ Error: ErrorConstructor

Base class in Coolio http package, which allows to perform API calls.

Type parameters

▪ T

Common body shape defined by bodyParser passed in .

Hierarchy

• HttpClient

Index

Constructors

Methods

Constructors

constructor

Parameters:

Methods

addInterceptor

Adds an interceptor to the client. Interceptor can be written either as class or as a function, which may mutate request options and post-process response from server. Multiple interceptors can be added to a single HttpClient. They can perform as:

• cache

• error handler

• authorizer

• logger

• auto-retry

• redirection handler

Parameters:

Returns: this

delete

Performs a DELETE request.

Type parameters:

▪ Body: T

Parameters:

get

Performs a GET request.

Type parameters:

▪ Body: T

Parameters:

patch

Performs a PATCH request.

Type parameters:

▪ Body: T

Parameters:

post

Performs a POST request.

Type parameters:

▪ Body: T

Parameters:

put

Performs a PUT request.

Type parameters:

▪ Body: T

Parameters:

remove

Performs a DELETE request.

deprecated Use delete instead of remove, since it matches HTTP request method.

Type parameters:

▪ Body: T

Parameters:

request

Type parameters:

▪ Body: T

Parameters:

Auth Interceptor

Auth interceptor can be plugged in to a HttpClient to ensure passing proper authorization data to all requests and automatically refresh the tokens when they expire. You can configure whether authorization is done by body, header or query param, you can define your own refresh mechanism or use some ready-made, commonly used options.

Quick Start

Add the Auth Interceptor package, assuming that you already have @coolio/http installed:

npm install @coolio/auth-interceptor

Declare httpClient as described in @coolio/http's README.md and then use createAuthInterceptor, passing all parameters required by options object. authInterceptor itself may also make it's own calls (via reauthorize function), so you may need to create another HttpClient, which won't interfere with your basic HttpClient's interceptors. See the Usage section for complete example.

Usage

import {
  BodyCasing,
  bodyParser,
  bodySerializer,
  fetchRequestHandler,
  getHostname,
  HttpClient,
  NormalizedHttpOptions
} from '@coolio/http';
import { createAuthInterceptor } from '@coolio/auth-interceptor';

/**
 * This client is only used for authorization purposes - it doesn't have any interceptors.
 */
const authorizationClient = new HttpClient({
  requestHandler: fetchRequestHandler(),
  responseParser: bodyParser({ bodyCasing: BodyCasing.CAMEL_CASE }),
  bodySerializer: bodySerializer({ bodyCasing: BodyCasing.SNAKE_CASE }),
  baseUrl: 'https://my-domain.org/'
});

const authInterceptor = createAuthInterceptor({
  reauthorize: async () => {
    const response = await authorizationClient.post('/oauth/token', {
      body: {
        clientId: 'client_id',
        refreshToken: 'refresh_token_from_store',
        grantType: 'refresh_token',
      },
    });
    const { accessToken, refreshToken, tokenType, expires } = await response.parsedBody();

    // Store received tokens somewhere (let's say... local storage?)
    // Note: it's not 100% safe to store tokens that way
    localStorage.setItem('secrets', JSON.stringify({
      accessToken, refreshToken, tokenType, expires,
    }));
  },
  setAuthorizationData: (options: NormalizedHttpOptions) => {
    // Get previously stored tokens
    const { accessToken, tokenType } = JSON.parse(localStorage.getItem('secrets') || '{}');
    if (!options.headers) {
      options.headers = {};
    }
    options.headers['Authorization'] = tokenType ? `${tokenType} ${accessToken}` : accessToken;
  },
  onAuthorizationFailure: (error: Error) => {
    console.log(error.message);
    // You may clear the app state here and redirect user to login page
    throw error;
  },
  canAuthorize: (options: NormalizedHttpOptions) => getHostname(options.url) === 'my-domain.org',
});

export const httpClient = new HttpClient({
  requestHandler: fetchRequestHandler(),
  responseParser: bodyParser({ bodyCasing: BodyCasing.CAMEL_CASE }),
  bodySerializer: bodySerializer({ bodyCasing: BodyCasing.SNAKE_CASE }),
  baseUrl: 'https://my-domain.org/'
})
  .addInterceptor(authInterceptor);

Now each request directed to my-domain.org has a proper Authorization header. In case of 401 response, all requests are paused and token refresh happens. When token is fresh, all requests are resumed. The whole process is transparent and doesn't affect calls.

OAuth2 Usage

If you're using OAuth2 authentication mechanisms, you can use an interceptor pre-made specifically for that case. See an example below:

import {
  BodyCasing,
  bodyParser,
  bodySerializer,
  ContentType,
  fetchRequestHandler,
  getHostname,
  HttpClient,
  NormalizedHttpOptions,
} from '@coolio/http';
import { createOAuth2Interceptor } from '@coolio/auth-interceptor';

const authInterceptor = createOAuth2Interceptor({
  httpClientOptions: {
    // You can override default client options used for making refresh token requests
  },
  clientId: 'client-id',
  clientSecret: 'client-secret',
  contentType: ContentType.JSON, // URL-encoded by default
  getAuthorizationData: () => JSON.parse(localStorage.getItem('auth')),
  setAuthorizationData: (data) => localStorage.setItem('auth', JSON.stringify(data)),
  canAuthorize: (options: NormalizedHttpOptions) => getHostname(options.url) === 'my-domain.org',
  refreshTokenUrl: 'https://my-domain.org/auth/token',
  onAuthorizationFailure: (error: Error) => {
    console.log(error.message);
    // You may clear the app state here and redirect user to login page
    throw error;
  },
});

export const httpClient = new HttpClient({
  requestHandler: fetchRequestHandler(),
  responseParser: bodyParser({ bodyCasing: BodyCasing.CAMEL_CASE }),
  bodySerializer: bodySerializer({ bodyCasing: BodyCasing.SNAKE_CASE }),
  baseUrl: 'https://my-domain.org/'
})
  .addInterceptor(authInterceptor);

JSON API

JSON API Client Wrapper

Quick Start

Add the JSON API package, assuming that you already have @coolio/http installed:

npm install @coolio/json-api

Declare httpClient as described in @coolio/http's README.md and then build JSON API Client:

import { HttpClient } from '@coolio/http';
import { JsonApiClient } from '@coolio/json-api';

const httpClient = new HttpClient(/* ... */);
export const jsonApiClient = new JsonApiClient(httpClient);

Make sure that httpClient uses standard bodyParser or a parser that returns complete body of server's response (an object including at least data property).

Usage

An instance of JsonApiClient exposes a collection of get(), getList(), post(), remove(), put() and patch() methods. Each method returns a request builder. For example:

import { Data, FilterOperator, MergedData, ResolvedRelationship, RelationshipArray } from '@coolio/json-api';
import { Config } from './config';
import { jsonApiClient } from './apiClient';

// First, define Attributes and Relationships for your API models
export interface AddressAttributes {
  street: string;
  buildingNumber: string;
  city: string;
  zipCode: string;
  state?: string;
  country: string;
}

export type AddressData = Data<AddressAttributes>;

export interface UserAttributes {
  name: string;
  surname: string;
  email: string;
}

export interface UserRelationships {
  address: ResolvedRelationship<AddressData>; // This relationship will be merged as a field into User.
  devices: RelationshipArray; // The result is only an array of identifiers
}

// JSON API-compatible type:
export type UserData = Data<UserAttributes, UserRelationships>;
// Parsed type, for easier use in your code:
export type User = MergedData<UserData>;

// The above `User` type is equal to such structure:
interface UserDefinedManually {
  id: string;  // Identifier from JSON API
  type: string; // Type from JSON API
  self: string; // Self field from JSON API
  name: string;
  surname: string;
  email: string;
  address: {
    id: string; // Identifier from JSON API
    type: string; // Type from JSON API
    self: string; // Self field from JSON API
    street: string;
    buildingNumber: string;
    city: string;
    zipCode: string;
    state?: string;
    country: string;
  }
  devices: string[]; // Array of identifiers extracted from JSON API's relationships
}

const getUsers = jsonApiClient.getList<UserAttributes>(`${Config.API_BASE_URL}/users`)
  .filter('name', 'John', FilterOperator.LIKE)
  // Pagination can be done by passing offset and limit
  .pageOffset(30)
  .pageLimit(10)
  // Pagination can be also done by passing page number
  .pageNumber(3)
  // Merges the data in "included" response property into values in "data"
  .resolveIncluded()
  .send({
    // other http options that can be passed to a standard httpClient method
  });

export const UsersRepository = {
  getUsers,
}

UsersRepository.getUsers() method presented above returns a Promise<JsonListResponse<UserAttributes, UserRelationships>>. @coolio/json-api merges attributes and relationships automatically.

import { UsersRepository } from './users.repository';

UsersRepository.getUsers().then(response => {
  response.elements(); // User[]
});

Index

Enumerations

• BodyCasing

• ContentType

• HttpCode

• HttpMethod

• ParsedBodyCacheState

Classes

• CFormData

• HttpClient

• HttpRequestError

• HttpResponseError

• HttpResponseHeaders

Interfaces

• BodyParserOptions

• BodySerializerOptions

• CFormDataEntryMetadata

• CFormDataEntryValue

• Endpoint

• FetchRequestHandlerOptions

• FormDataFromOptions

• HttpClientConfig

• HttpInterceptorInterface

• HttpRequestHandlerOptions

• HttpRequestOptions

• HttpResponse

• HttpResponseOptions

• Log

• LoggingInterceptorOptions

• MockOptions

• NormalizedHttpOptions

• RawHttpResponse

• RedirectionInterceptorOptions

• SimpleServer

• XhrRequestHandlerOptions

Type aliases

• BodyParser

• BodyParserImplementation

• BodySerializer

• BufferEncoding

• CFormDataValue

• CaseConverter

• ContentTypeMap

• HttpBody

• HttpFetch

• HttpHeaders

• HttpInterceptor

• HttpInterceptorFunction

• HttpOptions

• HttpRequestHandler

• MockHttpRequestHandler

• NormalizedHttpBody

• PromiseFunction

• RequestMode

Variables

• DEFAULT_REQUEST_TIMEOUT_MS

• DONE

• HEADERS_RECEIVED

• SUPPORTS_BROWSER_FORM_DATA

• TypedArray

• symbol

Functions

• bodyParser

• bodySerializer

• cacheParsedBody

• createAsyncBodyHandler

• createErrorInterceptor

• createHttpResponse

• createLoggingInterceptor

• createRedirectionInterceptor

• createSimpleServer

• deepKeyMap

• defaultHeaders

• encodeArrayBuffer

• encodeText

• fetchRequestHandler

• getBoundaryFromContentTypeHeader

• getCaseConverter

• getEncodingFromHeaders

• getFileMeta

• getHeader

• getHostname

• handleRequest

• httpRequestHandler

• isBlob

• isBrowserFormData

• isHttpInterceptorInterface

• isHttpRequestError

• isHttpResponseError

• mockRequestHandler

• noConversion

• parseHeaders

• processMultipartBody

• readBlob

• sanitizeHeaders

• sleep

• splitWords

• switchContentType

• toCamelCase

• toKebabCase

• toPascalCase

• toScreamingSnakeCase

• toSnakeCase

• toUrlEncoded

• urlCombine

• urlDecode

• urlDestruct

• urlEncode

• useInterceptor

• xhrRequestHandler

Object literals

• ContentTypeRegex

• HttpClientHelper

• HttpStatusText

• Interceptors

Type aliases

BodyParser

Ƭ BodyParser: function

Type declaration:

▸ (response: RawHttpResponse): HttpResponse‹T›

Parameters:

BodyParserImplementation

Ƭ BodyParserImplementation: function

Type declaration:

▸ (rawResponse: RawHttpResponse): Promise‹any›

Parameters:

BodySerializer

Ƭ BodySerializer: function

Type declaration:

▸ (request: HttpOptions): NormalizedHttpBody

Parameters:

BufferEncoding

Ƭ BufferEncoding: "ascii" | "utf8" | "utf-8" | "utf16le" | "ucs2" | "ucs-2" | "base64" | "latin1" | "binary" | "hex"

CFormDataValue

Ƭ CFormDataValue: string | Blob | Readable

CaseConverter

Ƭ CaseConverter: function

Type declaration:

▸ (object: any): any

Parameters:

ContentTypeMap

Ƭ ContentTypeMap: Record‹keyof typeof ContentTypeRegex, T›

HttpBody

Ƭ HttpBody: object | TypedArray | string

HttpFetch

Ƭ HttpFetch: function

Type declaration:

▸ (): Promise‹HttpResponse‹Body››

HttpHeaders

Ƭ HttpHeaders: Record‹string, string | number | boolean | undefined | null›

HttpInterceptor

Ƭ HttpInterceptor: HttpInterceptorFunction | HttpInterceptorInterface

HttpInterceptorFunction

Ƭ HttpInterceptorFunction: function

Type declaration:

▸ <Body>(request: HttpFetch‹Body›, options: NormalizedHttpOptions): HttpFetch‹Body›

Type parameters:

▪ Body

Parameters:

HttpOptions

Ƭ HttpOptions: Partial‹HttpRequestOptions›

HttpRequestHandler

Ƭ HttpRequestHandler: function

Type declaration:

▸ (requestOptions: NormalizedHttpOptions): Promise‹RawHttpResponse›

Parameters:

MockHttpRequestHandler

Ƭ MockHttpRequestHandler: HttpRequestHandler & object

NormalizedHttpBody

Ƭ NormalizedHttpBody: FormData | CFormData | TypedArray | string | undefined

PromiseFunction

Ƭ PromiseFunction: function

Type declaration:

▸ (): Promise‹T›

RequestMode

Ƭ RequestMode: "navigate" | "same-origin" | "no-cors" | "cors"

Variables

Const DEFAULT_REQUEST_TIMEOUT_MS

• DEFAULT_REQUEST_TIMEOUT_MS: number = 5 * 60 * 1000

Default request timeout - 5 minutes.

Const DONE

• DONE: 4 = 4

Const HEADERS_RECEIVED

• HEADERS_RECEIVED: 2 = 2

Const SUPPORTS_BROWSER_FORM_DATA

• SUPPORTS_BROWSER_FORM_DATA: boolean = (() => { try { return !({} instanceof FormData); } catch { return false; } })()

TypedArray

• TypedArray: any

Const symbol

• symbol: unique symbol = Symbol('HttpResponseError')

Functions

Const bodyParser

▸ bodyParser(__namedParameters: object): BodyParser‹any›

Parameters:

▪Default value __namedParameters: object= {}

Returns: BodyParser‹any›

Const bodySerializer

▸ bodySerializer(__namedParameters: object): BodySerializer

Parameters:

▪Default value __namedParameters: object= {}

Returns: BodySerializer

Const cacheParsedBody

▸ cacheParsedBody<T>(parsedBody: PromiseFunction‹T›): PromiseFunction‹T›

This is not a regular cache! This function is only used across subsequent executions of parsedBody() on a single HttpResponse. To implement cache, make use of interceptors.

Type parameters:

▪ T

Parameters:

Returns: PromiseFunction‹T›

a promise function returning body, it can be called many times

Const createAsyncBodyHandler

▸ createAsyncBodyHandler<T>(): object

Type parameters:

▪ T

Returns: object

• call(): Promise‹T›

• onBodyFailure(failer: function): void

• onBodyReceived(getter: function): void

Const createErrorInterceptor

▸ createErrorInterceptor(): HttpInterceptorFunction

Returns: HttpInterceptorFunction

Const createHttpResponse

▸ createHttpResponse(__namedParameters: object): HttpResponse

Parameters:

▪ __namedParameters: object

Returns: HttpResponse

Const createLoggingInterceptor

▸ createLoggingInterceptor(__namedParameters: object): HttpInterceptorFunction

Parameters:

▪ __namedParameters: object