@e-mc/request

Interface

View Source

import type { IModule, ModuleConstructor } from "./index";
import type { HttpAdapterConstructor, HttpAgentSettings, HttpProtocolVersion, HttpRequestClient, InternetProtocolVersion } from "./http";
import type { ApplyOptions, Aria2Options, HeadersOnCallback, HostConfig, OpenOptions, PostFileParts, PostOptions, ProxySettings, PutOptions, RcloneOptions, ReadExpectType, RequestInit, StatusOnCallback } from "./request";
import type { DnsLookupSettings, RequestModule, RequestSettings } from "./settings";

import type { ClientRequest, OutgoingHttpHeaders } from "node:http";
import type { LookupFunction } from "node:net";
import type { Writable } from "node:stream";

interface IRequest extends IModule {
    module: RequestModule;
    startTime: number;
    acceptEncoding: boolean;
    keepAlive: boolean | null;
    readTimeout: number;
    readExpect: ReadExpectType;
    proxy: ProxySettings | null;
    init(config?: RequestInit): this;
    apply(options: ApplyOptions): this;
    addDns(hostname: string, address: string, timeout: number): void;
    addDns(hostname: string, address: string, family?: string, timeout?: number): void;
    lookupDns(hostname: string): LookupFunction;
    proxyOf(uri: string, localhost?: boolean): ProxySettings | undefined;
    statusOn(name: number | number[], callback: StatusOnCallback): void;
    statusOn(name: number | number[], globUrl: string, callback: StatusOnCallback): void;
    headersOn(name: string | string[], callback: HeadersOnCallback): void;
    headersOn(name: string | string[], globUrl: string, callback: HeadersOnCallback): void;
    headersOf(uri: string): OutgoingHttpHeaders | undefined;
    aria2c(uri: string | URL, pathname: string | URL): Promise<string[]>;
    aria2c(uri: string | URL, options?: Aria2Options): Promise<string[]>;
    rclone(uri: string, pathname: string | URL): Promise<string[]>;
    rclone(uri: string, options?: RcloneOptions): Promise<string[]>;
    json(uri: string | URL, options?: OpenOptions): Promise<object | null>;
    blob(uri: string | URL, options?: OpenOptions): Promise<Blob | null>;
    pipe(uri: string | URL, to: Writable, options?: OpenOptions): Promise<null>;
    opts(url: string | URL, options?: OpenOptions): HostConfig;
    open(uri: string | URL, options: OpenOptions): HttpRequestClient;
    head(uri: string | URL, options?: OpenOptions): ClientRequest;
    put(uri: string | URL, data: unknown, options: PutOptions): Promise<Buffer | string | null>;
    put(uri: string | URL, data: unknown, contentType?: string, options?: PutOptions): Promise<Buffer | string | null>;
    post(uri: string | URL, parts: PostFileParts): Promise<Buffer | string | null>;
    post(uri: string | URL, form: Record<string, unknown>, parts: PostFileParts): Promise<Buffer | string | null>;
    post(uri: string | URL, data: unknown, options: PostOptions): Promise<Buffer | string | null>;
    post(uri: string | URL, data: unknown, contentType?: string, options?: PostOptions): Promise<Buffer | string | null>;
    get(uri: string | URL, options?: OpenOptions): Promise<Buffer | object | string | null>;
    detach(singleton?: boolean): void;
    reset(): void;
    close(): void;
    set adapter(value: HttpAdapterConstructor);
    set agentTimeout(value);
    get agentTimeout(): number;
    set httpVersion(value);
    get httpVersion(): HttpProtocolVersion | null;
    set ipVersion(value);
    get ipVersion(): InternetProtocolVersion;
    get settings(): RequestSettings;
}

