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

headers-boundaries.mddocs/

Headers and Boundaries

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 });