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

Headers and Boundaries

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

Header generation and boundary management for multipart streams, including automatic content-type header creation, custom boundary setting, and user header merging.

Capabilities

Get Headers

Generates headers object with proper content-type and boundary, merging with optional user headers.

/**
 * Get headers including content-type with boundary
 * @param userHeaders - Optional additional headers to merge
 * @returns Headers object with content-type and merged user headers
 */
getHeaders(userHeaders?: Headers): Headers;

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

Usage Examples:

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

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

// Basic headers
const headers = form.getHeaders();
console.log(headers);
// Output: { 'content-type': 'multipart/form-data; boundary=--------------------------...' }

// Merge with custom headers
const headers = form.getHeaders({
  'Authorization': 'Bearer token123',
  'User-Agent': 'MyApp/1.0',
  'X-Custom-Header': 'custom-value'
});

// Use with Node.js HTTP client
const request = http.request({
  method: 'POST',
  host: 'example.com',
  path: '/upload',
  headers: form.getHeaders({
    'Accept': 'application/json'
  })
});

form.pipe(request);

Set Boundary

Sets a custom boundary string for the multipart stream.

/**
 * Set custom boundary string
 * @param boundary - Boundary string (must not appear in data)
 * @throws TypeError if boundary is not a string
 */
setBoundary(boundary: string): void;

Usage Examples:

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

const form = new FormData();

// Set custom boundary
form.setBoundary('MyCustomBoundary123');

// Boundary must be unique and not appear in data
form.setBoundary('----formdata-custom-boundary');

console.log(form.getBoundary()); // 'MyCustomBoundary123'

// Invalid boundary (not a string)
try {
  form.setBoundary(123); // Throws TypeError
} catch (err) {
  console.error('Boundary must be a string');
}

Get Boundary

Retrieves the current boundary string, generating one if not set.

/**
 * Get current boundary string (generates if not set)
 * @returns Current boundary string
 */
getBoundary(): string;

Usage Examples:

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

const form = new FormData();

// Get auto-generated boundary
const boundary = form.getBoundary();
console.log(boundary);
// Output: --------------------------515890814546601021194782

// Boundary is consistent across calls
console.log(form.getBoundary() === form.getBoundary()); // true

// Different forms have different boundaries
const form2 = new FormData();
console.log(form.getBoundary() !== form2.getBoundary()); // true

Boundary Generation

Form-Data automatically generates cryptographically secure boundaries:

// Auto-generated boundary format:
// 26 dashes + 24 random hex characters = 50 total characters
// Example: --------------------------1234567890abcdef12345678

const form = new FormData();
const boundary = form.getBoundary();
console.log(boundary.length); // 50
console.log(boundary.startsWith('--------------------------')); // true

Header Case Handling

Form-Data normalizes header names to lowercase for consistency:

const form = new FormData();
const headers = form.getHeaders({
  'Content-Length': '1024',
  'USER-AGENT': 'MyApp',
  'X-Custom-Header': 'value'
});

console.log(headers);
// Output: {
//   'content-type': 'multipart/form-data; boundary=...',
//   'content-length': '1024',
//   'user-agent': 'MyApp', 
//   'x-custom-header': 'value'
// }

Integration Examples

With Express.js:

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

app.post('/proxy-upload', (req, res) => {
  const form = new FormData();
  form.append('file', fs.createReadStream('local-file.pdf'));
  form.append('metadata', JSON.stringify({ user: req.user.id }));
  
  // Forward to external service
  form.submit({
    host: 'external-api.com',
    path: '/upload',
    headers: form.getHeaders({
      'Authorization': 'Bearer ' + req.headers.authorization
    })
  }, (err, response) => {
    if (err) return res.status(500).json({ error: err.message });
    res.status(response.statusCode).json({ success: true });
  });
});

With Axios:

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

const form = new FormData();
form.append('data', 'value');

axios.post('http://api.example.com/upload', form, {
  headers: {
    ...form.getHeaders(),
    'Authorization': 'Bearer token',
    'X-Request-ID': 'req-123'
  },
  maxContentLength: Infinity,
  maxBodyLength: Infinity
}).then(response => {
  console.log('Upload successful');
});

Custom Boundary with Headers:

const form = new FormData();
form.setBoundary('MyAppBoundary2023');

// Use in custom header string
const customHeader = 
  '\r\n--' + form.getBoundary() + '\r\n' +
  'Content-Disposition: form-data; name="special"\r\n' +
  'X-Custom-Attribute: special-value\r\n\r\n';

form.append('regular_field', 'value');
form.append('special_field', 'data', { header: customHeader });