documonster 0.20.2 → 0.21.0

package/dist/esm/modules/stream/browser/utils.js

@@ -1,257 +1,31 @@
 /**
- * Browser Stream - Utilities
+ * Browser Stream - utilities
  */
-import { Duplex } from "./duplex.js";
-import { removeEmitterListener, addEmitterListener } from "./helpers.js";
-import { pipeline, finished } from "./pipeline.js";
-import { Readable } from "./readable.js";
-import { Transform } from "./transform.js";
-import { Writable } from "./writable.js";
+import { finished, pipeline } from "./pipeline.js";
 import { createAddAbortSignal } from "../core/add-abort-signal.js";
-import { toStreamBytes } from "../core/binary-chunk.js";
 import { createConsumers } from "../core/consumers.js";
-import { createIsTransform, createIsDuplex, createIsStream, isAsyncIterable, isReadableStream } from "../core/type-guards.js";
-import { getDefaultHighWaterMark } from "../core/utils.js";
-import { UnsupportedStreamTypeError } from "../errors.js";
-import { concatUint8Arrays, createTextDecoder } from "../../../utils/binary.js";
-// =============================================================================
-// Utility Functions
-// =============================================================================
-/** Convert a stream to a promise that resolves when finished */
+import { streamToString, streamToUint8Array } from "../core/stream-helpers.js";
+import { createIsDuplex, createIsStream, createIsTransform } from "../core/type-guards.js";
+import { Duplex, Readable, Transform } from "../kernel/classes.js";
+import { Writable } from "../kernel/writable.js";
+export { drainStream, isDisturbed, isReadable, isWritable, streamToBuffer, streamToString, streamToUint8Array } from "../core/stream-helpers.js";
+/** Resolve when a stream has finished. */
 export const streamToPromise = finished;
-/** Copy from a readable stream to a writable stream */
+/** Copy from a readable stream to a writable stream. */
 export const copyStream = pipeline;
