Defaults

Instance-level defaults are applied to every request made by that instance. They are set when constructing a Rezo instance and can be modified at any time via the defaults property. Per-request options always take precedence over defaults.

Setting Defaults

At Construction

import { Rezo } from 'rezo';

const client = new Rezo({
  baseURL: 'https://api.example.com/v2',
  timeout: 10000,
  headers: { 'Authorization': 'Bearer token123' },
  responseType: 'json',
  retry: 3,
  cache: true
});

After Construction

client.defaults.timeout = 15000;
client.defaults.headers = {
  ...client.defaults.headers as Record<string, string>,
  'X-Custom': 'value'
};

Via create() or extend()

import rezo from 'rezo';

// Fresh instance with defaults
const api = rezo.create({
  baseURL: 'https://api.example.com',
  timeout: 5000
});

// Child inheriting + extending parent defaults
const authed = api.extend({
  headers: { 'Authorization': 'Bearer token123' }
});

RezoDefaultOptions Reference

baseURL

string — Prepended to relative URLs in all requests.

{
  baseURL: 'https://api.example.com/v2'
}
// client.get('/users') requests https://api.example.com/v2/users

headers

Request headers applied to every request. Accepts the same formats as per-request headers: plain object, array of tuples, Headers, or RezoHeaders.

{
  headers: {
    'Accept': 'application/json',
    'Authorization': 'Bearer token123',
    'X-App-Version': '2.0.0'
  }
}

hooks

Lifecycle hooks for intercepting and modifying request/response behavior. All hooks are optional.

{
  hooks: {
    init: [(options) => {
      // Called synchronously after config is created
    }],
    beforeRequest: [async (options, context) => {
      // Modify options before sending
      // Return a response object to short-circuit (mock)
    }],
    afterResponse: [async (response, config, context) => {
      // Transform or inspect the response
      return response;
    }],
    beforeError: [async (error) => {
      // Transform errors before they are thrown
      return error;
    }],
    beforeCache: [(cacheEvent) => {
      // Return false to prevent caching this response
    }],
    beforeRedirect: [(options) => {
      // Called before following a redirect
    }]
  }
}

Hooks set on the instance are merged with per-request hooks. Instance hooks run first.

responseType

ResponseType — Default response parsing mode. One of 'auto', 'json', 'text', 'buffer', 'arrayBuffer', or 'blob'. Default is 'auto'.

{
  responseType: 'json'
}

timeout

number — Default timeout in milliseconds for all requests. No timeout by default.

{
  timeout: 10000  // 10 seconds
}

retry

Default retry configuration for failed requests. Applied to all requests unless overridden per-request.

// Simple count
{ retry: 3 }

// Full configuration
{
  retry: {
    limit: 3,
    delay: 1000,
    backoff: 2,
    retryOn: [408, 429, 500, 502, 503, 504],
    retryOnTimeout: true,
    retryOnNetworkError: true,
    methods: ['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE']
  }
}

proxy

Default proxy for all requests. Accepts a URL string or a detailed proxy options object.

// URL string
{ proxy: 'http://proxy.example.com:8080' }

// Detailed options
{
  proxy: {
    protocol: 'socks5',
    host: '127.0.0.1',
    port: 1080,
    auth: { username: 'user', password: 'pass' }
  }
}

proxyManager

Advanced proxy rotation and pool management. Provide a ProxyManager instance or a config object to create one internally. When set, the proxy manager overrides the proxy option.

import { ProxyManager } from 'rezo';

// Config object (auto-creates ProxyManager)
{
  proxyManager: {
    rotation: 'random',
    proxies: [
      { protocol: 'http', host: 'proxy1.example.com', port: 8080 },
      { protocol: 'socks5', host: '127.0.0.1', port: 1080 }
    ],
    whitelist: ['api.example.com'],
    autoDisableDeadProxies: true
  }
}

// Pre-created ProxyManager instance
{
  proxyManager: new ProxyManager({
    rotation: 'sequential',
    proxies: [...]
  })
}

cache

Response and DNS caching configuration.

// Enable both response and DNS caching with defaults
{ cache: true }

