RezoFormData

RezoFormData is a universal FormData wrapper that works across Node.js 18+, Bun, Deno, browsers, Cloudflare Workers, and edge runtimes. It provides synchronous content-type access, buffer conversion, and static factory methods.

Constructor

new RezoFormData()

Creates an empty form data instance with a pre-generated boundary string.

Example

import { RezoFormData } from 'rezo';

const form = new RezoFormData();
form.append('username', 'alice');
form.append('avatar', new Blob([imageData]), 'avatar.png');

Data Manipulation

append(name, value, filename?)

Appends a field to the form data. Supports strings, Blobs, and Buffers.

append(name: string, value: string | Blob | Buffer, filename?: string): void

set(name, value, filename?)

Sets a field, replacing any existing field with the same name.

set(name: string, value: string | Blob | Buffer, filename?: string): void

get(name)

Returns the first value for the given field name.

get(name: string): FormDataEntryValue | null

getAll(name)

Returns all values for the given field name.

getAll(name: string): FormDataEntryValue[]

has(name)

Returns true if a field with the given name exists.

has(name: string): boolean

delete(name)

Removes all values for the given field name.

delete(name: string): void

Example

const form = new RezoFormData();

form.append('tags', 'javascript');
form.append('tags', 'typescript');

console.log(form.get('tags'));     // "javascript"
console.log(form.getAll('tags'));  // ["javascript", "typescript"]
console.log(form.has('tags'));     // true

form.set('tags', 'node');          // Replaces all "tags" values
console.log(form.getAll('tags')); // ["node"]

form.delete('tags');
console.log(form.has('tags'));     // false

Iteration

entries()

entries(): IterableIterator<[string, FormDataEntryValue]>

keys()

keys(): IterableIterator<string>

values()

values(): IterableIterator<FormDataEntryValue>

forEach(callback)

forEach(callback: (value: FormDataEntryValue, key: string, parent: FormData) => void): void

Symbol.iterator

[Symbol.iterator](): IterableIterator<[string, FormDataEntryValue]>

Example

const form = new RezoFormData();
form.append('name', 'Alice');
form.append('role', 'admin');

for (const [key, value] of form) {
  console.log(`${key}: ${value}`);
}

form.forEach((value, key) => {
  console.log(`${key} = ${value}`);
});

Native Conversion

toNativeFormData()

Returns the underlying native FormData instance.

toNativeFormData(): FormData

Boundary and Content-Type

getBoundary()

Returns the multipart boundary string. Returns an empty string if getContentTypeAsync() has not been called yet; after that returns the boundary from the cached Content-Type.

getBoundary(): string

getContentType()

Returns the content type synchronously. Uses a generated boundary if no async build has occurred.

getContentType(): string

const form = new RezoFormData();
form.append('field', 'value');
console.log(form.getContentType());
// "multipart/form-data; boundary=----RezoFormBoundary..."

getContentTypeAsync()

Returns the content type with the actual boundary from the runtime’s FormData serialization.

async getContentTypeAsync(): Promise<string>

Headers

getHeaders()

Returns headers synchronously. Returns an empty object if no async build has occurred.

getHeaders(): Record<string, string>

getHeadersAsync()

Returns complete headers including content-type and content-length.

async getHeadersAsync(): Promise<Record<string, string>>

Example

const form = new RezoFormData();
form.append('file', new Blob(['hello']), 'test.txt');

const headers = await form.getHeadersAsync();
// { 'content-type': 'multipart/form-data; boundary=...', 'content-length': '189' }

Length

getLengthSync()

Returns the body length synchronously from cache, or undefined if not yet computed.

getLengthSync(): number | undefined

getLength()

Returns the body length asynchronously. Triggers a build if needed.

async getLength(): Promise<number>

Buffer / Binary Conversion

getBuffer()

Returns the body as a Buffer synchronously from cache. Returns null if not available.

getBuffer(): Buffer | null

Node.js/Bun/Deno only. Returns null in browser environments.

toBuffer()

Returns the body as a Buffer asynchronously.

async toBuffer(): Promise<Buffer>

toArrayBuffer()

Returns the body as an ArrayBuffer. Works in all environments.

async toArrayBuffer(): Promise<ArrayBuffer>

toUint8Array()

Returns the body as a Uint8Array. Works in all environments.

async toUint8Array(): Promise<Uint8Array>

Example

const form = new RezoFormData();
form.append('data', 'hello world');

const buffer = await form.toBuffer();
const arrayBuffer = await form.toArrayBuffer();
const uint8 = await form.toUint8Array();

URL Encoding

toUrlQueryString()

Converts string-only fields to a URL query string. Binary data is omitted.

toUrlQueryString(): string

toURLSearchParams()

Converts string-only fields to a URLSearchParams instance. Binary data is omitted.

toURLSearchParams(): URLSearchParams

Example

const form = new RezoFormData();
form.append('name', 'Alice');
form.append('age', '30');

console.log(form.toUrlQueryString()); // "name=Alice&age=30"

const params = form.toURLSearchParams();
console.log(params.get('name')); // "Alice"

Static Methods

RezoFormData.fromObject(obj, options?)

Creates a RezoFormData from a plain object. Nested objects and arrays are JSON-encoded by default. Pass nestedKeys: true to use bracket notation instead.

static fromObject(obj: Record<string, unknown>, options?: { nestedKeys?: boolean }): RezoFormData

Example

// Default: JSON-encode nested values
const form1 = RezoFormData.fromObject({
  name: 'Alice',
  tags: ['a', 'b'],
  meta: { role: 'admin' }
});
// tags = '["a","b"]', meta = '{"role":"admin"}'

// With bracket notation
const form2 = RezoFormData.fromObject({
  name: 'Alice',
  tags: ['a', 'b'],
  meta: { role: 'admin' }
}, { nestedKeys: true });
// tags[0] = 'a', tags[1] = 'b', meta[role] = 'admin'

// File descriptor
const form3 = RezoFormData.fromObject({
  avatar: { value: new Blob([data]), filename: 'photo.jpg', contentType: 'image/jpeg' }
});

RezoFormData.createUrlEncoded(data)

Creates a URL-encoded string from a plain object. Suitable for application/x-www-form-urlencoded form POST bodies.

static createUrlEncoded(data: Record<string, string | number | boolean>): string

Example

const body = RezoFormData.createUrlEncoded({
  grant_type: 'client_credentials',
  client_id: 'abc',
  client_secret: 'xyz'
});
// "grant_type=client_credentials&client_id=abc&client_secret=xyz"

RezoFormData.fromNativeFormData(formData)

Creates a RezoFormData from a native FormData instance.

static fromNativeFormData(formData: FormData): RezoFormData

Example

const native = new FormData();
native.append('field', 'value');

const rezoForm = RezoFormData.fromNativeFormData(native);