electron-request

Zero-dependency, Lightweight HTTP request client for Electron or Node.js

Why electron-request ?

Electron-request uses its built-in net module in Electron environment and uses its built-in HTTP module in Node.js environment.

Net module is used in electron to better support proxy, authentication, traffic monitoring proxies and other features. Please refer to net for details.

Features

Zero-dependency, Lightweight
Quick start, similar window.fetch
No need to import other libraries, support file download progress and file verification
Support to run on Electron or Node.js, use Electron's net module first
Unified error handling

Install

npm install electron-request --save
# or
yarn add electron-request

Usage

import request from 'electron-request';

void (async () => {
  const url = 'https://github.com/';
  const defaultOptions = {
    method: 'GET',
    body: null,
    followRedirect: true,
    maxRedirectCount: 20,
    timeout: 0,
    size: 0,
  };
  const response = await request(url, defaultOptions);
  const text = await response.text();
})();

API

request(url[, options])

url: Request URL

options: Options

interface Options {
  /**
   * Request method
   * @default 'GET'
   */
  method?: string;
  /**
   * Request body
   * @default null
   */
  body?: string | null | Buffer | Stream;
  /**
   * Request headers
   */
  headers?: Record<string, string | string[]>;
  /**
   * Request query
   */
  query?: Record<string, string>;
  /**
   * Allow redirect
   * @default true
   */
  followRedirect?: boolean;
  /**
   * Maximum redirect count. 0 to not follow redirect
   * @default 20
   */
  maxRedirectCount?: number;
  /**
   * Request/Response timeout in ms. 0 to disable
   * @default 0
   */
  timeout?: number;
  /**
   * Maximum response body size in bytes. 0 to disable
   * @default 0
   */
  size?: number;
  /**
   * Whether to use nodejs native request
   * @default false
   */
  useNative?: boolean;

  // Docs: https://www.electronjs.org/docs/api/client-request#new-clientrequestoptions

  /**
   * Only in Electron. When use authenticated HTTP proxy, username to use to authenticate
   */
  username?: string;
  /**
   * Only in Electron. When use authenticated HTTP proxy, password to use to authenticate
   */
  password?: string;
  /**
   * Only in Electron. Whether to send cookies with this request from the provided session
   * @default true
   */
  useSessionCookies?: boolean;
  /**
   * Only in Electron. The Session instance with which the request is associated
   * @default electron.session.defaultSession
   */
  session?: Session;
}

Response

interface Response {
  /** Whether the response was successful (status in the range 200-299) */
  ok: boolean;
  /** Response headers */
  headers: Record<string, string | string[]>;
  /** Return origin stream */
  stream: Stream;
  /** Decode response as ArrayBuffer */
  arrayBuffer(): Promise<ArrayBuffer>;
  /** Decode response as Blob */
  blob(): Promise<Blob>;
  /** Decode response as text */
  text(): Promise<string>;
  /** Decode response as json */
  json<T>(): Promise<T>;
  /** Decode response as buffer */
  buffer(): Promise<Buffer>;
  /**
   * Download file to destination
   * @param {Writable} destination Writable destination stream
   * @param {ProgressCallback=} onProgress Download progress callback
   * @param {ValidateOptions=} validateOptions Validate options
   */
  download: (
    destination: Writable,
    onProgress?: ProgressCallback,
    validateOptions?: ValidateOptions,
  ) => Promise<void>;
}

/** Download progress information */
interface ProgressInfo {
  /** Total file bytes */
  total: number;
  /** Delta file bytes */
  delta: number;
  /** Transferred file bytes */
  transferred: number;
  /** Transferred percentage */
  percent: number;
  /** Bytes transferred per second */
  bytesPerSecond: number;
}