@gjsify/stream 0.3.21 → 0.4.0

package/src/transform.ts

@@ -0,0 +1,108 @@
+// Transform stream — a Duplex whose readable side is fed by `_transform`.
+//
+// Reference: refs/node/lib/internal/streams/transform.js
+// Reimplemented for GJS — direct opts.transform/flush/final assignment matches
+// Node's instance-method override pattern.
+
+import { nextTick } from '@gjsify/utils';
+import type { TransformOptions } from 'node:stream';
+
+import { Duplex_ } from './duplex.js';
+import type { ErrCallback } from './internal/types.js';
+
+type TransformFn = (this: Transform_, chunk: unknown, encoding: string, callback: (error?: Error | null, data?: unknown) => void) => void;
+type FlushFn = (this: Transform_, callback: (error?: Error | null, data?: unknown) => void) => void;
+type FinalFn = (this: Transform_, callback: ErrCallback) => void;
+
+interface TransformInstanceMethods {
+  _transform: TransformFn;
+  _flush: FlushFn;
+  _final: FinalFn;
+}
+
+export class Transform_ extends Duplex_ {
+  constructor(opts?: TransformOptions) {
+    // 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.
+    const self = this as unknown as TransformInstanceMethods;
+    if (opts?.transform) self._transform = opts.transform as unknown as TransformFn;
+    if (opts?.flush) self._flush = opts.flush as unknown as FlushFn;
+    if (opts?.final) self._final = opts.final as unknown as FinalFn;
+  }
+
+  _transform(_chunk: unknown, _encoding: string, _callback: (error?: Error | null, data?: unknown) => 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?: unknown) => void): void {
+    callback();
+  }
+
+  _write(chunk: unknown, encoding: string, callback: ErrCallback): void {
+    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) {
+      // ERR_METHOD_NOT_IMPLEMENTED must propagate synchronously (test-stream-transform-constructor-set-methods).
+      // User-provided _transform errors are converted to 'error' events.
+      const e = err as { code?: string };
+      if (e?.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: ErrCallback): void {
+    this._flush((err, data) => {
+      if (err) {
+        callback(err);
+        return;
+      }
+      if (data !== undefined && data !== null) {
+        this.push(data);
+      }
+      // Signal readable side is done
+      this.push(null);
+      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 unknown as TransformInstanceMethods)._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();
+    }
+  }
+}

package/src/utils/finished.ts

