or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

browser-compatibility.md buffer-operations.md form-construction.md headers-boundaries.md http-submission.md index.md length-calculation.md

tile.json

Form Construction

Core functionality for building multipart forms by appending fields, files, and streams with extensive customization options for content types, filenames, and headers.

Capabilities

FormData Constructor

Creates a new FormData instance with optional configuration.

import * as stream from 'stream';

/**
 * Create readable "multipart/form-data" streams
 * @param options - Properties to be added/overridden for FormData and CombinedStream
 */
class FormData extends stream.Readable {
  constructor(options?: Options);
}

interface Options {
  /** Enable writable stream behavior */
  writable?: boolean;
  /** Enable readable stream behavior */
  readable?: boolean;
  /** Initial data size hint */
  dataSize?: number;
  /** Maximum allowed data size */
  maxDataSize?: number;
  /** Whether to pause streams automatically */
  pauseStreams?: boolean;
}

Usage Examples:

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

// Basic form
const form = new FormData();

// Form with options
const form = new FormData({
  maxDataSize: 20971520, // 20MB limit
  pauseStreams: false
});

Append Method

Appends data to the form with various value types and customization options.

/**
 * Append data to the form
 * @param field - Field name
 * @param value - Field value (string, number, Buffer, Stream, null, etc.)
 * @param options - Options object or filename string
 */
append(field: string, value: any, options?: AppendOptions | string): void;

interface AppendOptions {
  /** Custom header string or headers object */
  header?: string | Headers;
  /** Pre-known content length for optimization */
  knownLength?: number;
  /** Custom filename for file uploads */
  filename?: string;
  /** Custom filepath (overrides filename) for relative paths */
  filepath?: string;
  /** Custom content type */
  contentType?: string;
}

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

Usage Examples:

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

const form = new FormData();

// String values
form.append('username', 'alice');
form.append('description', 'User profile data');

// Numbers (automatically converted to strings)
form.append('age', 25);
form.append('score', 95.5);

// Buffers
form.append('data', Buffer.from('binary data'));

// Files with automatic content-type detection
form.append('profile_pic', fs.createReadStream('/path/photo.jpg'));

// Files with custom options
form.append('document', fs.createReadStream('/path/file.pdf'), {
  filename: 'resume.pdf',
  contentType: 'application/pdf',
  knownLength: 150000
});

// HTTP response streams
const http = require('http');
http.request('http://example.com/image.png', (response) => {
  form.append('remote_image', response);
});

// Custom headers
form.append('special_field', 'value', {
  header: 'Content-Type: text/plain\r\nX-Custom: true'
});

// Filepath for directory uploads
form.append('nested_file', fs.createReadStream('/files/docs/readme.txt'), {
  filepath: 'docs/readme.txt'
});

Supported Value Types

Form-Data accepts various data types for field values:

Strings: Directly added as field values
Numbers: Automatically converted to strings
null/undefined: Converted to string representations
Buffers: Added as binary data
Readable Streams: Including fs.ReadStream, http.IncomingMessage
Request Streams: Compatible with libraries like 'request'

Note: Arrays are not supported and will cause an error. Convert arrays to JSON strings if needed:

// Wrong - will throw error
form.append('tags', ['red', 'blue', 'green']);

// Correct - convert to JSON
form.append('tags', JSON.stringify(['red', 'blue', 'green']));

Content Type Detection

Form-Data automatically detects content types based on:

Custom contentType option: Takes highest priority
File extensions: Uses name property from formidable/browser uploads
File paths: Uses path property from fs streams and request streams
HTTP responses: Uses content-type header from HTTP responses
Fallback: Uses application/octet-stream for object values

// Automatic detection from file extension
form.append('image', fs.createReadStream('photo.jpg')); // → image/jpeg

// Override with custom type
form.append('data', someBuffer, {
  contentType: 'application/json'
});

Static Properties

/** Line break constant used in multipart formatting */
FormData.LINE_BREAK = '\r\n';

/** Default content type for unknown binary data */
FormData.DEFAULT_CONTENT_TYPE = 'application/octet-stream';

Version

Tile

Files