@gjsify/stream 0.1.7 → 0.1.9

package/src/callable.spec.ts

@@ -0,0 +1,157 @@
+// Legacy `.call(this)` + `util.inherits(Sub, Parent)` compatibility tests.
+//
+// Ported from refs/node-test/parallel/test-util-inherits.js
+// Original: MIT license, Node.js contributors
+// Modifications: adapted to @gjsify/unit and extended to cover all six stream
+// classes that are wrapped by `makeCallable` in `./callable.ts`.
+//
+// Regression coverage for the npm `send` (express.static) bug and for our own
+// `@gjsify/crypto` `Hash.copy()` path which both do `Stream.call(this)` /
+// `Transform.call(copy)` on pre-ES2015 CJS-style constructors.
+
+import { describe, it, expect } from '@gjsify/unit';
+import { Stream, Readable, Writable, Duplex, Transform, PassThrough } from 'node:stream';
+import { inherits } from 'node:util';
+
+export default async () => {
+	await describe('makeCallable: new invocation still works', async () => {
+		await it('new Stream() returns a valid instance', async () => {
+			const s = new Stream();
+			expect(typeof (s as any).pipe).toBe('function');
+			expect(s instanceof Stream).toBe(true);
+		});
+
+		await it('new Readable() initialises readable state', async () => {
+			const r = new Readable({ read() {} });
+			expect(r.readable).toBe(true);
+			expect(r instanceof Readable).toBe(true);
+			expect(r instanceof Stream).toBe(true);
+		});
+
+		await it('new Transform() initialises both readable + writable state', async () => {
+			const t = new Transform({ transform(chunk, _enc, cb) { cb(null, chunk); } });
+			expect(t.readable).toBe(true);
+			expect(t.writable).toBe(true);
+			expect(t instanceof Transform).toBe(true);
+			expect(t instanceof Duplex).toBe(true);
+			expect(t instanceof Readable).toBe(true);
+		});
+
+		await it('Stream.prototype is accessible via the wrapper', async () => {
+			expect(typeof (Stream as any).prototype).toBe('object');
+			expect(typeof (Stream as any).prototype.pipe).toBe('function');
+		});
+	});
+
+	await describe('makeCallable: legacy Stream.call(this) + util.inherits', async () => {
+		await it('Stream.call(plainObject) assigns EventEmitter bookkeeping', async () => {
+			// Plain object promoted to a Stream via .call()
+			const plain: any = Object.create(Stream.prototype);
+			(Stream as any).call(plain);
+			// EventEmitter state is now present
+			plain.on('ping', function(this: any, msg: string) { this.received = msg; });
+			plain.emit('ping', 'hi');
+			expect(plain.received).toBe('hi');
+		});
+
+		await it('legacy subclass pattern (function + inherits + .call) works', async () => {
+			function SubStream(this: any) {
+				(Stream as any).call(this);
+				this.foo = 42;
+			}
+			inherits(SubStream as any, Stream as any);
+			(SubStream.prototype as any).greet = function() { return 'hello'; };
+
+			const s: any = new (SubStream as any)();
+			expect(s.foo).toBe(42);
+			expect(s.greet()).toBe('hello');
+			// Inherited from Stream.prototype
+			expect(typeof s.pipe).toBe('function');
+			expect(s instanceof Stream).toBe(true);
+		});
+
+		await it('multi-level inherits (A.call -> B.call -> C) works', async () => {
+			function A(this: any) {
+				(Stream as any).call(this);
+				this._a = 'a';
+			}
+			inherits(A as any, Stream as any);
+			(A.prototype as any).a = function() { return this._a; };
+
+			function B(this: any) {
+				(A as any).call(this);
+				this._b = 'b';
+			}
+			inherits(B as any, A as any);
+			(B.prototype as any).b = function() { return this._b; };
+
+			const b: any = new (B as any)();
+			expect(b.a()).toBe('a');
+			expect(b.b()).toBe('b');
+			expect(b instanceof A).toBe(true);
+			expect(b instanceof Stream).toBe(true);
+		});
+	});
+
+	await describe('makeCallable: Readable / Writable / Transform .call(this)', async () => {
+		await it('Readable.call(plain) sets up readable state', async () => {
+			const r: any = Object.create(Readable.prototype);
+			(Readable as any).call(r, { read() {} });
+			expect(r.readable).toBe(true);
+			expect(typeof r.readableHighWaterMark).toBe('number');
+			// pipe is inherited from Stream.prototype through Readable.prototype
+			expect(typeof r.pipe).toBe('function');
+		});
+
+		await it('Writable.call(plain) sets up writable state', async () => {
+			const w: any = Object.create(Writable.prototype);
+			(Writable as any).call(w, { write(_c: any, _e: any, cb: any) { cb(); } });
+			expect(w.writable).toBe(true);
+			expect(typeof w.writableHighWaterMark).toBe('number');
+		});
+
+		await it('Transform.call(plain) sets up both readable and writable state', async () => {
+			// This is the exact pattern used by @gjsify/crypto Hash.copy():
+			//   const copy = Object.create(Hash.prototype);
+			//   Transform.call(copy);
+			const copy: any = Object.create(Transform.prototype);
+			(Transform as any).call(copy);
+			expect(copy.readable).toBe(true);
+			expect(copy.writable).toBe(true);
+			// The Transform should be usable after .call() initialization —
+			// field initializers from all ancestors ran on copy.
+			expect(typeof copy.readableHighWaterMark).toBe('number');
+			expect(typeof copy.writableHighWaterMark).toBe('number');
+		});
+
+		await it('PassThrough.call(plain) inherits the full chain', async () => {
+			const pt: any = Object.create(PassThrough.prototype);
+			(PassThrough as any).call(pt);
+			expect(pt.readable).toBe(true);
+			expect(pt.writable).toBe(true);
+		});
+	});
+
+	await describe('makeCallable: integration with util.inherits', async () => {
+		await it('inherits(Sub, Readable) + Readable.call(this) yields a working Readable subclass', async () => {
+			function SimpleSrc(this: any, items: number[]) {
+				(Readable as any).call(this, { objectMode: true });
+				this._items = items;
+			}
+			inherits(SimpleSrc as any, Readable as any);
+			(SimpleSrc.prototype as any)._read = function() {
+				const item = this._items.shift();
+				this.push(item !== undefined ? item : null);
+			};
+
+			const src: any = new (SimpleSrc as any)([1, 2, 3]);
+			const out: number[] = [];
+			await new Promise<void>((resolve, reject) => {
+				src.on('data', (chunk: number) => out.push(chunk));
+				src.on('end', resolve);
+				src.on('error', reject);
+			});
+			expect(out).toEqualArray([1, 2, 3]);
+		});
+	});
+};

