@xof/fetch

Installation & Usage

Installation

Install @xof/fetch using npm:

npm install @xof/fetch

After installation, import the module into your Node.js project:

const go = require('@xof/fetch');

For ES Module:

import go from '@xof/fetch';

@xof/fetch provides a simple and modern interface for making HTTP requests using a lightweight request engine with advanced configuration support.

It supports common HTTP methods such as GET, POST, PUT, PATCH, DELETE, HEAD, and More. for communicating with APIs and web services.

Features

• Simple HTTP request API
• Native Node.js HTTP/HTTPS support
• Automatic JSON parsing
• Automatic JSON body serialization
• Browser-style request headers
• Dynamic User-Agent support
• Custom request instances
• Redirect handling
• Compression support
• Cookie compatible
• CommonJS and ESM support
• Lightweight and extensible architecture
• Optional request retry system
• Retry metadata tracking
• Response data conversion helpers
• Buffer, text, and JSON response converters
• URL path parameter replacement
• Automatic query string builder
• Runtime header toggle API
• Explicit request body support
• CookieJar request
• HeadersJar request
• Request throttling
• Optional request retry system
• Retry on network errors
• Retry on specific HTTP status codes
• Retry metadata tracking
• HTTP/HTTPS proxy support
• Proxy tunneling
• Proxy authentication
• Proxy connection reuse

Basic GET Request

Example:

const go = require('@xof/fetch');

async function main() {
  const response = await go.get('https://api.example.com/data');

  console.log(response.data);
}

main();

Params, Query, Options

await go.get('/users/:id', {
  params: {
    id: 123
  },
  query: {
    page: 1
  },
  timeout: 5000
});

POST Request

Send JSON data directly using the POST method:

const response = await go.post(url, {
  body: {
    username: 'xof',
    active: true
  }
});

console.log(response.data);

Object request bodies are automatically serialized into JSON format.

Custom Request Instance

Create a reusable client with default configuration:

const Go = require('@xof/fetch');

const api = Go.create({
  headers: {
    Authorization: 'Bearer your-token'
  }
});

const response = await api.get(
  'https://api.example.com/profile'
);

console.log(response.data);

Auto CookieJar

Enable automatic cookie management:

const Go = require('@xof/fetch');

const api = Go.create({
  baseURL: 'https://example.com',
  browser: true,
  cookieJar: true
});

await api.post('/login', {
  body: {
    username: 'admin',
    password: 'secret'
  }
});

// Cookies are automatically sent
const profile = await api.get('/profile');

console.log(profile.data);

Cookies received from Set-Cookie are stored automatically and attached to subsequent requests for the same domain.

Read Stored Cookies

const cookies = api.cookieJar.getAll();

console.log(cookies);

Example output:

[
  {
    name: "session",
    value: "eyJhbGciOi...",
    domain: "example.com",
    path: "/",
    expires: 2026-08-06T10:23:53.000Z
  },
  {
    name: "ads_session",
    value: "eyJhbGciOi...",
    domain: "example.com",
    path: "/",
    expires: 2026-08-06T10:54:59.000Z
  }
]

Custom instances can store:

• Default headers
• Authentication headers
• Timeout settings
• Request options
• API configurations

Response Object

Every request returns a response object containing request information, server response details, and parsed response data.

Example:

const response = await go.get('https://api.example.com');

console.log(response.status);
console.log(response.headers);
console.log(response.data);

Available Properties

response.status

HTTP status code returned by the server.

Example:

200

response.statusText

HTTP status message.

Example:

"OK"

response.headers

Response headers returned by the server.

Example:

{
  "content-type": "application/json",
  "server": "nginx"
}

response.config

Configuration used during the request.

Example:

{
  method: "GET",
  url: "https://api.example.com"
}

response.request

Contains request information including the generated HTTP request.

response.data

Parsed response data.

Example:

{
  "message": "success",
  "data": []
}

response.meta

Contains internal request metadata.

Example:

{
  "retry": {
    "attempts": 1,
    "maxRetries": 3
  }
}

Response Helpers

@xof/fetch provides helper methods for converting response data.

response.toBuffer()

Convert response data into a Node.js Buffer.

Example:

const response = await go.get('https://example.com/file');
const buffer = await response.toBuffer();
console.log(Buffer.isBuffer(buffer));

const response = await go.get('https://example.com');
const html = await response.text();
console.log(html);

const response = await go.get('https://api.example.com/data');
const json = await response.json();
console.log(json);

Request Throttling

Request throttling allows you to control how frequently requests are started.

Throttling is disabled by default.

const Go = require('@xof/fetch');

const api = Go.create({
  throttle: {
    rps: 10
  }
});

const response = await api.get('https://api.example.com/data');

console.log(response.data);

With rps: 10, the instance schedules requests at approximately 10 requests per second.

All requests made through the same instance share the same throttle queue.

const Go = require('@xof/fetch');

const api = Go.create({
  throttle: {
    rps: 10
  }
});

const responses = await api.all([
  api.get('https://api.example.com/1'),
  api.get('https://api.example.com/2'),
  api.get('https://api.example.com/3'),
  api.get('https://api.example.com/4'),
  api.get('https://api.example.com/5')
]);

