@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(
  {
    cache: new InMemoryCacheStore(),
    dedupe: new InMemoryDedupeStore(),
    rateLimit: new InMemoryRateLimitStore(),
  },
  { defaultCacheTTL: 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({ cache: new InMemoryCacheStore() });

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

API

new HttpClient(stores?, options?)

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

Request options (client.get)

Stores:

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(
  {},
  {
    rateLimitHeaders: {
      retryAfter: ['RetryAfterSeconds'],
      remaining: ['Remaining-Requests'],
      reset: ['Window-Reset-Seconds'],
    },
  },
);

Exports

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

License

ISC