package/src/callable.ts

@@ -0,0 +1,3 @@
+// Re-exported from @gjsify/utils — second consumer (events) triggered promotion.
+// See packages/gjs/utils/src/callable.ts for implementation and comments.
+export { makeCallable } from '@gjsify/utils';

package/src/consumers/index.spec.ts

@@ -33,13 +33,13 @@ export default async () => {
     await describe('json', async () => {
       await it('should consume stream as JSON', async () => {
         const stream = Readable.from(['{"key":', '"value"}']);
-        const result = await json(stream);
+        const result = await json(stream) as { key: string };
         expect(result.key).toBe('value');
       });
 
       await it('should parse JSON array', async () => {
         const stream = Readable.from(['[1,2,3]']);
-        const result = await json(stream);
+        const result = await json(stream) as number[];
         expect(Array.isArray(result)).toBe(true);
         expect(result.length).toBe(3);
         expect(result[0]).toBe(1);

package/src/index.ts

@@ -25,6 +25,16 @@ export function setDefaultHighWaterMark(objectMode: boolean, value: number): voi
   }
 }
 
+/** Validate a named high-water-mark option and throw ERR_INVALID_ARG_VALUE on NaN/non-number. */
+function validateHighWaterMark(name: string, value: unknown): void {
+  if (value === undefined) return;
+  if (typeof value !== 'number' || Number.isNaN(value)) {
+    const err = new TypeError(`The value of "${name}" is invalid. Received ${value}`);
+    (err as any).code = 'ERR_INVALID_ARG_VALUE';
+    throw err;
+  }
+}
+
 // ---- Types ----
 
 /** Base options accepted by the Stream constructor (superset used by subclass options). */
@@ -48,14 +58,10 @@ interface StreamLike extends EventEmitter {
 /** Tracked pipe destination for unpipe support. */
 interface PipeState {
   dest: Writable;
-  ondata: (chunk: unknown) => void;
-  ondrain: () => void;
-  onend: () => void;
   cleanup: () => void;
-  doEnd: boolean;
 }
 
-export class Stream extends EventEmitter {
+class Stream_ extends EventEmitter {
   constructor(opts?: StreamOptions) {
     super(opts);
   }
@@ -64,44 +70,74 @@ export class Stream extends EventEmitter {
     const source = this as unknown as Readable;
     const doEnd = options?.end !== false;
 
+    // Drain listener is added lazily only when backpressure occurs.
+    let drainListenerAdded = false;
+    const ondrain = () => {
+      drainListenerAdded = false;
+      destination.removeListener('drain', ondrain);
+      if (typeof (source as StreamLike).resume === 'function') {
+        (source as StreamLike).resume!();
+      }
+    };
+
     const ondata = (chunk: unknown) => {
       if (destination.writable) {
         if (destination.write(chunk) === false && typeof (source as StreamLike).pause === 'function') {
           (source as StreamLike).pause!();
+          if (!drainListenerAdded) {
+            drainListenerAdded = true;
+            destination.on('drain', ondrain);
+          }
         }
       }
     };
 
     source.on('data', ondata);
 
-    const ondrain = () => {
-      if (typeof (source as StreamLike).resume === 'function') {
-        (source as StreamLike).resume!();
-      }
-    };
-    destination.on('drain', ondrain);
+    let didEnd = false;
 
     const onend = () => {
+      if (didEnd) return;
+      didEnd = true;
+      if (doEnd) destination.end();
+    };
+
+    const onclose = () => {
+      if (didEnd) return;
+      didEnd = true;
       if (doEnd) {
-        destination.end();
+        // Modern Readable streams (Readable_) do NOT destroy dest on source close —
+        // only call dest.end/destroy for legacy Stream objects (no Readable_ prototype).
+        if (!(source instanceof Readable) && typeof (destination as any).destroy === 'function') {
+          (destination as any).destroy();
+        }
       }
     };
+
     if (doEnd) {
       source.on('end', onend);
+      source.on('close', onclose);
     }
 
     const cleanup = () => {
       source.removeListener('data', ondata);
-      destination.removeListener('drain', ondrain);
+      if (drainListenerAdded) destination.removeListener('drain', ondrain);
       source.removeListener('end', onend);
+      source.removeListener('close', onclose);
+      // Self-remove from both end and close
+      source.removeListener('end', cleanup);
+      source.removeListener('close', cleanup);
+      destination.removeListener('close', cleanup);
     };
 
+    source.on('end', cleanup);
     source.on('close', cleanup);
     destination.on('close', cleanup);
 
     // Track piped destinations for unpipe
     if (source instanceof Readable) {
-      source._pipeDests.push({ dest: destination, ondata, ondrain, onend, cleanup, doEnd });
+      source._pipeDests.push({ dest: destination, cleanup });
+      (source as any)._readableState.pipes.push(destination);
     }
 
     destination.emit('pipe', source);
@@ -111,7 +147,7 @@ export class Stream extends EventEmitter {
 
 // ---- Readable ----
 
-export class Readable extends Stream {
+class Readable_ extends Stream_ {
   readable = true;
   readableFlowing: boolean | null = null;
   readableLength = 0;
@@ -126,7 +162,7 @@ export class Readable extends Stream {
   _pipeDests: PipeState[] = [];
 
   private _buffer: unknown[] = [];
-  private _readableState = { ended: false, endEmitted: false, reading: false, constructed: true };
+  _readableState = { ended: false, endEmitted: false, reading: false, constructed: true, highWaterMark: 0, objectMode: false, pipes: [] as any[] };
   private _readablePending = false;
   private _readImpl: ((size: number) => void) | undefined;
   private _destroyImpl: ((error: Error | null, cb: (error?: Error | null) => void) => void) | undefined;
@@ -137,6 +173,8 @@ export class Readable extends Stream {
     this.readableHighWaterMark = opts?.highWaterMark ?? getDefaultHighWaterMark(opts?.objectMode ?? false);
     this.readableEncoding = opts?.encoding ?? null;
     this.readableObjectMode = opts?.objectMode ?? false;
+    this._readableState.highWaterMark = this.readableHighWaterMark;
+    this._readableState.objectMode = this.readableObjectMode;
     if (opts?.read) this._readImpl = opts.read;
     if (opts?.destroy) this._destroyImpl = opts.destroy;
     if (opts?.construct) this._constructImpl = opts.construct;
@@ -275,6 +313,22 @@ export class Readable extends Stream {
       return false;
     }
 
+    // Validate chunk type for non-objectMode streams (Node.js ERR_INVALID_ARG_TYPE).
+    // Accept string, Buffer, or any ArrayBufferView — the latter covers Uint8Array
+    // and TypedArrays from any realm (GJS vs host bundle), avoiding cross-realm
+    // `instanceof Uint8Array` mismatches that would otherwise reject real Buffers.
+    if (!this.readableObjectMode) {
+      const isValid = typeof chunk === 'string' || ArrayBuffer.isView(chunk);
+      if (!isValid) {
+        const err = Object.assign(
+          new TypeError(`Invalid non-string/buffer chunk type: ${typeof chunk}`),
+          { code: 'ERR_INVALID_ARG_TYPE' }
+        );
+        nextTick(() => this.emit('error', err));
+        return false;
+      }
+    }
+
     this._buffer.push(chunk);
     this.readableLength += this.readableObjectMode ? 1 : (chunk.length ?? 1);
 
@@ -410,6 +464,7 @@ export class Readable extends Stream {
         state.dest.emit('unpipe', this);
       }
       this._pipeDests = [];
+      this._readableState.pipes = [];
       this.readableFlowing = false;
     } else {
       const idx = this._pipeDests.findIndex(s => s.dest === destination);
@@ -417,6 +472,8 @@ export class Readable extends Stream {
         const state = this._pipeDests[idx];
         state.cleanup();
         this._pipeDests.splice(idx, 1);
+        const pipeIdx = this._readableState.pipes.indexOf(destination);
+        if (pipeIdx !== -1) this._readableState.pipes.splice(pipeIdx, 1);
         destination.emit('unpipe', this);
         if (this._pipeDests.length === 0) {
           this.readableFlowing = false;
@@ -426,6 +483,14 @@ export class Readable extends Stream {
     return this;
   }
 
+  _destroy(error: Error | null, callback: (error?: Error | null) => void): void {
+    if (this._destroyImpl) {
+      this._destroyImpl.call(this, error, callback);
+    } else {
+      callback(error ?? undefined);
+    }
+  }
+
   destroy(error?: Error): this {
     if (this.destroyed) return this;
     this.destroyed = true;
@@ -439,7 +504,14 @@ export class Readable extends Stream {
       nextTick(() => this.emit('close'));
     };
 
-    if (this._destroyImpl) {
+    // Dispatch virtually ONLY when the user overrode _destroy on the instance
+    // (e.g. tests: `stream._destroy = fn`). Do NOT call a subclass prototype
+    // _destroy: net.Socket's prototype `_destroy` synchronously cancels in-flight
+    // Gio I/O and would break tests that call destroy() during pending writes.
+    // The opts.destroy path still runs via _destroyImpl as before.
+    if (Object.prototype.hasOwnProperty.call(this, '_destroy')) {
+      (this as any)._destroy(error ?? null, cb);
+    } else if (this._destroyImpl) {
       this._destroyImpl.call(this, error ?? null, cb);
     } else {
       cb(error);
@@ -541,7 +613,21 @@ export class Readable extends Stream {
 
 // ---- Writable ----
 
-export class Writable extends Stream {
+class Writable_ extends Stream_ {
+  // Allow `duplex instanceof Writable` to return true even though Duplex inherits
+  // from Readable_ only. Mirrors Node.js: standard prototype-chain check first,
+  // then duck-type fallback — but only when checking against Writable itself, not
+  // against a user subclass. Because `Writable` is exported as a makeCallable Proxy,
+  // `this === Writable_` fails for `obj instanceof Writable`; however the Proxy's
+  // default `get` trap forwards `.prototype` straight to the target, so the
+  // prototype reference check below correctly recognises both.
+  static [Symbol.hasInstance](obj: any): boolean {
+    if (typeof (this as any).prototype !== 'undefined' &&
+        Object.prototype.isPrototypeOf.call((this as any).prototype, obj)) return true;
+    if ((this as any).prototype !== Writable_.prototype) return false;
+    return obj !== null && obj !== undefined && typeof obj.writableHighWaterMark === 'number';
+  }
+
   writable = true;
   writableHighWaterMark: number;
   writableLength = 0;
@@ -649,7 +735,7 @@ export class Writable extends Stream {
       } else {
         nextTick(() => {
           callback();
-          if (this.writableNeedDrain && this.writableLength < this.writableHighWaterMark) {
+          if (this.writableNeedDrain && this.writableLength <= this.writableHighWaterMark) {
             this.writableNeedDrain = false;
             this.emit('drain');
           }
@@ -817,7 +903,7 @@ export class Writable extends Stream {
           this.emit('error', err);
         } else {
           for (const b of buffered) b.callback();
-          if (this.writableNeedDrain && this.writableLength < this.writableHighWaterMark) {
+          if (this.writableNeedDrain && this.writableLength <= this.writableHighWaterMark) {
             this.writableNeedDrain = false;
             this.emit('drain');
           }
@@ -861,7 +947,7 @@ export class Writable extends Stream {
 
 // ---- Duplex ----
 
-export class Duplex extends Readable {
+class Duplex_ extends Readable_ {
   writable = true;
   writableHighWaterMark: number;
   writableLength = 0;
@@ -873,6 +959,9 @@ export class Duplex extends Readable {
   allowHalfOpen: boolean;
   private _decodeStrings: boolean;
 
+  // Exposed writable-side state (mirrors Node.js _writableState for split HWM tests)
+  _writableState = { highWaterMark: 0, objectMode: false };
+
   private _duplexCorkedBuffer: Array<{ chunk: any; encoding: string; callback: (error?: Error | null) => void }> = [];
   private _writeImpl: ((chunk: any, encoding: string, cb: (error?: Error | null) => void) => void) | undefined;
   private _finalImpl: ((cb: (error?: Error | null) => void) => void) | undefined;
@@ -882,8 +971,34 @@ export class Duplex extends Readable {
 
   constructor(opts?: DuplexOptions) {
     super(opts);
-    this.writableHighWaterMark = opts?.writableHighWaterMark ?? opts?.highWaterMark ?? getDefaultHighWaterMark(opts?.writableObjectMode ?? opts?.objectMode ?? false);
+
+    validateHighWaterMark('writableHighWaterMark', opts?.writableHighWaterMark);
+    validateHighWaterMark('readableHighWaterMark', opts?.readableHighWaterMark);
+
+    // Writable side: highWaterMark (shared) takes priority over writableHighWaterMark.
     this.writableObjectMode = opts?.writableObjectMode ?? opts?.objectMode ?? false;
+    this.writableHighWaterMark = opts?.highWaterMark
+      ?? opts?.writableHighWaterMark
+      ?? getDefaultHighWaterMark(this.writableObjectMode);
+    this._writableState.highWaterMark = this.writableHighWaterMark;
+    this._writableState.objectMode = this.writableObjectMode;
+
+    // Readable side overrides: Readable_ constructor already applied opts.highWaterMark,
+    // so only override with readableHighWaterMark when highWaterMark was NOT set.
+    if (opts?.highWaterMark === undefined && opts?.readableHighWaterMark !== undefined) {
+      this.readableHighWaterMark = opts.readableHighWaterMark;
+      this._readableState.highWaterMark = opts.readableHighWaterMark;
+    }
+    if (opts?.readableObjectMode !== undefined) {
+      this.readableObjectMode = opts.readableObjectMode;
+      this._readableState.objectMode = opts.readableObjectMode;
+      // Re-derive readable HWM for objectMode when neither readableHighWaterMark nor highWaterMark was set.
+      if (opts?.readableHighWaterMark === undefined && opts?.highWaterMark === undefined) {
+        this.readableHighWaterMark = getDefaultHighWaterMark(opts.readableObjectMode);
+        this._readableState.highWaterMark = this.readableHighWaterMark;
+      }
+    }
+
     this.allowHalfOpen = opts?.allowHalfOpen !== false;
     this._decodeStrings = opts?.decodeStrings !== false;
     if (opts?.write) this._writeImpl = opts.write;
@@ -982,7 +1097,7 @@ export class Duplex extends Readable {
       } else {
         nextTick(() => {
           cb();
-          if (this.writableNeedDrain && this.writableLength < this.writableHighWaterMark) {
+          if (this.writableNeedDrain && this.writableLength <= this.writableHighWaterMark) {
             this.writableNeedDrain = false;
             this.emit('drain');
           }
@@ -1018,11 +1133,15 @@ export class Duplex extends Readable {
     const doFinal = () => {
       this._final((err) => {
         this.writableFinished = true;
-        nextTick(() => {
-          if (err) this.emit('error', err);
-          this.emit('finish');
-          nextTick(() => this.emit('close'));
-          if (callback) callback();
+        // Allow subclasses (Transform) to run post-final hooks (e.g. flush)
+        // before the 'finish' event fires.
+        this._doPrefinishHooks(() => {
+          nextTick(() => {
+            if (err) this.emit('error', err);
+            this.emit('finish');
+            nextTick(() => this.emit('close'));
+            if (callback) callback();
+          });
         });
       });
     };
@@ -1037,6 +1156,11 @@ export class Duplex extends Readable {
     return this;
   }
 
+  /** Hook for subclasses to run logic between _final and 'finish'. Default: no-op. */
+  protected _doPrefinishHooks(cb: () => void): void {
+    cb();
+  }
+
   cork(): void { this.writableCorked++; }
 
   uncork(): void {
@@ -1055,7 +1179,7 @@ export class Duplex extends Readable {
             }
           });
         }
-        if (this.writableNeedDrain && this.writableLength < this.writableHighWaterMark) {
+        if (this.writableNeedDrain && this.writableLength <= this.writableHighWaterMark) {
           this.writableNeedDrain = false;
           nextTick(() => this.emit('drain'));
         }
@@ -1071,48 +1195,62 @@ export class Duplex extends Readable {
 
 // ---- Transform ----
 
-export class Transform extends Duplex {
-  private _transformImpl: ((chunk: any, encoding: string, cb: (error?: Error | null, data?: any) => void) => void) | undefined;
-  private _flushImpl: ((cb: (error?: Error | null, data?: any) => void) => void) | undefined;
-
+class Transform_ extends Duplex_ {
   constructor(opts?: TransformOptions) {
-    super({
-      ...opts,
-      write: undefined, // Override write to use transform
-    });
-    if (opts?.transform) this._transformImpl = opts.transform;
-    if (opts?.flush) this._flushImpl = opts.flush;
+    // Don't forward transform/flush/final/write — Transform's own method assignments
+    // handle those. Passing write/final through would register them in Duplex_'s
+    // _writeImpl/_finalImpl and bypass Transform's override.
+    super({ ...opts, write: undefined, final: undefined });
+    // Direct assignment mirrors Node.js: opts.transform/flush/final overwrite the
+    // prototype methods on the instance so `t._transform === opts.transform` holds.
+    if (opts?.transform) (this as any)._transform = opts.transform;
+    if (opts?.flush) (this as any)._flush = opts.flush;
+    if (opts?.final) (this as any)._final = opts.final;
   }
 
-  _transform(chunk: any, encoding: string, callback: (error?: Error | null, data?: any) => void): void {
-    if (this._transformImpl) {
-      this._transformImpl.call(this, chunk, encoding, callback);
-    } else {
-      callback(null, chunk);
-    }
+  _transform(_chunk: any, _encoding: string, _callback: (error?: Error | null, data?: any) => void): void {
+    // Throw when no implementation was provided (no opts.transform and no subclass override).
+    const err = Object.assign(
+      new Error('The _transform() method is not implemented'),
+      { code: 'ERR_METHOD_NOT_IMPLEMENTED' }
+    );
+    throw err;
   }
 
   _flush(callback: (error?: Error | null, data?: any) => void): void {
-    if (this._flushImpl) {
-      this._flushImpl.call(this, callback);
-    } else {
-      callback();
-    }
+    callback();
   }
 
   _write(chunk: any, encoding: string, callback: (error?: Error | null) => void): void {
-    this._transform(chunk, encoding, (err, data) => {
-      if (err) {
-        callback(err);
-        return;
-      }
-      if (data !== undefined && data !== null) {
-        this.push(data);
-      }
-      callback();
-    });
+    let called = false;
+    try {
+      this._transform(chunk, encoding, (err, data) => {
+        if (called) {
+          const e = Object.assign(new Error('Callback called multiple times'), { code: 'ERR_MULTIPLE_CALLBACK' });
+          nextTick(() => this.emit('error', e));
+          return;
+        }
+        called = true;
+        if (err) {
+          callback(err);
+          return;
+        }
+        if (data !== undefined && data !== null) {
+          this.push(data);
+        }
+        callback();
+      });
+    } catch (err: any) {
+      // ERR_METHOD_NOT_IMPLEMENTED must propagate synchronously (test-stream-transform-constructor-set-methods).
+      // User-provided _transform errors are converted to 'error' events.
+      if (err?.code === 'ERR_METHOD_NOT_IMPLEMENTED') throw err;
+      callback(err as Error);
+    }
   }
 
+  // Transform's built-in _final: calls _flush then pushes null.
+  // This is the default; when the user provides opts.final it is overridden on
+  // the instance and _doPrefinishHooks ensures _flush is still called after it.
   _final(callback: (error?: Error | null) => void): void {
     this._flush((err, data) => {
       if (err) {
@@ -1127,11 +1265,24 @@ export class Transform extends Duplex {
       callback();
     });
   }
+
+  // When a user-provided _final overrides the prototype method, we still need
+  // to call the built-in flush+push-null logic (mirroring Node.js's prefinish).
+  protected override _doPrefinishHooks(cb: () => void): void {
+    const protoFinal = Transform_.prototype._final;
+    if ((this as any)._final !== protoFinal) {
+      // User replaced _final; call the built-in flush+push-null now.
+      protoFinal.call(this, cb);
+    } else {
+      // _final already ran flush+push-null; nothing extra needed.
+      cb();
+    }
+  }
 }
 
 // ---- PassThrough ----
 
-export class PassThrough extends Transform {
+class PassThrough_ extends Transform_ {
   constructor(opts?: TransformOptions) {
     super({
       ...opts,
@@ -1326,6 +1477,31 @@ export function isErrored(stream: unknown): boolean {
 }
 
 // ---- Exports ----
+//
+// The class declarations above use underscore-suffixed internal names
+// (`Stream_`, `Readable_`, etc.) — we wrap each one with `makeCallable` so
+// legacy CJS consumers can do `Stream.call(this)` (npm `send`,
+// `util.inherits(Sub, Stream)`, our own `@gjsify/crypto` `Hash.copy()`).
+// See `./callable.ts` for the rationale and implementation.
+//
+// Public API preserves the historical names. Both value and type positions
+// work because of the `type X = X_` aliases below.
+
+import { makeCallable } from './callable.js';
+
+export const Stream = makeCallable(Stream_) as typeof Stream_;
+export const Readable = makeCallable(Readable_) as typeof Readable_;
+export const Writable = makeCallable(Writable_) as typeof Writable_;
+export const Duplex = makeCallable(Duplex_) as typeof Duplex_;
+export const Transform = makeCallable(Transform_) as typeof Transform_;
+export const PassThrough = makeCallable(PassThrough_) as typeof PassThrough_;
+
+export type Stream = Stream_;
+export type Readable = Readable_;
+export type Writable = Writable_;
+export type Duplex = Duplex_;
+export type Transform = Transform_;
+export type PassThrough = PassThrough_;
 
 // Default export
 const _default = Object.assign(Stream, {