@cj-tech-master/excelts 5.1.18 → 6.0.0-beta.1

package/dist/browser/modules/stream/browser/pipe-manager.js

@@ -0,0 +1,158 @@
+/**
+ * Browser Stream - PipeManager
+ *
+ * Encapsulates pipe/unpipe logic for Readable streams.
+ * Owns the destination list and the per-destination listener bookkeeping,
+ * so Readable doesn't need to know anything about piping internals.
+ */
+import { StreamTypeError } from "../errors.js";
+import { removeEmitterListener } from "./helpers.js";
+// =============================================================================
+// PipeManager
+// =============================================================================
+export class PipeManager {
+    constructor(_source) {
+        this._source = _source;
+        this._destinations = [];
+        this._listeners = new Map();
+        this._sourceOverride = null;
+    }
+    /**
+     * Override the source identity used when emitting "pipe" and "unpipe" events
+     * on destinations. This allows Transform/Duplex wrappers to present
+     * themselves (rather than their internal Readable) as the pipe source.
+     */
+    setSource(source) {
+        this._sourceOverride = source;
+    }
+    /** The identity to emit in "pipe"/"unpipe" events. */
+    get _emitSource() {
+        return this._sourceOverride ?? this._source;
+    }
+    /** Pipe source data to `destination`. Returns `destination` for chaining. */
+    pipe(destination, options) {
+        // IMPORTANT:
+        // Do not rely on `instanceof` here.
+        // In bundled/minified builds, multiple copies of this module can exist,
+        // causing `instanceof Transform/Writable/Duplex` to fail even when the object
+        // is a valid destination.
+        const dest = destination;
+        const eventTarget = dest;
+        const hasWrite = typeof dest?.write === "function";
+        const hasEnd = typeof dest?.end === "function";
+        const hasOn = typeof eventTarget?.on === "function";
+        const hasOnce = typeof eventTarget?.once === "function";
+        const hasOff = typeof eventTarget?.off === "function";
+        if (!hasWrite || !hasEnd || (!hasOnce && !hasOn) || (!hasOff && !eventTarget?.removeListener)) {
+            throw new StreamTypeError("Writable", typeof dest);
+        }
+        this._destinations.push(dest);
+        // Create listeners that we can later remove
+        let drainListener;
+        const removeDrainListener = () => {
+            if (!drainListener) {
+                return;
+            }
+            removeEmitterListener(eventTarget, "drain", drainListener);
+            drainListener = undefined;
+        };
+        const dataListener = (chunk) => {
+            const canWrite = dest.write(chunk);
+            if (!canWrite) {
+                this._source.pause();
+                if (!drainListener) {
+                    drainListener = () => {
+                        removeDrainListener();
+                        this._source.resume();
+                    };
+                    eventTarget.on("drain", drainListener);
+                    const entry = this._listeners.get(dest);
+                    if (entry) {
+                        entry.drain = drainListener;
+                    }
+                }
+            }
+        };
+        const endEnabled = options?.end !== false;
+        const endListener = endEnabled
+            ? () => {
+                dest.end();
+            }
+            : undefined;
+        // Auto-unpipe when destination closes or finishes (Node.js compatibility).
+        // Node.js internally listens for 'finish' and 'close' on the destination
+        // and calls unpipe() so the source stops pushing data.
+        const onDestCleanup = () => {
+            this.unpipe(dest);
+        };
+        // Use once() if available, otherwise fall back to on() + manual removal
+        const onceFn = typeof eventTarget.once === "function" ? "once" : "on";
+        eventTarget[onceFn]("close", onDestCleanup);
+        eventTarget[onceFn]("finish", onDestCleanup);
+        this._listeners.set(dest, {
+            data: dataListener,
+            end: endListener,
+            destClose: onDestCleanup,
+            destFinish: onDestCleanup,
+            eventTarget
+        });
+        this._source.on("data", dataListener);
+        if (endListener) {
+            this._source.once("end", endListener);
+        }
+        // Node.js pipe() does NOT forward errors from source to destination.
+        // Users must handle errors on each stream independently.
+        // Emit 'pipe' event on destination (Node.js compatibility)
+        eventTarget.emit?.("pipe", this._emitSource);
+        this._source.resume();
+        return destination;
+    }
+    /** Unpipe from a specific destination, or all destinations if none given. */
+    unpipe(destination) {
+        if (destination) {
+            const idx = this._destinations.indexOf(destination);
+            if (idx !== -1) {
+                this._destinations.splice(idx, 1);
+                this._removeListeners(destination);
+                // Pause source when no destinations remain (match Node.js behavior)
+                if (this._destinations.length === 0) {
+                    this._source.pause();
+                }
+            }
+        }
+        else {
+            const hadDestinations = this._destinations.length > 0;
+            for (const target of this._destinations) {
+                this._removeListeners(target);
+            }
+            this._destinations = [];
+            // Only pause if we actually had destinations to remove
+            if (hadDestinations) {
+                this._source.pause();
+            }
+        }
+    }
+    _removeListeners(destination) {
+        const listeners = this._listeners.get(destination);
+        if (!listeners) {
+            return;
+        }
+        this._source.off("data", listeners.data);
+        if (listeners.end) {
+            this._source.off("end", listeners.end);
+        }
+        if (listeners.drain) {
+            removeEmitterListener(listeners.eventTarget, "drain", listeners.drain);
+        }
+        // Remove destination close/finish listeners
+        if (listeners.destClose) {
+            removeEmitterListener(listeners.eventTarget, "close", listeners.destClose);
+        }
+        if (listeners.destFinish) {
+            removeEmitterListener(listeners.eventTarget, "finish", listeners.destFinish);
+        }
+        // Emit 'unpipe' event on destination (Node.js compatibility)
+        listeners.eventTarget.emit?.("unpipe", this._emitSource);
+        this._listeners.delete(destination);
+    }
+}