@@ -0,0 +1,156 @@
+// finished + addAbortSignal + is* helpers.
+//
+// Reference: refs/node/lib/internal/streams/end-of-stream.js
+//            refs/node/lib/internal/streams/utils.js
+// Reimplemented for GJS using @gjsify/utils microtask scheduling.
+
+import { queueMicrotask } from '@gjsify/utils';
+import type { FinishedOptions } from 'node:stream';
+
+import { Stream_ } from '../stream-base.js';
+import type { Readable_ } from '../readable.js';
+import type { Writable_ } from '../writable.js';
+
+type AnyStream = Stream_ | Readable_ | Writable_;
+
+export function finished(stream: AnyStream, callback: (err?: Error | null) => void): () => void;
+export function finished(stream: AnyStream, opts: FinishedOptions, callback: (err?: Error | null) => void): () => void;
+export function finished(stream: AnyStream, optsOrCb: FinishedOptions | ((err?: Error | null) => void), callback?: (err?: Error | null) => void): () => void {
+  let cb: (err?: Error | null) => void;
+
+  if (typeof optsOrCb === 'function') {
+    cb = optsOrCb;
+  } else {
+    // opts not currently consumed — Node uses it for error/readable/writable filters.
+    cb = callback!;
+  }
+
+  let called = false;
+  function done(err?: Error | null) {
+    if (!called) {
+      called = true;
+      cb(err);
+    }
+  }
+
+  const onFinish = () => done();
+  const onEnd = () => done();
+  const onError = (err: Error) => done(err);
+  const onClose = () => {
+    const w = stream as Writable_;
+    const r = stream as Readable_;
+    if (!w.writableFinished && !r.readableEnded) {
+      done(new Error('premature close'));
+    }
+  };
+
+  stream.on('finish', onFinish);
+  stream.on('end', onEnd);
+  stream.on('error', onError);
+  stream.on('close', onClose);
+
+  // Check initial state — handle already-finished/destroyed streams
+  // Reference: refs/node/lib/internal/streams/end-of-stream.js lines 228-249
+  const s = stream as unknown as Record<string, unknown>;
+  const isWritableStream = typeof (stream as Writable_).write === 'function';
+  const isReadableStream = typeof (stream as Readable_).read === 'function';
+  const writableFinished = s.writableFinished === true;
+  const readableEnded = s.readableEnded === true;
+  const destroyed = s.destroyed === true;
+
+  if (destroyed) {
+    const storedErr = s._err as Error | null | undefined;
+    if (storedErr) {
+      // Stream was destroyed with an error (may have fired before we registered listener)
+      queueMicrotask(() => done(storedErr));
+    } else if ((isWritableStream && writableFinished) || (isReadableStream && readableEnded)) {
+      // Stream was destroyed after completing normally — treat as success
+      queueMicrotask(() => done());
+    } else {
+      // Stream was destroyed without completing — premature close
+      queueMicrotask(() => done(new Error('premature close')));
+    }
+  } else if (isWritableStream && !isReadableStream && writableFinished) {
+    queueMicrotask(() => done());
+  } else if (!isWritableStream && isReadableStream && readableEnded) {
+    queueMicrotask(() => done());
+  } else if (isWritableStream && isReadableStream && writableFinished && readableEnded) {
+    queueMicrotask(() => done());
+  }
+
+  return function cleanup() {
+    stream.removeListener('finish', onFinish);
+    stream.removeListener('end', onEnd);
+    stream.removeListener('error', onError);
+    stream.removeListener('close', onClose);
+  };
+}
+
+export function addAbortSignal<T extends AnyStream>(signal: AbortSignal, stream: T): T {
+  if (!(signal instanceof AbortSignal)) {
+    throw new TypeError('The first argument must be an AbortSignal');
+  }
+  if (!(stream instanceof Stream_)) {
+    throw new TypeError('The second argument must be a Stream');
+  }
+
+  const destroyable = stream as Readable_ | Writable_;
+
+  if (signal.aborted) {
+    destroyable.destroy(new Error('The operation was aborted'));
+  } else {
+    const onAbort = () => {
+      destroyable.destroy(new Error('The operation was aborted'));
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    // Cleanup when stream closes
+    stream.once('close', () => {
+      signal.removeEventListener('abort', onAbort);
+    });
+  }
+
+  return stream;
+}
+
+// ---- Utility functions ----
+
+export function isReadable(stream: unknown): boolean {
+  if (stream == null) return false;
+  const s = stream as Record<string, unknown>;
+  if (typeof s.readable !== 'boolean') return false;
+  if (typeof s.read !== 'function') return false;
+  if (s.destroyed === true) return false;
+  if (s.readableEnded === true) return false;
+  return s.readable === true;
+}
+
+export function isWritable(stream: unknown): boolean {
+  if (stream == null) return false;
+  const s = stream as Record<string, unknown>;
+  if (typeof s.writable !== 'boolean') return false;
+  if (typeof s.write !== 'function') return false;
+  if (s.destroyed === true) return false;
+  if (s.writableEnded === true) return false;
+  return s.writable === true;
+}
+
+export function isDestroyed(stream: unknown): boolean {
+  if (stream == null) return false;
+  return (stream as Record<string, unknown>).destroyed === true;
+}
+
+export function isDisturbed(stream: unknown): boolean {
+  if (stream == null) return false;
+  const s = stream as Record<string, unknown>;
+  // A stream is disturbed if data has been read from it
+  return s.readableDidRead === true || (s.readableFlowing !== null && s.readableFlowing !== undefined);
+}
+
+export function isErrored(stream: unknown): boolean {
+  if (stream == null) return false;
+  // Check for errored state on either side
+  const s = stream as Record<string, unknown>;
+  if (s.destroyed === true && typeof s.readable === 'boolean' && s.readable === false) return true;
+  if (s.destroyed === true && typeof s.writable === 'boolean' && s.writable === false) return true;
+  return false;
+}

package/src/utils/pipe.ts

@@ -0,0 +1,113 @@
+// Free-function pipe helper used by Stream_.pipe.
+//
+// Reference: refs/node/lib/internal/streams/legacy.js Stream.prototype.pipe.
+// Reimplemented for GJS — extracted so stream-base.ts (Stream_) can stay
+// dependency-free of the per-class files. The Readable_ instance check is
+// resolved lazily at call time, breaking what would otherwise be a top-level
+// import cycle (stream-base → pipe → readable → stream-base).
+
+import { _setPipeImpl, type Stream_ } from '../stream-base.js';
+import { Readable_ } from '../readable.js';
+import type { Writable_ } from '../writable.js';
+import type { StreamLike } from '../internal/types.js';
+
+/** Tracked pipe destination for unpipe support. */
+export interface PipeState {
+  dest: Writable_;
+  cleanup: () => void;
+}
+
+export function pipe<T extends Writable_>(
+  sourceStream: Stream_,
+  destination: T,
+  options?: { end?: boolean },
+): T {
+  // The source is conceptually Readable-shaped; the legacy Stream signature
+  // allows any EventEmitter that emits 'data'/'end'/'close', so we keep the
+  // structural cast and only branch on the modern Readable_ check below.
+  const source = sourceStream 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);
+    const s = source as StreamLike;
+    if (typeof s.resume === 'function') {
+      s.resume();
+    }
+  };
+
+  const ondata = (chunk: unknown) => {
+    if (destination.writable) {
+      const s = source as StreamLike;
+      if (destination.write(chunk) === false && typeof s.pause === 'function') {
+        s.pause();
+        if (!drainListenerAdded) {
+          drainListenerAdded = true;
+          destination.on('drain', ondrain);
+        }
+      }
+    }
+  };
+
+  source.on('data', ondata);
+
+  let didEnd = false;
+
+  const onend = () => {
+    if (didEnd) return;
+    didEnd = true;
+    if (doEnd) destination.end();
+  };
+
+  const onclose = () => {
+    if (didEnd) return;
+    didEnd = true;
+    if (doEnd) {
+      // 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_)) {
+        const d = destination as unknown as { destroy?: () => void };
+        if (typeof d.destroy === 'function') {
+          d.destroy();
+        }
+      }
+    }
+  };
+
+  if (doEnd) {
+    source.on('end', onend);
+    source.on('close', onclose);
+  }
+
+  const cleanup = () => {
+    source.removeListener('data', ondata);
+    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, cleanup });
+    source._readableState.pipes.push(destination);
+  }
+
+  destination.emit('pipe', source);
+  return destination;
+}
+
+// Wire the implementation back into Stream_.prototype.pipe — see _setPipeImpl
+// in ../stream-base.ts for why this is done at module-load time rather than
+// via a static top-level import.
+_setPipeImpl(pipe);

