or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

browser-compatibility.mdbuffer-operations.mdform-construction.mdheaders-boundaries.mdhttp-submission.mdindex.mdlength-calculation.md
tile.json

tessl/npm-form-data

A library to create readable multipart/form-data streams for form and file uploads.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/form-data@4.0.x

To install, run

npx @tessl/cli install tessl/npm-form-data@4.0.0

index.mddocs/

Form-Data

Form-Data is a Node.js library that creates readable multipart/form-data streams for submitting forms and uploading files to web applications. It provides a streaming interface inspired by XMLHttpRequest-2 FormData with extensive customization options for headers, boundaries, and content types.

Package Information

  • Package Name: form-data
  • Package Type: npm
  • Language: JavaScript
  • Installation: npm install form-data

Core Imports

const FormData = require('form-data');

For TypeScript:

import FormData = require('form-data');
// or
import * as FormData from 'form-data';

Note: This package uses CommonJS exports (export = FormData), not ES modules.

Basic Usage

const FormData = require('form-data');
const fs = require('fs');

// Create form instance
const form = new FormData();

// Append various data types
form.append('my_field', 'my value');
form.append('my_buffer', Buffer.from('hello'));
form.append('my_file', fs.createReadStream('/path/file.jpg'));

// Submit directly
form.submit('http://example.org/upload', (err, res) => {
  if (err) throw err;
  console.log('Upload completed!');
  res.resume();
});

Architecture

Form-Data is built around several key components:

  • FormData Class: Main constructor that extends CombinedStream for readable stream functionality
  • Multipart Stream Generation: Creates properly formatted multipart/form-data streams with boundaries
  • Content Type Detection: Automatic MIME type detection for files and streams
  • HTTP Integration: Built-in HTTP/HTTPS client support for direct submission
  • Browser Compatibility: Fallback to native FormData in browser environments

Capabilities

Form Construction

Core functionality for building multipart forms by appending fields, files, and streams with customizable options.

import * as stream from 'stream';

class FormData extends stream.Readable {
  constructor(options?: Options);
  append(field: string, value: any, options?: AppendOptions | string): void;
  
  // Static properties
  static LINE_BREAK: string;
  static DEFAULT_CONTENT_TYPE: string;
}

interface Options {
  writable?: boolean;
  readable?: boolean;
  dataSize?: number;
  maxDataSize?: number;
  pauseStreams?: boolean;
  // Additional options from ReadableOptions
  highWaterMark?: number;
  encoding?: string;
  objectMode?: boolean;
  autoDestroy?: boolean;
}

interface AppendOptions {
  header?: string | Headers;
  knownLength?: number;
  filename?: string;
  filepath?: string;
  contentType?: string;
}

Form Construction

HTTP Submission

Direct HTTP submission capabilities with automatic header management and content-length calculation.

submit(
  params: string | SubmitOptions,
  callback?: (error: Error | null, response: http.IncomingMessage) => void
): http.ClientRequest;

interface SubmitOptions extends http.RequestOptions {
  protocol?: 'https:' | 'http:';
}

HTTP Submission

Headers and Boundaries

Header generation and boundary management for multipart streams, including custom boundary setting and header merging.

getHeaders(userHeaders?: Headers): Headers;
setBoundary(boundary: string): void;
getBoundary(): string;

interface Headers {
  [key: string]: any;
}

Headers and Boundaries

Length Calculation

Content length calculation for streams and form data, both synchronous and asynchronous methods.

getLength(callback: (err: Error | null, length: number) => void): void;
getLengthSync(): number;
hasKnownLength(): boolean;

Length Calculation

Buffer Operations

Buffer generation for form data and stream integration with other HTTP clients.

getBuffer(): Buffer;
toString(): string;

Buffer Operations

Browser Compatibility

Browser compatibility layer that provides fallback to native FormData in browser environments.

// In browser environments, exports native FormData
module.exports = typeof self === 'object' ? self.FormData : window.FormData;

Browser Compatibility

Types

import * as stream from 'stream';
import * as http from 'http';

type Headers = { [key: string]: any };

interface ReadableOptions {
  highWaterMark?: number;
  encoding?: string;
  objectMode?: boolean;
  read?(this: stream.Readable, size: number): void;
  destroy?(this: stream.Readable, error: Error | null, callback: (error: Error | null) => void): void;
  autoDestroy?: boolean;
}

interface Options extends ReadableOptions {
  writable?: boolean;
  readable?: boolean;
  dataSize?: number;
  maxDataSize?: number;
  pauseStreams?: boolean;
}

interface AppendOptions {
  header?: string | Headers;
  knownLength?: number;
  filename?: string;
  filepath?: string;
  contentType?: string;
}

interface SubmitOptions extends http.RequestOptions {
  protocol?: 'https:' | 'http:';
}