https://github.com/fgiova/undici-rest-client
A simple generic REST client using undici
https://github.com/fgiova/undici-rest-client
client rest undici
Last synced: 4 months ago
JSON representation
A simple generic REST client using undici
- Host: GitHub
- URL: https://github.com/fgiova/undici-rest-client
- Owner: fgiova
- License: mit
- Created: 2024-01-19T09:58:26.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-09-08T09:20:29.000Z (10 months ago)
- Last Synced: 2025-09-08T10:29:17.812Z (10 months ago)
- Topics: client, rest, undici
- Language: TypeScript
- Homepage:
- Size: 302 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Simple REST client using undici
[](https://www.npmjs.com/package/@fgiova/undici-rest-client)
[](http://www.typescriptlang.org/)
[](https://biomejs.dev)
[](https://qlty.sh/gh/fgiova/projects/undici-rest-client)
[](https://qlty.sh/gh/fgiova/projects/undici-rest-client)
## Description
This is a simple REST client using [undici](https://www.npmjs.com/package/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 18 use version 2.x >, version > 4.x support only Node.js >= 20 .
## Installation
```bash
npm install @fgiova/undici-rest-client
```
## Usage
```typescript
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({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",
}
});
const responseWHeaders = await client.post("/foo/bar", {
headers: {
"x-foo": "bar",
},
ttl: 1000,
requestKey: "foo-bar",
body: {
foo: "bar",
},
returnHeaders: true,
});
console.log(response.body); // { foo: "bar" }
console.log(response.headers); // { "x-foo-return": "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 | | 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 |
| interceptors | DispatcherComposeInterceptor[] | | Array of interceptors for undici |
## RequestOptions
| Option | Type | Default | Description |
|---------------|------------------------|---------|--------------------------------------------------------------------------|
| headers | Record | | 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 |
| returnHeaders | boolean | false | If true return headers into headers property and body into body property |
**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
```typescript
request(options: RequestOptions): Promise>;
```
### get
```typescript
get(path: string, options?: Omit): Promise>;
```
### post
```typescript
post(path: string, options?: Omit): Promise>;
```
### put
```typescript
put(path: string, options?: Omit): Promise>;
```
### patch
```typescript
patch(path: string, options?: Omit): Promise>;
```
### delete
```typescript
delete(path: string, options?: Omit): Promise>;
```
## License
Licensed under [MIT](./LICENSE).