teex 1.0.1: teex

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/teex@1.0.1
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/teex@1.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:2d0ce3c4902c9fcc4e2c9250f970f31f488dd249d7489c4d0b0a2f70ab9b5eab","contract":["teex splits a readable stream into two readable streams by default","teex splits a readable stream into a specified number of fork streams","teex streams receive all data emitted by the source stream in the same order","teex propagates the end event of the source stream to all branched streams","teex destroys all branched streams with error when source emits an error","teex pauses and resumes source stream based on downstream consumption","splitStream and teePair helper functions wrap teex with expected signatures"],"goal":"verify pkg:npm/teex@1.0.1","kind":"HOW","packages":["pkg:npm/teex@1.0.1"],"schemaVersion":1,"symbols":["teex"]},"contractCommand":["node","test/contract.mjs"],"environment":{"arch":"x64","distro":"ubuntu","ecosystem":"npm","libc":"glibc","libcVersion":"2.39","os":"linux","osVersionBucket":"24","packageManager":"npm","schemaVersion":1},"license":"MIT-0","packages":["pkg:npm/teex@1.0.1"],"schemaVersion":1,"subject":"pkg:npm/teex@1.0.1","symbols":["teex"],"verifierAdapter":"node-typescript@1"}

{
  "name": "sample-teex",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-teex",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "streamx": "^2.12.5",
        "teex": "1.0.1"
      }
    },
    "node_modules/b4a": {
      "version": "1.8.1",
      "resolved": "https://registry.npmjs.org/b4a/-/b4a-1.8.1.tgz",
      "integrity": "sha512-aiqre1Nr0B/6DgE2N5vwTc+2/oQZ4Wh1t4NznYY4E00y8LCt6NqdRv81so00oo27D8MVKTpUa/MwUUtBLXCoDw==",
      "license": "Apache-2.0",
      "peerDependencies": {
        "react-native-b4a": "*"
      },
      "peerDependenciesMeta": {
        "react-native-b4a": {
          "optional": true
        }
      }
    },
    "node_modules/bare-events": {
      "version": "2.9.1",
      "resolved": "https://registry.npmjs.org/bare-events/-/bare-events-2.9.1.tgz",
      "integrity": "sha512-Z0oHEHAFDZkffN8Qc39zNZjQlMDkPJRyyyZieU1VH7u8c5S+qHZ2S8ixdKIAxEjfHO7FJxXmJWgteOghVanIsg==",
      "license": "Apache-2.0",
      "peerDependencies": {
        "bare-abort-controller": "*"
      },
      "peerDependenciesMeta": {
        "bare-abort-controller": {
          "optional": true
        }
      }
    },
    "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.0",
      "resolved": "https://registry.npmjs.org/streamx/-/streamx-2.28.0.tgz",
      "integrity": "sha512-1Yowhzjf0ivGMrTIkY9hav5TxobO9qIVqUE41fiCGMGgc3CLlf4MY+9AHmZqBWgDTue0fY9zWjYFVyf6Diuobw==",
      "license": "MIT",
      "dependencies": {
        "events-universal": "^1.0.0",
        "fast-fifo": "^1.3.2",
        "text-decoder": "^1.1.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-teex",
  "version": "1.0.0",
  "private": true,
  "description": "Clean-room verification of teex in teex@1.0.1",
  "main": "src/index.mjs",
  "type": "module",
  "license": "MIT-0",
  "dependencies": {
    "streamx": "^2.12.5",
    "teex": "1.0.1"
  }
}

{
  "schemaVersion": 1,
  "goal": "verify pkg:npm/teex@1.0.1",
  "kind": "HOW",
  "packages": [
    "pkg:npm/teex@1.0.1"
  ],
  "symbols": [
    "teex"
  ]
}

import teex from "teex";
import { Readable, Writable } from "streamx";

/**
 * Splits a single readable stream into multiple readable streamx streams.
 *
 * @param {import('streamx').Readable | NodeJS.ReadableStream} stream - The source readable stream.
 * @param {number} [forks=2] - The number of streams to split into.
 * @returns {import('streamx').Readable[]} Array of split readable streams.
 */
export function splitStream(stream, forks = 2) {
  return teex(stream, forks);
}

/**
 * Convenience helper to tee a readable stream into exactly two readable streams.
 *
 * @param {import('streamx').Readable | NodeJS.ReadableStream} stream - The source readable stream.
 * @returns {[import('streamx').Readable, import('streamx').Readable]} Pair of split readable streams.
 */
export function teePair(stream) {
  const [first, second] = teex(stream, 2);
  return [first, second];
}

export { teex, Readable, Writable };
export default teex;

import assert from "node:assert/strict";
import teex, {
  splitStream,
  teePair,
  Readable,
} from "../src/index.mjs";

// 1. teex splits a readable stream into two readable streams by default
{
  const src = new Readable({
    read(cb) {
      this.push("hello");
      this.push(null);
      cb(null);
    },
  });
  const streams = teex(src);
  assert.ok(Array.isArray(streams), "teex return value should be an array");
  assert.strictEqual(streams.length, 2, "Default forks should be 2");
  assert.ok(streams[0] instanceof Readable, "Fork 0 must be a Readable stream");
  assert.ok(streams[1] instanceof Readable, "Fork 1 must be a Readable stream");
}