interface RequestConstructor extends ModuleConstructor {
    readCACert(value: string, cache?: boolean): string;
    readTLSKey(value: string, cache?: boolean): string;
    readTLSCert(value: string, cache?: boolean): string;
    isCert(value: string): boolean;
    /** @deprecated @e-mc/request/util */
    fromURL(url: URL, value: string): string;
    /** @deprecated @e-mc/request/util */
    fromStatusCode(value: number | string): string;
    defineHttpAgent(options: HttpAgentSettings): void;
    defineDnsLookup(options: DnsLookupSettings, clear?: boolean): void;
    defineHttpAdapter(module: unknown): void;
    isRclone(value: string | URL): boolean;
    getAria2Path(): string;
    getRclonePath(): string;
    readonly prototype: IRequest;
    new(module?: RequestModule): IRequest;
}

Changelog

Added in version 0.13.9:

• IRequest function blob for native Blob/File buffer instance was created.

Note

Backported: 0.12.16

Removed in version 0.13.0:

• NPM package zstd-codec is no longer available for Zstd compression. [1]

Changed in version 0.13.0:

• IRequest function aria2c | rclone argument pathname can accept a URL instance.

Added in version 0.12.3:

• RequestConstructor function isRclone for URI detection was created.

Added in version 0.12.0:

• IRequest function rclone for pre-configured cloud storage transfers was created.

Added in version 0.11.0:

• IRequest property setter adapter for the local HTTP implementation as IHttpAdapter was created.

• RequestConstructor function defineHttpAdapter for the global HTTP implementation as IHttpAdapter was created.

• IRequest function get supports Zstd decompression for Content-Encoding. [1]

Deprecated since version 0.11.0:

• RequestConstructor function fromURL | fromStatusCode were relocated into the utility package.

Added in version 0.10.3:

• IRequest function put for HTTP method PUT was created.

Changed in version 0.9.0:

• RequestInit property requestTimeout was renamed readTimeout.

Added in version 0.8.2:

• IRequest function statusOn was created.

Added in version 0.8.1:

• IRequest function headersOn was created.

Settings

View JSON

import type { PermittedDirectories } from "./core";
import type { SecureConfig } from "./http";
import type { PurgeComponent } from "./settings";

import type { LookupAddress } from "node:dns";
import type { AgentOptions, OutgoingHttpHeaders } from "node:http";

interface RequestModule {
    handler: "@e-mc/request";
    timeout?: number | string;
    read_timeout?: number | string;
    max_concurrent_streams?: number | string;
    agent?: {
        keep_alive?: boolean;
        keep_alive_interval?: number | string;
        timeout?: number | string;
        proxy_env?: AgentOptions["proxyEnv"];
    };
    connect?: {
        timeout?: number | string;
        retry_wait?: number | string;
        retry_after?: number | string;
        retry_limit?: number;
        redirect_limit?: number;
    };
    dns?: {
        family?: number;
        expires?: number | string;
        resolve?: Record<string, Partial<LookupAddress>>;
    };
    use?: {
        http_version?: 1 | 2;
        accept_encoding?: boolean;
    };
    proxy?: {
        address?: string;
        port?: number;
        origin?: string;
        username?: string;
        password?: string;
        include?: string[];
        exclude?: string[];
        keep_alive?: boolean;
        keep_alive_interval?: number | string;
    };
    headers: Record<string, OutgoingHttpHeaders>;
    certs?: Record<string, SecureConfig<string | string[]>>;
    localhost?: string[];
    protocol?: {
        "http/1.1"?: string[];
        h2c?: string[];
        h2?: string[];
    };
    write_stream?: Record<string, number | string>;
    post_limit?: number | string;
    settings?: {
        broadcast_id?: string | string[];
        time_format?: "readable" | "relative" | "none";
        purge?: PurgeComponent;
    }
}