-/**
- * Collect all data from a readable stream into a Uint8Array
- * (Browser equivalent of Node.js streamToBuffer)
- */
-export async function streamToUint8Array(stream) {
-    const [chunks, totalLength] = await collectStreamChunks(stream);
-    return concatUint8Arrays(chunks, totalLength);
-}
-/**
- * Alias for streamToUint8Array (Node.js compatibility)
- */
-export async function streamToBuffer(stream) {
-    return streamToUint8Array(stream);
-}
-/**
- * Collect all data from a readable stream into a string
- */
-export async function streamToString(stream, encoding) {
-    const iterable = toReadableAsyncIterable(stream, "streamToString");
-    const decoder = createTextDecoder(encoding);
-    let text = "";
-    for await (const chunk of iterable) {
-        const bytes = toStreamBytes(chunk);
-        if (!bytes) {
-            throw new UnsupportedStreamTypeError("streamToString", typeof chunk);
-        }
-        text += decoder.decode(bytes, { stream: true });
-    }
-    text += decoder.decode();
-    return text;
-}
-/**
- * Drain a stream (consume all data without processing)
- */
-export async function drainStream(stream) {
-    const iterable = toReadableAsyncIterable(stream, "drainStream");
-    for await (const _chunk of iterable) {
-        // Consume data
-    }
-}
-// =============================================================================
-// Type Guards
-// =============================================================================
-/** Check if an object is a transform stream */
-export const isTransform = createIsTransform(Transform);
-/** Check if an object is a duplex stream */
-export const isDuplex = createIsDuplex(Duplex, Transform);
-/** Check if an object is any kind of stream */
-export const isStream = createIsStream(Readable, Writable);
-// =============================================================================
-// Additional Utility Functions (Node.js Compatibility)
-// =============================================================================
-/** Add abort signal handling to any stream */
-export const addAbortSignal = createAddAbortSignal({
+export const isTransform = 
+/* @__PURE__ */ createIsTransform(Transform);
+export const isDuplex = 
+/* @__PURE__ */ createIsDuplex(Duplex);
+export const isStream = 
+/* @__PURE__ */ createIsStream(Readable, Writable);
+export const addAbortSignal = /* @__PURE__ */ createAddAbortSignal({
     add(emitter, event, listener) {
-        addEmitterListener(emitter, event, listener, { once: true });
+        emitter.once?.(event, listener);
     },
-    remove: removeEmitterListener
-});
-// =============================================================================
-// Stream State Inspection Functions
-// =============================================================================
-/**
- * Check if a readable stream has been disturbed (read from or cancelled).
- * Matches Node.js native: readableDidRead || readableAborted.
- * For Web ReadableStreams, returns `locked` (matches Node.js behaviour).
- */
-export function isDisturbed(stream) {
-    if (stream instanceof Readable) {
-        return Readable.isDisturbed(stream);
+    remove(emitter, event, listener) {
+        (emitter.off ?? emitter.removeListener)?.call(emitter, event, listener);
     }
-    if (stream instanceof Duplex) {
-        return Readable.isDisturbed(stream._readable);
-    }
-    // Web ReadableStream: `locked` is the closest indicator of disturbance
-    // (a reader has been acquired). Matches the Node.js isDisturbed check.
-    if (stream?.locked !== undefined) {
-        return !!stream.locked;
-    }
-    const s = stream;
-    return !!(s?.readableDidRead || s?._didRead || s?.readableAborted);
-}
-/**
- * Check if an object is a readable stream that is still in a readable state.
- * Returns false for destroyed or ended/finished streams (matches Node.js behavior).
- */
-export function isReadable(stream) {
-    if (stream == null) {
-        return false;
-    }
-    const s = stream;
-    // Check if destroyed
-    if (s.destroyed) {
-        return false;
-    }
-    // Must be a readable stream type
-    if (!(stream instanceof Readable || stream instanceof Transform || stream instanceof Duplex)) {
-        if (!(typeof s.read === "function" && typeof s.pipe === "function")) {
-            return false;
-        }
-    }
-    // Check if reading has finished (readableEnded or equivalent)
-    if (s.readableEnded === true) {
-        return false;
-    }
-    return true;
-}
-/**
- * Check if an object is a writable stream that is still in a writable state.
- * Returns false for destroyed or ended/finished streams (matches Node.js behavior).
- */
-export function isWritable(stream) {
-    if (stream == null) {
-        return false;
-    }
-    const s = stream;
-    // Check if destroyed
-    if (s.destroyed) {
-        return false;
-    }
-    // Must be a writable stream type
-    if (!(stream instanceof Writable || stream instanceof Transform || stream instanceof Duplex)) {
-        if (!(typeof s.write === "function" && typeof s.end === "function")) {
-            return false;
-        }
-    }
-    // Check if writing has ended (writableEnded or equivalent)
-    if (s.writableEnded === true) {
-        return false;
-    }
-    return true;
-}
-// =============================================================================
-// Duplex Pair
-// =============================================================================
-/**
- * Create a pair of connected Duplex streams
- * Data written to one stream can be read from the other
- */
-export function duplexPair(options) {
-    const objectMode = options?.readableObjectMode ?? options?.writableObjectMode ?? options?.objectMode ?? false;
-    const highWaterMark = options?.readableHighWaterMark ??
-        options?.writableHighWaterMark ??
-        options?.highWaterMark ??
-        getDefaultHighWaterMark(objectMode);
-    const duplexOpts = {
-        readableHighWaterMark: options?.readableHighWaterMark ?? highWaterMark,
-        writableHighWaterMark: options?.writableHighWaterMark ?? highWaterMark,
-        readableObjectMode: options?.readableObjectMode ?? objectMode,
-        writableObjectMode: options?.writableObjectMode ?? objectMode,
-        allowHalfOpen: options?.allowHalfOpen
-    };
-    // Holder object allows both streams to reference each other via closure
-    // while satisfying the `const` constraint (each variable is assigned once).
-    const pair = {};
-    const stream1 = new Duplex({
-        ...duplexOpts,
-        read() {
-            // Data will be pushed from stream2's write()
-        },
-        write(chunk, _encoding, callback) {
-            // Push to peer; if peer signals backpressure, defer callback until drain.
-            if (!pair.s2.push(chunk)) {
-                pair.s2.once("drain", () => callback());
-            }
-            else {
-                callback();
-            }
-        },
-        final(callback) {
-            pair.s2.push(null);
-            callback();
-        }
-    });
-    const stream2 = new Duplex({
-        ...duplexOpts,
-        read() {
-            // Data will be pushed from stream1's write()
-        },
-        write(chunk, _encoding, callback) {
-            // Push to peer; if peer signals backpressure, defer callback until drain.
-            if (!stream1.push(chunk)) {
-                stream1.once("drain", () => callback());
-            }
-            else {
-                callback();
-            }
-        },
-        final(callback) {
-            stream1.push(null);
-            callback();
-        }
-    });
-    pair.s1 = stream1;
-    pair.s2 = stream2;
-    return [stream1, stream2];
-}
-// =============================================================================
-// Private Helpers
-// =============================================================================
-// Helper function to collect stream chunks with total length tracking
-async function collectStreamChunks(stream) {
-    const chunks = [];
-    let totalLength = 0;
-    const iterable = toReadableAsyncIterable(stream, "collectStreamChunks");
-    for await (const chunk of iterable) {
-        const bytes = toStreamBytes(chunk);
-        if (!bytes) {
-            throw new UnsupportedStreamTypeError("streamToBuffer", typeof chunk);
-        }
-        chunks.push(bytes);
-        totalLength += bytes.length;
-    }
-    return [chunks, totalLength];
-}
-function toReadableAsyncIterable(stream, name) {
-    if (isReadableStream(stream)) {
-        // Boundary: `isReadableStream` erases the Web stream's element type; the
-        // caller-supplied T is reasserted for the wrapped Readable.
-        return Readable.fromWeb(stream);
-    }
-    if (isAsyncIterable(stream)) {
-        return stream;
-    }
-    throw new UnsupportedStreamTypeError(name, typeof stream);
-}
-// =============================================================================
-// Stream Consumers (like stream.consumers in Node.js)
-// =============================================================================
-export const consumers = createConsumers({ streamToUint8Array, streamToString });
-// =============================================================================
-// Promises API (like stream/promises in Node.js)
-// =============================================================================
+});
+export const consumers = /* @__PURE__ */ createConsumers({ streamToUint8Array, streamToString });
 export const promises = { pipeline, finished };

package/dist/esm/modules/stream/browser/web.js

@@ -0,0 +1,25 @@
+/**
+ * Browser Stream - Web Streams conversions and `toWritable`
+ *
+ * Its own module so that converting a Writable does not keep the Readable
+ * side of the kernel in a bundle.
+ */
+import { makeReadableFromWeb, makeWritableFromWeb } from "../core/web-conversions.js";
+import { Readable } from "../kernel/classes.js";
+import { isWritableStream } from "../kernel/stream-utils.js";
+import { Writable } from "../kernel/writable.js";
+/** A Web `ReadableStream` as a Readable, with the module's guarantees; see `web-conversions`. */
+export const readableFromWeb = /* @__PURE__ */ makeReadableFromWeb(Readable);
+/** A Web `WritableStream` as a Writable, with the module's guarantees; see `web-conversions`. */
+export const writableFromWeb = /* @__PURE__ */ makeWritableFromWeb(Writable);
+export { readableToWeb, writableToWeb } from "../core/web-conversions.js";
+/**
+ * Normalize a user-provided writable into one this module can drive: a Web
+ * `WritableStream` is adapted, anything Node-like is used as is.
+ */
+export function toWritable(stream) {
+    if (isWritableStream(stream)) {
+        return writableFromWeb(stream);
+    }
+    return stream;
+}

package/dist/esm/modules/stream/buffered-stream.js

@@ -202,7 +202,8 @@ export class BufferedStream extends EventEmitter {
         while (this._bufferReadIndex < this._buffers.length) {
             const buf = this._buffers[this._bufferReadIndex];
             if (buf.isEOD) {
-                this._bufferReadIndex++;
+                // Drop the reference so a consumed batch can be collected before compaction.
+                this._buffers[this._bufferReadIndex++] = undefined;
                 continue;
             }
             // Track length reduction
@@ -210,7 +211,7 @@ export class BufferedStream extends EventEmitter {
             const data = buf.read(size);
             this._totalLength -= beforeLen - buf.length;
             if (buf.isEOD) {
-                this._bufferReadIndex++;
+                this._buffers[this._bufferReadIndex++] = undefined;
             }
             // Reset/compact buffer queue occasionally
             if (this._bufferReadIndex === this._buffers.length) {
@@ -258,10 +259,7 @@ export class BufferedStream extends EventEmitter {
         // Allocate exactly once, then copy remaining chunks/buffers.
         const out = new Uint8Array(this._totalLength);
         let offset = 0;
-        for (let i = this._chunkReadIndex; i < this._chunks.length; i++) {
-            const chunk = this._chunks[i];
-            offset += chunk.copy(out, offset, 0, chunk.length);
-        }
+        // Older data first: what was already moved into buffers, then pending chunks.
         for (let i = this._bufferReadIndex; i < this._buffers.length; i++) {
             const buf = this._buffers[i];
             if (buf.isEOD) {
@@ -271,6 +269,10 @@ export class BufferedStream extends EventEmitter {
             out.set(view, offset);
             offset += view.length;
         }
+        for (let i = this._chunkReadIndex; i < this._chunks.length; i++) {
+            const chunk = this._chunks[i];
+            offset += chunk.copy(out, offset, 0, chunk.length);
+        }
         // Reset internal state — data has been consumed.
         this._chunks = [];
         this._chunkReadIndex = 0;

package/dist/esm/modules/stream/core/factories.js

@@ -0,0 +1,166 @@
+/**
+ * Stream factory functions shared by the Node and browser entry points.
+ *
+ * The bodies are identical on both platforms; only the stream classes differ,
+ * so each entry point builds them with its own.
+ */
+import { BufferedStream } from "../buffered-stream.js";
+import { PullStream } from "../pull-stream.js";
+import { stringToUint8Array } from "../../../utils/binary.js";
+/**
+ * Deliver a value that may be a promise to a Node-style callback; `undefined`
+ * means "nothing to push".
+ *
+ * A promise is recognised as `await` recognises one — anything with a `then`
+ * method — not with `instanceof Promise`, which is false for a promise from
+ * another realm (an iframe, a `vm` context) and for any other thenable, and
+ * pushed the promise itself as the chunk. `Promise.resolve` then adopts it as
+ * `await` would, so a thenable that calls back twice or throws still settles
+ * once. A plain value keeps the synchronous path.
+ */
+function settle(run, callback) {
+    let result;
+    try {
+        result = run();
+    }
+    catch (err) {
+        callback(err);
+        return;
+    }
+    if (typeof result?.then === "function") {
+        Promise.resolve(result).then(data => (data !== undefined ? callback(null, data) : callback()), err => callback(err));
+    }
+    else if (result !== undefined) {
+        callback(null, result);
+    }
+    else {
+        callback();
+    }
+}
+function emptyRead() {
+    this.push(null);
+}
+function nullWrite(_chunk, _encoding, callback) {
+    callback();
+}
+/** `createPullStream`; platform-independent. */
+export function createPullStream(options) {
+    return new PullStream(options);
+}
+/** `createBufferedStream`; platform-independent. */
+export function createBufferedStream(options) {
+    return new BufferedStream(options);
+}
+// One maker per factory, each called once per platform with the one class it
+// needs. A shared object of every class would make each factory keep all of
+// them — the whole Readable/compose kernel behind a lone `createWritable`.
+export function makeCreateReadable(Readable) {
+    return options => new Readable(options);
+}
+export function makeCreateReadableFromAsyncIterable(Readable) {
+    return (iterable, options) => Readable.from(iterable, { ...options, objectMode: options?.objectMode ?? true });
+}
+/**
+ * `undefined` entries are skipped: a stream's end-of-data signal is a nullish
+ * push, so there is no in-band way to carry an undefined chunk, while `0`, `""`
+ * and `false` are ordinary values that must survive.
+ */
+export function makeCreateReadableFromArray(Readable) {
+    return (data, options) => {
+        let index = 0;
+        return new Readable({
+            ...options,
+            objectMode: options?.objectMode ?? true,
+            read() {
+                while (index < data.length) {
+                    const chunk = data[index++];
+                    if (chunk === undefined) {
+                        continue;
+                    }
+                    if (!this.push(chunk)) {
+                        return;
+                    }
+                }
+                this.push(null);
+            }
+        });
+    };
+}
+export function makeCreateReadableFromGenerator(Readable) {
+    return (generator, options) => Readable.from(generator(), { ...options, objectMode: options?.objectMode ?? true });
+}
+export function makeCreateReadableFromPromise(Readable) {
+    return (promise, options) => {
+        const readable = new Readable({
+            ...options,
+            objectMode: options?.objectMode ?? true,
+            read() { }
+        });
+        // Adopted as `await` would: a promise from another realm or any thenable
+        // works, one that calls back twice settles once, and a `then` that throws
+        // fails the stream rather than the call.
+        Promise.resolve()
+            .then(() => promise)
+            .then(value => {
+            readable.push(value);
+            readable.push(null);
+        }, err => readable.destroy(err));
+        return readable;
+    };
+}
+export function makeCreateEmptyReadable(Readable) {
+    return options => new Readable({ ...options, read: emptyRead });
+}
+export function makeCreateWritable(Writable) {
+    return options => new Writable(options);
+}
+export function makeCreateNullWritable(Writable) {
+    return options => new Writable({ ...options, write: nullWrite });
+}
+/** The shorthand `transformFn` returns its result; `undefined` pushes nothing. */
+export function makeCreateTransform(Transform) {
+    return (transformFn, options) => {
+        const flush = options?.flush;
+        return new Transform({
+            ...options,
+            transform(chunk, encoding, callback) {
+                settle(() => transformFn(chunk, encoding), callback);
+            },
+            flush: flush
+                ? (callback) => settle(flush, callback)
+                : undefined
+        });
+    };
+}
+export function makeCreatePassThrough(PassThrough) {
+    return options => new PassThrough(options);
+}
+export function makeCreateDuplex(Duplex) {
+    return options => new Duplex(options);
+}
+export function makeFromBytes(Readable) {
+    return data => new Readable({
+        read() {
+            this.push(data);
+            this.push(null);
+        }
+    });
+}
+export function makeFromString(Readable) {
+    const fromBytes = makeFromBytes(Readable);
+    return str => fromBytes(stringToUint8Array(str));
+}
+export function makeFromJSON(Readable) {
+    const fromString = makeFromString(Readable);
+    return data => fromString(JSON.stringify(data));
+}
+export function makeTransform(Transform) {
+    const createTransform = makeCreateTransform(Transform);
+    return fn => createTransform(fn);
+}
+export function makeFilter(Transform) {
+    const createTransform = makeCreateTransform(Transform);
+    return (predicate) => createTransform(async (chunk) => ((await predicate(chunk)) ? chunk : undefined), {
+        objectMode: true
+    });
+}

package/dist/esm/modules/stream/core/pipeline-api.js

@@ -0,0 +1,32 @@
+/**
+ * The module's `pipeline()` calling convention, shared by both entry points:
+ * stages, then optional `{ signal, end }` options, then an optional callback;
+ * a promise is returned either way. Each entry supplies how to run the stages.
+ */
+import { isPipelineOptions } from "./options.js";
+export function createPipeline(run) {
+    return function pipeline(...args) {
+        let stages = args;
+        let options;
+        let callback;
+        if (typeof stages[stages.length - 1] === "function") {
+            // A trailing function is always the completion callback.
+            callback = stages[stages.length - 1];
+            stages = stages.slice(0, -1);
+        }
+        if (isPipelineOptions(stages[stages.length - 1])) {
+            options = stages[stages.length - 1];
+            stages = stages.slice(0, -1);
+        }
+        const promise = stages.length < 2
+            ? Promise.reject(new Error("Pipeline requires at least 2 streams"))
+            : new Promise((resolve, reject) => {
+                run(stages, options).then(resolve, reject);
+            });
+        if (callback) {
+            const cb = callback;
+            promise.then(() => cb(), err => cb(err));
+        }
+        return promise;
+    };
+}