or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

body-processing.mderror-handling.mdfile-blob.mdheaders.mdhttp-client.mdindex.mdrequest-response.mdutilities.md
tile.json

tessl/npm-node-fetch

A light-weight module that brings Fetch API to Node.js

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/node-fetch@3.1.x

To install, run

npx @tessl/cli install tessl/npm-node-fetch@3.1.0

index.mddocs/

node-fetch

node-fetch is a light-weight module that brings the Web Standards Fetch API to Node.js. It provides a consistent, promise-based HTTP client that mirrors the browser's fetch() functionality while adding Node.js-specific enhancements like stream support, HTTP agent configuration, and file system integration.

Package Information

  • Package Name: node-fetch
  • Package Type: npm
  • Language: JavaScript (ES Modules)
  • Installation: npm install node-fetch

Core Imports

import fetch from 'node-fetch';

With named imports:

import fetch, { Request, Response, Headers, FormData, FetchError, AbortError } from 'node-fetch';

For CommonJS environments (Node.js < 14), use dynamic import:

const fetch = (...args) => import('node-fetch').then(({default: fetch}) => fetch(...args));

Basic Usage

import fetch from 'node-fetch';

// Simple GET request
const response = await fetch('https://api.github.com/users/octocat');
const data = await response.json();

// POST request with JSON body
const postResponse = await fetch('https://httpbin.org/post', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ key: 'value' })
});

// Check response status
if (response.ok) {
  console.log('Request successful');
} else {
  console.error(`HTTP Error: ${response.status} ${response.statusText}`);
}

Architecture

node-fetch implements the Web Standards Fetch API with these key components:

  • fetch() Function: Main HTTP client function accepting URLs and options
  • Request/Response Classes: Full-featured objects representing HTTP requests and responses
  • Headers Class: HTTP header manipulation with case-insensitive operations
  • Body Interface: Shared functionality for reading request/response bodies as text, JSON, streams, etc.
  • Error Classes: Specialized error types for network failures and aborted requests
  • Node.js Extensions: Stream support, HTTP agents, compression, redirect limits, and file utilities

Capabilities

HTTP Client Operations

Core fetch functionality for making HTTP requests with full Web Standards compatibility plus Node.js-specific enhancements.

function fetch(url: string | URL | Request, options?: RequestInit): Promise<Response>;

interface RequestInit {
  method?: string;
  headers?: HeadersInit;
  body?: BodyInit | null;
  redirect?: 'follow' | 'error' | 'manual';
  signal?: AbortSignal | null;
  // Node.js extensions
  agent?: http.Agent | ((parsedUrl: URL) => http.Agent);
  compress?: boolean;
  follow?: number;
  size?: number;
  highWaterMark?: number;
}

HTTP Client Operations

Request and Response Handling

Classes for creating and manipulating HTTP requests and responses with full Body interface support.

class Request {
  constructor(input: string | URL | Request, init?: RequestInit);
  readonly method: string;
  readonly url: string;
  readonly headers: Headers;
  readonly body: ReadableStream | null;
  clone(): Request;
}

class Response {
  constructor(body?: BodyInit | null, init?: ResponseInit);
  readonly status: number;
  readonly statusText: string;
  readonly ok: boolean;
  readonly redirected: boolean;
  readonly headers: Headers;
  readonly body: ReadableStream | null;
  clone(): Response;
  static redirect(url: string, status?: number): Response;
  static error(): Response;
  static json(data: any, init?: ResponseInit): Response;
}

Request and Response Handling

Headers Management

HTTP header manipulation with case-insensitive operations and Web Standards compatibility.

class Headers {
  constructor(init?: HeadersInit);
  append(name: string, value: string): void;
  delete(name: string): void;
  get(name: string): string | null;
  has(name: string): boolean;
  set(name: string, value: string): void;
  forEach(callback: (value: string, key: string, headers: Headers) => void): void;
  entries(): IterableIterator<[string, string]>;
  keys(): IterableIterator<string>;
  values(): IterableIterator<string>;
  // Node.js extension
  raw(): Record<string, string[]>;
}

Headers Management

Body Processing

Unified interface for reading and processing request/response bodies with support for multiple formats.

interface Body {
  readonly body: ReadableStream | null;
  readonly bodyUsed: boolean;
  arrayBuffer(): Promise<ArrayBuffer>;
  blob(): Promise<Blob>;
  formData(): Promise<FormData>;
  json(): Promise<any>;
  text(): Promise<string>;
}

Body Processing

Error Handling

Specialized error classes for different types of failures during HTTP operations.

class FetchError extends Error {
  constructor(message: string, type: string, systemError?: Record<string, unknown>);
  readonly name: 'FetchError';
  readonly type: string;
  readonly code?: string;
  readonly errno?: string;
}

class AbortError extends Error {
  constructor(message: string, type?: string);
  readonly name: 'AbortError';
  readonly type: string;
}

Error Handling

File and Blob Operations

Integration with file system and blob operations for uploading files and handling binary data.

// Re-exports from fetch-blob
class Blob {
  constructor(blobParts?: BlobPart[], options?: BlobPropertyBag);
  readonly size: number;
  readonly type: string;
  arrayBuffer(): Promise<ArrayBuffer>;
  stream(): ReadableStream;
  text(): Promise<string>;
}

class File extends Blob {
  constructor(fileBits: BlobPart[], fileName: string, options?: FilePropertyBag);
  readonly name: string;
  readonly lastModified: number;
}

// Utility functions
function fileFrom(path: string, type?: string): Promise<File>;
function fileFromSync(path: string, type?: string): File;
function blobFrom(path: string, type?: string): Promise<Blob>;
function blobFromSync(path: string, type?: string): Blob;

File and Blob Operations

Utility Functions

Utility functions for HTTP status code validation and common operations.

function isRedirect(code: number): boolean;

Utility Functions

Types

type HeadersInit = Headers | Record<string, string> | Iterable<readonly [string, string]>;

type BodyInit = Blob | Buffer | URLSearchParams | FormData | ReadableStream | string;

type RequestInfo = string | Request;

interface ResponseInit {
  status?: number;
  statusText?: string;
  headers?: HeadersInit;
}

interface BlobPropertyBag {
  type?: string;
  endings?: 'transparent' | 'native';
}

interface FilePropertyBag extends BlobPropertyBag {
  lastModified?: number;
}