tar-stream 3.2.0: extract

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 tar-stream.extract in pkg:npm/tar-stream@3.2.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/tar-stream@3.2.0
Demonstrate these symbols/APIs:
  - tar-stream.extract

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:f21b4b06c65e579fe53bca4a1f8f26699b96a838a2454168b5e4828c238d8a6f","contract":["extract emits entry event with header metadata and readable stream for each archived file","extract emits empty stream with header for directory entries and zero-sized files","extract parses multiple sequential entries and preserves entry order and content buffers","extract propagates error when entry callback next is invoked with an error","extract emits an error when parsing corrupted or invalid tar header bytes","extract emits unexpected end of data error when stream ends truncated mid-entry","extract supports aborting entry processing via stream destroy","extract supports async iteration yielding readable entry streams with header metadata"],"goal":"verify tar-stream.extract in pkg:npm/tar-stream@3.2.0","kind":"HOW","packages":["pkg:npm/tar-stream@3.2.0"],"schemaVersion":1,"symbols":["tar-stream.extract"]},"contractCommand":["node","test/contract.mjs"],"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/tar-stream@3.2.0"],"schemaVersion":1,"subject":"pkg:npm/tar-stream@3.2.0","symbols":["tar-stream.extract"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-tar-stream-extract",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-tar-stream-extract",
      "version": "1.0.0",
      "dependencies": {
        "tar-stream": "3.2.0"
      }
    },
    "node_modules/b4a": {
      "version": "1.9.0",
      "resolved": "https://registry.npmjs.org/b4a/-/b4a-1.9.0.tgz",
      "integrity": "sha512-dpfcF9fDNR6++cthXR67iyhgqWy9CBouAvIWhIntzBG6cvK/cnIPiZQjBwi/ZqjjBEDGfoNDtmB0kTjroOJ3pQ==",
      "license": "Apache-2.0",
      "peerDependencies": {
        "react-native-b4a": "*"
      },
      "peerDependenciesMeta": {
        "react-native-b4a": {
          "optional": true
        }
      }
    },
    "node_modules/bare-events": {
      "version": "2.9.2",
      "resolved": "https://registry.npmjs.org/bare-events/-/bare-events-2.9.2.tgz",
      "integrity": "sha512-AIPKioV7/Y/8KfZ3AAhjPJxLLbY49S64Ym5DakZlUg75qQiTgUq9hEJoEwa4eUezPUlXRy/i5NpsKvo9jgKmoA==",
      "license": "Apache-2.0",
      "peerDependencies": {
        "bare-abort-controller": "*"
      },
      "peerDependenciesMeta": {
        "bare-abort-controller": {
          "optional": true
        }
      }
    },
    "node_modules/bare-fs": {
      "version": "4.8.1",
      "resolved": "https://registry.npmjs.org/bare-fs/-/bare-fs-4.8.1.tgz",
      "integrity": "sha512-N1nnXdHZAOSstz0XiHikGS4HGMH4CnSwhqWdGQQMqqdvp4Jybm9sE3R1WVnpWVd4SFkc8ryPDBLViNLwiEqECg==",
      "license": "Apache-2.0",
      "dependencies": {
        "bare-events": "^2.5.4",
        "bare-path": "^3.0.0",
        "bare-stream": "^2.6.4",
        "bare-url": "^2.2.2",
        "fast-fifo": "^1.3.2"
      },
      "engines": {
        "bare": ">=1.28.0"
      },
      "peerDependencies": {
        "bare-buffer": "*"
      },
      "peerDependenciesMeta": {
        "bare-buffer": {
          "optional": true
        }
      }
    },
    "node_modules/bare-path": {
      "version": "3.1.2",
      "resolved": "https://registry.npmjs.org/bare-path/-/bare-path-3.1.2.tgz",
      "integrity": "sha512-ZyKbsuuqK6Ag0K8pX6V5Txq6XeJRvY+wXucnFGRjiyVYP9YWDpIQugk/b+enRYrEYBJaqLzghRQpXPMR7341Nw==",
      "license": "Apache-2.0"
    },
    "node_modules/bare-stream": {
      "version": "2.13.4",
      "resolved": "https://registry.npmjs.org/bare-stream/-/bare-stream-2.13.4.tgz",
      "integrity": "sha512-PcrQ8lVLbiJscNm1Kez+Yp4Gy4AHGcN1lzwjvf5NybWen7VvEgUfyfnXYJ2zNqWnzOfCb1Abq6lH8ti0syQszA==",
      "license": "Apache-2.0",
      "dependencies": {
        "b4a": "^1.8.1",
        "streamx": "^2.25.0",
        "teex": "^1.0.1"
      },
      "peerDependencies": {
        "bare-abort-controller": "*",
        "bare-buffer": "*",
        "bare-events": "*"
      },
      "peerDependenciesMeta": {
        "bare-abort-controller": {
          "optional": true
        },
        "bare-buffer": {
          "optional": true
        },
        "bare-events": {
          "optional": true
        }
      }
    },
    "node_modules/bare-url": {
      "version": "2.5.4",
      "resolved": "https://registry.npmjs.org/bare-url/-/bare-url-2.5.4.tgz",
      "integrity": "sha512-Gxa7UVWBr0/edU1b+TJhn/AZvMQUj9OGspvYsaTYQrAbZA4BOTZGL3LiZxvD+CeMlDH4juwD84+eTAp/bLYW5g==",
      "license": "Apache-2.0",
      "dependencies": {
        "bare-path": "^3.0.0"
      }
    },
    "node_modules/events-universal": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/events-universal/-/events-universal-1.0.1.tgz",
      "integrity": "sha512-LUd5euvbMLpwOF8m6ivPCbhQeSiYVNb8Vs0fQ8QjXo0JTkEHpz8pxdQf0gStltaPpw0Cca8b39KxvK9cfKRiAw==",
      "license": "Apache-2.0",
      "dependencies": {
        "bare-events": "^2.7.0"
      }
    },
    "node_modules/fast-fifo": {
      "version": "1.3.2",
      "resolved": "https://registry.npmjs.org/fast-fifo/-/fast-fifo-1.3.2.tgz",
      "integrity": "sha512-/d9sfos4yxzpwkDkuN7k2SqFKtYNmCTzgfEpz82x34IM9/zc8KGxQoXg1liNC/izpRM/MBdt44Nmx41ZWqk+FQ==",
      "license": "MIT"
    },
    "node_modules/streamx": {
      "version": "2.28.1",
      "resolved": "https://registry.npmjs.org/streamx/-/streamx-2.28.1.tgz",
      "integrity": "sha512-zEzXb0s5Cds7tqMH6rhZ05lcJydCWiQPEwiNngVqzsxCc962vLY4Uw+mW7od8kDH258k2Uz/JrOkdIAAhSh9VA==",
      "license": "MIT",
      "dependencies": {
        "events-universal": "^1.0.0",
        "fast-fifo": "^1.3.2",
        "text-decoder": "^1.1.0"
      }
    },
    "node_modules/tar-stream": {
      "version": "3.2.0",
      "resolved": "https://registry.npmjs.org/tar-stream/-/tar-stream-3.2.0.tgz",
      "integrity": "sha512-ojzvCvVaNp6aOTFmG7jaRD0meowIAuPc3cMMhSgKiVWws1GyHbGd/xvnyuRKcKlMpt3qvxx6r0hreCNITP9hIg==",
      "license": "MIT",
      "dependencies": {
        "b4a": "^1.6.4",
        "bare-fs": "^4.5.5",
        "fast-fifo": "^1.2.0",
        "streamx": "^2.15.0"
      }
    },
    "node_modules/teex": {
      "version": "1.0.1",
      "resolved": "https://registry.npmjs.org/teex/-/teex-1.0.1.tgz",
      "integrity": "sha512-eYE6iEI62Ni1H8oIa7KlDU6uQBtqr4Eajni3wX7rpfXD8ysFx8z0+dri+KWEPWpBsxXfxu58x/0jvTVT1ekOSg==",
      "license": "MIT",
      "dependencies": {
        "streamx": "^2.12.5"
      }
    },
    "node_modules/text-decoder": {
      "version": "1.2.7",
      "resolved": "https://registry.npmjs.org/text-decoder/-/text-decoder-1.2.7.tgz",
      "integrity": "sha512-vlLytXkeP4xvEq2otHeJfSQIRyWxo/oZGEbXrtEEF9Hnmrdly59sUbzZ/QgyWuLYHctCHxFF4tRQZNQ9k60ExQ==",
      "license": "Apache-2.0",
      "dependencies": {
        "b4a": "^1.6.4"
      }
    }
  }
}

