@http-client-toolkit/core

Core HTTP client with pluggable caching, deduplication, and rate limiting. Part of the http-client-toolkit monorepo.

Installation

npm install @http-client-toolkit/core

Requires Node.js >= 20.

You'll also need at least one store backend:

npm install @http-client-toolkit/store-memory
# or
npm install @http-client-toolkit/store-sqlite

Quick Start

import { HttpClient } from '@http-client-toolkit/core';
import {
  InMemoryCacheStore,
  InMemoryDedupeStore,
  InMemoryRateLimitStore,
} from '@http-client-toolkit/store-memory';

const client = new HttpClient({
  name: 'example-api',
  cache: new InMemoryCacheStore(),
  dedupe: new InMemoryDedupeStore(),
  rateLimit: new InMemoryRateLimitStore(),
  cacheTTL: 300,
});

const data = await client.get<{ name: string }>(
  'https://api.example.com/user/1',
);

Every store is optional. Use only what you need:

// Cache-only client
const client = new HttpClient({
  name: 'cached',
  cache: new InMemoryCacheStore(),
});

// Rate-limited client with no caching
const client = new HttpClient({
  name: 'rate-limited',
  rateLimit: new InMemoryRateLimitStore({
    defaultConfig: { limit: 100, windowMs: 60_000 },
  }),
});

Recommended Usage

Create a thin wrapper module per third-party API so callers don't configure anything and per-request tuning lives in one place. See the Recommended Usage guide for a full walkthrough.

API

new HttpClient(options)

HttpClient exposes a single request method: get(url, options?). The url must be an absolute URL.

Request options (client.get)

Constructor options:

Request Flow

1. Cache - Return cached response if available
2. Dedupe - If an identical request is already in-flight, wait for its result
3. Rate Limit - Wait or throw if the rate limit is exceeded
4. Fetch - Execute the HTTP request
5. Transform & Validate - Apply responseTransformer then responseHandler
6. Store - Cache the result, record the rate limit hit, and resolve any deduplicated waiters

Error Handling

All HTTP errors are wrapped in HttpClientError:

import { HttpClientError } from '@http-client-toolkit/core';

try {
  await client.get(url);
} catch (error) {
  if (error instanceof HttpClientError) {
    console.log(error.message);
    console.log(error.statusCode);
  }
}

Cancellation

Pass an AbortSignal to cancel a request, including while waiting for a rate limit window:

const controller = new AbortController();
const data = await client.get(url, { signal: controller.signal });
controller.abort();

Header-Based Rate Limiting

HttpClient respects server-provided rate-limit headers out of the box:

• Retry-After
• RateLimit-Remaining / RateLimit-Reset
• X-RateLimit-Remaining / X-RateLimit-Reset

Map non-standard header names per API:

const client = new HttpClient({
  name: 'custom-api',
  rateLimitHeaders: {
    retryAfter: ['RetryAfterSeconds'],
    remaining: ['Remaining-Requests'],
    reset: ['Window-Reset-Seconds'],
  },
});

Custom Rate-Limit Buckets

Use resourceKeyResolver when list and retrieve routes should share the same rate-limit bucket:

const client = new HttpClient({
  name: 'issues-api',
  resourceKeyResolver: (url) => {
    const path = new URL(url).pathname;
    if (path === '/api/issues' || path.startsWith('/api/issue/')) {
      return 'issues';
    }
    return new URL(url).origin;
  },
  rateLimit: {
    store: rateLimitStore,
  },
});

rateLimit.resourceExtractor is deprecated and kept temporarily for backward compatibility.

Exports

• HttpClient - Main client class
• HttpClientError - Error class with statusCode
• hashRequest - Deterministic SHA-256 request hashing
• Store interfaces: CacheStore, DedupeStore, RateLimitStore, AdaptiveRateLimitStore

License

ISC