@etsoo/restclient

TypeScript promise based HTTP/REST API client. Unified axios and fetch usage.

- axios: https://github.com/axios/axios, based on XHR: https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest
- fetch: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch

Vitest applied, supports CommonJs and ESM. About how to build a NPM package and CI/CD with Github action: https://dev.to/garryxiao/build-a-react-components-npm-package-and-ci-cd-with-github-action-1jm6

Includes FetchLikeApi for extension quickly:

``ts
/**
* Fetch API
*/
export class FetchApi extends FetchLikeApi {
constructor() {
super(fetch);
}
}

// Under Node
// install node-fetch (https://github.com/node-fetch/node-fetch) first, and @types/node-fetch with TypeScript
const { FetchLikeApi } = require("@etsoo/restclient");
const fetch,
{ Response } = require("node-fetch");
class FetchApi extends FetchLikeApi {
constructor() {
super(fetch);
}
}
`

Installing

Using npm:

`bash
$ npm install @etsoo/restclient
`

Using yarn:

`bash
$ yarn add @etsoo/restclient
`

Example

$3

- Depending on the envioronment, fetch first, then use axios.
- Under node, supports node-fetch.

`ts
import { createClient } from "@etsoo/restclient";
const client = createClient();

// Or
import { createClientAsync } from "@etsoo/restclient";
const client = await createClientAsync();
`

- Depending on your decision.

`ts
import { FetchApi } from "@etsoo/restclient";
const client = new FetchApi();

// Or
import { AxiosApi } from "@etsoo/restclient";
const client = new AxiosApi();
`

$3

`ts
// Customer data structure
interface Customer {
id: string;
name: string;
}

// API client
const client = createClient();

// Authorization, JWT
client.authorize(ApiAuthorizationScheme.Bearer, " JWT token ");

// Read customer list with asyc/await ES6+ style
const customers = await client.get("/api/customer");
// or with traditional callback way
client.get("/api/customer").then((customers) => {});

// Read one customer
const customer = await client.get("/api/customer/1");
if (customer == null) {
// Error found
return;
}
console.log(customer.name);
`

$3

`ts
// API client
const client = createClient();

// Global error handling
client.onError = (error) => {
console.log(error);
};

// Read one customer
var payload: IApiPayload = {
// Current call's error handling
onError = (error) => {
console.log(error);
// return false to prevent further error handling
return false;
},
// Pass default value to distinguish return value with error or undefined
defaultValue: {}
};

const customer = await client.get(
"/api/customer/1",
undefined,
payload
);
if (customer == null) {
// Error found
// client.lastError cache the last error
// For accurate check, validate client.lastError.data.url
return;
}

// Now call payload.response to access headers
// client.transformResponse(payload.response) to get a standard IApiResponse
`

Properties

| Name | Description |
| ------------------: | ---------------------------------------------- |
| baseUrl | API base URL, add to the API root of all calls |
| charset | Charset for sending data, default is 'utf-8' |
| config | See axios/Request Config or fetch/RequestInit |
| defaultResponseType | Default type is JSON |
| jsonContentType | JSON content type string, 'application/json' |
| lastError | Last error for track |
| name | The name of the API, default value is 'system' |
| onError | Error occured callback |
| onRequest | Before request callback |
| onComplete | After request completed but before onResponse |
| onResponse | After response callback |

Methods

Provides delete, get, head, options, patch, post, put syntactic sugar for request method. Return with undefined means error found. If the API return nothing with success, a empty object {} will be returned to distingush the error case. Define a onError callback function at payload only for the call or client's property onError for global error handling.

`ts
/**
* Authorize the call
* https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization
* @param scheme Scheme
* @param token Token, empty/null/undefined to remove it
* @param writeHeaders Headers to write authtication, default to all calls
*/
authorize(
scheme: ApiAuthorizationScheme | string,
token: string | undefined,
writeHeaders?: HeadersInit
): void;

/**
* Detect IP data
* @param ip IP address or query URLs
* @returns IP data
*/
detectIP(ip?: string | URL | string[]): Promise;

/**
* Get authorization header value
* @returns Authorization header value
*/
getAuthorization(): { scheme: string; token: string } | undefined;

/**
* Get HTTP content dispostion
* @param responseOrValue Response or header value
* @returns Result
*/
getContentDisposition(response: R): ContentDisposition | undefined;
getContentDisposition(header: string): ContentDisposition | undefined;

/**
* Get content length
* @param headers Headers
* @returns
*/
getContentLength(headers: HeadersAll): number | undefined;

/**
* Get content type and charset
* @param headers Headers
*/
getContentTypeAndCharset(headers: HeadersInit): [string, string?];

/**
* Get content type
* @param headers Headers
*/
getHeaderValue(headers: HeadersInit, key: string): string | null;

/**
* Get Json data directly
* @param url URL
* @returns Json data
*/
getJson(url: string): Promise;

/**
* Get status text
* @param status Status code
* @returns Status text
*/
getStatusText(status: number): string;

/**
* Request to API
* @param method Method
* @param url API URL
* @param data Passed data
* @param payload Payload
*/
request(
method: ApiMethod,
url: string,
data?: ApiRequestData,
payload?: IApiPayload
): Promise;

/**
* Set content language
* @param language Content language
* @param headers Headers, default is global headers
*/
setContentLanguage(
language: string | null | undefined,
headers?: HeadersInit
): void;

/**
* Set header value
* @param key Header name
* @param value Header value
* @param headers Headers to lookup
*/
setHeaderValue(
key: string,
value: string | null | undefined,
headers: HeadersInit
): void;

/**
* Transform the original response to a unified object
* @param response Original response
*/
transformResponse(response: R): IApiResponse;
``

Call Payload

When you call any API, pass additional properties with the payload parameter.

| Name | Description |
| -----------: | -------------------------------------------------------------------------------- |
| contentType | Specify data type to send, like 'application/json' |
| onError | Current API call error callback |
| config | Current API config. See axios/Request Config or fetch/RequestInit |
| defaultValue | Default value, like [] for array return to distinguish undefined or error return |
| params | URL parameters |
| parser | Current API response data parser |
| response | Request response object |
| responseType | Specify response data type |
| showLoading | Whether to show loading bar |
| local | Local URL and ignore baseUrl |

License

MIT