package/dist/browser/modules/stream/browser/pipeline.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Browser Stream - Pipeline & Finished
+ */
+import type { PipelineStreamLike } from "../types.js";
+import type { PipelineOptions, PipelineCallback, FinishedOptions } from "../common/options.js";
+export type { PipelineOptions, FinishedOptions } from "../common/options.js";
+export { isPipelineOptions } from "../common/options.js";
+type PipelineStream = PipelineStreamLike;
+export declare const toBrowserPipelineStream: (stream: PipelineStream) => any;
+/**
+ * Pipeline streams together with proper error handling and cleanup.
+ * Supports both callback and promise-based usage like Node.js.
+ *
+ * @example
+ * // Promise usage
+ * await pipeline(source, transform, destination);
+ *
+ * @example
+ * // With options
+ * await pipeline(source, transform, destination, { signal: controller.signal });
+ *
+ * @example
+ * // Callback usage
+ * pipeline(source, transform, destination, (err) => {
+ *   if (err) console.error('Pipeline failed', err);
+ * });
+ */
+export declare function pipeline(...args: [...PipelineStream[], PipelineOptions | PipelineCallback] | PipelineStream[]): Promise<void>;
+/**
+ * Wait for a stream to finish, close, or error.
+ * Node.js compatible with support for options and callbacks.
+ *
+ * @example
+ * // Promise usage
+ * await finished(stream);
+ *
+ * @example
+ * // With options
+ * await finished(stream, { readable: false }); // Only wait for writable side
+ *
+ * @example
+ * // Callback usage
+ * finished(stream, (err) => {
+ *   if (err) console.error('Stream error', err);
+ * });
+ */
+export declare function finished(stream: PipelineStreamLike, optionsOrCallback?: FinishedOptions | ((err?: Error | null) => void), callback?: (err?: Error | null) => void): Promise<void>;
+/**
+ * Wait for multiple streams to finish
+ */
+export declare const finishedAll: (streams: ReadonlyArray<PipelineStreamLike>) => Promise<void>;

package/dist/browser/modules/stream/browser/pipeline.js