{
  "name": "sample-tar-stream-extract",
  "version": "1.0.0",
  "private": true,
  "dependencies": {
    "tar-stream": "3.2.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify tar-stream.extract in pkg:npm/tar-stream@3.2.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/tar-stream@3.2.0"
  ],
  "symbols": [
    "tar-stream.extract"
  ]
}

import assert from 'node:assert/strict';
import { Buffer } from 'node:buffer';
import tar from 'tar-stream';

// 1. extract emits entry event with header metadata and readable stream for each archived file
await new Promise((resolve, reject) => {
	const pack = tar.pack();
	const extract = tar.extract();

	let seen = false;
	extract.on('entry', (header, stream, next) => {
		const chunks = [];
		stream.on('data', (c) => chunks.push(c));
		stream.on('end', () => {
			try {
				assert.equal(header.name, 'test.txt');
				assert.equal(header.size, 13);
				assert.equal(header.type, 'file');
				assert.equal(Buffer.concat(chunks).toString('utf8'), 'hello extract');
				seen = true;
				next();
			} catch (err) {
				reject(err);
			}
		});
		stream.resume();
	});

	extract.on('finish', () => {
		try {
			assert.equal(seen, true);
			resolve();
		} catch (err) {
			reject(err);
		}
	});
	extract.on('error', reject);

	pack.pipe(extract);
	pack.entry({ name: 'test.txt', size: 13 }, 'hello extract', (err) => {
		if (err) return reject(err);
		pack.finalize();
	});
});

