@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

ESLint + AirbnbBase + Prettier, Jest(ts-jest) 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:

/**
 * Fetch API
 */
export class FetchApi extends FetchLikeApi<Response> {
  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<Response> {
  constructor() {
    super(fetch);
  }
}

Installing

Using npm:

$ npm install @etsoo/restclient

Using yarn:

$ yarn add @etsoo/restclient

Example

Initialization

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

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

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

• Depending on your decision.

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

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

Calls

// 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<Customer[]>("/api/customer");
// or with traditional callback way
client.get<Customer[]>("/api/customer").then((customers) => {});

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

Error handling

// API client
const client = createClient();

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

// Read one customer
var payload: IApiPayload<Customer, any> = {
  // 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<Customer>(
  "/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.

    /**
     * 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
     * @returns IP data
     */
    detectIP(): Promise<IPData | 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<T = DataTypes.ReadonlyData>(url: string): Promise<T>;

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

    /**
     * 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