content-disposition 2.0.1

Clean-room public code sample — generation instructions

Write a brand-new, minimal, self-contained code sample in this clean-room directory.
Do not copy, paraphrase, or reference any existing project source. Work only from this spec.

A csx.json manifest scaffold already exists. Do not recreate it from memory. Preserve its case.goal, packages and symbols; fill its empty case.contract with exact assertions and correct its environment, commands and verifierAdapter for the files you generate.

Goal: verify pkg:npm/content-disposition@2.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/content-disposition@2.0.1

Rules:
  - One focused purpose; the smallest project that proves the goal.
  - Include a contract test (test/contract.*) that runs OFFLINE and exits 0 exactly when the goal behavior works.
  - Pin every dependency with a lockfile so resolution is reproducible.
  - No secrets, credentials, or tokens. No real URLs (only example.com or localhost). No absolute paths.
  - No personal names, emails, company names, or project identifiers of any kind.
  - No binaries and no generated output (node_modules, dist, target, venv, .git, .env).
  - Keep it under 200 files and 256KB packed.

{"case":{"caseId":"case:sha256:16b742a4588e92703f7b0cdb3c886a932df906db09b0ee6d8342f936f36be061","constraints":{"executionContext":"node"},"contract":["create() formats an attachment Content-Disposition header without parameters when called with no filename","create(filename, options) formats ASCII filenames and supports custom disposition types","create(filename, options) generates US-ASCII fallback and RFC 8187 filename* parameter for Unicode filenames","parse(header, options) parses disposition type and parameters and decodes RFC 8187 extended parameters","parse(header, { multipart: true }) decodes multipart/form-data escaped quotes and newlines","format(obj, options) formats ContentDisposition objects including extended Unicode parameters and multipart escaping","encodeExtended(str) and decodeExtended(str) encode and decode RFC 8187 extended field values"],"goal":"verify pkg:npm/content-disposition@2.0.1","kind":"HOW","packages":["pkg:npm/content-disposition@2.0.1"],"schemaVersion":1,"symbols":["create","parse","format","encodeExtended","decodeExtended"]},"contractCommand":["node","test/contract.cjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","language":"javascript","libc":"glibc","libcVersion":"2.39","moduleSystem":"cjs","os":"linux","osVersionBucket":"24","packageManager":"npm","packageManagerVersion":"10.9.8","runtime":"node","runtimeVersion":"22.23.2","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/content-disposition@2.0.1"],"schemaVersion":1,"subject":"pkg:npm/content-disposition@2.0.1","verifierAdapter":"node-typescript@1"}

{
  "name": "sample-content-disposition",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-content-disposition",
      "version": "1.0.0",
      "dependencies": {
        "content-disposition": "2.0.1"
      }
    },
    "node_modules/content-disposition": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-2.0.1.tgz",
      "integrity": "sha512-e+H0ZXHSWYrENhQzw1LPuP4oF5MzVKmDU6d3hxlvaPEYLLg62MxtQNPRx4SYSuYJSBUgnQIG4HIN2tEtNv7Dog==",
      "license": "MIT",
      "engines": {
        "node": ">=18"
      },
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/express"
      }
    }
  }
}

{
  "name": "sample-content-disposition",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification for content-disposition",
  "main": "src/index.js",
  "dependencies": {
    "content-disposition": "2.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/content-disposition@2.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/content-disposition@2.0.1"
  ]
}

const {
  create,
  parse,
  format,
  encodeExtended,
  decodeExtended
} = require('content-disposition');

module.exports = {
  create,
  parse,
  format,
  encodeExtended,
  decodeExtended
};

const assert = require('node:assert');
const {
  create,
  parse,
  format,
  encodeExtended,
  decodeExtended
} = require('../src/index.js');

// 1. create() formats an attachment Content-Disposition header without parameters when called with no filename
assert.strictEqual(create(), 'attachment');
assert.strictEqual(create(undefined, { type: 'inline' }), 'inline');

// 2. create(filename, options) formats ASCII filenames and supports custom disposition types
assert.strictEqual(create('report.pdf'), 'attachment; filename=report.pdf');
assert.strictEqual(
  create('my report.pdf', { type: 'inline' }),
  'inline; filename="my report.pdf"'
);

// 3. create(filename, options) generates US-ASCII fallback and RFC 8187 filename* parameter for Unicode filenames
assert.strictEqual(
  create('€ rates.txt'),
  'attachment; filename="? rates.txt"; filename*=UTF-8\'\'%E2%82%AC%20rates.txt'
);
assert.strictEqual(
  create('€ rates.txt', { fallback: 'euro_rates.txt' }),
  'attachment; filename=euro_rates.txt; filename*=UTF-8\'\'%E2%82%AC%20rates.txt'
);
assert.strictEqual(
  create('€ rates.txt', { fallback: false }),
  'attachment; filename*=UTF-8\'\'%E2%82%AC%20rates.txt'
);
assert.throws(() => {
  create('€ rates.txt', { fallback: '€' });
}, TypeError);

// 4. parse(header, options) parses disposition type and parameters and decodes RFC 8187 extended parameters
const parsedBasic = parse('attachment; filename="plans.pdf"');
assert.strictEqual(parsedBasic.type, 'attachment');
assert.deepStrictEqual(Object.assign({}, parsedBasic.parameters), {
  filename: 'plans.pdf'
});

const parsedExtended = parse(
  "attachment; filename=\"? rates.txt\"; filename*=UTF-8''%E2%82%AC%20rates.txt"
);
assert.strictEqual(parsedExtended.type, 'attachment');
assert.strictEqual(parsedExtended.parameters.filename, '€ rates.txt');

const parsedNoExtended = parse(
  "attachment; filename=\"? rates.txt\"; filename*=UTF-8''%E2%82%AC%20rates.txt",
  { extended: false }
);
assert.strictEqual(parsedNoExtended.parameters.filename, '? rates.txt');

// 5. parse(header, { multipart: true }) decodes multipart/form-data escaped quotes and newlines
const parsedMultipart = parse('form-data; name="field"; filename="line1%0Aline2%22.txt"', {
  multipart: true
});
assert.strictEqual(parsedMultipart.type, 'form-data');
assert.strictEqual(parsedMultipart.parameters.name, 'field');
assert.strictEqual(parsedMultipart.parameters.filename, 'line1\nline2".txt');

// 6. format(obj, options) formats ContentDisposition objects including extended Unicode parameters and multipart escaping
assert.strictEqual(
  format({ type: 'attachment', parameters: { filename: '€ rates.txt' } }),
  "attachment; filename*=UTF-8''%E2%82%AC%20rates.txt"
);
assert.strictEqual(
  format(
    { type: 'form-data', parameters: { name: 'file', filename: 'a"b\nc.txt' } },
    { multipart: true }
  ),
  'form-data; name="file"; filename="a%22b%0Ac.txt"'
);
assert.throws(() => {
  format({ type: 'invalid type' });
}, TypeError);

// 7. encodeExtended(str) and decodeExtended(str) encode and decode RFC 8187 extended field values
const encoded = encodeExtended('€ rates.txt');
assert.strictEqual(encoded, "UTF-8''%E2%82%AC%20rates.txt");
assert.strictEqual(decodeExtended(encoded), '€ rates.txt');
assert.strictEqual(decodeExtended("iso-8859-1'en'%A3%20rates.txt"), '£ rates.txt');
assert.strictEqual(decodeExtended('invalid-value'), undefined);

console.log('Contract tests passed.');