merge-stream 2.0.0

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/merge-stream@2.0.0
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/merge-stream@2.0.0

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:9891d7b2fee44b103cd99a947c3d5fb40df78f9591a689b3ebb59dd469b8cffc","contract":["mergeStream() creates an empty PassThrough stream in objectMode with isEmpty() returning true","mergeStream(...streams) merges data events from multiple readable streams and ends when all source streams complete","merged.add(stream) and merged.add(streams) dynamically adds single streams or arrays of streams and returns the merged stream instance for chaining","merged.isEmpty() transitions from true to false when streams are added","merged forwards error events emitted by any attached source stream","mergeStream supports merging streams operating in object mode with arbitrary object payloads"],"goal":"verify pkg:npm/merge-stream@2.0.0","kind":"HOW","packages":["pkg:npm/merge-stream@2.0.0"],"schemaVersion":1},"contractCommand":["node","test/contract.cjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","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/merge-stream@2.0.0"],"schemaVersion":1,"subject":"pkg:npm/merge-stream@2.0.0","verifierAdapter":"node-typescript@1"}

'use strict';

const mergeStream = require('merge-stream');

/**
 * Merge multiple readable streams into a single composite stream.
 *
 * @param {...(import('stream').Readable|Array<import('stream').Readable>)} streams - Streams or stream arrays to merge.
 * @returns {import('stream').PassThrough & { add: Function, isEmpty: Function }} Merged composite stream.
 */
function combineStreams(...streams) {
  return mergeStream(...streams);
}

/**
 * Check whether a merged stream currently has no active source streams.
 *
 * @param {object} merged - Merged stream instance.
 * @returns {boolean} True if no source streams are attached.
 */
function isStreamEmpty(merged) {
  return merged.isEmpty();
}

/**
 * Add additional source stream(s) to an existing merged stream.
 *
 * @param {object} merged - Merged stream instance.
 * @param {import('stream').Readable|Array<import('stream').Readable>} source - Stream or array of streams to add.
 * @returns {object} The merged stream instance for chaining.
 */
function addStream(merged, source) {
  return merged.add(source);
}

module.exports = {
  mergeStream,
  combineStreams,
  isStreamEmpty,
  addStream
};

{
  "name": "sample-merge-stream",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-merge-stream",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "merge-stream": "2.0.0"
      }
    },
    "node_modules/merge-stream": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/merge-stream/-/merge-stream-2.0.0.tgz",
      "integrity": "sha512-abv/qOcuPfk3URPfDzmZU1LKmuw8kT+0nIHvKrKgFrwifol/doWcdA4ZqsWQ8ENrFKkd67Mfpo/LovbIUsbt3w==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-merge-stream",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of merge-stream stream combination and event forwarding",
  "main": "index.js",
  "scripts": {
    "test": "node test/contract.cjs"
  },
  "license": "MIT-0",
  "dependencies": {
    "merge-stream": "2.0.0"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/merge-stream@2.0.0",
  "kind": "HOW",
  "packages": [
    "pkg:npm/merge-stream@2.0.0"
  ]
}

'use strict';

const assert = require('node:assert');
const { Readable, PassThrough } = require('node:stream');
const mergeStream = require('merge-stream');
const { combineStreams, isStreamEmpty, addStream } = require('../index.js');

async function runContractTests() {
  // 1. Function exports verification and empty stream creation
  assert.strictEqual(typeof mergeStream, 'function', 'mergeStream should be a function');
  assert.strictEqual(typeof combineStreams, 'function', 'combineStreams should be a function');

  const emptyMerged = mergeStream();
  assert.strictEqual(typeof emptyMerged.add, 'function');
  assert.strictEqual(typeof emptyMerged.isEmpty, 'function');
  assert.strictEqual(emptyMerged.isEmpty(), true);
  assert.strictEqual(isStreamEmpty(emptyMerged), true);

  // 2. Merging multiple streams emits data from all sources and ends when all finish
  const s1 = Readable.from(['alpha', 'beta']);
  const s2 = Readable.from(['gamma', 'delta']);
  const merged = combineStreams(s1, s2);
  assert.strictEqual(merged.isEmpty(), false);
  assert.strictEqual(isStreamEmpty(merged), false);

  const chunks = [];
  for await (const chunk of merged) {
    chunks.push(chunk);
  }
  assert.strictEqual(chunks.length, 4);
  assert(chunks.includes('alpha'));
  assert(chunks.includes('beta'));
  assert(chunks.includes('gamma'));
  assert(chunks.includes('delta'));

  // 3. Dynamic stream addition with add() supports single stream and array of streams
  const dynamicMerged = mergeStream();
  assert.strictEqual(dynamicMerged.isEmpty(), true);

  const s3 = Readable.from([1, 2]);
  const s4 = Readable.from([3]);
  const s5 = Readable.from([4, 5]);

  const chained = addStream(dynamicMerged, s3);
  assert.strictEqual(chained, dynamicMerged, 'addStream should return stream for chaining');
  dynamicMerged.add([s4, s5]);
  assert.strictEqual(dynamicMerged.isEmpty(), false);

  const dynamicResults = [];
  for await (const item of dynamicMerged) {
    dynamicResults.push(item);
  }
  assert.deepStrictEqual(dynamicResults.sort((a, b) => a - b), [1, 2, 3, 4, 5]);

  // 4. Error forwarding from source stream to merged stream
  const errorSource = new PassThrough();
  const errorMerged = mergeStream(errorSource);
  const testError = new Error('simulated stream error');

  let errorCaught = null;
  errorMerged.on('error', (err) => {
    errorCaught = err;
  });

  errorSource.emit('error', testError);
  assert.strictEqual(errorCaught, testError, 'Error must be forwarded from source to merged stream');

  // 5. Object mode support for objects and primitives
  const objStream1 = Readable.from([{ key: 'val1' }, { key: 'val2' }]);
  const objStream2 = Readable.from([{ key: 'val3' }]);
  const objMerged = combineStreams(objStream1, objStream2);

  const objResults = [];
  for await (const item of objMerged) {
    objResults.push(item);
  }
  assert.strictEqual(objResults.length, 3);
  assert.deepStrictEqual(objResults, [{ key: 'val1' }, { key: 'val2' }, { key: 'val3' }]);

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

runContractTests().catch((err) => {
  console.error('Contract test failed:', err);
  process.exit(1);
});