minipass-fetch 4.0.1: Headers

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 Headers in pkg:npm/minipass-fetch@4.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/minipass-fetch@4.0.1
Demonstrate these symbols/APIs:
  - Headers

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:4652db0a33f33334ca556b9a3b6ddec04785960622610c0b33b036cc20657aa2","contract":["Headers constructor accepts null/undefined, plain records, iterable [name, value] tuple sequences, or another Headers instance, and throws TypeError on non-object or malformed tuple initializers","append, set, get, has, and delete match header names case-insensitively while preserving first-seen key casing in raw() and joining multi-values with ', ' in get(), throwing TypeError on invalid token names or control-character values","keys(), values(), entries(), Symbol.iterator, and forEach iterate over sorted lowercase header names and comma-joined values via a HeadersIterator instance","Headers.exportNodeCompatibleHeaders unwraps the Host header array to a single string on a null-prototype object, and Headers.createHeadersLenient skips invalid header names and invalid values without throwing"],"goal":"verify Headers in pkg:npm/minipass-fetch@4.0.1","kind":"HOW","packages":["pkg:npm/minipass-fetch@4.0.1"],"schemaVersion":1,"symbols":["Headers"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","executionContext":"node","libc":"glibc","libcVersion":"2.39","moduleSystem":"esm","os":"linux","osVersionBucket":"24","packageManager":"npm","runtime":"node","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/minipass-fetch@4.0.1"],"schemaVersion":1,"subject":"pkg:npm/minipass-fetch@4.0.1","symbols":["Headers"],"verifierAdapter":"node-typescript@1"}

{
  "name": "minipass-fetch-headers-sample",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "minipass-fetch-headers-sample",
      "version": "1.0.0",
      "dependencies": {
        "minipass-fetch": "4.0.1"
      }
    },
    "node_modules/encoding": {
      "version": "0.1.13",
      "resolved": "https://registry.npmjs.org/encoding/-/encoding-0.1.13.tgz",
      "integrity": "sha512-ETBauow1T35Y/WZMkio9jiM0Z5xjHHmJ4XmjZOq1l/dXz3lr2sRn87nJy20RupqSh1F2m3HHPSp8ShIPQJrJ3A==",
      "license": "MIT",
      "optional": true,
      "dependencies": {
        "iconv-lite": "^0.6.2"
      }
    },
    "node_modules/iconv-lite": {
      "version": "0.6.3",
      "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.6.3.tgz",
      "integrity": "sha512-4fCk79wshMdzMp2rH06qWrJE4iolqLhCUH+OiuIgU++RB0+94NlDL81atO7GX55uUKueo0txHNtvEyI6D7WdMw==",
      "license": "MIT",
      "optional": true,
      "dependencies": {
        "safer-buffer": ">= 2.1.2 < 3.0.0"
      },
      "engines": {
        "node": ">=0.10.0"
      }
    },
    "node_modules/minipass": {
      "version": "7.1.3",
      "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz",
      "integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==",
      "license": "BlueOak-1.0.0",
      "engines": {
        "node": ">=16 || 14 >=14.17"
      }
    },
    "node_modules/minipass-fetch": {
      "version": "4.0.1",
      "resolved": "https://registry.npmjs.org/minipass-fetch/-/minipass-fetch-4.0.1.tgz",
      "integrity": "sha512-j7U11C5HXigVuutxebFadoYBbd7VSdZWggSe64NVdvWNBqGAiXPL2QVCehjmw7lY1oF9gOllYbORh+hiNgfPgQ==",
      "license": "MIT",
      "dependencies": {
        "minipass": "^7.0.3",
        "minipass-sized": "^1.0.3",
        "minizlib": "^3.0.1"
      },
      "engines": {
        "node": "^18.17.0 || >=20.5.0"
      },
      "optionalDependencies": {
        "encoding": "^0.1.13"
      }
    },
    "node_modules/minipass-sized": {
      "version": "1.0.3",
      "resolved": "https://registry.npmjs.org/minipass-sized/-/minipass-sized-1.0.3.tgz",
      "integrity": "sha512-MbkQQ2CTiBMlA2Dm/5cY+9SWFEN8pzzOXi6rlM5Xxq0Yqbda5ZQy9sU75a673FE9ZK0Zsbr6Y5iP6u9nktfg2g==",
      "license": "ISC",
      "dependencies": {
        "minipass": "^3.0.0"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/minipass-sized/node_modules/minipass": {
      "version": "3.3.6",
      "resolved": "https://registry.npmjs.org/minipass/-/minipass-3.3.6.tgz",
      "integrity": "sha512-DxiNidxSEK+tHG6zOIklvNOwm3hvCrbUrdtzY74U6HKTJxvIDfOUL5W5P2Ghd3DTkhhKPYGqeNUIh5qcM4YBfw==",
      "license": "ISC",
      "dependencies": {
        "yallist": "^4.0.0"
      },
      "engines": {
        "node": ">=8"
      }
    },
    "node_modules/minizlib": {
      "version": "3.1.0",
      "resolved": "https://registry.npmjs.org/minizlib/-/minizlib-3.1.0.tgz",
      "integrity": "sha512-KZxYo1BUkWD2TVFLr0MQoM8vUUigWD3LlD83a/75BqC+4qE0Hb1Vo5v1FgcfaNXvfXzr+5EhQ6ing/CaBijTlw==",
      "license": "MIT",
      "dependencies": {
        "minipass": "^7.1.2"
      },
      "engines": {
        "node": ">= 18"
      }
    },
    "node_modules/safer-buffer": {
      "version": "2.1.2",
      "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz",
      "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==",
      "license": "MIT",
      "optional": true
    },
    "node_modules/yallist": {
      "version": "4.0.0",
      "resolved": "https://registry.npmjs.org/yallist/-/yallist-4.0.0.tgz",
      "integrity": "sha512-3wdGidZyq5PB084XLES5TpOSRA3wjXAlIWMhum2kRcv/41Sn2emQ0dycQW4uZXLejwKvg6EsvbdlVL+FYEct7A==",
      "license": "ISC"
    }
  }
}