@@ -0,0 +1,486 @@
+/**
+ * Browser Stream - Pipeline & Finished
+ */
+import { createFinishedAll } from "../common/finished-all.js";
+import { createAbortError } from "../errors.js";
+import { isReadableStream, isTransformStream, isWritableStream } from "../internal/type-guards.js";
+import { isPipelineOptions } from "../common/options.js";
+import { Readable } from "./readable.js";
+import { Writable } from "./writable.js";
+import { Transform } from "./transform.js";
+import { Duplex } from "./duplex.js";
+import { createListenerRegistry } from "./helpers.js";
+export { isPipelineOptions } from "../common/options.js";
+const supportsReadableSide = (stream) => {
+    // Check for readable-side properties/methods.  Writable.pipe() is a no-op
+    // that emits ERR_STREAM_CANNOT_PIPE, so `typeof pipe === "function"` alone
+    // is not sufficient — we must also see an actual readable indicator.
+    return "readableEnded" in stream || "readable" in stream || typeof stream.read === "function";
+};
+const supportsWritableSide = (stream) => {
+    return "writableFinished" in stream || "writable" in stream || typeof stream.write === "function";
+};
+const isStreamCompleted = (stream) => {
+    const readableDone = !supportsReadableSide(stream) || !!stream.readableEnded;
+    const writableDone = !supportsWritableSide(stream) || !!stream.writableFinished;
+    return readableDone && writableDone;
+};
+const createPrematureCloseError = () => {
+    const err = new Error("Premature close");
+    err.code = "ERR_STREAM_PREMATURE_CLOSE";
+    err.name = "Error [ERR_STREAM_PREMATURE_CLOSE]";
+    return err;
+};
+/**
+ * Wait for a stream's 'close' event after it has finished/ended.
+ * If the stream will emit close (autoDestroy && emitClose), wait for it.
+ * Otherwise resolve immediately (matching Node.js pipeline behavior where
+ * autoDestroy:false streams don't wait for close).
+ */
+const waitForClose = (stream, done, registry) => {
+    const s = stream;
+    // Already closed — resolve immediately.
+    if (s.closed || s._closed) {
+        done();
+        return;
+    }
+    const hasInternals = "_emitClose" in s && "_autoDestroy" in s;
+    const willEmitClose = hasInternals && s._emitClose !== false && s._autoDestroy !== false;
+    if (willEmitClose) {
+        registry.once(stream, "close", () => done());
+    }
+    else {
+        done();
+    }
+};
+export const toBrowserPipelineStream = (stream) => {
+    if (stream instanceof Readable ||
+        stream instanceof Writable ||
+        stream instanceof Transform ||
+        stream instanceof Duplex) {
+        return stream;
+    }
+    if (isTransformStream(stream)) {
+        return Transform.fromWeb(stream);
+    }
+    if (isReadableStream(stream)) {
+        return Readable.fromWeb(stream);
+    }
+    if (isWritableStream(stream)) {
+        return Writable.fromWeb(stream);
+    }
+    return stream;
+};
+/**
+ * Check if a pipeline stage is a generator/async generator function.
+ * These are used as transform stages: fn(source) => AsyncIterable.
+ */
+const isGeneratorFunction = (fn) => {
+    return typeof fn === "function" && !(fn instanceof Readable) && !(fn instanceof Writable);
+};
+/**
+ * Apply a generator function as a transform stage.
+ * Consumes the source stream via its async iterator, passes it through the
+ * generator function, and produces a new Readable from the resulting iterable.
+ */
+const applyGeneratorStage = (source, fn) => {
+    const iterable = fn(source);
+    return Readable.from(iterable);
+};
+/**
+ * Pipeline streams together with proper error handling and cleanup.
+ * Supports both callback and promise-based usage like Node.js.
+ *
+ * @example
+ * // Promise usage
+ * await pipeline(source, transform, destination);
+ *
+ * @example
+ * // With options
+ * await pipeline(source, transform, destination, { signal: controller.signal });
+ *
+ * @example
+ * // Callback usage
+ * pipeline(source, transform, destination, (err) => {
+ *   if (err) console.error('Pipeline failed', err);
+ * });
+ */
+export function pipeline(...args) {
+    // Parse arguments
+    let streams;
+    let options = {};
+    let callback;
+    const lastArg = args[args.length - 1];
+    if (typeof lastArg === "function") {
+        callback = lastArg;
+        // Check for combined style: pipeline(s1, s2, ..., options, callback)
+        const secondToLast = args[args.length - 2];
+        if (isPipelineOptions(secondToLast)) {
+            options = secondToLast;
+            streams = args.slice(0, -2);
+        }
+        else {
+            // Callback only: pipeline(s1, s2, ..., callback)
+            streams = args.slice(0, -1);
+        }
+    }
+    else if (isPipelineOptions(lastArg)) {
+        // Options only: pipeline(s1, s2, ..., { signal })
+        options = lastArg;
+        streams = args.slice(0, -1);
+    }
+    else {
+        // No callback or options: pipeline(s1, s2, s3)
+        streams = args;
+    }
+    const promise = new Promise((resolve, reject) => {
+        if (streams.length < 2) {
+            const err = new Error("Pipeline requires at least 2 streams");
+            reject(err);
+            return;
+        }
+        // Pre-process: normalize streams and resolve generator functions.
+        // Generator functions consume their source as an async iterable and produce
+        // a new Readable — they do NOT participate in .pipe() chains.
+        // We build a flat list of pipe-able stream stages.
+        const rawStages = streams.map(toBrowserPipelineStream);
+        // allStreams: every stream created (for cleanup on error).
+        // pipeStages: only the streams that need .pipe() chaining.
+        const allStreams = [];
+        const pipeStages = [];
+        let current = rawStages[0];
+        allStreams.push(current);
+        pipeStages.push(current);
+        for (let i = 1; i < rawStages.length; i++) {
+            const stage = rawStages[i];
+            if (isGeneratorFunction(stage)) {
+                // Generator consumes `current` internally → produces a new Readable.
+                // This Readable replaces `current` as the source for subsequent stages.
+                current = applyGeneratorStage(current, stage);
+                allStreams.push(current);
+                // Replace the last entry in pipeStages (the consumed source) with
+                // the generator-produced Readable, so the next real stream stage
+                // will be piped FROM this Readable.
+                pipeStages[pipeStages.length - 1] = current;
+            }
+            else {
+                allStreams.push(stage);
+                pipeStages.push(stage);
+                current = stage;
+            }
+        }
+        const source = pipeStages[0];
+        const destination = pipeStages[pipeStages.length - 1];
+        const transforms = pipeStages.slice(1, -1);
+        // Check for already-destroyed streams upfront.
+        // If a stream is already destroyed and its close event has already fired,
+        // our close listener would never fire — causing the pipeline to hang.
+        // Node.js detects this and immediately rejects with ERR_STREAM_PREMATURE_CLOSE.
+        for (const stream of allStreams) {
+            if (stream.destroyed) {
+                if (!isStreamCompleted(stream)) {
+                    reject(createPrematureCloseError());
+                    return;
+                }
+            }
+        }
+        let completed = false;
+        const registry = createListenerRegistry();
+        let onAbort;
+        const cleanupWithSignal = (error) => {
+            if (completed) {
+                return;
+            }
+            completed = true;
+            if (onAbort && options.signal) {
+                options.signal.removeEventListener("abort", onAbort);
+            }
+            // Node.js only destroys streams on ERROR, NOT on success.
+            // On error, pass the error to destroy(); on success, leave streams intact.
+            if (error) {
+                const noop = () => { };
+                for (const stream of allStreams) {
+                    if (typeof stream.on === "function") {
+                        stream.on("error", noop);
+                    }
+                    if (typeof stream.destroy === "function" && !stream.destroyed) {
+                        stream.destroy(error);
+                    }
+                }
+            }
+            registry.cleanup();
+            if (error) {
+                reject(error);
+            }
+            else {
+                resolve();
+            }
+        };
+        // Handle abort signal
+        if (options.signal) {
+            if (options.signal.aborted) {
+                cleanupWithSignal(createAbortError(options.signal.reason));
+                return;
+            }
+            onAbort = () => cleanupWithSignal(createAbortError(options.signal.reason));
+            options.signal.addEventListener("abort", onAbort);
+        }
+        // Chain the streams
+        current = source;
+        for (const transform of transforms) {
+            current.pipe(transform);
+            current = transform;
+        }
+        // Pipe to destination
+        if (options.end !== false) {
+            current.pipe(destination);
+        }
+        else {
+            // Don't end destination
+            let paused = false;
+            let waitingForDrain = false;
+            const onDrain = () => {
+                waitingForDrain = false;
+                if (paused && typeof current.resume === "function") {
+                    paused = false;
+                    current.resume();
+                }
+            };
+            const onData = (chunk) => {
+                const ok = destination.write(chunk);
+                if (!ok && !waitingForDrain) {
+                    waitingForDrain = true;
+                    if (!paused && typeof current.pause === "function") {
+                        paused = true;
+                        current.pause();
+                    }
+                    registry.once(destination, "drain", onDrain);
+                }
+            };
+            registry.add(current, "data", onData);
+            // end:false — wait for source to fully close (not just 'end').
+            // Node.js pipeline uses finished(source, {writable:false}) internally,
+            // which waits until the 'close' event when the stream will emit close.
+            registry.once(current, "end", () => {
+                // Source ended — now wait for its close event (autoDestroy → close)
+                // before resolving the pipeline. If the stream has already closed
+                // (or won't emit close), resolve immediately.
+                waitForClose(current, cleanupWithSignal, registry);
+            });
+        }
+        // Handle completion — wait for destination to fully close, not just finish.
+        // Node.js pipeline internally uses finished(destination) which waits for
+        // 'close' after 'finish' when the stream will emit close (autoDestroy &&
+        // emitClose). For streams that won't emit close (autoDestroy: false),
+        // resolve on 'finish' alone (matching Node.js behavior).
+        if (options.end !== false) {
+            registry.once(destination, "finish", () => {
+                waitForClose(destination, cleanupWithSignal, registry);
+            });
+        }
+        // Node parity: close before completion is a premature close error.
+        for (const stream of allStreams) {
+            registry.once(stream, "close", () => {
+                if (completed) {
+                    return;
+                }
+                if (!isStreamCompleted(stream)) {
+                    cleanupWithSignal(createPrematureCloseError());
+                }
+            });
+        }
+        // Handle errors on all streams
+        for (const stream of allStreams) {
+            registry.once(stream, "error", (err) => cleanupWithSignal(err));
+        }
+    });
+    // If callback provided, use it
+    if (callback) {
+        promise.then(() => callback()).catch(err => callback(err));
+    }
+    return promise;
+}
+// =============================================================================
+// Finished
+// =============================================================================
+/**
+ * Wait for a stream to finish, close, or error.
+ * Node.js compatible with support for options and callbacks.
+ *
+ * @example
+ * // Promise usage
+ * await finished(stream);
+ *
+ * @example
+ * // With options
+ * await finished(stream, { readable: false }); // Only wait for writable side
+ *
+ * @example
+ * // Callback usage
+ * finished(stream, (err) => {
+ *   if (err) console.error('Stream error', err);
+ * });
+ */
+export function finished(stream, optionsOrCallback, callback) {
+    let options = {};
+    let cb;
+    if (typeof optionsOrCallback === "function") {
+        cb = optionsOrCallback;
+    }
+    else {
+        options = optionsOrCallback ?? {};
+        cb = callback;
+    }
+    const promise = new Promise((resolve, reject) => {
+        const normalizedStream = toBrowserPipelineStream(stream);
+        let resolved = false;
+        const registry = createListenerRegistry();
+        let onAbort;
+        const cleanup = () => {
+            registry.cleanup();
+            if (onAbort && options.signal) {
+                options.signal.removeEventListener("abort", onAbort);
+            }
+        };
+        const done = (err) => {
+            if (resolved) {
+                return;
+            }
+            resolved = true;
+            cleanup();
+            if (err) {
+                reject(err);
+            }
+            else {
+                resolve();
+            }
+        };
+        // Handle abort signal
+        if (options.signal) {
+            if (options.signal.aborted) {
+                done(createAbortError(options.signal.reason));
+                return;
+            }
+            onAbort = () => done(createAbortError(options.signal.reason));
+            options.signal.addEventListener("abort", onAbort);
+        }
+        // Node.js: if the stream is already destroyed, resolve/reject immediately.
+        // An already-destroyed stream with an error rejects; otherwise it's premature close.
+        const s = normalizedStream;
+        if (s.destroyed || s._destroyed) {
+            if (s.errored || s._errored) {
+                done(s.errored ?? s._errored);
+            }
+            else {
+                // Already destroyed without error — check if it finished gracefully.
+                // Respect options.readable / options.writable to match Node.js behavior:
+                // if the caller only cares about one side, only check that side.
+                const supportsReadable = "readableEnded" in s || "readable" in s || typeof s.read === "function";
+                const supportsWritable = "writableFinished" in s || "writable" in s || typeof s.write === "function";
+                const checkReadable = options.readable !== false && supportsReadable;
+                const checkWritable = options.writable !== false && supportsWritable;
+                const readableOk = !checkReadable || !!(s.readableEnded || s._endEmitted);
+                const writableOk = !checkWritable || !!(s.writableFinished || s._finished);
+                if (readableOk && writableOk) {
+                    done();
+                }
+                else {
+                    done(createPrematureCloseError());
+                }
+            }
+            return;
+        }
+        const supportsReadable = "readableEnded" in normalizedStream ||
+            "readable" in normalizedStream ||
+            typeof normalizedStream.read === "function";
+        const supportsWritable = "writableFinished" in normalizedStream ||
+            "writable" in normalizedStream ||
+            typeof normalizedStream.write === "function";
+        const checkReadable = options.readable !== false && supportsReadable;
+        const checkWritable = options.writable !== false && supportsWritable;
+        let readableDone = !checkReadable || !!normalizedStream.readableEnded;
+        let writableDone = !checkWritable || !!normalizedStream.writableFinished;
+        // Node.js finished() waits for the 'close' event before resolving when
+        // the stream will actually emit 'close'.  Node.js computes willEmitClose as:
+        //   state.autoDestroy && state.emitClose && state.closed === false
+        // This means: if autoDestroy is false, close won't fire automatically after
+        // finish, so finished() must NOT wait for it — otherwise it deadlocks.
+        //
+        // Guard: only consult _emitClose / _autoDestroy when the stream actually
+        // exposes them (i.e. our own Readable/Writable/Transform/Duplex instances).
+        // Third-party or duck-typed streams may lack these internals — for those we
+        // default to NOT waiting for 'close', which avoids a deadlock.
+        const s2 = normalizedStream;
+        const hasInternals = "_emitClose" in s2 && "_autoDestroy" in s2;
+        const willEmitClose = hasInternals && s2._emitClose !== false && s2._autoDestroy !== false && !s2._closed;
+        const maybeDone = () => {
+            if (readableDone && writableDone) {
+                if (willEmitClose) {
+                    // Don't resolve yet — wait for 'close' event
+                    return;
+                }
+                done();
+            }
+        };
+        // Already finished?
+        if (readableDone && writableDone) {
+            // If the stream is already closed (or won't emit close), resolve now
+            if (!willEmitClose || normalizedStream.closed) {
+                done();
+                return;
+            }
+            // Otherwise wait for 'close'
+        }
+        // Listen for events
+        if (checkWritable && !writableDone) {
+            registry.once(normalizedStream, "finish", () => {
+                writableDone = true;
+                maybeDone();
+            });
+        }
+        if (checkReadable && !readableDone) {
+            registry.once(normalizedStream, "end", () => {
+                readableDone = true;
+                maybeDone();
+            });
+        }
+        // Node.js: with error:false, don't listen for the 'error' event.
+        // Errors are still detected via stream.errored in the close handler.
+        if (options.error !== false) {
+            registry.once(normalizedStream, "error", (err) => done(err));
+        }
+        registry.once(normalizedStream, "close", () => {
+            const closedReadableDone = readableDone || !!normalizedStream.readableEnded;
+            const closedWritableDone = writableDone || !!normalizedStream.writableFinished;
+            if (closedReadableDone && closedWritableDone) {
+                readableDone = closedReadableDone;
+                writableDone = closedWritableDone;
+                // Even with error:false, check stream.errored — Node.js close handler
+                // still passes errors detected via stream.errored to the callback.
+                const streamErr = normalizedStream.errored ?? normalizedStream._errored;
+                done(streamErr ?? undefined);
+                return;
+            }
+            // Premature close — stream closed before finishing.
+            // Check for stream error first (e.g. destroyed with error).
+            const streamErr = normalizedStream.errored ?? normalizedStream._errored;
+            if (streamErr) {
+                done(streamErr);
+                return;
+            }
+            const err = new Error("Premature close");
+            err.code = "ERR_STREAM_PREMATURE_CLOSE";
+            err.name = "Error [ERR_STREAM_PREMATURE_CLOSE]";
+            done(err);
+        });
+    });
+    // If callback provided, use it
+    if (cb) {
+        promise.then(() => cb()).catch(err => cb(err));
+    }
+    return promise;
+}
+/**
+ * Wait for multiple streams to finish
+ */
+export const finishedAll = createFinishedAll(finished);