@gibme/fetch

A TypeScript wrapper around cross-fetch that extends the standard Fetch API with timeout support, cookie jar persistence, authentication helpers, and convenience methods for JSON and form data — for both Node.js and browser environments.

Features

• Timeout support — abort requests after a configurable duration
• Cookie jar persistence — maintain cookies across requests (Node.js only)
• Authentication helpers — Basic, Bearer, and JWT auth via simple options
• JSON & form data shortcuts — auto-serialization with correct Content-Type headers
• HTTP method helpers — fetch.get(), fetch.post(), fetch.put(), fetch.del(), plus WebDAV, CalDAV, and other extended methods
• Custom agents — pass http.Agent or https.Agent for connection pooling (Node.js only)
• SSL/TLS control — disable certificate validation for development (Node.js only)
• Dual entry points — optimized builds for Node.js and browser

Requirements

• Node.js >= 22

Installation

npm install @gibme/fetch
# or
yarn add @gibme/fetch

Usage

Basic Request

import fetch from '@gibme/fetch';

const response = await fetch('https://api.example.com/data', { timeout: 5000 });

console.log(await response.json());

HTTP Method Helpers

import fetch from '@gibme/fetch';

const response = await fetch.get('https://api.example.com/users');
const created = await fetch.post('https://api.example.com/users', {
    json: { name: 'Alice' }
});
const updated = await fetch.put('https://api.example.com/users/1', {
    json: { name: 'Bob' }
});
const deleted = await fetch.del('https://api.example.com/users/1');

Standard HTTP: fetch.get(), fetch.head(), fetch.post(), fetch.put(), fetch.del(), fetch.patch(), fetch.options(), fetch.trace(), fetch.connect(), fetch.query()

WebDAV family (WebDAV, CalDAV, ACL, Search, Bindings): fetch.propFind(), fetch.propPatch(), fetch.mkCol(), fetch.mkCalendar(), fetch.copy(), fetch.move(), fetch.lock(), fetch.unlock(), fetch.report(), fetch.acl(), fetch.search(), fetch.bind(), fetch.unbind(), fetch.rebind()

JSON Body

const response = await fetch('https://api.example.com/data', {
    method: 'POST',
    json: { key: 'value', count: 42 }
});

Automatically stringifies the body and sets Content-Type: application/json.

Form Data

const response = await fetch('https://api.example.com/submit', {
    method: 'POST',
    formData: { username: 'alice', password: 'secret' }
});

Accepts a plain object or URLSearchParams. Sets Content-Type: application/x-www-form-urlencoded.

Authentication

// Basic Auth
const response = await fetch('https://api.example.com/protected', {
    username: 'alice',
    password: 'secret'
});

// Bearer Token
const response = await fetch('https://api.example.com/protected', {
    bearer: 'your-token-here'
});

// JWT
const response = await fetch('https://api.example.com/protected', {
    jwt: 'eyJhbGciOiJIUzI1NiIs...'
});

Cookie Jar (Node.js only)

Persist cookies across multiple requests using a CookieJar:

import fetch, { CookieJar } from '@gibme/fetch';

const cookieJar = new CookieJar();

// First request stores cookies in the jar
await fetch('https://example.com/login', {
    method: 'POST',
    json: { user: 'alice', pass: 'secret' },
    cookieJar
});

// Subsequent requests automatically include stored cookies
const response = await fetch('https://example.com/dashboard', { cookieJar });

Timeout

const response = await fetch('https://slow-api.example.com/data', {
    timeout: 10000 // abort after 10 seconds
});

Custom Agents (Node.js only)

import { Agent as HttpsAgent } from 'https';

const agent = new HttpsAgent({ keepAlive: true });

const response = await fetch('https://api.example.com/data', { agent });

Disable SSL Verification (Node.js only)

const response = await fetch('https://self-signed.local/api', {
    rejectUnauthorized: false
});

Browser Usage

import fetch from '@gibme/fetch/browser';

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

The browser entry point excludes Node.js-specific features (cookie jar, agents, SSL control) for a smaller bundle. A pre-built minified bundle (Fetch.min.js) is also available in the dist/ directory.

Extended Options

All standard Fetch API RequestInit options are supported, plus:

Option	Type	Platform	Description
timeout	number	Both	Request timeout in milliseconds
json	any	Both	Auto-stringified JSON body
formData	Record<string, any> | URLSearchParams	Both	URL-encoded form body
username	string	Both	Basic auth username
password	string	Both	Basic auth password
bearer	string	Both	Bearer token
jwt	string	Both	JWT token (sent as Bearer)
cookieJar	CookieJar	Node.js	Cookie persistence across requests
agent	http.Agent | https.Agent	Node.js	Custom HTTP/HTTPS agent
rejectUnauthorized	boolean	Node.js	SSL/TLS certificate validation (default: true)

Exports

Import Path	Description
@gibme/fetch	Node.js entry point (default)
@gibme/fetch/node	Node.js entry point (explicit)
@gibme/fetch/browser	Browser entry point

Named Exports

Both entry points export: fetch (default), Headers, Request, Response, toURLSearchParams, normalizeInit

The Node.js entry point additionally exports: Cookie, CookieJar

License

MIT