{
  "name": "minipass-fetch-headers-sample",
  "version": "1.0.0",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node test/contract.mjs"
  },
  "dependencies": {
    "minipass-fetch": "4.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify Headers in pkg:npm/minipass-fetch@4.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/minipass-fetch@4.0.1"
  ],
  "symbols": [
    "Headers"
  ]
}

import assert from 'node:assert/strict'
import fetch from 'minipass-fetch'

const { Headers } = fetch

// 1. Constructor initialization shapes & validation
const empty1 = new Headers()
const empty2 = new Headers(null)
assert.equal(Object.prototype.toString.call(empty1), '[object Headers]')
assert.deepEqual(Object.keys(empty1.raw()), [])
assert.deepEqual(Object.keys(empty2.raw()), [])

const fromRecord = new Headers({
  'X-Alpha': '1',
  'Content-Type': 'application/json',
})
assert.equal(fromRecord.get('x-alpha'), '1')
assert.equal(fromRecord.get('CONTENT-TYPE'), 'application/json')

const fromPairs = new Headers([
  ['X-Multi', 'first'],
  ['x-multi', 'second'],
  ['Accept', 'text/plain'],
])
assert.equal(fromPairs.get('X-MULTI'), 'first, second')
assert.equal(Object.getPrototypeOf(fromPairs.raw()), null)
assert.deepEqual({ ...fromPairs.raw() }, {
  'X-Multi': ['first', 'second'],
  Accept: ['text/plain'],
})

const cloned = new Headers(fromPairs)
cloned.append('x-multi', 'third')
assert.equal(fromPairs.get('x-multi'), 'first, second')
assert.equal(cloned.get('x-multi'), 'first, second, third')

assert.throws(() => new Headers('not-an-object'), TypeError)
assert.throws(() => new Headers([['only-one']]), TypeError)
assert.throws(() => new Headers([123]), TypeError)

// 2. Case-insensitive get, set, append, has, delete, raw, and validation
const h = new Headers()
assert.equal(h.get('X-Missing'), null)
assert.equal(h.has('X-Missing'), false)

h.append('X-Token', 'alpha')
h.append('x-token', 'beta')
assert.equal(h.has('X-TOKEN'), true)
assert.equal(h.get('x-token'), 'alpha, beta')
assert.deepEqual(h.raw()['X-Token'], ['alpha', 'beta'])

h.set('x-token', 'replaced')
assert.equal(h.get('X-Token'), 'replaced')
assert.deepEqual(h.raw()['X-Token'], ['replaced'])

h.delete('X-TOKEN')
assert.equal(h.has('X-Token'), false)
assert.equal(h.get('X-Token'), null)

assert.throws(() => h.set('', 'val'), TypeError)
assert.throws(() => h.set('invalid name', 'val'), TypeError)
assert.throws(() => h.set('X-Valid', 'bad\nvalue'), TypeError)

// 3. Sorted lowercase iteration (keys, values, entries, Symbol.iterator, forEach)
const iterHeaders = new Headers([
  ['X-Zebra', 'z1'],
  ['x-zebra', 'z2'],
  ['X-Apple', 'a1'],
])
const keyIter = iterHeaders.keys()
assert.equal(Object.prototype.toString.call(keyIter), '[object HeadersIterator]')
assert.deepEqual(Array.from(keyIter), ['x-apple', 'x-zebra'])
assert.deepEqual(Array.from(iterHeaders.values()), ['a1', 'z1, z2'])
assert.deepEqual(Array.from(iterHeaders.entries()), [
  ['x-apple', 'a1'],
  ['x-zebra', 'z1, z2'],
])
assert.deepEqual(Array.from(iterHeaders), [
  ['x-apple', 'a1'],
  ['x-zebra', 'z1, z2'],
])

const visited = []
const ctx = { prefix: 'seen' }
iterHeaders.forEach(function (value, name, parent) {
  assert.equal(parent, iterHeaders)
  visited.push(`${this.prefix}:${name}=${value}`)
}, ctx)
assert.deepEqual(visited, ['seen:x-apple=a1', 'seen:x-zebra=z1, z2'])

// 4. Static helpers: exportNodeCompatibleHeaders and createHeadersLenient
const nodeHeadersInput = new Headers({
  'Custom-Host': 'keep-array',
  Host: 'example.com:8080',
})
const exported = Headers.exportNodeCompatibleHeaders(nodeHeadersInput)
assert.equal(Object.getPrototypeOf(exported), null)
assert.equal(exported.Host, 'example.com:8080')
assert.deepEqual(exported['Custom-Host'], ['keep-array'])

const lenient = Headers.createHeadersLenient({
  'Valid-Single': 'ok',
  'Valid-Array': ['good1', 'bad\nval', 'good2'],
  'bad header name': 'ignored',
  'Bad-Value': 'bad\x00char',
})
assert.equal(lenient.get('valid-single'), 'ok')
assert.equal(lenient.get('valid-array'), 'good1, good2')
assert.equal(lenient.has('Bad-Value'), false)