Response Schema

Every Rezo request resolves to a response object. Standard requests return a RezoResponse<T>. Streaming, download, and upload operations return event-emitting response objects.

RezoResponse<T>

The standard response object returned by get, post, put, patch, delete, head, options, trace, and request.

const response = await rezo.get<User[]>('https://api.example.com/users');

data

T — The response body, parsed according to the responseType option. When responseType is 'auto' (default), JSON responses are parsed to objects, text responses return strings, and binary responses return Buffers.

const { data } = await rezo.get<User[]>('/users');
// data is User[]

const { data } = await rezo.get('/page', { responseType: 'text' });
// data is string

const { data } = await rezo.get('/image.png', { responseType: 'buffer' });
// data is Buffer

status

number — The HTTP status code (e.g., 200, 404, 500).

if (response.status === 200) {
  console.log('Success');
}

statusText

string — The HTTP status text (e.g., "OK", "Not Found").

console.log(response.statusText); // "OK"

headers

RezoHeaders — The response headers, with convenience methods for common operations.

// Standard Headers API
response.headers.get('content-type');
response.headers.has('x-request-id');

// Iterate all headers
for (const [name, value] of response.headers) {
  console.log(`${name}: ${value}`);
}

// Convert to plain object
const obj = response.headers.toObject();

cookies

Cookies — Response cookies parsed from Set-Cookie headers, available in five formats for different use cases.

// Array of Cookie instances (for programmatic access)
response.cookies.array.forEach(cookie => {
  console.log(cookie.key, cookie.value, cookie.domain);
});

// Serialized plain objects (for JSON storage)
const json = JSON.stringify(response.cookies.serialized);

// Netscape format string (for file-based storage)
fs.writeFileSync('cookies.txt', response.cookies.netscape);

// Cookie header string (for sending in requests)
// Format: "key=value; key2=value2"
console.log(response.cookies.string);

// Array of Set-Cookie header strings
response.cookies.setCookiesString.forEach(header => {
  console.log(header);
  // "session=abc123; Domain=example.com; Path=/; HttpOnly"
});

config

RezoConfig — The resolved configuration that was used for the request. Includes merged defaults and per-request options.

console.log(response.config.method);   // "GET"
console.log(response.config.url);      // "https://api.example.com/users"
console.log(response.config.timeout);  // 5000

contentType

string | undefined — The Content-Type header value, or undefined if not present.

if (response.contentType?.includes('application/json')) {
  // response.data is parsed JSON
}

contentLength

number — The Content-Length header parsed as a number. 0 when not present.

console.log(`Response size: ${response.contentLength} bytes`);

finalUrl

string — The final URL after all redirects. Same as the request URL when no redirects occurred.

const response = await rezo.get('https://example.com/old-page');
console.log(response.finalUrl);
// "https://example.com/new-page" (after 301 redirect)

urls

string[] — The complete URL chain including the initial request URL and all intermediate redirect URLs.

const response = await rezo.get('https://short.url/abc');
console.log(response.urls);
// ["https://short.url/abc", "https://example.com/redirect", "https://example.com/final"]

RezoStreamResponse

Returned by rezo.stream(). An event emitter that delivers the response body in chunks as they arrive from the server. Does not buffer the entire response in memory.

const stream = rezo.stream('https://example.com/large-file');

Events

data

Emitted for each chunk of the response body.

stream.on('data', (chunk: Uint8Array | string) => {
  process.stdout.write(chunk);
});

start

Emitted when the request begins.

stream.on('start', (info) => {
  console.log('Request started at:', info.timestamp);
});

initiated

Emitted when the connection is established.

stream.on('initiated', () => {
  console.log('Connection established');
});

headers

Emitted when response headers are received, before any body data.

stream.on('headers', (info) => {
  console.log('Status:', info.status, info.statusText);
  console.log('Content-Type:', info.headers.get('content-type'));
  console.log('Content-Length:', info.contentLength);
});

status

Emitted with the HTTP status code and text.

stream.on('status', (status: number, statusText: string) => {
  console.log(`${status} ${statusText}`);
});

cookies

Emitted with parsed cookies from the response.

stream.on('cookies', (cookies: Cookie[]) => {
  cookies.forEach(c => console.log(c.key, c.value));
});

redirect

Emitted for each redirect before it is followed.

stream.on('redirect', (info) => {
  console.log('Redirecting to:', info.url);
});

progress

Emitted periodically with transfer progress.

stream.on('progress', (progress) => {
  console.log(`${progress.percent}% (${progress.transferred}/${progress.total})`);
});

finish / done

Emitted when the stream completes. Both event names fire with the same payload.

stream.on('finish', (info) => {
  console.log('Total bytes received:', info.totalBytes);
  console.log('Duration:', info.duration, 'ms');
});

error

Emitted when an error occurs.

stream.on('error', (err: RezoError) => {
  console.error(err.code, err.message);
});

Methods

isFinished()

Returns true if the stream has completed.

if (stream.isFinished()) {
  console.log('Stream already done');
}

setEncoding(encoding)

Sets the character encoding for string chunks.

stream.setEncoding('utf-8');
stream.on('data', (chunk: string) => {
  // chunk is now a string, not Uint8Array
});

RezoDownloadResponse

Returned by rezo.download(). An event emitter that streams the response body directly to a file on disk.

const download = rezo.download('https://example.com/file.zip', './file.zip');

Properties

Events

The download response emits the same event set as RezoStreamResponse except that data is not emitted (the data goes directly to file). The key events are:

• start — Request initiated
• initiated — Connection established
• headers — Response headers received
• status — HTTP status code received
• cookies — Response cookies parsed
• redirect — Redirect encountered
• progress — Transfer progress (percent, transferred, total)
• finish / done — Download complete
• error — Error occurred

const download = rezo.download('https://example.com/archive.tar.gz', './archive.tar.gz');

download.on('headers', (info) => {
  console.log('File size:', info.contentLength, 'bytes');
});

download.on('progress', (p) => {
  const bar = '='.repeat(Math.floor(p.percent / 2));
  process.stdout.write(`
[${bar.padEnd(50)}] ${p.percent}%`);
});

download.on('finish', (info) => {
  console.log('
Download complete:', info.filePath);
});

download.on('error', (err) => {
  console.error('Download failed:', err.message);
});

RezoUploadResponse

Returned by rezo.upload(). An event emitter that tracks upload progress and delivers the server’s response.

const upload = rezo.upload('https://api.example.com/upload', fileBuffer);

Properties

Events

Same event set as download, with progress tracking the upload direction:

• start — Request initiated
• initiated — Connection established
• headers — Response headers received
• status — HTTP status code received
• cookies — Response cookies parsed
• redirect — Redirect encountered
• progress — Upload progress (percent, transferred, total)
• finish / done — Upload complete (includes server response body)
• error — Error occurred

const upload = rezo.upload('https://api.example.com/files', largeBuffer);

upload.on('progress', (p) => {
  console.log(`Uploading: ${p.percent}%`);
});

upload.on('finish', (info) => {
  console.log('Server response status:', info.status);
  console.log('Server response body:', info.data);
});

upload.on('error', (err) => {
  console.error('Upload failed:', err.code, err.message);
});

Type Summary

import type {
  RezoResponse,
  RezoStreamResponse,
  RezoDownloadResponse,
  RezoUploadResponse
} from 'rezo';