console.log(responses);

Each request instance has its own independent throttle.

const slowApi = go.create({
  throttle: {
    rps: 5
  }
});

const fastApi = go.create({
  throttle: {
    rps: 20
  }
});

Throttling can be disabled by omitting the throttle option.

const api = go.create();

Or explicitly disable it:

const api = go.create({
  throttle: false
});

Options

• rps — number — Maximum request start rate per second.

const Go = require('@xof/fetch');

const api = Go.create({
  throttle: {
    rps: 10
  }
});

rps controls the request start rate, not the number of requests that can be active simultaneously.

Error Handling

@xof/fetch uses FetchError for request-level and network-level errors.

Network errors such as DNS failures, connection refusals, connection resets, timeouts, and broken pipes are exposed through the error object.

Example:

try {
  const response = await go.get('https://example.com');

  console.log(response.data);
} catch (err) {
  console.log(err.code);
  console.log(err.data);
}

For example, a DNS failure may produce:

err.code
// ENOTFOUND

err.data
// ENOTFOUND

err.message
// getaddrinfo ENOTFOUND example.com

The original Node.js error is preserved through err.cause:

try {
  await go.get('https://example.com');
} catch (err) {
  console.log(err.cause);
}

Network errors occur before an HTTP response is received, so err.response will be null:

try {
  await go.get('https://example.com');
} catch (err) {
  console.log(err.response);
  // null
}

FetchError Properties

• err.message — Human-readable error message.
• err.code — Error code such as ENOTFOUND, ECONNRESET, or ETIMEDOUT.
• err.data — Exposed error data.
• err.cause — Original underlying Node.js error.
• err.config — Request configuration.
• err.request — Underlying request object when available.
• err.response — HTTP response when available.

Proxy Support

@xof/fetch supports HTTP and HTTPS proxy requests with proxy tunneling, authentication, and connection reuse.

Proxy can be configured globally on a custom request instance:

const Go = require('@xof/fetch');

const api = Go.create({
  proxy: 'http://127.0.0.1:8080'
});

const response = await api.get('https://api.example.com/data');

console.log(response.data);

Proxy authentication is also supported:

const api = Go.create({
  proxy: 'http://username:[email protected]:8080'
});

Proxy configuration can also be provided per request:

const response = await go.get('https://api.example.com/data', {
    proxy: 'http://127.0.0.1:8080'
  }
);

@xof/fetch handles proxy connections according to the target URL protocol and supports connection reuse when KeepAlive is enabled.

Requests Retry

Retry is disabled by default.

Retry can be configured globally or per request.

const Go = require('@xof/fetch');

const api = Go.create({
  retry: {
    max: 3,
    delay: 1000
  }
});

const response = await api.get('https://api.example.com/data');

console.log(response.data);

Retry can also be configured directly on a request:

const response = await go.get('https://api.example.com/data', {
    retry: {
      max: 3,
      delay: 500
    }
  }
);

console.log(response.meta.retry);

Retry Conditions

@xof/fetch can retry requests when a network error occurs.

Supported network errors:

• ECONNRESET
• ETIMEDOUT
• ECONNREFUSED
• EPIPE

Retry can also be triggered by specific HTTP status codes using retry.status:

const response = await go.get('https://api.example.com/data', {
    retry: {
      max: 3,
      delay: 1000,
      status: [408, 429, 500, 502, 503, 504]
    }
  }
);

The status option defines which HTTP response status codes should trigger another request attempt.

Retry Options

• max — number — Maximum number of retry attempts.
• delay — number — Delay between retry attempts in milliseconds.
• timeout — number — Timeout configuration used by the retry system.
• status — number[] — HTTP status codes that should trigger a retry.

Example:

const api = Go.create({
  retry: {
    max: 3,
    delay: 1000,
    timeout: 20000,
    status: [408, 429, 500, 502, 503, 504]
  }
});

Retry metadata is available through the response:

console.log(response.meta.retry);

/*
{
  attempts: 2,
  maxRetries: 3
}
*/

Headers

@xof/fetch automatically provides modern browser-style request headers.

Included headers:

• User-Agent
• Accept
• Accept-Encoding
• Accept-Language
• Cache-Control
• Sec-CH-UA
• Sec-Fetch headers
• Upgrade-Insecure-Requests

Custom headers can be added manually:

const response = await go.get('https://api.example.com', {
    headers: {
      'X-App-Name': 'MyApp'
    }
  }
);

Cookies

@xof/fetch supports cookie-based requests through custom headers.

Example:

const response = await go.get('https://example.com', {
    headers: {
      Cookie: 'session=value'
    }
  }
);

Method

• GET
• POST
• PUT
• PATCH
• HEAD
• DELETE
• OPTIONS
• TRACE
• CONNECT

Complete Example

const go = require('@xof/fetch');

async function example() {
  const response = await go.get('https://api.example.com/users');

  console.log('Status:', response.status);
  console.log('Headers:', response.headers);
  console.log('Request:', response.requestHeaders);
  console.log('Data:', response.data);
}

example();

New Feature

New

Changelog

Changelog

License

MIT © XOF