// 2. extract emits empty stream with header for directory entries and zero-sized files
await new Promise((resolve, reject) => {
	const pack = tar.pack();
	const extract = tar.extract();

	const entries = [];
	extract.on('entry', (header, stream, next) => {
		const chunks = [];
		stream.on('data', (c) => chunks.push(c));
		stream.on('end', () => {
			try {
				entries.push({ name: header.name, type: header.type, length: Buffer.concat(chunks).length });
				next();
			} catch (err) {
				reject(err);
			}
		});
		stream.resume();
	});

	extract.on('finish', () => {
		try {
			assert.equal(entries.length, 2);
			assert.equal(entries[0].name, 'docs/');
			assert.equal(entries[0].type, 'directory');
			assert.equal(entries[0].length, 0);

			assert.equal(entries[1].name, 'empty.txt');
			assert.equal(entries[1].type, 'file');
			assert.equal(entries[1].length, 0);
			resolve();
		} catch (err) {
			reject(err);
		}
	});
	extract.on('error', reject);

	pack.pipe(extract);
	pack.entry({ name: 'docs/', type: 'directory' });
	pack.entry({ name: 'empty.txt', size: 0 }, Buffer.alloc(0), (err) => {
		if (err) return reject(err);
		pack.finalize();
	});
});

// 3. extract parses multiple sequential entries and preserves entry order and content buffers
await new Promise((resolve, reject) => {
	const pack = tar.pack();
	const extract = tar.extract();

	const results = [];
	extract.on('entry', (header, stream, next) => {
		const chunks = [];
		stream.on('data', (c) => chunks.push(c));
		stream.on('end', () => {
			results.push({
				name: header.name,
				data: Buffer.concat(chunks),
			});
			next();
		});
		stream.resume();
	});

	extract.on('finish', () => {
		try {
			assert.equal(results.length, 3);
			assert.equal(results[0].name, 'first.bin');
			assert.deepEqual(results[0].data, Buffer.from([1, 2, 3]));
			assert.equal(results[1].name, 'second.bin');
			assert.deepEqual(results[1].data, Buffer.from([4, 5, 6, 7]));
			assert.equal(results[2].name, 'third.txt');
			assert.equal(results[2].data.toString('utf8'), 'third payload');
			resolve();
		} catch (err) {
			reject(err);
		}
	});
	extract.on('error', reject);

	pack.pipe(extract);
	pack.entry({ name: 'first.bin' }, Buffer.from([1, 2, 3]));
	pack.entry({ name: 'second.bin' }, Buffer.from([4, 5, 6, 7]));
	pack.entry({ name: 'third.txt' }, 'third payload', (err) => {
		if (err) return reject(err);
		pack.finalize();
	});
});

