or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

browser-polyfill.mdconversion-utilities.mdindex.mdnode-esm.md
tile.json

index.mddocs/

FormData Polyfill

FormData Polyfill provides a comprehensive HTML5 FormData implementation that enables consistent FormData functionality across browsers and Node.js environments. It offers a spec-compatible implementation that normalizes FormData support across platforms, including complete method support, iterator functionality, and proper file handling.

Package Information

  • Package Name: formdata-polyfill
  • Package Type: npm
  • Language: JavaScript/TypeScript
  • Installation: npm install formdata-polyfill

Core Imports

ESM (Node.js):

import { FormData, formDataToBlob, File } from "formdata-polyfill/esm.min.js";

Browser polyfill:

import "formdata-polyfill"; // Patches global FormData

CommonJS (Node.js):

// Note: ESM module requires import syntax, not CommonJS require
// For CommonJS compatibility, use dynamic import:
const { FormData, formDataToBlob, File } = await import("formdata-polyfill/esm.min.js");

Standalone utility:

import { formDataToBlob } from "formdata-polyfill/formdata-to-blob.js";

Basic Usage

Node.js ESM usage:

import { FormData, formDataToBlob, File } from "formdata-polyfill/esm.min.js";

const fd = new FormData();
fd.append("name", "John Doe");
fd.append("file", new File(["content"], "example.txt", { type: "text/plain" }));

// Convert to blob for HTTP libraries
const blob = formDataToBlob(fd);
fetch("https://example.com/upload", { method: "POST", body: blob });

Browser polyfill usage:

import "formdata-polyfill"; // Automatically patches global FormData

const fd = new FormData();
fd.append("name", "John Doe");
fd.set("email", "john@example.com");

// Works with fetch, XMLHttpRequest automatically
fetch("/api/submit", { method: "POST", body: fd });

Architecture

FormData Polyfill consists of three main components:

  • ESM Module: Pure JavaScript implementation for Node.js with minimal dependencies (only fetch-blob)
  • Browser Polyfill: Conditionally replaces native FormData and patches XMLHttpRequest, fetch, and sendBeacon
  • Conversion Utilities: Functions to convert FormData instances to properly formatted multipart/form-data Blobs

The package maintains full HTML5 FormData specification compatibility while providing platform-specific optimizations and compatibility layers.

Capabilities

Node.js ESM Module

Pure FormData implementation for Node.js environments with full spec compatibility and iterator support. Ideal for server-side applications using modern HTTP libraries.

class FormData {
  constructor();
  append(name: string, value: string | Blob | File, filename?: string): void;
  delete(name: string): void;
  get(name: string): string | File | null;
  getAll(name: string): (string | File)[];
  has(name: string): boolean;
  set(name: string, value: string | Blob | File, filename?: string): void;
  forEach(callback: (value: string | File, name: string, formData: FormData) => void, thisArg?: any): void;
  entries(): Iterator<[string, string | File]>;
  keys(): Iterator<string>;
  values(): Iterator<string | File>;
  [Symbol.iterator](): Iterator<[string, string | File]>;
}

function formDataToBlob(formData: FormData, BlobClass?: typeof Blob): Blob;

// File class (re-exported from fetch-blob/file.js for convenience)
class File extends Blob {
  constructor(fileBits: BlobPart[], fileName: string, options?: FilePropertyBag);
  readonly name: string;
  readonly lastModified: number;
}

Node.js ESM Module

Browser Polyfill

Enhanced FormData implementation that conditionally replaces the native browser FormData with full feature support and automatic HTTP integration.

// Global FormData is enhanced/replaced
class FormData {
  constructor(form?: HTMLFormElement);
  // ... all standard FormData methods plus:
  _asNative(): FormData; // Convert to native FormData
  _blob(): Blob; // Convert to multipart Blob
}

// Automatically patched globals:
// - XMLHttpRequest.prototype.send
// - fetch 
// - navigator.sendBeacon

Browser Polyfill

Conversion Utilities

Standalone utilities for converting FormData instances to multipart/form-data Blobs, useful for HTTP libraries that need explicit Blob handling.

function formDataToBlob(formData: FormData, BlobClass?: typeof Blob): Blob;

Conversion Utilities

Types

// Core FormData interface (matches HTML5 spec)
interface FormData {
  append(name: string, value: string | Blob | File, filename?: string): void;
  delete(name: string): void;
  get(name: string): string | File | null;
  getAll(name: string): (string | File)[];
  has(name: string): boolean;
  set(name: string, value: string | Blob | File, filename?: string): void;
  forEach(callback: (value: string | File, name: string, formData: FormData) => void, thisArg?: any): void;
  entries(): Iterator<[string, string | File]>;
  keys(): Iterator<string>;
  values(): Iterator<string | File>;
  [Symbol.iterator](): Iterator<[string, string | File]>;
}

// File interface (from fetch-blob)
interface File extends Blob {
  readonly name: string;
  readonly lastModified: number;
}

// FilePropertyBag interface for File constructor options
interface FilePropertyBag extends BlobPropertyBag {
  lastModified?: number;
}