// Fine-grained control
{
  cache: {
    response: {
      enable: true,
      ttl: 300000,       // 5 minutes
      maxEntries: 500
    },
    dns: true
  }
}

// Response cache only
{
  cache: {
    response: true,
    dns: false
  }
}

Response cache defaults: 30 minute TTL, 500 entries, GET/HEAD methods only. DNS cache defaults: 1 minute TTL, 1000 entries.

stealth

Browser fingerprint stealth configuration. Must be a RezoStealth instance. Set at the instance level only.

import { RezoStealth } from 'rezo';

// Specific browser profile
{
  stealth: new RezoStealth({ profile: 'chrome-131' })
}

// Random profile from a family
{
  stealth: new RezoStealth({ family: 'chrome' })
}

// Rotate identity per request
{
  stealth: new RezoStealth({ family: 'chrome', rotate: true })
}

When stealth is configured, Rezo automatically applies realistic browser headers (User-Agent, sec-ch-ua, sec-fetch-*, etc.) to every request. User-set headers always take priority over stealth defaults.

debug

boolean — Enable debug logging for all requests from this instance.

{ debug: true }

Cookie Options

jar

A RezoCookieJar instance for managing cookies across requests.

import { RezoCookieJar } from 'rezo';

{ jar: new RezoCookieJar() }

disableJar

boolean — Disable automatic cookie handling. Default is false.

{ disableJar: true }

cookies

Default cookies to send with every request. Accepts the same formats as per-request cookies.

{
  cookies: ['session=abc123; Domain=example.com; Path=/']
}

cookieFile

Path to a cookie file for automatic persistence. JSON files save cookies as serialized objects. Text files use Netscape format. Cookies are loaded at construction and saved after each request.

{ cookieFile: './cookies.json' }
{ cookieFile: './cookies.txt' }

Queue Options

queue

Request queue for concurrency control, rate limiting, and priority scheduling.

import { RezoHttpQueue } from 'rezo';

// Config object (auto-creates queue)
{ queue: { concurrency: 5 } }

// HTTP-aware queue with domain concurrency
{ queue: { concurrency: 10, domainConcurrency: 2 } }

// Pre-created queue instance
{
  queue: new RezoHttpQueue({
    concurrency: 10,
    domainConcurrency: 2,
    retryOnRateLimit: true
  })
}

Other Defaults

mergeConfig()

Deep-merges two configuration objects. Headers and params are merged (not replaced). Properties from the second config take precedence.

import { Rezo } from 'rezo';

const merged = Rezo.mergeConfig(
  { baseURL: 'https://api.example.com', headers: { 'Accept': 'application/json' }, timeout: 5000 },
  { headers: { 'Authorization': 'Bearer token' }, timeout: 10000 }
);

// Result:
// {
//   baseURL: 'https://api.example.com',
//   headers: { 'Accept': 'application/json', 'Authorization': 'Bearer token' },
//   timeout: 10000
// }

Also available on the default instance:

import rezo from 'rezo';

const merged = rezo.mergeConfig(config1, config2);

How Defaults Cascade

Rezo applies configuration in this order, with later sources overriding earlier ones:

1. Library defaults — Built-in values (e.g., followRedirects: true, validateStatus: 200-299)
2. Instance defaults — Set via new Rezo(config) or rezo.create(config)
3. Per-request options — Passed to get(url, options), post(url, data, options), etc.

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

// Per-request timeout overrides instance default
const response = await client.get('/users', {
  timeout: 3000           // This request uses 3s timeout
});

// Per-request headers are merged with instance headers
const response = await client.get('/users', {
  headers: { 'X-Request-Id': 'abc123' }
  // Sends both Accept and X-Request-Id
});

For extend(), the cascade adds a layer:

1. Library defaults
2. Parent instance defaults
3. Child instance defaults (merged with parent via mergeConfig)
4. Per-request options

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

const child = parent.extend({
  timeout: 5000,
  headers: { 'Authorization': 'Bearer token' }
});

// child.defaults = {
//   baseURL: 'https://api.example.com',
//   timeout: 5000,
//   headers: { 'Accept': 'application/json', 'Authorization': 'Bearer token' }
// }