@seanhogg/builderforce-webcontainers-core 2026.10.2 → 2026.10.3

package/src/node/stream/readable.ts

@@ -0,0 +1,345 @@
+/**
+ * stream.Readable — flowing and paused modes, `pipe` with backpressure,
+ * `setEncoding`, async iteration and `Readable.from`. State lives in
+ * `_readableState` with Node's field names, because packages (on-finished,
+ * destroy, readable-stream interop) peek at it.
+ */
+import { EventEmitterBase } from '../events.js';
+import { Buffer } from '../buffer.js';
+
+export const tick = (fn: () => void) => queueMicrotask(fn);
+
+export interface ReadableOptions {
+  highWaterMark?: number;
+  encoding?: string;
+  objectMode?: boolean;
+  readableObjectMode?: boolean;
+  read?(this: Readable, size: number): void;
+  destroy?(this: Readable, error: Error | null, callback: (error?: Error | null) => void): void;
+  autoDestroy?: boolean;
+  emitClose?: boolean;
+  signal?: AbortSignal;
+}
+
+export interface ReadableState {
+  objectMode: boolean;
+  highWaterMark: number;
+  buffer: unknown[];
+  length: number;
+  flowing: boolean | null;
+  ended: boolean;
+  endEmitted: boolean;
+  reading: boolean;
+  destroyed: boolean;
+  closed: boolean;
+  errored: Error | null;
+  encoding: string | null;
+  autoDestroy: boolean;
+  emitClose: boolean;
+  flowScheduled: boolean;
+  pipes: unknown[];
+}
+
+const chunkLength = (state: ReadableState, chunk: unknown) => (state.objectMode ? 1 : (chunk as { length: number }).length);
+
+export function initReadable(self: Readable, options: ReadableOptions = {}): void {
+  const objectMode = !!(options.objectMode || options.readableObjectMode);
+  self._readableState = {
+    objectMode,
+    highWaterMark: options.highWaterMark ?? (objectMode ? 16 : 16 * 1024),
+    buffer: [],
+    length: 0,
+    flowing: null,
+    ended: false,
+    endEmitted: false,
+    reading: false,
+    destroyed: false,
+    closed: false,
+    errored: null,
+    encoding: options.encoding ?? null,
+    autoDestroy: options.autoDestroy ?? true,
+    emitClose: options.emitClose ?? true,
+    flowScheduled: false,
+    pipes: [],
+  };
+  if (typeof options.read === 'function') self._read = options.read;
+  if (typeof options.destroy === 'function') self._destroy = options.destroy;
+  options.signal?.addEventListener('abort', () => self.destroy(new Error('The operation was aborted')));
+}
+
+export class Readable extends EventEmitterBase {
+  declare _readableState: ReadableState;
+
+  constructor(options?: ReadableOptions) {
+    super();
+    initReadable(this, options);
+  }
+
+  static from(iterable: Iterable<unknown> | AsyncIterable<unknown>, options: ReadableOptions = {}): Readable {
+    if (typeof iterable === 'string' || iterable instanceof Uint8Array) {
+      const r = new Readable({ objectMode: false, ...options, read() {} });
+      r.push(iterable);
+      r.push(null);
+      return r;
+    }
+    const iterator = (Symbol.asyncIterator in iterable ? (iterable as AsyncIterable<unknown>)[Symbol.asyncIterator]() : (iterable as Iterable<unknown>)[Symbol.iterator]()) as AsyncIterator<unknown> | Iterator<unknown>;
+    let pulling = false;
+    return new Readable({
+      objectMode: true,
+      ...options,
+      async read() {
+        if (pulling) return;
+        pulling = true;
+        try {
+          for (;;) {
+            const { value, done } = await iterator.next();
+            if (done) {
+              this.push(null);
+              break;
+            }
+            if (!this.push(await value)) break;
+          }
+        } catch (error) {
+          this.destroy(error as Error);
+        } finally {
+          pulling = false;
+        }
+      },
+    });
+  }
+
+  get readable(): boolean {
+    const s = this._readableState;
+    return !!s && !s.destroyed && !s.endEmitted && !s.errored;
+  }
+  set readable(_value: boolean) {
+    // legacy code assigns this; state is authoritative
+  }
+  get readableEnded(): boolean { return this._readableState.endEmitted; }
+  get readableFlowing(): boolean | null { return this._readableState.flowing; }
+  get readableLength(): number { return this._readableState.length; }
+  get readableHighWaterMark(): number { return this._readableState.highWaterMark; }
+  get readableObjectMode(): boolean { return this._readableState.objectMode; }
+  get readableEncoding(): string | null { return this._readableState.encoding; }
+  get destroyed(): boolean { return this._readableState.destroyed; }
+  set destroyed(value: boolean) { this._readableState.destroyed = value; }
+  get closed(): boolean { return this._readableState.closed; }
+  get errored(): Error | null { return this._readableState.errored; }
+
+  _read(_size: number): void {
+    throw new Error('The _read() method is not implemented');
+  }
+
+  _destroy(error: Error | null, callback: (error?: Error | null) => void): void {
+    callback(error);
+  }
+
+  push(chunk: unknown, encoding?: string): boolean {
+    const s = this._readableState;
+    s.reading = false;
+    if (chunk === null) {
+      s.ended = true;
+      this._scheduleFlow();
+      return false;
+    }
+    if (s.ended || s.destroyed) return false;
+    let value = chunk;
+    if (!s.objectMode) {
+      if (typeof value === 'string') value = s.encoding ? value : Buffer.from(value, encoding);
+      else if (value instanceof Uint8Array && !(value instanceof Buffer)) value = Buffer.from(value.buffer as ArrayBuffer, value.byteOffset, value.byteLength);
+      if (s.encoding && value instanceof Uint8Array) value = (value as Buffer).toString(s.encoding as 'utf8');
+      if ((value as { length: number }).length === 0) return s.length < s.highWaterMark;
+    }
+    s.buffer.push(value);
+    s.length += chunkLength(s, value);
+    this._scheduleFlow();
+    return s.length < s.highWaterMark;
+  }
+
+  unshift(chunk: unknown): void {
+    const s = this._readableState;
+    s.buffer.unshift(chunk);
+    s.length += chunkLength(s, chunk);
+  }
+
+  read(n?: number): unknown {
+    const s = this._readableState;
+    if (!s.buffer.length) {
+      if (s.ended) this._scheduleFlow();
+      else this._pull();
+      return null;
+    }
+    let out: unknown;
+    if (s.objectMode) out = s.buffer.shift();
+    else if (n === undefined || n >= s.length) {
+      if (n !== undefined && n > s.length && !s.ended) {
+        this._pull();
+        return null;
+      }
+      out = s.encoding ? (s.buffer as string[]).join('') : s.buffer.length === 1 ? s.buffer[0] : Buffer.concat(s.buffer as Uint8Array[]);
+      s.buffer = [];
+    } else {
+      const all = s.encoding ? (s.buffer as string[]).join('') : Buffer.concat(s.buffer as Uint8Array[]);
+      out = all.slice(0, n);
+      s.buffer = [all.slice(n)];
+    }
+    s.length -= chunkLength(s, out);
+    if (s.length < s.highWaterMark) this._pull();
+    if (s.ended && !s.buffer.length) this._scheduleFlow();
+    return out;
+  }
+
+  setEncoding(encoding: string): this {
+    const s = this._readableState;
+    s.encoding = encoding;
+    s.buffer = s.buffer.map((c) => (c instanceof Uint8Array ? (c as Buffer).toString(encoding as 'utf8') : c));
+    return this;
+  }
+
+  override on(event: string | symbol, listener: (...args: any[]) => unknown): this {
+    super.on(event, listener);
+    const s = this._readableState;
+    if (event === 'data' && s.flowing !== false) this.resume();
+    if (event === 'readable') {
+      s.flowing = false;
+      this._scheduleFlow();
+    }
+    return this;
+  }
+
+  override addListener(event: string | symbol, listener: (...args: any[]) => unknown): this {
+    return this.on(event, listener);
+  }
+
+  resume(): this {
+    this._readableState.flowing = true;
+    this._scheduleFlow();
+    return this;
+  }
+
+  pause(): this {
+    this._readableState.flowing = false;
+    return this;
+  }
+
+  isPaused(): boolean {
+    return this._readableState.flowing === false;
+  }
+
+  pipe<T extends { write(chunk: unknown): boolean; end(): unknown; on?(e: string, l: () => void): unknown; once?(e: string, l: () => void): unknown; emit?(e: string, ...a: unknown[]): unknown }>(dest: T, options: { end?: boolean } = {}): T {
+    const s = this._readableState;
+    s.pipes.push(dest);
+    const onData = (chunk: unknown) => {
+      if (dest.write(chunk) === false) {
+        this.pause();
+        (dest.once ?? dest.on)?.call(dest, 'drain', () => this.resume());
+      }
+    };
+    this.on('data', onData);
+    if (options.end !== false) this.once('end', () => dest.end());
+    dest.emit?.('pipe', this);
+    this.resume();
+    return dest;
+  }
+
+  unpipe(dest?: unknown): this {
+    const s = this._readableState;
+    s.pipes = dest ? s.pipes.filter((p) => p !== dest) : [];
+    if (!s.pipes.length) this.removeAllListeners('data');
+    return this;
+  }
+
+  destroy(error?: Error | null): this {
+    const s = this._readableState;
+    if (s.destroyed) return this;
+    s.destroyed = true;
+    if (error) s.errored = error;
+    this._destroy(error ?? null, (err) => {
+      tick(() => {
+        if (err) this.emit('error', err);
+        s.closed = true;
+        if (s.emitClose) this.emit('close');
+      });
+    });
+    return this;
+  }
+
+  async *[Symbol.asyncIterator](): AsyncGenerator<unknown> {
+    const s = this._readableState;
+    let wake: (() => void) | undefined;
+    let failure: Error | undefined;
+    const signal = () => {
+      wake?.();
+      wake = undefined;
+    };
+    this.on('readable', signal);
+    this.on('end', signal);
+    this.on('close', signal);
+    this.on('error', (error: Error) => {
+      failure = error;
+      signal();
+    });
+    try {
+      for (;;) {
+        if (failure) throw failure;
+        const chunk = this.read();
+        if (chunk !== null) {
+          yield chunk;
+          continue;
+        }
+        if (s.endEmitted || (s.ended && !s.length) || s.destroyed) {
+          if (failure) throw failure;
+          return;
+        }
+        await new Promise<void>((resolve) => (wake = resolve));
+      }
+    } finally {
+      if (!s.endEmitted) this.destroy();
+    }
+  }
+
+  /** Ask the implementation for more data, once at a time. */
+  _pull(): void {
+    const s = this._readableState;
+    if (s.reading || s.ended || s.destroyed) return;
+    s.reading = true;
+    try {
+      this._read(s.highWaterMark);
+    } catch (error) {
+      this.destroy(error as Error);
+    }
+  }
+
+  _scheduleFlow(): void {
+    const s = this._readableState;
+    if (s.flowScheduled) return;
+    s.flowScheduled = true;
+    tick(() => {
+      s.flowScheduled = false;
+      this._flow();
+    });
+  }
+
+  private _flow(): void {
+    const s = this._readableState;
+    if (s.destroyed) return;
+    if (s.flowing === false && s.buffer.length) this.emit('readable');
+    while (s.flowing === true && s.buffer.length) {
+      const chunk = s.buffer.shift();
+      s.length -= chunkLength(s, chunk);
+      this.emit('data', chunk);
+    }
+    if (s.ended && !s.buffer.length) {
+      if (!s.endEmitted && (s.flowing !== null || this.listenerCount('end') || this.listenerCount('readable'))) {
+        if (s.flowing === false) this.emit('readable');
+        s.endEmitted = true;
+        this.emit('end');
+        // A duplex is destroyed only once BOTH sides are done (see Writable's finish).
+        const writable = (this as { _writableState?: { finished: boolean } })._writableState;
+        if (s.autoDestroy && (!writable || writable.finished)) this.destroy();
+      }
+      return;
+    }
+    if (s.flowing && s.length < s.highWaterMark) this._pull();
+  }
+}

