Quick Start

This guide walks you through setting up an HTTP client with caching, deduplication, and rate limiting.

Basic Setup

The simplest way to get started is with in-memory stores:

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

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

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

Use Only What You Need

Every store is optional. Pick the concerns you care about:

const client = new HttpClient({
  name: 'my-api',
  cache: { store: new InMemoryCacheStore() },
});

const client = new HttpClient({
  name: 'my-api',
  rateLimit: {
    store: new InMemoryRateLimitStore({
      defaultConfig: { limit: 100, windowMs: 60_000 },
    }),
  },
});

const client = new HttpClient({
  name: 'my-api',
  cache: { store: new InMemoryCacheStore() },
  dedupe: new InMemoryDedupeStore(),
});

Persistent Storage

For data that should survive process restarts, use SQLite stores:

import { HttpClient } from '@http-client-toolkit/core';
import { createSQLiteStores } from '@http-client-toolkit/store-sqlite';

const stores = createSQLiteStores({ database: './app.db' });

const client = new HttpClient({
  name: 'my-api',
  cache: { store: stores.cache },
  dedupe: stores.dedupe,
  rateLimit: { store: stores.rateLimit },
});

// Cleanup
await stores.close();

Distributed / Serverless

For multi-instance or serverless environments, use DynamoDB stores:

import { HttpClient } from '@http-client-toolkit/core';
import { createDynamoDBStores } from '@http-client-toolkit/store-dynamodb';

const stores = createDynamoDBStores({ region: 'us-east-1' });

const client = new HttpClient({
  name: 'my-api',
  cache: { store: stores.cache },
  dedupe: stores.dedupe,
  rateLimit: { store: stores.rateLimit },
});

// Cleanup
await stores.close();

Full Example

Here’s a more complete example using SQLite with adaptive rate limiting, response transformation, and error handling:

import { HttpClient, HttpClientError } from '@http-client-toolkit/core';
import { createSQLiteStores } from '@http-client-toolkit/store-sqlite';

const stores = createSQLiteStores({
  database: './http-store.db',
  rateLimit: {
    defaultConfig: { limit: 200, windowMs: 3_600_000 },
  },
});

const client = new HttpClient({
  name: 'my-api',
  cache: { store: stores.cache, ttl: 600 },
  dedupe: stores.dedupe,
  rateLimit: {
    store: stores.adaptiveRateLimit,
    throw: false,
    maxWaitTime: 30_000,
  },
  responseTransformer: (data) => data,
});

try {
  // User-initiated request — gets higher rate limit allocation
  const user = await client.get<{ name: string }>(
    'https://api.example.com/user/1',
    { priority: 'user' },
  );

  // Background sync — lower priority
  const items = await client.get<Array<{ id: number }>>(
    'https://api.example.com/items',
    { priority: 'background' },
  );
} catch (error) {
  if (error instanceof HttpClientError) {
    console.error(error.message, error.statusCode);
  }
}