// 2. teex splits a readable stream into a specified number of fork streams
{
  const src = new Readable({
    read(cb) {
      this.push("test");
      this.push(null);
      cb(null);
    },
  });
  const streams = teex(src, 4);
  assert.ok(Array.isArray(streams), "teex return value should be an array");
  assert.strictEqual(streams.length, 4, "Should create exactly 4 fork streams");
}

// 3. teex streams receive all data emitted by the source stream in the same order
{
  const chunks = ["chunk-1", "chunk-2", "chunk-3"];
  let idx = 0;
  const src = new Readable({
    read(cb) {
      if (idx < chunks.length) {
        this.push(chunks[idx++]);
      } else {
        this.push(null);
      }
      cb(null);
    },
  });

  const [s1, s2, s3] = teex(src, 3);
  const r1 = [];
  const r2 = [];
  const r3 = [];

  const p1 = new Promise((resolve, reject) => {
    s1.on("data", (d) => r1.push(d.toString()));
    s1.on("end", resolve);
    s1.on("error", reject);
  });
  const p2 = new Promise((resolve, reject) => {
    s2.on("data", (d) => r2.push(d.toString()));
    s2.on("end", resolve);
    s2.on("error", reject);
  });
  const p3 = new Promise((resolve, reject) => {
    s3.on("data", (d) => r3.push(d.toString()));
    s3.on("end", resolve);
    s3.on("error", reject);
  });

  await Promise.all([p1, p2, p3]);

  assert.deepStrictEqual(r1, chunks, "s1 must receive all chunks in order");
  assert.deepStrictEqual(r2, chunks, "s2 must receive all chunks in order");
  assert.deepStrictEqual(r3, chunks, "s3 must receive all chunks in order");
}

// 4. teex propagates the end event of the source stream to all branched streams
{
  const src = new Readable({
    read(cb) {
      this.push(null);
      cb(null);
    },
  });

  const [s1, s2] = teex(src, 2);
  let s1Ended = false;
  let s2Ended = false;

  const p1 = new Promise((resolve) => {
    s1.on("end", () => {
      s1Ended = true;
      resolve();
    });
    s1.resume();
  });
  const p2 = new Promise((resolve) => {
    s2.on("end", () => {
      s2Ended = true;
      resolve();
    });
    s2.resume();
  });

  await Promise.all([p1, p2]);
  assert.strictEqual(s1Ended, true, "s1 must end when source ends");
  assert.strictEqual(s2Ended, true, "s2 must end when source ends");
}

// 5. teex destroys all branched streams with error when source emits an error
{
  const expectedErr = new Error("source stream failure");
  const src = new Readable({
    read(cb) {
      cb(expectedErr);
    },
  });

  const [s1, s2] = teex(src, 2);
  let s1Err = null;
  let s2Err = null;

  const p1 = new Promise((resolve) => {
    s1.on("error", (err) => {
      s1Err = err;
      resolve();
    });
    s1.resume();
  });
  const p2 = new Promise((resolve) => {
    s2.on("error", (err) => {
      s2Err = err;
      resolve();
    });
    s2.resume();
  });

  await Promise.all([p1, p2]);
  assert.strictEqual(s1Err, expectedErr, "s1 should receive error emitted by source");
  assert.strictEqual(s2Err, expectedErr, "s2 should receive error emitted by source");
  assert.strictEqual(s1.destroyed, true, "s1 should be destroyed");
  assert.strictEqual(s2.destroyed, true, "s2 should be destroyed");
}

// 6. teex pauses and resumes source stream based on downstream consumption
{
  let pushCount = 0;
  const src = new Readable({
    read(cb) {
      while (pushCount < 50) {
        pushCount++;
        if (!this.push(Buffer.alloc(512))) {
          break;
        }
      }
      if (pushCount >= 50) {
        this.push(null);
      }
      cb(null);
    },
  });

  const [s1, s2] = teex(src, 2);
  let s1Count = 0;
  let s2Count = 0;

  const p1 = new Promise((resolve) => {
    s1.on("data", () => s1Count++);
    s1.on("end", resolve);
  });
  const p2 = new Promise((resolve) => {
    s2.on("data", () => s2Count++);
    s2.on("end", resolve);
  });

  await Promise.all([p1, p2]);
  assert.strictEqual(s1Count, 50, "s1 must receive all 50 chunks");
  assert.strictEqual(s2Count, 50, "s2 must receive all 50 chunks");
}

// 7. splitStream and teePair helper functions wrap teex with expected signatures
{
  const src1 = new Readable({
    read(cb) {
      this.push("sample");
      this.push(null);
      cb(null);
    },
  });
  const splits = splitStream(src1, 3);
  assert.strictEqual(splits.length, 3, "splitStream should return 3 streams");

  const src2 = new Readable({
    read(cb) {
      this.push("sample2");
      this.push(null);
      cb(null);
    },
  });
  const [a, b] = teePair(src2);
  assert.ok(a instanceof Readable, "teePair stream 0 should be Readable");
  assert.ok(b instanceof Readable, "teePair stream 1 should be Readable");
}

console.log("All teex contract assertions passed successfully.");