@fgiova/undici-rest-client

Simple REST client using undici

Description

This is a simple REST client using undici as http client.
It's support a simple retry mechanism using exponential backoff or using delay based on retry-after HTTP header It's implement a simple LRU cache mechanism on idempotent HTTP methods.

[!NOTE] For node 16 use version 1.x, version 2.x support only Node.js >= 18.

Installation

npm install @fgiova/undici-rest-client

Usage

import { RestClient } from "@fgiova/undici-rest-client";

const client = new RestClient({
    baseUrl: "https://foo.bar.org",
    retry: {
        httpCodes: [503, 429],
        baseTimeout: 1000,
        maxTimeout: 10000,
        maxRetry: 5,
        backoff: (retryCount) => 2 ** retryCount * 1000,
    },
	cache: new LRUCache<string, any>({max: 10})
});

const response = await client.get("/foo/bar", {
    headers: {
        "x-foo": "bar",
    },
    ttl: 1000,
    requestKey: "foo-bar",
});

const response = await client.post("/foo/bar", {
    headers: {
        "x-foo": "bar",
    },
    ttl: 1000,
    requestKey: "foo-bar",
    body: {
        foo: "bar",
    }
});

Client Options

Option	Type	Default	Description
baseUrl	string		The base domain url to be used for the client
retry	Retry Options		The retry options
cache	LRUCache<string, any>		The LRU cache instance
undici	Undici Option		The undici options

Retry Options

Option	Type	Default	Description
httpCodes	number[]	502, 503, 429, 408, 504, 599	The HTTP codes to be retried
baseTimeout	number	300	The base timeout in ms
maxTimeout	number	30000	The max timeout in ms
maxRetry	number	3	The max number of retry
backoff	(retryCount: number) => number	exponential backoff	The backoff function

Undici Options

Option	Type	Default	Description
clientOption	Pool.Options		The number of connections
pipelining	number		The number of pipelining

RequestOptions

Option	Type	Default	Description
headers	Record<string, string>		The HTTP headers
body	any		The HTTP body
ttl	number		The TTL for the cache
requestKey	string		The key for the cache
path	string		The path for the request

Notes:
The cache is a simple LRU cache with a max size of 1000 items and a default TTL of 30 seconds.
The cache TTL can be overridden using the ttl option in the request.
The cache key is generated using the request method, the request path and the request body.
The cache key can be overridden using the requestKey option in the request.
When the request is not idempotent, the cache is disabled.
When the body is a plain object the header content-type "application/json" is added to request.
When response is a not compressible (typically a binary response) array buffer are returned.
Parallel idempotent requests at same resource are deduplicated.

Methods

request

request<T = any>(options: RequestOptions): Promise<Response<T>>;

get

get<T = any>(path: string, options?: Omit<RequestOptions, "path" | "method" | "body" >): Promise<Response<T>>;

post

post<T = any>(path: string, options?: Omit<RequestOptions, "path" | "method">): Promise<Response<T>>;

put

put<T = any>(path: string, options?: Omit<RequestOptions, "path" | "method">): Promise<Response<T>>;

patch

patch<T = any>(path: string, options?: Omit<RequestOptions, "path" | "method">): Promise<Response<T>>;

delete

delete<T = any>(path: string, options?: Omit<RequestOptions, "path" | "method" | "body" | "ttl">): Promise<Response<T>>;

License

Licensed under MIT.