// 4. extract propagates error when entry callback next is invoked with an error
await new Promise((resolve, reject) => {
	const pack = tar.pack();
	const extract = tar.extract();

	extract.on('entry', (header, stream, next) => {
		stream.on('error', () => {});
		stream.resume();
		next(new Error('consumer processing failed'));
	});

	extract.on('error', (err) => {
		try {
			assert.ok(err instanceof Error);
			assert.equal(err.message, 'consumer processing failed');
			resolve();
		} catch (e) {
			reject(e);
		}
	});

	pack.pipe(extract);
	pack.entry({ name: 'f.txt' }, 'data', (err) => {
		if (err) return reject(err);
		pack.finalize();
	});
});

// 5. extract emits an error when parsing corrupted or invalid tar header bytes
await new Promise((resolve, reject) => {
	const extract = tar.extract();

	extract.on('error', (err) => {
		try {
			assert.ok(err instanceof Error);
			assert.match(err.message, /Invalid tar header/);
			resolve();
		} catch (e) {
			reject(e);
		}
	});

	// Write 512 bytes of corrupted header
	const corrupt = Buffer.alloc(512, 0xff);
	extract.write(corrupt);
});

// 6. extract emits unexpected end of data error when stream ends truncated mid-entry
await new Promise((resolve, reject) => {
	const pack = tar.pack();
	const extract = tar.extract();

	extract.on('entry', (header, stream, next) => {
		stream.on('error', () => {});
		stream.resume();
		next();
	});

	extract.on('error', (err) => {
		try {
			assert.ok(err instanceof Error);
			assert.match(err.message, /Unexpected end of data/);
			resolve();
		} catch (e) {
			reject(e);
		}
	});

	// Collect first part of tar data (header + partial body), then end extract prematurely
	const chunks = [];
	pack.on('data', (c) => chunks.push(c));
	pack.on('end', () => {
		const full = Buffer.concat(chunks);
		// write header (512 bytes) + 10 bytes of body, then end
		extract.write(full.subarray(0, 522));
		extract.end();
	});

	pack.entry({ name: 'truncated.bin', size: 100 }, Buffer.alloc(100, 0xaa), (err) => {
		if (err) return reject(err);
		pack.finalize();
	});
});

// 7. extract supports aborting entry processing via stream destroy
await new Promise((resolve, reject) => {
	const pack = tar.pack();
	const extract = tar.extract();

	extract.on('entry', (header, stream, next) => {
		stream.on('error', () => {});
		stream.destroy(new Error('aborted by stream destroy'));
	});

	extract.on('error', (err) => {
		try {
			assert.ok(err instanceof Error);
			assert.equal(err.message, 'aborted by stream destroy');
			resolve();
		} catch (e) {
			reject(e);
		}
	});

	pack.pipe(extract);
	pack.entry({ name: 'abort.txt', size: 20 }, Buffer.alloc(20), (err) => {
		if (err) return reject(err);
		pack.finalize();
	});
});

// 8. extract supports async iteration yielding readable entry streams with header metadata
{
	const pack = tar.pack();
	const extract = tar.extract();

	pack.pipe(extract);
	pack.entry({ name: 'async.txt', size: 9 }, 'async tar', (err) => {
		if (err) throw err;
		pack.finalize();
	});

	const entries = [];
	for await (const entry of extract) {
		const chunks = [];
		for await (const chunk of entry) {
			chunks.push(chunk);
		}
		entries.push({
			name: entry.header.name,
			content: Buffer.concat(chunks).toString('utf8'),
		});
	}

	assert.equal(entries.length, 1);
	assert.equal(entries[0].name, 'async.txt');
	assert.equal(entries[0].content, 'async tar');
}