readable-stream 2.3.8: Transform

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 readable-stream.Transform in pkg:npm/readable-stream@2.3.8
Kind: HOW

Use EXACTLY these public packages and versions:
  - pkg:npm/readable-stream@2.3.8
Demonstrate these symbols/APIs:
  - readable-stream.Transform

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:31d4fef6688f0af9907c16a67e8797c6278c147af8ef36b4c7a1621229dd9d47","contract":["Transform stream instantiates with custom transform option and converts written chunks to uppercase","Transform stream subclass transforms chunks and appends trailing data via _flush lifecycle hook upon stream end","Transform stream with objectMode processes JavaScript objects and allows 1-to-N output item emission","Transform stream callback propagates errors and triggers error event listener","Transform stream supports piping from a Readable and into a Writable while preserving data integrity"],"goal":"verify readable-stream.Transform in pkg:npm/readable-stream@2.3.8","kind":"HOW","packages":["pkg:npm/readable-stream@2.3.8"],"schemaVersion":1,"symbols":["readable-stream.Transform"]},"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/readable-stream@2.3.8"],"schemaVersion":1,"subject":"pkg:npm/readable-stream@2.3.8","symbols":["readable-stream.Transform"],"verifierAdapter":"node-typescript@1"}

import { Transform } from 'readable-stream';

/**
 * Creates an uppercase Transform stream.
 * @returns {Transform}
 */
export function createUppercaseTransform() {
  return new Transform({
    transform(chunk, encoding, callback) {
      callback(null, chunk.toString().toUpperCase());
    }
  });
}

/**
 * Custom Transform stream that counts chunks and flushes summary statistics on stream end.
 */
export class FramingTransform extends Transform {
  constructor(options) {
    super(options);
    this.totalChunks = 0;
  }

  _transform(chunk, encoding, callback) {
    this.totalChunks++;
    this.push(`[CHUNK:${chunk.toString()}]`);
    callback();
  }

  _flush(callback) {
    this.push(`[TOTAL:${this.totalChunks}]`);
    callback();
  }
}

export { Transform };

{
  "name": "sample-readable-stream-transform",
  "version": "1.0.0",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sample-readable-stream-transform",
      "version": "1.0.0",
      "license": "MIT-0",
      "dependencies": {
        "readable-stream": "2.3.8"
      }
    },
    "node_modules/core-util-is": {
      "version": "1.0.3",
      "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz",
      "integrity": "sha512-ZQBvi1DcpJ4GDqanjucZ2Hj3wEO5pZDS89BWbkcrvdxksJorwUDDZamX9ldFkp9aw2lmBDLgkObEA4DWNJ9FYQ==",
      "license": "MIT"
    },
    "node_modules/inherits": {
      "version": "2.0.4",
      "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz",
      "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==",
      "license": "ISC"
    },
    "node_modules/isarray": {
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/isarray/-/isarray-1.0.0.tgz",
      "integrity": "sha512-VLghIWNM6ELQzo7zwmcg0NmTVyWKYjvIeM83yjp0wRDTmUnrM678fQbcKBo6n2CJEF0szoG//ytg+TKla89ALQ==",
      "license": "MIT"
    },
    "node_modules/process-nextick-args": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/process-nextick-args/-/process-nextick-args-2.0.1.tgz",
      "integrity": "sha512-3ouUOpQhtgrbOa17J7+uxOTpITYWaGP7/AhoR3+A+/1e9skrzelGi/dXzEYyvbxubEF6Wn2ypscTKiKJFFn1ag==",
      "license": "MIT"
    },
    "node_modules/readable-stream": {
      "version": "2.3.8",
      "resolved": "https://registry.npmjs.org/readable-stream/-/readable-stream-2.3.8.tgz",
      "integrity": "sha512-8p0AUk4XODgIewSi0l8Epjs+EVnWiK7NoDIEGU0HhE7+ZyY8D1IMY7odu5lRrFXGg71L15KG8QrPmum45RTtdA==",
      "license": "MIT",
      "dependencies": {
        "core-util-is": "~1.0.0",
        "inherits": "~2.0.3",
        "isarray": "~1.0.0",
        "process-nextick-args": "~2.0.0",
        "safe-buffer": "~5.1.1",
        "string_decoder": "~1.1.1",
        "util-deprecate": "~1.0.1"
      }
    },
    "node_modules/safe-buffer": {
      "version": "5.1.2",
      "resolved": "https://registry.npmjs.org/safe-buffer/-/safe-buffer-5.1.2.tgz",
      "integrity": "sha512-Gd2UZBJDkXlY7GbJxfsE8/nvKkUEU1G38c1siN6QP6a9PT9MmHB8GnpscSmMJSoF8LOIrt8ud/wPtojys4G6+g==",
      "license": "MIT"
    },
    "node_modules/string_decoder": {
      "version": "1.1.1",
      "resolved": "https://registry.npmjs.org/string_decoder/-/string_decoder-1.1.1.tgz",
      "integrity": "sha512-n/ShnvDi6FHbbVfviro+WojiFzv+s8MPMHBczVePfUpDJLwoLT0ht1l4YwBCbi8pJAveEEdnkHyPyTP/mzRfwg==",
      "license": "MIT",
      "dependencies": {
        "safe-buffer": "~5.1.0"
      }
    },
    "node_modules/util-deprecate": {
      "version": "1.0.2",
      "resolved": "https://registry.npmjs.org/util-deprecate/-/util-deprecate-1.0.2.tgz",
      "integrity": "sha512-EPD5q1uXyFxJpCrLnCc1nHnq3gOa6DZBocAIiI2TaSCA7VCJ1UJDMagCzIkXNsUYfD1daK//LTEQ8xiIbrHtcw==",
      "license": "MIT"
    }
  }
}