package/src/node/stream/writable.ts

@@ -0,0 +1,244 @@
+/**
+ * stream.Writable — a write queue drained one `_write` at a time, `'drain'`
+ * backpressure, `end` → `_final` → `'finish'`, cork/uncork. Its methods are also
+ * mixed into Duplex (see duplex.ts), so they only touch `_writableState`.
+ */
+import { EventEmitterBase } from '../events.js';
+import { Buffer } from '../buffer.js';
+import { tick } from './readable.js';
+
+type Callback = (error?: Error | null) => void;
+
+export interface WritableOptions {
+  highWaterMark?: number;
+  objectMode?: boolean;
+  writableObjectMode?: boolean;
+  decodeStrings?: boolean;
+  defaultEncoding?: string;
+  write?(this: Writable, chunk: any, encoding: string, callback: Callback): void;
+  writev?(this: Writable, chunks: Array<{ chunk: any; encoding: string }>, callback: Callback): void;
+  final?(this: Writable, callback: Callback): void;
+  destroy?(this: Writable, error: Error | null, callback: Callback): void;
+  autoDestroy?: boolean;
+  emitClose?: boolean;
+}
+
+export interface WritableState {
+  objectMode: boolean;
+  highWaterMark: number;
+  decodeStrings: boolean;
+  defaultEncoding: string;
+  queue: Array<{ chunk: unknown; encoding: string; callback?: Callback }>;
+  length: number;
+  writing: boolean;
+  corked: number;
+  needDrain: boolean;
+  ending: boolean;
+  ended: boolean;
+  finalCalled: boolean;
+  finished: boolean;
+  destroyed: boolean;
+  closed: boolean;
+  errored: Error | null;
+  autoDestroy: boolean;
+  emitClose: boolean;
+}
+
+export function initWritable(self: Writable, options: WritableOptions = {}): void {
+  const objectMode = !!(options.objectMode || options.writableObjectMode);
+  self._writableState = {
+    objectMode,
+    highWaterMark: options.highWaterMark ?? (objectMode ? 16 : 16 * 1024),
+    decodeStrings: options.decodeStrings !== false,
+    defaultEncoding: options.defaultEncoding ?? 'utf8',
+    queue: [],
+    length: 0,
+    writing: false,
+    corked: 0,
+    needDrain: false,
+    ending: false,
+    ended: false,
+    finalCalled: false,
+    finished: false,
+    destroyed: false,
+    closed: false,
+    errored: null,
+    autoDestroy: options.autoDestroy ?? true,
+    emitClose: options.emitClose ?? true,
+  };
+  if (typeof options.write === 'function') self._write = options.write;
+  if (typeof options.writev === 'function') self._writev = options.writev;
+  if (typeof options.final === 'function') self._final = options.final;
+  if (typeof options.destroy === 'function') self._destroy = options.destroy;
+}
+
+export class Writable extends EventEmitterBase {
+  declare _writableState: WritableState;
+  _writev?(chunks: Array<{ chunk: any; encoding: string }>, callback: Callback): void;
+  _final?(callback: Callback): void;
+
+  constructor(options?: WritableOptions) {
+    super();
+    initWritable(this, options);
+  }
+
+  get writable(): boolean {
+    const s = this._writableState;
+    return !!s && !s.destroyed && !s.ending && !s.errored;
+  }
+  set writable(_value: boolean) {
+    // legacy code assigns this; state is authoritative
+  }
+  get writableEnded(): boolean { return this._writableState.ending; }
+  get writableFinished(): boolean { return this._writableState.finished; }
+  get writableLength(): number { return this._writableState.length; }
+  get writableHighWaterMark(): number { return this._writableState.highWaterMark; }
+  get writableObjectMode(): boolean { return this._writableState.objectMode; }
+  get writableCorked(): number { return this._writableState.corked; }
+  get writableNeedDrain(): boolean { return this._writableState.needDrain; }
+  get destroyed(): boolean { return this._writableState.destroyed; }
+  set destroyed(value: boolean) { this._writableState.destroyed = value; }
+
+  _write(chunk: unknown, encoding: string, callback: Callback): void {
+    if (this._writev) this._writev([{ chunk, encoding }], callback);
+    else throw new Error('The _write() method is not implemented');
+  }
+
+  _destroy(error: Error | null, callback: Callback): void {
+    callback(error);
+  }
+
+  write(chunk: unknown, encoding?: string | Callback, callback?: Callback): boolean {
+    if (typeof encoding === 'function') [callback, encoding] = [encoding, undefined];
+    const s = this._writableState;
+    if (s.ending || s.destroyed) {
+      const error = Object.assign(new Error(s.destroyed ? 'Cannot call write after a stream was destroyed' : 'write after end'), { code: s.destroyed ? 'ERR_STREAM_DESTROYED' : 'ERR_STREAM_WRITE_AFTER_END' });
+      tick(() => {
+        callback?.(error);
+        this.emit('error', error);
+      });
+      return false;
+    }
+    let value = chunk;
+    let enc = encoding ?? s.defaultEncoding;
+    if (!s.objectMode) {
+      if (typeof value === 'string' && s.decodeStrings) {
+        value = Buffer.from(value, enc);
+        enc = 'buffer';
+      } else if (value instanceof Uint8Array) {
+        if (!(value instanceof Buffer)) value = Buffer.from(value.buffer as ArrayBuffer, value.byteOffset, value.byteLength);
+        enc = 'buffer';
+      } else if (typeof value !== 'string') {
+        throw new TypeError('The "chunk" argument must be of type string or an instance of Buffer or Uint8Array');
+      }
+    }
+    s.length += s.objectMode ? 1 : (value as { length: number }).length;
+    s.queue.push({ chunk: value, encoding: enc, callback });
+    const ok = s.length < s.highWaterMark;
+    if (!ok) s.needDrain = true;
+    if (!s.corked) this._drainQueue();
+    return ok;
+  }
+
+  end(chunk?: unknown, encoding?: string | Callback, callback?: Callback): this {
+    if (typeof chunk === 'function') [callback, chunk] = [chunk as Callback, undefined];
+    else if (typeof encoding === 'function') [callback, encoding] = [encoding, undefined];
+    const s = this._writableState;
+    if (chunk !== undefined && chunk !== null) this.write(chunk, encoding as string | undefined);
+    if (callback) {
+      if (s.finished) tick(() => callback!());
+      else this.once('finish', () => callback!());
+    }
+    if (s.ending) return this;
+    s.ending = true;
+    s.corked = 0;
+    this._drainQueue();
+    return this;
+  }
+
+  cork(): void {
+    this._writableState.corked++;
+  }
+
+  uncork(): void {
+    const s = this._writableState;
+    if (s.corked) s.corked--;
+    if (!s.corked) this._drainQueue();
+  }
+
+  setDefaultEncoding(encoding: string): this {
+    this._writableState.defaultEncoding = encoding;
+    return this;
+  }
+
+  destroy(error?: Error | null): this {
+    const s = this._writableState;
+    if (s.destroyed) return this;
+    s.destroyed = true;
+    if (error) s.errored = error;
+    this._destroy(error ?? null, (err) => {
+      tick(() => {
+        if (err) this.emit('error', err);
+        s.closed = true;
+        if (s.emitClose) this.emit('close');
+      });
+    });
+    return this;
+  }
+
+  _drainQueue(): void {
+    const s = this._writableState;
+    if (s.writing || s.destroyed) return;
+    const next = s.queue.shift();
+    if (!next) {
+      if (s.ending) this._finishMaybe();
+      return;
+    }
+    s.writing = true;
+    let sync = true;
+    const done = (error?: Error | null) => {
+      const after = () => {
+        s.writing = false;
+        s.length -= s.objectMode ? 1 : (next.chunk as { length: number }).length;
+        next.callback?.(error ?? null);
+        if (error) {
+          s.errored = error;
+          this.destroy(error);
+          return;
+        }
+        if (s.needDrain && s.length === 0) {
+          s.needDrain = false;
+          this.emit('drain');
+        }
+        this._drainQueue();
+      };
+      if (sync) tick(after); // never re-enter write() callers synchronously
+      else after();
+    };
+    try {
+      this._write(next.chunk, next.encoding, done);
+    } catch (error) {
+      done(error as Error);
+    }
+    sync = false;
+  }
+
+  private _finishMaybe(): void {
+    const s = this._writableState;
+    if (s.finished || s.finalCalled || s.writing || s.queue.length) return;
+    s.finalCalled = true;
+    s.ended = true;
+    const finish = (error?: Error | null) => {
+      if (error) {
+        this.destroy(error);
+        return;
+      }
+      s.finished = true;
+      this.emit('finish');
+      const readable = (this as { _readableState?: { endEmitted: boolean } })._readableState;
+      if (s.autoDestroy && (!readable || readable.endEmitted)) this.destroy();
+    };
+    if (this._final) this._final((error) => tick(() => finish(error)));
+    else tick(() => finish());
+  }
+}