@etsoo/restclient v1.1.3

@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

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.

License

MIT