tessl/npm-form-data

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

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Pending

The risk profile of this skill

Overview

Eval results

Files

Form Construction

Name: tessl/npm-form-data
Author: tessl

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';