Instances

Rezo provides multiple ways to create HTTP client instances. You can use the pre-configured default export, create new instances with custom configuration, derive child instances that inherit parent defaults, or import adapter-specific builds for tree-shaking.

Default Instance

The default export from rezo is a pre-configured instance using the HTTP adapter. It is callable as a function and has all HTTP methods attached.

import rezo from 'rezo';

// Use as a function (Fetch API style)
const response = await rezo('https://api.example.com/users');

// Use named methods
const response = await rezo.get('https://api.example.com/users');
await rezo.postJson('https://api.example.com/users', { name: 'Alice' });

Creating Instances with `new Rezo()`

The Rezo class constructor accepts an optional defaults configuration object and an optional adapter function.

import { Rezo } from 'rezo';

const client = new Rezo({
  baseURL: 'https://api.example.com/v2',
  timeout: 10000,
  headers: { 'Accept': 'application/json' }
});

const response = await client.get('/users');
// Requests go to https://api.example.com/v2/users with 10s timeout

With a Custom Adapter

Pass an adapter as the second argument to control which HTTP transport is used.

import { Rezo } from 'rezo';
import { executeRequest as fetchAdapter } from 'rezo/adapters/fetch';

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

Constructor Signature

new Rezo(config?: RezoDefaultOptions, adapter?: AdapterFunction)

config — Instance-level default options applied to every request. See Defaults.
adapter — The HTTP adapter function. When omitted, the global adapter is used (set automatically when importing from rezo).

Creating Instances with `rezo.create()`

The default instance exposes a create() method that returns a new Rezo instance sharing the same adapter.

import rezo from 'rezo';

const api = rezo.create({
  baseURL: 'https://api.example.com/v2',
  timeout: 5000,
  headers: {
    'Authorization': 'Bearer my-token'
  }
});

const users = await api.get('/users');
const posts = await api.get('/posts');

Note that create() starts fresh — it does not inherit the parent’s defaults. To chain defaults, use extend().

Extending Instances with `extend()`

The extend() method creates a child instance that inherits all defaults from the parent, merged with new options. This is useful for building layered configurations.

import rezo from 'rezo';

// Base API client
const api = rezo.create({
  baseURL: 'https://api.example.com',
  timeout: 10000
});

// Authenticated child -- inherits baseURL and timeout
const authed = api.extend({
  headers: { 'Authorization': 'Bearer my-token' }
});

// Admin child -- inherits everything from authed
const admin = authed.extend({
  headers: { 'X-Admin-Key': 'secret' }
});

// admin has: baseURL, timeout, Authorization header, and X-Admin-Key header
const response = await admin.get('/admin/users');

Headers and params are deep-merged — keys from the child override the parent, but other keys are preserved.

const parent = rezo.create({
  headers: { 'Accept': 'application/json', 'X-Tracking': 'enabled' }
});

const child = parent.extend({
  headers: { 'Accept': 'text/html' }
});

// child.defaults.headers = { 'Accept': 'text/html', 'X-Tracking': 'enabled' }

The `createRezoInstance()` Factory

For advanced use cases, createRezoInstance() creates a callable instance (like the default export) from a specific adapter and config.

import { createRezoInstance } from 'rezo';
import { executeRequest } from 'rezo/adapters/fetch';

const fetchClient = createRezoInstance(executeRequest, {
  baseURL: 'https://api.example.com',
  timeout: 5000
});

// Callable as a function
const response = await fetchClient('https://api.example.com/users');

// And via named methods
const response = await fetchClient.get('/users');

// Has static helpers attached
fetchClient.isRezoError(error);
fetchClient.mergeConfig(config1, config2);

The returned RezoInstance is both a function and an object with all Rezo methods. It also includes compatibility helpers: create, mergeConfig, isRezoError, isCancel, Cancel, CancelToken, all, and spread.

Per-Adapter Imports

Import directly from an adapter entry point for explicit adapter selection and better tree-shaking.

// Node.js HTTP adapter (default)
import { Rezo } from 'rezo/adapters/http';

// Fetch API adapter (browsers, Deno, edge runtimes)
import { Rezo } from 'rezo/adapters/fetch';

Each adapter entry point exports a Rezo class pre-configured with that adapter. No global adapter setup is needed.

import { Rezo } from 'rezo/adapters/fetch';

const client = new Rezo({
  baseURL: 'https://api.example.com',
  timeout: 5000
});

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

Session IDs

Every Rezo instance has a unique sessionId that persists across all requests from that instance. This is useful for correlating requests in logs and debugging.

const client = new Rezo({ baseURL: 'https://api.example.com' });
console.log(client.sessionId);
// "ses_1711234567890_a1b2c3d4e"

// The session ID is injected into every request's internal config

The session ID is generated when the instance is constructed and never changes. Different instances always have different session IDs.

Instance Lifecycle

destroy()

Call destroy() when an instance is no longer needed to clean up internal resources. This is primarily important when using a ProxyManager, which maintains timers and state.

import { Rezo } from 'rezo';
import { ProxyManager } from 'rezo';

const client = new Rezo({
  proxyManager: {
    rotation: 'random',
    proxies: [
      { protocol: 'http', host: 'proxy1.example.com', port: 8080 },
      { protocol: 'http', host: 'proxy2.example.com', port: 8080 }
    ]
  }
});

// ... use client ...

// Clean up timers and proxy state
client.destroy();

If you are not using a ProxyManager, destroy() is a no-op and calling it is optional.

Every instance maintains a cookie jar. Access it via the jar property.

const client = new Rezo();

// Get the jar
const jar = client.jar;

// Replace the jar
import { RezoCookieJar } from 'rezo';
client.jar = new RezoCookieJar();

// Set cookies
client.setCookies([
  'session=abc123; Domain=example.com; Path=/'
], 'https://example.com');

// Get cookies
const cookies = client.getCookies('https://example.com');
console.log(cookies.string);  // "session=abc123"

// Save cookies to file
client.saveCookies('./cookies.json');

Cache Access

When caching is enabled, instances expose cache management methods.

const client = new Rezo({ cache: true });

// Clear all caches
client.clearCache();

// Invalidate a specific URL
client.invalidateCache('https://api.example.com/users');

// Get cache statistics
const stats = client.getCacheStats();
console.log(stats.response?.size);  // Number of cached responses
console.log(stats.dns?.size);       // Number of cached DNS entries

Complete Example

import rezo, { Rezo, RezoCookieJar } from 'rezo';

// Shared cookie jar across instances
const jar = new RezoCookieJar();

// Base client
const api = new Rezo({
  baseURL: 'https://api.example.com/v2',
  timeout: 10000,
  jar,
  cache: true,
  headers: { 'Accept': 'application/json' }
});

// Service-specific clients
const users = api.extend({
  baseURL: 'https://api.example.com/v2/users',
  headers: { 'X-Service': 'users' }
});

const billing = api.extend({
  baseURL: 'https://api.example.com/v2/billing',
  headers: { 'X-Service': 'billing' }
});

// Use them
const userList = await users.get('/');
const invoices = await billing.get('/invoices');

// Cleanup
api.destroy();