interface DownloadModule {
    expires?: number | string;
    aria2?: {
        bin?: string | false;
        exec?: {
            uid?: number;
            gid?: number;
        };
        update_status?: number | { interval?: number; broadcast_only?: boolean };
        max_concurrent_downloads?: number;
        max_connection_per_server?: number;
        check_integrity?: boolean;
        bt_stop_timeout?: number;
        bt_tracker_connect_timeout?: number;
        bt_tracker_timeout?: number;
        min_split_size?: string;
        disk_cache?: number | string;
        lowest_speed_limit?: number | string;
        always_resume?: boolean;
        file_allocation?: "none" | "prealloc" | "trunc" | "falloc";
        conf_path?: string;
    };
    rclone?: {
        bin?: string | false;
        exec?: {
            uid?: number;
            gid?: number;
        };
        check_first?: boolean;
        checksum?: boolean;
        combined?: string;
        csv?: boolean;
        differ?: string;
        error?: string;
        format?: string;
        separator?: string;
        timeformat?: string;
        hash: "md5" | "SHA-1" | "DropboxHash";
        cutoff_mode?: "HARD" | "SOFT" | "CAUTIOUS";
        ignore_case_sync?: boolean;
        ignore_checksum?: boolean;
        ignore_existing?: boolean;
        ignore_size?: boolean;
        ignore_times?: boolean;
        immutable?: boolean;
        inplace?: boolean;
        max_backlog?: number;
        max_duration?: string;
        max_transfer?: string;
        metadata?: boolean;
        modify_window?: string;
        multi_thread_chunk_size?: string;
        multi_thread_cutoff?: string;
        multi_thread_streams?: number;
        multi_thread_write_buffer_size?: string;
        no_check_dest?: boolean;
        no_traverse?: boolean;
        no_update_dir_modtime?: boolean;
        no_update_modtime?: boolean;
        order_by?: string;
        refresh_times?: boolean;
        size_only?: boolean;
        streaming_upload_cutoff?: string;
        update?: boolean;
        fast_list?: boolean;
        bind?: string;
        contimeout?: string;
        disable_http2?: boolean;
        timeout?: string;
        config?: string;
    };
}

Changelog

Added in version 0.14.0:

• DownloadModule section rclone properties were created:

  format

  separator

  timeformat

  order_by

Added in version 0.13.9:

• RequestModule property max_concurrent_streams for limiting HTTP2 connections per session group was created.

Changed in version 0.13.5:

• RequestModule agent properties keep_alive_interval | proxy_env for configuring the HTTP/s global Agent instance were created.

• RequestModule property proxy.keep_alive_interval for throttling the keep alive packets (ms) was created.

Added in version 0.13.0:

• DownloadModule section rclone properties were created:

  combined csv

  differ error

  hash no_update_modtime

  streaming_upload_cutoff

Changed in version 0.12.0:

• RequestModule settings section rclone for cloud storage copying was created.

Changed in version 0.11.0:

• RequestModule property proxy.exclude can be prefixed with “!” to negate a subset of glob addresses.

Added in version 0.10.1:

• RequestModule property proxy.origin is a combined alias for address and port.

Added in version 0.10.0:

• DownloadModule property check_integrity in aria2 for hash validation was implemented.

• RequestModule property write_stream for stream size (kb) configuration by host was created.

Example usage

const Request = require("@e-mc/request");

const instance = new Request({
  read_timeout: 30,
  connect: {
    timeout: 20, // Seconds
    retry_wait: 1,
    retry_after: 30,
    retry_limit: 3, // Max attempts
    redirect_limit: 10
  },
  use: {
    http_version: 2,
    accept_encoding: true
  },
  dns: {
    family: 4 // ipVersion
  },
  agent: { keep_alive: true }
});
request.init({ ipVersion: 6 });

const options = {
  format: "yaml",
  httpVersion: 1,
  silent: true,
  headers: { "x-goog-user-project": "project-1" }
};
instance.get("http://hostname/path/config.yml", options).then(data => {
  console.log(data.property);
});

References

• https://www.unpkg.com/@e-mc/types/lib/http.d.ts

• https://www.unpkg.com/@e-mc/types/lib/request.d.ts

• https://www.unpkg.com/@e-mc/types/lib/settings.d.ts

• https://www.npmjs.com/package/@types/node

[1] (1,2)

NodeJS 22.15 has native support for Zstandard.