{
  "name": "sample-readable-stream-transform",
  "version": "1.0.0",
  "type": "module",
  "private": true,
  "dependencies": {
    "readable-stream": "2.3.8"
  },
  "license": "MIT-0"
}

{
  "schemaVersion": 1,
  "goal": "verify readable-stream.Transform in pkg:npm/readable-stream@2.3.8",
  "kind": "HOW",
  "packages": [
    "pkg:npm/readable-stream@2.3.8"
  ],
  "symbols": [
    "readable-stream.Transform"
  ]
}

import assert from 'node:assert/strict';
import { Readable, Writable, Transform } from 'readable-stream';
import { createUppercaseTransform, FramingTransform } from '../index.mjs';

// 1. Transform stream instantiates with custom transform option and converts written chunks to uppercase
await new Promise((resolve, reject) => {
  const upperTransform = createUppercaseTransform();
  const output = [];

  upperTransform.on('data', (chunk) => {
    output.push(chunk.toString());
  });

  upperTransform.on('end', () => {
    try {
      assert.deepEqual(output, ['HELLO', 'WORLD']);
      resolve();
    } catch (err) {
      reject(err);
    }
  });

  upperTransform.on('error', reject);

  upperTransform.write('hello');
  upperTransform.write('world');
  upperTransform.end();
});

// 2. Transform stream subclass transforms chunks and appends trailing data via _flush lifecycle hook upon stream end
await new Promise((resolve, reject) => {
  const framer = new FramingTransform();
  const output = [];

  framer.on('data', (chunk) => {
    output.push(chunk.toString());
  });

  framer.on('end', () => {
    try {
      assert.deepEqual(output, [
        '[CHUNK:item1]',
        '[CHUNK:item2]',
        '[TOTAL:2]'
      ]);
      resolve();
    } catch (err) {
      reject(err);
    }
  });

  framer.on('error', reject);

  framer.write('item1');
  framer.write('item2');
  framer.end();
});

// 3. Transform stream with objectMode processes JavaScript objects and allows 1-to-N output item emission
await new Promise((resolve, reject) => {
  const expander = new Transform({
    objectMode: true,
    transform(chunk, encoding, callback) {
      for (let i = 0; i < chunk.repeat; i++) {
        this.push({ id: chunk.id, index: i, value: chunk.value });
      }
      callback();
    }
  });

  const output = [];
  expander.on('data', (chunk) => {
    output.push(chunk);
  });

  expander.on('end', () => {
    try {
      assert.deepEqual(output, [
        { id: 1, index: 0, value: 'A' },
        { id: 1, index: 1, value: 'A' },
        { id: 2, index: 0, value: 'B' }
      ]);
      resolve();
    } catch (err) {
      reject(err);
    }
  });

  expander.on('error', reject);

  expander.write({ id: 1, repeat: 2, value: 'A' });
  expander.write({ id: 2, repeat: 1, value: 'B' });
  expander.end();
});

// 4. Transform stream callback propagates errors and triggers error event listener
await new Promise((resolve, reject) => {
  const errorTransform = new Transform({
    transform(chunk, encoding, callback) {
      if (chunk.toString() === 'bad') {
        callback(new Error('transform processing error'));
      } else {
        callback(null, chunk);
      }
    }
  });

  errorTransform.on('error', (err) => {
    try {
      assert.equal(err.message, 'transform processing error');
      resolve();
    } catch (e) {
      reject(e);
    }
  });

  errorTransform.on('end', () => {
    reject(new Error('Stream should have emitted error and stopped'));
  });

  errorTransform.write('good');
  errorTransform.write('bad');
  errorTransform.write('after');
  errorTransform.end();
});

// 5. Transform stream supports piping from a Readable and into a Writable while preserving data integrity
await new Promise((resolve, reject) => {
  const source = new Readable({
    read() {}
  });

  const transform = new Transform({
    transform(chunk, encoding, callback) {
      callback(null, `${chunk.toString()}-processed`);
    }
  });

  const results = [];
  const destination = new Writable({
    write(chunk, encoding, callback) {
      results.push(chunk.toString());
      callback();
    }
  });

  destination.on('finish', () => {
    try {
      assert.deepEqual(results, ['step1-processed', 'step2-processed']);
      resolve();
    } catch (err) {
      reject(err);
    }
  });

  destination.on('error', reject);
  transform.on('error', reject);
  source.on('error', reject);

  source.pipe(transform).pipe(destination);

  source.push('step1');
  source.push('step2');
  source.push(null);
});

console.log('All readable-stream.Transform contract tests passed.');