documonster 0.20.2 → 0.21.0

package/dist/esm/modules/stream/core/sink-adapter.js

@@ -10,7 +10,12 @@
  *   - `write(chunk)` resolves once the chunk has been accepted by the
  *     sink (after awaiting `drain` for Node-style sinks under
  *     backpressure, or `writer.ready` for Web streams).
- *   - `end()` finalises the sink and resolves on close.
+ *   - `end()` finalises the sink and resolves once it has really finished
+ *     (`'finish'` for a Node-style sink — a `'close'` before it is a
+ *     premature close). Calling it again returns the same promise.
+ *   - `abort(reason)` gives the sink up after a producer failure.
+ *   - A Web sink's writer is released once the sink is closed, aborted or
+ *     errored, so the stream is not left locked.
  *   - The first sink error is captured and re-thrown from the next
  *     `write` / `end` so callers can't lose it.
  *
@@ -39,13 +44,19 @@ export class SinkAdapter {
     constructor(sink) {
         this._error = null;
         this._ended = false;
+        this._ending = null;
+        this._writerReleased = false;
         if (isWebWritable(sink)) {
             this._kind = "web";
             this._webWriter = sink.getWriter();
             // Web writers expose .closed; surface termination errors through
             // the same _error channel so producers see them.
             this._webWriter.closed.catch((err) => {
-                this._captureError(err);
+                // Releasing our own lock rejects `closed` too; that is not a sink error.
+                if (!this._writerReleased) {
+                    this._captureError(err);
+                    this._releaseWriter();
+                }
             });
         }
         else if (isNodeWritable(sink)) {
@@ -109,53 +120,70 @@ export class SinkAdapter {
             drain?.cancel();
         }
     }
-    async end() {
-        if (this._ended) {
-            return;
+    /** Finish the sink. Every call returns the same promise. */
+    end() {
+        if (!this._ending) {
+            this._ended = true;
+            this._ending = this._finish();
         }
+        return this._ending;
+    }
+    /**
+     * Give the sink up after a producer failure: a Web sink is aborted and its
+     * lock released, a Node-style one destroyed with `reason`.
+     */
+    async abort(reason) {
         this._ended = true;
+        const error = reason instanceof Error ? reason : new Error(String(reason ?? "aborted"));
+        this._captureError(error);
+        if (this._kind === "web") {
+            if (!this._writerReleased) {
+                await this._webWriter.abort(error).catch(() => { });
+                this._releaseWriter();
+            }
+            return;
+        }
+        const sink = (this._kind === "node" ? this._nodeSink : this._duckSink);
+        if (typeof sink.destroy === "function" && !sink.destroyed) {
+            sink.destroy(error);
+        }
+    }
+    async _finish() {
         this._throwIfErrored();
         if (this._kind === "web") {
             // close() rejects if the stream has already errored — we let that
             // propagate so callers see the underlying failure.
-            await this._webWriter.close();
-            return;
-        }
-        if (this._kind === "node") {
-            const sink = this._nodeSink;
-            // Prefer the close event when available; some Node writables emit
-            // 'finish' first and only emit 'close' on `destroy()`. We listen
-            // for both.
-            const finished = createEventWaiter(sink, ["close", "finish"]);
             try {
-                await sink.end();
-                await finished.promise;
+                await this._webWriter.close();
             }
-            catch (error) {
-                finished.cancel();
-                throw error;
+            finally {
+                this._releaseWriter();
             }
-            this._throwIfErrored();
             return;
         }
-        // duck
-        const sink = this._duckSink;
+        const sink = this._kind === "node" ? this._nodeSink : this._duckSink;
         if (hasEvents(sink)) {
-            const finished = createEventWaiter(sink, ["close", "finish"]);
+            const finished = waitForFinish(sink);
             try {
                 await sink.end();
-                await finished.promise;
             }
             catch (error) {
                 finished.cancel();
                 throw error;
             }
+            await finished.promise;
         }
         else {
             await sink.end();
         }
         this._throwIfErrored();
     }
+    _releaseWriter() {
+        if (!this._writerReleased) {
+            this._writerReleased = true;
+            this._webWriter.releaseLock();
+        }
+    }
     _captureError(err) {
         if (this._error) {
             return;
@@ -184,3 +212,45 @@ export class SinkAdapter {
 function hasEvents(sink) {
     return typeof sink.once === "function" || typeof sink.on === "function";
 }
+/**
+ * Resolve on `'finish'`; reject on `'error'`, or on a `'close'` that comes
+ * first while the sink reports it has not finished — that is a premature
+ * close, not a successful end.
+ */
+function waitForFinish(sink) {
+    let cleanup = () => { };
+    const promise = new Promise((resolve, reject) => {
+        const onFinish = () => {
+            cleanup();
+            resolve();
+        };
+        const onError = (err) => {
+            cleanup();
+            reject(err instanceof Error ? err : new Error(String(err)));
+        };
+        const onClose = () => {
+            cleanup();
+            // A sink that reports no finished state (a duck sink signalling with
+            // 'close' alone) is taken at its word; one that does must have finished.
+            const finished = sink.writableFinished;
+            if (typeof finished !== "boolean" || finished) {
+                resolve();
+                return;
+            }
+            const err = new Error("Premature close");
+            err.code = "ERR_STREAM_PREMATURE_CLOSE";
+            reject(err);
+        };
+        const on = (sink.on ?? sink.once).bind(sink);
+        on("finish", onFinish);
+        on("error", onError);
+        on("close", onClose);
+        cleanup = () => {
+            const off = (sink.off ?? sink.removeListener)?.bind(sink);
+            off?.("finish", onFinish);
+            off?.("error", onError);
+            off?.("close", onClose);
+        };
+    });
+    return { promise, cancel: () => cleanup() };
+}

package/dist/esm/modules/stream/core/stream-helpers.js

@@ -0,0 +1,160 @@
+/**
+ * Stream helpers shared by the Node and browser entry points.
+ *
+ * Everything here works on the public shape of a stream — async iteration,
+ * a Web `ReadableStream`'s reader, the `readable*` / `writable*` getters — so
+ * it is the same code on both platforms. A Web stream is read through its own
+ * reader; it is not wrapped in a Node-style stream first.
+ */
+import { toStreamBytes } from "./binary-chunk.js";
+import { isAsyncIterable, isReadableStream } from "./type-guards.js";
+import { UnsupportedStreamTypeError } from "../errors.js";
+import { concatUint8Arrays, createTextDecoder } from "../../../utils/binary.js";
+/** `true` for an object with a Web `ReadableStream`'s `getReader()`. */
+export const isReadableStreamLike = isReadableStream;
+/**
+ * Read a Web `ReadableStream` with `for await`, whether or not the platform's
+ * `ReadableStream` is async-iterable itself. Every value is yielded as read —
+ * `null` and `undefined` included, as `ReadableStream.prototype.values()` does —
+ * so the caller decides what a value it cannot use means. Leaving the loop
+ * early cancels the stream; the lock is released either way.
+ */
+export async function* readableStreamToAsyncIterable(stream) {
+    const reader = stream.getReader();
+    let done = false;
+    try {
+        while (true) {
+            const result = await reader.read();
+            if (result.done) {
+                done = true;
+                return;
+            }
+            yield result.value;
+        }
+    }
+    finally {
+        if (!done) {
+            await Promise.resolve(reader.cancel?.()).catch(() => { });
+        }
+        reader.releaseLock?.();
+    }
+}
+/** Every chunk of a stream, in an array. */
+export async function collect(stream) {
+    const result = [];
+    for await (const chunk of stream) {
+        result.push(chunk);
+    }
+    return result;
+}
+/** A whole stream decoded as UTF-8 text. */
+export function text(stream) {
+    return streamToString(stream);
+}
+/** A whole stream parsed as JSON. */
+export async function json(stream) {
+    return JSON.parse(await text(stream));
+}
+/** A whole stream's bytes. */
+export function bytes(stream) {
+    return streamToUint8Array(stream);
+}
+function toAsyncIterable(stream, name) {
+    if (isReadableStream(stream)) {
+        return readableStreamToAsyncIterable(stream);
+    }
+    if (isAsyncIterable(stream)) {
+        return stream;
+    }
+    throw new UnsupportedStreamTypeError(name, typeof stream);
+}
+/** Collect every byte of a stream. */
+export async function streamToUint8Array(stream) {
+    const chunks = [];
+    let totalLength = 0;
+    for await (const chunk of toAsyncIterable(stream, "streamToUint8Array")) {
+        const bytes = toStreamBytes(chunk);
+        if (!bytes) {
+            throw new UnsupportedStreamTypeError("streamToUint8Array", typeof chunk);
+        }
+        chunks.push(bytes);
+        totalLength += bytes.byteLength;
+    }
+    return concatUint8Arrays(chunks, totalLength);
+}
+/** Alias of {@link streamToUint8Array}, named after Node's `Buffer`. */
+export function streamToBuffer(stream) {
+    return streamToUint8Array(stream);
+}
+/** Decode a whole stream as text. */
+export async function streamToString(stream, encoding) {
+    const decoder = createTextDecoder(encoding);
+    let text = "";
+    for await (const chunk of toAsyncIterable(stream, "streamToString")) {
+        const bytes = toStreamBytes(chunk);
+        if (!bytes) {
+            throw new UnsupportedStreamTypeError("streamToString", typeof chunk);
+        }
+        text += decoder.decode(bytes, { stream: true });
+    }
+    return text + decoder.decode();
+}
+/** Consume a stream to its end, discarding the data. */
+export async function drainStream(stream) {
+    for await (const _chunk of toAsyncIterable(stream, "drainStream")) {
+        // discard
+    }
+}
+/** `true` for a Node-style readable stream that can still be read from. */
+export function isReadable(stream) {
+    const s = stream;
+    return (!!s &&
+        typeof s.read === "function" &&
+        typeof s.pipe === "function" &&
+        !s.destroyed &&
+        s.readable !== false &&
+        s.readableEnded !== true);
+}
+/** `true` for a Node-style writable stream that can still be written to. */
+export function isWritable(stream) {
+    const s = stream;
+    return (!!s &&
+        typeof s.write === "function" &&
+        typeof s.end === "function" &&
+        !s.destroyed &&
+        s.writable !== false &&
+        s.writableEnded !== true);
+}
+const kIsDisturbed = Symbol.for("nodejs.stream.disturbed");
+/**
+ * `true` once a readable stream has been read from or aborted.
+ *
+ * Node's own Web streams answer through an internal symbol, which is consulted
+ * first. Elsewhere a Web `ReadableStream` has no public "disturbed" flag, but
+ * the Fetch spec makes it observable: `new Response(stream)` must throw for a
+ * stream that is disturbed or locked, and does nothing to one that is neither —
+ * it takes no lock and reads nothing. So an unlocked stream gets an exact
+ * answer. A locked one cannot be told apart (locked-and-read and
+ * locked-but-unread both throw) and reports `false`, as Node does for a stream
+ * that is locked but not yet read.
+ */
+export function isDisturbed(stream) {
+    const s = stream;
+    if (!s) {
+        return false;
+    }
+    const known = s[kIsDisturbed] ?? (s.readableDidRead || s.readableAborted);
+    if (known !== undefined) {
+        return !!known;
+    }
+    if (isReadableStream(s) && !s.locked && typeof Response === "function") {
+        try {
+            new Response(s);
+            return false;
+        }
+        catch {
+            return true;
+        }
+    }
+    return false;
+}

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

@@ -4,7 +4,6 @@
  * Platform-neutral utility functions shared by Node.js and Browser implementations:
  * - Stream state inspection (isDestroyed, isErrored)
  * - Callback-to-promise conversion (promisify)
- * - High water mark management (getDefaultHighWaterMark, setDefaultHighWaterMark)
  */
 // =============================================================================
 // State Inspection
@@ -39,25 +38,3 @@ export function promisify(fn) {
         });
     });
 }
-// =============================================================================
-// High Water Mark
-// =============================================================================
-let _defaultHighWaterMark = 65536; // 64KB default (matches Node's own on every supported line)
-let _defaultHighWaterMarkObjectMode = 16; // 16 objects default
-/**
- * Get the default high water mark for streams
- */
-export function getDefaultHighWaterMark(objectMode) {
-    return objectMode ? _defaultHighWaterMarkObjectMode : _defaultHighWaterMark;
-}
-/**
- * Set the default high water mark for streams
- */
-export function setDefaultHighWaterMark(objectMode, value) {
-    if (objectMode) {
-        _defaultHighWaterMarkObjectMode = value;
-    }
-    else {
-        _defaultHighWaterMark = value;
-    }
-}

package/dist/esm/modules/stream/core/web-conversions.js

@@ -0,0 +1,31 @@
+/**
+ * Web Streams conversions with the module's guarantees, on both entry points.
+ *
+ * `Readable.fromWeb` / `.toWeb` and friends stay exactly what each platform's
+ * classes provide — on the Node entry, Node's own, with Node's known defects
+ * (see the README). These functions run the module's adapters instead, with
+ * that platform's classes, so the same call behaves the same on both:
+ *
+ * - no chunk is lost: a write made while `'drain'` is pending still reaches the
+ *   Node-style stream, and a `null` read from a Web stream fails it rather than
+ *   ending it early;
+ * - strings from `setEncoding()` can be queued;
+ * - the lock on a Web stream is handed back once the adapted stream ends,
+ *   errors or is destroyed, and is never taken at all when adapting fails;
+ * - the adapters remove their own listeners when they are done.
+ */
+import { readableFromWeb as adaptReadableFromWeb, readableToWeb as adaptReadableToWeb, writableFromWeb as adaptWritableFromWeb, writableToWeb as adaptWritableToWeb } from "../kernel/web-adapters.js";
+export function makeReadableFromWeb(Readable) {
+    return (stream, options) => adaptReadableFromWeb(Readable, stream, options);
+}
+export function makeWritableFromWeb(Writable) {
+    return (stream, options) => adaptWritableFromWeb(Writable, stream, options);
+}
+/** A Node-style Readable as a Web `ReadableStream`. */
+export function readableToWeb(stream, options) {
+    return adaptReadableToWeb(stream, options);
+}
+/** A Node-style Writable as a Web `WritableStream`. */
+export function writableToWeb(stream) {
+    return adaptWritableToWeb(stream);
+}

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

@@ -0,0 +1,90 @@
+/**
+ * An all-Web pipeline, run by the platform.
+ *
+ * When every stage is a Web stream, both entry points hand the pipeline to the
+ * platform's own `pipeThrough` / `pipeTo` instead of pumping chunks in
+ * JavaScript. That carries backpressure, cancellation and abort natively — and
+ * on Node it also avoids `stream.pipeline`, which never settles when such a
+ * pipeline is aborted while its source is waiting for data.
+ */
+import { isReadableStream, isTransformStream, isWritableStream } from "../kernel/stream-utils.js";
+import { createAbortError } from "../../../utils/errors.js";
+/** `ReadableStream → TransformStream* → WritableStream`: nothing but Web streams. */
+export function isWebOnlyPipeline(streams) {
+    if (!isReadableStream(streams[0]) || !isWritableStream(streams[streams.length - 1])) {
+        return false;
+    }
+    for (let i = 1; i < streams.length - 1; i++) {
+        if (!isTransformStream(streams[i])) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Run an all-Web pipeline with the platform's own `pipeTo`.
+ *
+ * The data moves natively, but the pipeline is managed here: every stage is
+ * checked for a lock before anything starts, each connection is its own
+ * `pipeTo`, and the promise settles only once every connection has finished
+ * tearing down — with the first error that occurred.
+ *
+ * A failure travels along the chain by the Streams spec's own propagation
+ * (error forwards, cancel backwards); only the caller's abort uses a signal.
+ * Aborting the other connections on the first failure as well looks tidier
+ * but races that propagation: Node's `pipeTo` then skips cancelling the
+ * source once there are two or more transforms.
+ */
+export async function pipeWebStreams(streams, options) {
+    const source = streams[0];
+    const transforms = streams.slice(1, -1);
+    const destination = streams[streams.length - 1];
+    if (source.locked ||
+        destination.locked ||
+        transforms.some(t => t.readable.locked || t.writable.locked)) {
+        throw new TypeError("pipeline: a stream is locked, so it cannot be piped");
+    }
+    // Every port must be distinct: a stage used twice would be connected twice,
+    // the second connection would fail to take its lock and never be made, and
+    // the rest would wait forever for an error that has no path to them.
+    const ports = [source, destination, ...transforms.flatMap(t => [t.readable, t.writable])];
+    if (new Set(ports).size !== ports.length) {
+        throw new TypeError("pipeline: the same stream appears more than once");
+    }
+    // The caller's abort, reported as the AbortError the rest of the module uses.
+    let signal;
+    let detach = () => { };
+    const outer = options?.signal;
+    if (outer) {
+        const controller = new AbortController();
+        const onAbort = () => controller.abort(createAbortError(outer.reason));
+        if (outer.aborted) {
+            onAbort();
+        }
+        else {
+            outer.addEventListener("abort", onAbort, { once: true });
+            detach = () => outer.removeEventListener("abort", onAbort);
+        }
+        signal = controller.signal;
+    }
+    const connections = [];
+    let upstream = source;
+    for (const transform of transforms) {
+        connections.push(upstream.pipeTo(transform.writable, { signal }));
+        upstream = transform.readable;
+    }
+    connections.push(upstream.pipeTo(destination, { signal, preventClose: options?.end === false }));
+    // Wait for every connection to settle, then report the failure seen first.
+    let failed = false;
+    let firstError;
+    await Promise.all(connections.map(connection => connection.catch((err) => {
+        if (!failed) {
+            failed = true;
+            firstError = err;
+        }
+    })));
+    detach();
+    if (failed) {
+        throw firstError;
+    }
+}

package/dist/esm/modules/stream/index.base.js

@@ -5,9 +5,9 @@
  * `index.ts` (Node) and `index.browser.ts`.
  */
 // Common re-exports (shared between Node.js and browser)
-export { isDestroyed, isErrored, getDefaultHighWaterMark, setDefaultHighWaterMark, promisify } from "./core/utils.js";
+export { isDestroyed, isErrored, promisify } from "./core/utils.js";
 export { ChunkedBuilder, TransactionalChunkedBuilder } from "./chunked-builder.js";
-export { collect, text, json, bytes, fromString, fromJSON, fromBytes, transform, filter, isReadableStreamLike, readableStreamToAsyncIterable } from "#platform/modules/stream/utils";
+export { bytes, collect, isReadableStreamLike, json, readableStreamToAsyncIterable, text } from "./core/stream-helpers.js";
 export { StreamError, StreamStateError, StreamTypeError, UnsupportedStreamTypeError, isStreamError } from "./errors.js";
 // Internal utilities exposed for cross-module use (e.g. archive, word/excel writers)
 export { isReadableStream, isWritableStream, isAsyncIterable, isTransformStream } from "./core/type-guards.js";

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

@@ -1,31 +1,25 @@
 /**
  * Stream Module (browser entry)
  *
- * Mirrors the public surface of `./index.ts`, but exports the browser
- * implementation from `./streams.browser`.
- *
- * This file is intentionally export-only (tree-shaking friendly).
+ * The same names as `index.ts`, backed by the browser kernel in `./browser`,
+ * a port of Node's `lib/internal/streams`.
  */
 // Shared type + platform-independent exports
 export * from "./index.base.js";
-// Core stream classes (browser implementations)
-import { Readable } from "./browser/readable.js";
-export { Writable, toWritable } from "./browser/writable.js";
-export { Transform } from "./browser/transform.js";
-import { Duplex } from "./browser/duplex.js";
-export { PassThrough } from "./browser/passthrough.js";
-export { Collector } from "./browser/collector.js";
-export { Readable, Duplex };
-// Late-binding injection: break circular Readable ↔ Duplex
-import { registerDuplexFrom } from "./browser/_lazy.js";
-// The registry is type-erased (`source: unknown`); re-project onto Duplex.from's
-// accepted source union at this single boundary.
-registerDuplexFrom(source => Duplex.from(source));
+// Core stream classes
+export { Readable, Duplex, Transform, PassThrough } from "./kernel/classes.js";
+export { Writable } from "./kernel/writable.js";
+export { getDefaultHighWaterMark, setDefaultHighWaterMark } from "./kernel/state.js";
+// Collector
+export { Collector, createCollector } from "./browser/collector.js";
 // Factory functions + re-exported helpers
-export { PullStream, BufferedStream, createStringChunk, createByteChunk, createReadable, createReadableFromAsyncIterable, createReadableFromArray, createWritable, createTransform, createCollector, createPassThrough, createPullStream, createBufferedStream, createDuplex, createReadableFromGenerator, createReadableFromPromise, createEmptyReadable, createNullWritable } from "./browser/factories.js";
+export { PullStream, BufferedStream, createStringChunk, createByteChunk, createReadable, createReadableFromAsyncIterable, createReadableFromArray, createWritable, createTransform, createPassThrough, createPullStream, createBufferedStream, createDuplex, createReadableFromGenerator, createReadableFromPromise, createEmptyReadable, createNullWritable, filter, fromBytes, fromJSON, fromString, transform } from "./browser/factories.js";
 // Pipeline & Finished
 export { pipeline, finished, finishedAll } from "./browser/pipeline.js";
 // Compose
 export { compose } from "./browser/compose.js";
 // Utilities
-export { streamToPromise, streamToUint8Array, streamToBuffer, streamToString, drainStream, copyStream, isTransform, isDuplex, isStream, addAbortSignal, isDisturbed, isReadable, isWritable, duplexPair, consumers, promises } from "./browser/utils.js";
+export { streamToPromise, streamToUint8Array, streamToBuffer, streamToString, drainStream, copyStream, isTransform, isDuplex, isStream, addAbortSignal, isDisturbed, isReadable, isWritable, consumers, promises } from "./browser/utils.js";
+// Web Streams conversions
+export { duplexPair } from "./browser/duplex-pair.js";
+export { readableFromWeb, readableToWeb, toWritable, writableFromWeb, writableToWeb } from "./browser/web.js";

package/dist/esm/modules/stream/index.js

@@ -1,11 +1,8 @@
 /**
  * Stream Module (Node.js entry)
  *
- * Public entrypoint for stream utilities and classes.
- *
- * Notes:
- * - This file is intentionally export-only (tree-shaking friendly).
- * - Browser builds should import from `@stream/index.browser`.
+ * Node's own `node:stream` classes, plus the module's helpers around them.
+ * `index.browser.ts` exports the same names backed by the browser kernel.
  *
  * @example
  * ```ts
@@ -19,17 +16,16 @@
 // Shared type + platform-independent exports
 export * from "./index.base.js";
 // Core stream classes (native Node.js)
-import { Readable, Transform, Duplex, PassThrough } from "stream";
-export { Readable, Transform, Duplex, PassThrough };
-// Writable (extended with browser-compatible API)
-export { Writable, toWritable } from "./node/writable.js";
+export { Readable, Writable, Duplex, Transform, PassThrough, getDefaultHighWaterMark, setDefaultHighWaterMark } from "stream";
 // Collector
 export { Collector, createCollector } from "./node/collector.js";
 // Factory functions + re-exported helpers
-export { PullStream, BufferedStream, createStringChunk, createByteChunk, createReadable, createReadableFromAsyncIterable, createReadableFromArray, createWritable, createTransform, createPassThrough, createPullStream, createBufferedStream, createDuplex, createReadableFromGenerator, createReadableFromPromise, createEmptyReadable, createNullWritable } from "./node/factories.js";
+export { PullStream, BufferedStream, createStringChunk, createByteChunk, createReadable, createReadableFromAsyncIterable, createReadableFromArray, createWritable, createTransform, createPassThrough, createPullStream, createBufferedStream, createDuplex, createReadableFromGenerator, createReadableFromPromise, createEmptyReadable, createNullWritable, filter, fromBytes, fromJSON, fromString, transform } from "./node/factories.js";
 // Pipeline & Finished
 export { pipeline, finished, finishedAll } from "./node/pipeline.js";
 // Compose
 export { compose } from "./node/compose.js";
 // Utilities
 export { streamToPromise, streamToUint8Array, streamToBuffer, streamToString, drainStream, copyStream, isTransform, isDuplex, isStream, addAbortSignal, isDisturbed, isReadable, isWritable, duplexPair, consumers, promises } from "./node/utils.js";
+// Web Streams conversions
+export { readableFromWeb, readableToWeb, toWritable, writableFromWeb, writableToWeb } from "./node/web.js";