package/src/utils/pipeline.ts

@@ -0,0 +1,59 @@
+// pipeline — chain streams and propagate destroy on error.
+//
+// Reference: refs/node/lib/internal/streams/pipeline.js
+// Reimplemented for GJS — minimal, callback-based variant. The promise form
+// lives under `@gjsify/stream/promises` and wraps this.
+
+import type { Stream_ } from '../stream-base.js';
+import type { Writable_ } from '../writable.js';
+
+export type PipelineCallback = (err: Error | null) => void;
+
+/** A stream that can be destroyed (duck-typed for pipeline). */
+export interface DestroyableStream extends Stream_ {
+  destroy?(error?: Error): void;
+}
+
+export function pipeline(...args: [...streams: DestroyableStream[], callback: PipelineCallback] | DestroyableStream[]): DestroyableStream {
+  const argList = args as Array<DestroyableStream | PipelineCallback>;
+  const last = argList[argList.length - 1];
+  const callback = typeof last === 'function' ? (argList.pop() as PipelineCallback) : undefined;
+  const streams = argList as DestroyableStream[];
+
+  if (streams.length < 2) {
+    throw new Error('pipeline requires at least 2 streams');
+  }
+
+  let error: Error | null = null;
+
+  function onError(err: Error) {
+    if (!error) {
+      error = err;
+      // Destroy all streams
+      for (const stream of streams) {
+        if (typeof stream.destroy === 'function') {
+          stream.destroy();
+        }
+      }
+      if (callback) callback(err);
+    }
+  }
+
+  // Pipe streams together
+  let current: Stream_ = streams[0];
+  for (let i = 1; i < streams.length; i++) {
+    const next = streams[i];
+    current.pipe(next as unknown as Writable_);
+    current.on('error', onError);
+    current = next;
+  }
+
+  // Listen for end on last stream
+  const lastStream = streams[streams.length - 1];
+  lastStream.on('error', onError);
+  lastStream.on('finish', () => {
+    if (callback && !error) callback(null);
+  });
+
+  return lastStream;
+}