---



- Motivation
- Features
- Requirements
- Installation
- Loading and configuring the module
- Quick Start
- Common Usage
- Plain text or HTML
- JSON
- Simple Post
- Post with JSON
- Post with form parameters
- Handling exceptions
- Handling client and server errors
- Advanced Usage
- Creating a Client Instance
- Streams
- Accessing Headers and other Metadata
- Request cancellation with AbortSignal
- Middleware
- Retry Logic
- Rate Limiting
- Pattern-Based Retry
- API
- [stealthIO(url[, options])](#stealthiourl-options)
- Options
- Class: StealthClient
- Class: StealthResponse
- Class: Headers
- Class: StealthIOError
- Class: TimeoutError
- Class: AbortError
- Class: NetworkError
- Class: HTTPError
- Class: RetryError
- Class: RateLimitError
- Middleware
- Built-in Middleware
- Custom Middleware
- Testing
- Architecture
- Team
- Contributing
- License

Motivation

Why build another HTTP client when so many exist? Because sometimes you need full control without the baggage of external dependencies. Stealth-IO is built entirely from Node.js core modules (http, https, url, stream, zlib, events), making it:

- Lightweight: Zero external runtime dependencies
- Secure: No supply chain vulnerabilities from third-party packages
- Predictable: Behavior determined solely by Node.js internals
- Portable: Works anywhere Node.js runs

Features

- Zero Dependencies: Built entirely from Node.js core modules
- Full HTTP Method Support: GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS
- Automatic JSON Handling: Serialize/deserialize JSON request and response bodies
- Response Body Processing: Support for JSON, text, buffer, and stream responses
- Middleware Pipeline: Koa-style onion model for request/response interception
- Configurable Retry Logic: Exponential backoff with jitter support
- Pattern-Based Retry: Retry on response body/header patterns (unique feature)
- Rate Limiting: Built-in rate limiter with queue support for API integrations
- Request Timeout: Configurable timeout with proper cleanup
- Abort/Cancellation: Full AbortController/AbortSignal support
- Automatic Redirects: Follow redirects with configurable limits
- Response Decompression: Automatic gzip, deflate, and brotli decompression
- Case-Insensitive Headers: Headers class with normalized key access
- Query String Handling: Parse and serialize query parameters
- Connection Pooling: Leverage Node.js built-in HTTP agents
- Pluggable Transport: Custom transport interface for advanced use cases

Requirements

- Node.js >= 18.0.0

Installation

``sh
npm install stealth-io
`

Loading and configuring the module

$3

`js
import stealthIO from 'stealth-io';
`

$3

`js
import { StealthClient, createClient, Headers } from 'stealth-io';
`

$3

Stealth-IO is an ESM-only module. For CommonJS projects, use dynamic import:

`js
const stealthIO = (...args) => import('stealth-io').then(({default: stealthIO}) => stealthIO(...args));
`

Quick Start

`js
import stealthIO from 'stealth-io';

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

console.log(data);
`

Common Usage

$3

`js
import stealthIO from 'stealth-io';

const response = await stealthIO.get('https://github.com/');
const body = await response.text();

console.log(body);
`

$3

`js
import stealthIO from 'stealth-io';

const response = await stealthIO.get('https://api.github.com/users/github');
const data = await response.json();

console.log(data);
`

$3

`js
import stealthIO from 'stealth-io';

const response = await stealthIO.post('https://httpbin.org/post', 'a=1');
const data = await response.json();

console.log(data);
`

$3

`js
import stealthIO from 'stealth-io';

const response = await stealthIO.post('https://httpbin.org/post', {
name: 'John Doe',
email: 'john@example.com'
});
const data = await response.json();

console.log(data);
`

$3

`js
import stealthIO from 'stealth-io';

const params = new URLSearchParams();
params.append('username', 'john');
params.append('password', 'secret');

const response = await stealthIO.post('https://httpbin.org/post', params.toString(), {
headers: { 'Content-Type': 'application/x-www-form-urlencoded' }
});
const data = await response.json();

console.log(data);
`

$3

`js
import stealthIO, { TimeoutError, NetworkError, AbortError } from 'stealth-io';

try {
const response = await stealthIO.get('https://domain.invalid/');
} catch (error) {
if (error instanceof TimeoutError) {
console.log('Request timed out:', error.timeout);
} else if (error instanceof NetworkError) {
console.log('Network error:', error.code);
} else if (error instanceof AbortError) {
console.log('Request was aborted');
} else {
console.log('Unknown error:', error);
}
}
`

$3

`js
import stealthIO, { HTTPError } from 'stealth-io';

try {
const response = await stealthIO.get('https://httpbin.org/status/404');
} catch (error) {
if (error instanceof HTTPError) {
console.log('HTTP Error:', error.status, error.statusText);
const body = await error.response.text();
console.log('Response body:', body);
}
}
`

Or disable automatic status validation:

`js
import stealthIO from 'stealth-io';

const response = await stealthIO.get('https://httpbin.org/status/404', {
validateStatus: false
});

if (!response.ok) {
console.log('Request failed with status:', response.status);
}
`

Advanced Usage

$3

For repeated requests to the same API, create a client instance with shared configuration:

`js
import { StealthClient, createClient } from 'stealth-io';

const client = new StealthClient({
baseURL: 'https://api.example.com',
timeout: 10000,
headers: {
'Authorization': 'Bearer your-token',
'X-API-Key': 'your-api-key'
}
});

const users = await client.get('/users');
const user = await client.post('/users', { name: 'John' });
`

Or use the factory function:

`js
const client = createClient({
baseURL: 'https://api.example.com',
timeout: 10000
});
`

$3

Stream responses for large files or real-time data:

`js
import { createWriteStream } from 'node:fs';
import { pipeline } from 'node:stream/promises';
import stealthIO from 'stealth-io';

const response = await stealthIO.get('https://example.com/large-file.zip');

if (!response.ok) throw new Error(Unexpected response: ${response.statusText});

await pipeline(response.stream(), createWriteStream('./large-file.zip'));
`

$3

`js
import stealthIO from 'stealth-io';

const response = await stealthIO.get('https://github.com/');

console.log(response.ok);
console.log(response.status);
console.log(response.statusText);
console.log(response.url);
console.log(response.headers.get('content-type'));
console.log(response.headers.entries());
`

$3

`js
import stealthIO, { AbortError } from 'stealth-io';

const controller = new AbortController();

setTimeout(() => controller.abort(), 150);

try {
const response = await stealthIO.get('https://example.com/slow-endpoint', {
signal: controller.signal
});
const data = await response.json();
} catch (error) {
if (error instanceof AbortError) {
console.log('Request was aborted');
}
}
`

Using the built-in abort controller:

`js
import { StealthClient } from 'stealth-io';

const client = new StealthClient();
const controller = client.createAbortController();

const promise = client.get('https://example.com/slow-endpoint', {
signal: controller.signal
});

setTimeout(() => controller.abort(), 1000);

try {
const response = await promise;
} catch (error) {
if (error.code === 'ABORTED') {
console.log('Request was cancelled');
}
}
`

$3

Add middleware to intercept requests and responses:

`js
import { StealthClient, createLoggingMiddleware, createAuthMiddleware } from 'stealth-io';

const client = new StealthClient({
baseURL: 'https://api.example.com'
});

client.use(createLoggingMiddleware({
logger: console.log
}));

client.use(createAuthMiddleware({
type: 'bearer',
token: 'your-token'
}));

const response = await client.get('/users');
`

$3

Configure automatic retries with exponential backoff:

`js
import { StealthClient, createRetryPolicy } from 'stealth-io';

const client = new StealthClient({
maxRetries: 3,
retryDelay: 1000,
retryStrategy: 'exponential_jitter'
});

const response = await client.get('/flaky-endpoint');
`

Using preset retry policies:

`js
import { StealthClient, createRetryPolicy } from 'stealth-io';

const client = new StealthClient({
...createRetryPolicy('aggressive')
});
`

Available policies:
- aggressive: 5 retries, 500ms delay, exponential jitter
- moderate: 3 retries, 1000ms delay, exponential
- conservative: 2 retries, 2000ms delay, exponential
- none: No retries

$3

Built-in rate limiting with queue support for API integrations:

`js
import { createClient } from 'stealth-io';

const client = createClient({
rateLimit: {
maxRequests: 50,
perMs: 1000,
queue: true
}
});

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

Alternative time-based configurations:

`js
const client = createClient({
rateLimit: { perSecond: 10 }
});

const client = createClient({
rateLimit: { perMinute: 60 }
});

const client = createClient({
rateLimit: { perHour: 1000 }
});
`

Full rate limit options:

`js
const client = createClient({
rateLimit: {
maxRequests: 50,
perMs: 1000,
queue: true,
maxQueueSize: 100,
queueTimeout: 60000,
algorithm: 'sliding-window',
burstLimit: null,
onThrottle: ({ waitTime, queueSize, queued }) => {
console.log(Rate limited. Wait: ${waitTime}ms);
},
onDequeue: ({ waitedMs, remainingQueue }) => {
console.log(Request dequeued after ${waitedMs}ms);
}
}
});
`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| maxRequests | number | 50 | Maximum requests per time window |
| perMs | number | 1000 | Time window in milliseconds |
| perSecond | number | - | Shorthand for requests per second |
| perMinute | number | - | Shorthand for requests per minute |
| perHour | number | - | Shorthand for requests per hour |
| queue | boolean | false | Queue requests instead of rejecting |
| maxQueueSize | number | 100 | Maximum queue size |
| queueTimeout | number | 60000 | Queue timeout in milliseconds |
| algorithm | string | 'sliding-window' | Algorithm: 'sliding-window' or 'token-bucket' |
| burstLimit | number | null | Burst limit for token bucket algorithm |
| onThrottle | function | null | Callback when rate limited |
| onDequeue | function | null | Callback when request is dequeued |

Accessing the rate limiter:

`js
const limiter = client.getRateLimiter();
console.log(limiter.getRemainingRequests());
console.log(limiter.getQueueSize());

client.setRateLimit({ perSecond: 20 });

client.setRateLimit(null);
`

$3

Retry requests based on response body or header patterns:

`js
import { createClient } from 'stealth-io';

const client = createClient({
retry: {
maxRetries: 5,
matchBody: /temporarily unavailable/i
}
});
`

Full pattern retry options:

`js
const client = createClient({
retry: {
maxRetries: 5,
retryDelay: 1000,
maxRetryDelay: 30000,
retryStrategy: 'exponential',
matchBody: [/temporarily unavailable/i, /rate limit/i],
matchHeaders: { 'x-ratelimit-remaining': '0' },
matchStatus: [429, 500, 502, 503, 504],
matchAny: true,
excludeBody: /permanent error/i,
excludeHeaders: { 'x-no-retry': 'true' },
excludeStatus: [404, 401],
onRetry: ({ response, attempt, delay, reason }) => {
console.log(Retry ${attempt + 1}, reason: ${reason});
},
onPatternMatch: ({ response, attempt, result }) => {
console.log(Pattern matched: ${result.reason});
}
}
});
`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| maxRetries | number | 3 | Maximum retry attempts |
| retryDelay | number | 1000 | Base retry delay in milliseconds |
| maxRetryDelay | number | 30000 | Maximum retry delay |
| retryStrategy | string | 'exponential' | Backoff strategy |
| matchBody | RegExp\|string\|function\|array | - | Body patterns to trigger retry |
| matchHeaders | object | - | Header patterns to trigger retry |
| matchStatus | number\|array\|Set\|function | - | Status codes to trigger retry |
| matchAny | boolean | false | Retry if any pattern matches (default: all must match) |
| excludeBody | RegExp\|string\|function\|array | - | Body patterns to prevent retry |
| excludeHeaders | object | - | Header patterns to prevent retry |
| excludeStatus | number\|array\|Set | - | Status codes to prevent retry |
| onRetry | function | - | Callback on retry |
| onPatternMatch | function | - | Callback when pattern matches |

Pre-built patterns for common APIs:

`js
import { createClient, createApiSpecificPatterns } from 'stealth-io';

const discordPatterns = createApiSpecificPatterns('discord');
const client = createClient({
retry: {
maxRetries: 5,
...discordPatterns
}
});
`

Supported APIs: discord, twitter, shopify, github, stripe

Common pattern matchers:

`js
import { createCommonPatternMatchers } from 'stealth-io';

const patterns = createCommonPatternMatchers();

const client = createClient({
retry: {
maxRetries: 3,
matchBody: [
patterns.temporarilyUnavailable,
patterns.rateLimited,
patterns.maintenance,
patterns.overloaded
],
matchAny: true
}
});
`

Available patterns:
- temporarilyUnavailable - Matches "temporarily unavailable"
- rateLimited - Matches "rate limit", "too many requests", "throttle"
- maintenance - Matches "maintenance", "down for maintenance"
- overloaded - Matches "overloaded", "capacity", "try again later"
- serviceUnavailable - Matches "service unavailable", "503"
- timeout - Matches "timeout", "timed out"
- internalError - Matches "internal error", "unexpected error"
- badGateway - Matches "bad gateway", "502"
- gatewayTimeout - Matches "gateway timeout", "504"
- connectionError - Matches "connection refused", "connection reset"
- retryLater - Matches "retry", "try again", "come back later"

API

$3

- url A string representing the URL for the request
- options Options for the HTTP(S) request
- Returns: Promise

Perform an HTTP(S) request.

$3

The default values are shown after each option key.

`js
{
method: 'GET',
headers: {},
body: null,
timeout: 30000,
followRedirects: true,
maxRedirects: 5,
validateStatus: true,
maxRetries: 0,
retryDelay: 1000,
retryStrategy: 'exponential',
responseType: 'auto',
signal: null,
params: {},
auth: null,
baseURL: null,
rateLimit: null,
retry: null
}
`

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| method | string | 'GET' | HTTP method |
| headers | object | {} | Request headers |
| body | any | null | Request body |
| timeout | number | 30000 | Request timeout in milliseconds |
| followRedirects | boolean | true | Whether to follow redirects |
| maxRedirects | number | 5 | Maximum redirects to follow |
| validateStatus | boolean | true | Throw HTTPError on 4xx/5xx status |
| maxRetries | number | 0 | Number of retry attempts |
| retryDelay | number | 1000 | Base retry delay in milliseconds |
| retryStrategy | string | 'exponential' | Retry strategy: 'fixed', 'exponential', 'exponential_jitter' |
| responseType | string | 'auto' | Response type: 'auto', 'json', 'text', 'buffer', 'stream' |
| signal | AbortSignal | null | AbortSignal for cancellation |
| params | object | {} | URL query parameters |
| auth | object | null | Authentication { username, password } |
| baseURL | string | null | Base URL prepended to relative URLs |
| rateLimit | object | null | Rate limiting configuration |
| retry | object | null | Pattern-based retry configuration |

$3

The main client class for making HTTP requests.

#### new StealthClient([options])

- options Default Options for all requests

Creates a new StealthClient instance with default options.

`js
const client = new StealthClient({
baseURL: 'https://api.example.com',
timeout: 10000,
headers: { 'Authorization': 'Bearer token' }
});
`

#### client.get(url[, options])

- url Request URL
- options Request Options
- Returns: Promise

#### client.post(url[, body[, options]])

- url Request URL
- body Request body (automatically serialized if object)
- options Request Options
- Returns: Promise

#### client.put(url[, body[, options]])

#### client.patch(url[, body[, options]])

#### client.delete(url[, options])

#### client.head(url[, options])

#### client.use(middleware)

- middleware Middleware object or function
- Returns: StealthClient (for chaining)

Add middleware to the request pipeline.

#### client.getRateLimiter()

- Returns: RateLimiter | null

Get the rate limiter instance.

#### client.setRateLimit(config)

- config Rate limit configuration object or null to disable
- Returns: void

Update or disable rate limiting.

$3

An HTTP response object.

#### response.ok

- boolean

true if status is 200-299.

#### response.status

- number

HTTP status code.

#### response.statusText

- string

HTTP status message.

#### response.headers

- Headers

Response headers.

#### response.url

- string

Final URL after redirects.

#### response.json()

- Returns: Promise

Parse response body as JSON.

#### response.text()

- Returns: Promise

Get response body as string.

#### response.buffer()

- Returns: Promise

Get response body as Buffer.

#### response.stream()

- Returns: Readable

Get response body as Node.js Readable stream.

$3

HTTP headers with case-insensitive key access.

#### new Headers([init])

- init Optional object, Headers instance, or entries array

`js
import { Headers } from 'stealth-io';

const headers = new Headers({
'Content-Type': 'application/json',
'X-Custom-Header': 'value'
});

headers.get('content-type');
headers.set('Authorization', 'Bearer token');
headers.has('x-custom-header');
headers.delete('X-Custom-Header');
`

$3

Base error class for all Stealth-IO errors.

$3

Thrown when a request times out.

- error.timeout - The timeout value in milliseconds

$3

Thrown when a request is aborted via AbortSignal.

$3

Thrown for network-level errors (DNS, connection refused, etc).

- error.code - System error code (e.g., 'ECONNREFUSED')

$3

Thrown for HTTP error status codes when validateStatus is enabled.

- error.status - HTTP status code
- error.statusText - HTTP status message
- error.response - The StealthResponse object

$3

Thrown when all retry attempts are exhausted.

- error.attempts - Number of attempts made
- error.lastError - The last error encountered

$3

Thrown when rate limit is exceeded and queue is disabled.

- error.retryAfter - Suggested wait time in milliseconds
- error.queueSize - Current queue size

`js
import { createClient, RateLimitError } from 'stealth-io';

const client = createClient({
rateLimit: { maxRequests: 2, perMs: 1000, queue: false }
});

try {
await client.get('/endpoint');
} catch (error) {
if (error instanceof RateLimitError) {
console.log(Rate limited. Retry after ${error.retryAfter}ms);
}
}
`

Middleware

$3

`js
import {
createLoggingMiddleware,
createAuthMiddleware,
createCacheMiddleware,
createTimingMiddleware,
createHeadersMiddleware,
createErrorMiddleware
} from 'stealth-io';
`

Logging Middleware

`js
client.use(createLoggingMiddleware({
logger: console.log,
logRequest: true,
logResponse: true
}));
`

Auth Middleware

`js
client.use(createAuthMiddleware({
type: 'bearer',
token: 'your-token'
}));

client.use(createAuthMiddleware({
type: 'basic',
username: 'user',
password: 'pass'
}));
`

Cache Middleware

`js
client.use(createCacheMiddleware({
ttl: 60000,
maxSize: 100
}));
`

Timing Middleware

`js
client.use(createTimingMiddleware({
onTiming: (timing) => console.log(Request took ${timing.duration}ms)
}));
`

$3

`js
client.use({
name: 'custom-middleware',
onRequest(config) {
config.headers.set('X-Request-ID', generateUUID());
return config;
},
onResponse(response, config) {
console.log(Response received: ${response.status});
return response;
},
onError(error, config) {
console.error(Request failed: ${error.message});
return null;
}
});
`

Testing

`sh
npm test
npm run test:coverage
`

Architecture

`
stealth-io/
src/
core/ # Constants, symbols, and error classes
utils/ # Utility functions (headers, query, url, streams)
types/ # Request and response type definitions
http/ # Transport, abort, retry, rate-limiter, pattern-retry
middleware/ # Middleware pipeline and built-in middleware
client/ # Main StealthClient class
index.js # Main entry point
test/ # Jest tests
``

Team

|  |
| ------------------------------------------------------------------------------------ |
| channdev |

Lead Author

Contributing

See CONTRIBUTING.md for details on how to contribute to this project.

License

MIT