@yume-chan/stream-extra 0.0.23 → 1.0.0

package/src/distribution.ts

@@ -1,4 +1,6 @@
-import { ConsumableTransformStream } from "./consumable.js";
+import { Consumable } from "./consumable.js";
+import { MaybeConsumable } from "./maybe-consumable.js";
+import { TransformStream } from "./stream.js";
 
 /**
  * Splits or combines buffers to specified size.
@@ -25,7 +27,7 @@ export class BufferCombiner {
      */
     *push(data: Uint8Array): Generator<Uint8Array, void, void> {
         let offset = 0;
-        let available = data.byteLength;
+        let available = data.length;
 
         if (this.#offset !== 0) {
             if (available >= this.#available) {
@@ -77,34 +79,42 @@ export class BufferCombiner {
     }
 }
 
-export class DistributionStream extends ConsumableTransformStream<
-    Uint8Array,
-    Uint8Array
+export class DistributionStream extends TransformStream<
+    MaybeConsumable<Uint8Array>,
+    MaybeConsumable<Uint8Array>
 > {
     constructor(size: number, combine = false) {
         const combiner = combine ? new BufferCombiner(size) : undefined;
         super({
             async transform(chunk, controller) {
-                if (combiner) {
-                    for (const buffer of combiner.push(chunk)) {
-                        await controller.enqueue(buffer);
-                    }
-                } else {
-                    let offset = 0;
-                    let available = chunk.byteLength;
-                    while (available > 0) {
-                        const end = offset + size;
-                        await controller.enqueue(chunk.subarray(offset, end));
-                        offset = end;
-                        available -= size;
+                await MaybeConsumable.tryConsume(chunk, async (chunk) => {
+                    if (combiner) {
+                        for (const buffer of combiner.push(chunk)) {
+                            await Consumable.ReadableStream.enqueue(
+                                controller,
+                                buffer,
+                            );
+                        }
+                    } else {
+                        let offset = 0;
+                        let available = chunk.length;
+                        while (available > 0) {
+                            const end = offset + size;
+                            await Consumable.ReadableStream.enqueue(
+                                controller,
+                                chunk.subarray(offset, end),
+                            );
+                            offset = end;
+                            available -= size;
+                        }
                     }
-                }
+                });
             },
-            async flush(controller) {
+            flush(controller) {
                 if (combiner) {
                     const data = combiner.flush();
                     if (data) {
-                        await controller.enqueue(data);
+                        controller.enqueue(data);
                     }
                 }
             },

package/src/duplex.ts

@@ -1,5 +1,5 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
 import { PromiseResolver } from "@yume-chan/async";
-import type { ValueOrPromise } from "@yume-chan/struct";
 
 import type {
     QueuingStrategy,
@@ -8,6 +8,7 @@ import type {
     WritableStreamDefaultWriter,
 } from "./stream.js";
 import { WritableStream } from "./stream.js";
+import { tryClose } from "./try-close.js";
 import { WrapReadableStream } from "./wrap-readable.js";
 
 const NOOP = () => {
@@ -27,7 +28,7 @@ export interface DuplexStreamFactoryOptions {
      * `DuplexStreamFactory#dispose` yourself, you can return `false`
      * (or a `Promise` that resolves to `false`) to disable the automatic call.
      */
-    close?: (() => ValueOrPromise<boolean | void>) | undefined;
+    close?: (() => MaybePromiseLike<boolean | void>) | undefined;
 
     /**
      * Callback when any `ReadableStream` is closed (the other peer doesn't produce any more data),
@@ -134,11 +135,7 @@ export class DuplexStreamFactory<R, W> {
         this.#closed.resolve();
 
         for (const controller of this.#readableControllers) {
-            try {
-                controller.close();
-            } catch {
-                // ignore
-            }
+            tryClose(controller);
         }
 
         await this.#options.dispose?.();

package/src/encoding.ts

@@ -0,0 +1,39 @@
+import type { TransformStream } from "./stream.js";
+
+export interface TextDecoderOptions {
+    fatal?: boolean;
+    ignoreBOM?: boolean;
+}
+
+declare class TextDecoderStreamType extends TransformStream<
+    ArrayBufferView | ArrayBuffer,
+    string
+> {
+    constructor(label?: string, options?: TextDecoderOptions);
+
+    readonly encoding: string;
+    readonly fatal: boolean;
+    readonly ignoreBOM: boolean;
+}
+
+declare class TextEncoderStreamType extends TransformStream<
+    string,
+    Uint8Array
+> {
+    constructor();
+
+    readonly encoding: string;
+}
+
+interface GlobalExtension {
+    TextDecoderStream: typeof TextDecoderStreamType;
+    TextEncoderStream: typeof TextEncoderStreamType;
+}
+
+const Global = globalThis as unknown as GlobalExtension;
+
+export const TextDecoderStream = Global.TextDecoderStream;
+export type TextDecoderStream = TextDecoderStreamType;
+
+export const TextEncoderStream = Global.TextEncoderStream;
+export type TextEncoderStream = TextEncoderStreamType;

package/src/index.ts

@@ -2,15 +2,18 @@ export * from "./buffered-transform.js";
 export * from "./buffered.js";
 export * from "./concat.js";
 export * from "./consumable.js";
-export * from "./decode-utf8.js";
 export * from "./distribution.js";
 export * from "./duplex.js";
+export * from "./encoding.js";
 export * from "./inspect.js";
+export * from "./maybe-consumable.js";
 export * from "./pipe-from.js";
 export * from "./push-readable.js";
 export * from "./split-string.js";
 export * from "./stream.js";
 export * from "./struct-deserialize.js";
 export * from "./struct-serialize.js";
+export * from "./task.js";
+export * from "./try-close.js";
 export * from "./wrap-readable.js";
 export * from "./wrap-writable.js";

package/src/maybe-consumable-ns.ts

@@ -0,0 +1,75 @@
+import { Consumable } from "./consumable.js";
+import type { MaybeConsumable } from "./maybe-consumable.js";
+import type {
+    QueuingStrategy,
+    WritableStreamDefaultController,
+} from "./stream.js";
+import { WritableStream as NativeWritableStream } from "./stream.js";
+
+export function getValue<T>(value: MaybeConsumable<T>): T {
+    return value instanceof Consumable ? value.value : value;
+}
+
+export function tryConsume<T, R>(
+    value: T,
+    callback: (value: T extends Consumable<infer U> ? U : T) => R,
+): R {
+    if (value instanceof Consumable) {
+        return value.tryConsume(callback);
+    } else {
+        return callback(value as never);
+    }
+}
+
+export interface WritableStreamSink<in T> {
+    start?(
+        controller: WritableStreamDefaultController,
+    ): void | PromiseLike<void>;
+    write?(
+        chunk: T,
+        controller: WritableStreamDefaultController,
+    ): void | PromiseLike<void>;
+    abort?(reason: unknown): void | PromiseLike<void>;
+    close?(): void | PromiseLike<void>;
+}
+
+export class WritableStream<in T> extends NativeWritableStream<
+    MaybeConsumable<T>
+> {
+    constructor(sink: WritableStreamSink<T>, strategy?: QueuingStrategy<T>) {
+        let wrappedStrategy: QueuingStrategy<MaybeConsumable<T>> | undefined;
+        if (strategy) {
+            wrappedStrategy = {};
+            if ("highWaterMark" in strategy) {
+                wrappedStrategy.highWaterMark = strategy.highWaterMark;
+            }
+            if ("size" in strategy) {
+                wrappedStrategy.size = (chunk) => {
+                    return strategy.size!(
+                        chunk instanceof Consumable ? chunk.value : chunk,
+                    );
+                };
+            }
+        }
+
+        super(
+            {
+                start(controller) {
+                    return sink.start?.(controller);
+                },
+                async write(chunk, controller) {
+                    await tryConsume(chunk, (chunk) =>
+                        sink.write?.(chunk as T, controller),
+                    );
+                },
+                abort(reason) {
+                    return sink.abort?.(reason);
+                },
+                close() {
+                    return sink.close?.();
+                },
+            },
+            wrappedStrategy,
+        );
+    }
+}

package/src/maybe-consumable.ts

@@ -0,0 +1,5 @@
+import type { Consumable } from "./consumable.js";
+
+export type MaybeConsumable<T> = T | Consumable<T>;
+
+export * as MaybeConsumable from "./maybe-consumable-ns.js";

package/src/push-readable.ts

@@ -17,9 +17,28 @@ export type PushReadableStreamSource<T> = (
     controller: PushReadableStreamController<T>,
 ) => void | Promise<void>;
 
-export class PushReadableStream<T> extends ReadableStream<T> {
-    #zeroHighWaterMarkAllowEnqueue = false;
+export type PushReadableLogger<T> = (
+    event:
+        | {
+              source: "producer";
+              operation: "enqueue";
+              value: T;
+              phase: "start" | "waiting" | "ignored" | "complete";
+          }
+        | {
+              source: "producer";
+              operation: "close" | "error";
+              explicit: boolean;
+              phase: "start" | "ignored" | "complete";
+          }
+        | {
+              source: "consumer";
+              operation: "pull" | "cancel";
+              phase: "start" | "complete";
+          },
+) => void;
 
+export class PushReadableStream<T> extends ReadableStream<T> {
     /**
      * Create a new `PushReadableStream` from a source.
      *
@@ -30,81 +49,256 @@ export class PushReadableStream<T> extends ReadableStream<T> {
     constructor(
         source: PushReadableStreamSource<T>,
         strategy?: QueuingStrategy<T>,
+        logger?: PushReadableLogger<T>,
     ) {
         let waterMarkLow: PromiseResolver<void> | undefined;
+        let zeroHighWaterMarkAllowEnqueue = false;
         const abortController = new AbortController();
 
         super(
             {
-                start: async (controller) => {
-                    await Promise.resolve();
-
+                start: (controller) => {
                     const result = source({
                         abortSignal: abortController.signal,
                         enqueue: async (chunk) => {
+                            logger?.({
+                                source: "producer",
+                                operation: "enqueue",
+                                value: chunk,
+                                phase: "start",
+                            });
+
                             if (abortController.signal.aborted) {
-                                // If the stream is already cancelled,
-                                // throw immediately.
-                                throw abortController.signal.reason;
+                                // In original `ReadableStream`, calling `enqueue` or `close`
+                                // on an cancelled stream will throw an error,
+                                //
+                                // But in `PushReadableStream`, `enqueue` is an async function,
+                                // the producer can't just check `abortSignal.aborted`
+                                // before calling `enqueue`, as it might change when waiting
+                                // for the backpressure to be reduced.
+                                //
+                                // So IMO it's better to handle this for the producer
+                                // by simply ignoring the `enqueue` call.
+                                //
+                                // Note that we check `abortSignal.aborted` instead of `stopped`,
+                                // as it's not allowed for the producer to call `enqueue` after
+                                // they called `close` or `error`.
+                                //
+                                // Obviously, the producer should listen to the `abortSignal` and
+                                // stop producing, but most pushing data sources don't support that.
+                                logger?.({
+                                    source: "producer",
+                                    operation: "enqueue",
+                                    value: chunk,
+                                    phase: "ignored",
+                                });
+                                return;
                             }
 
                             if (controller.desiredSize === null) {
                                 // `desiredSize` being `null` means the stream is in error state,
                                 // `controller.enqueue` will throw an error for us.
                                 controller.enqueue(chunk);
+                                // istanbul ignore next
                                 return;
                             }
 
-                            if (this.#zeroHighWaterMarkAllowEnqueue) {
-                                this.#zeroHighWaterMarkAllowEnqueue = false;
+                            if (zeroHighWaterMarkAllowEnqueue) {
+                                // When `highWaterMark` is set to `0`,
+                                // `controller.desiredSize` will always be `0`,
+                                // even if the consumer has called `reader.read()`.
+                                // (in this case, each `reader.read()`/`pull`
+                                // should allow one `enqueue` of any size)
+                                //
+                                // If the consumer has already called `reader.read()`,
+                                // before the producer tries to `enqueue`,
+                                // `controller.desiredSize` is `0` and normal `waterMarkLow` signal
+                                // will never trigger,
+                                // (because `ReadableStream` prevents reentrance of `pull`)
+                                // The stream will stuck.
+                                //
+                                // So we need a special signal for this case.
+                                zeroHighWaterMarkAllowEnqueue = false;
                                 controller.enqueue(chunk);
+                                logger?.({
+                                    source: "producer",
+                                    operation: "enqueue",
+                                    value: chunk,
+                                    phase: "complete",
+                                });
                                 return;
                             }
 
                             if (controller.desiredSize <= 0) {
+                                logger?.({
+                                    source: "producer",
+                                    operation: "enqueue",
+                                    value: chunk,
+                                    phase: "waiting",
+                                });
+
                                 waterMarkLow = new PromiseResolver<void>();
                                 await waterMarkLow.promise;
+
+                                // Recheck consumer cancellation after async operations.
+                                if (abortController.signal.aborted) {
+                                    logger?.({
+                                        source: "producer",
+                                        operation: "enqueue",
+                                        value: chunk,
+                                        phase: "ignored",
+                                    });
+                                    return;
+                                }
                             }
 
-                            // `controller.enqueue` will throw error for us
-                            // if the stream is already errored.
                             controller.enqueue(chunk);
+                            logger?.({
+                                source: "producer",
+                                operation: "enqueue",
+                                value: chunk,
+                                phase: "complete",
+                            });
                         },
                         close() {
+                            logger?.({
+                                source: "producer",
+                                operation: "close",
+                                explicit: true,
+                                phase: "start",
+                            });
+
+                            // Since `enqueue` on an cancelled stream won't throw an error,
+                            // so does `close`.
+                            if (abortController.signal.aborted) {
+                                logger?.({
+                                    source: "producer",
+                                    operation: "close",
+                                    explicit: true,
+                                    phase: "ignored",
+                                });
+                                return;
+                            }
+
                             controller.close();
+                            logger?.({
+                                source: "producer",
+                                operation: "close",
+                                explicit: true,
+                                phase: "complete",
+                            });
                         },
                         error(e) {
+                            logger?.({
+                                source: "producer",
+                                operation: "error",
+                                explicit: true,
+                                phase: "start",
+                            });
+
+                            // Calling `error` on an already closed or errored stream is a no-op.
                             controller.error(e);
+
+                            logger?.({
+                                source: "producer",
+                                operation: "error",
+                                explicit: true,
+                                phase: "complete",
+                            });
                         },
                     });
 
                     if (result && "then" in result) {
+                        // If `source` returns a `Promise`,
+                        // close the stream when the `Promise` is resolved,
+                        // and error the stream when the `Promise` is rejected.
+                        // The producer can return a never-settling `Promise`
+                        // to disable this behavior.
                         result.then(
                             () => {
+                                logger?.({
+                                    source: "producer",
+                                    operation: "close",
+                                    explicit: false,
+                                    phase: "start",
+                                });
+
                                 try {
                                     controller.close();
-                                } catch (e) {
-                                    // controller already closed
+
+                                    logger?.({
+                                        source: "producer",
+                                        operation: "close",
+                                        explicit: false,
+                                        phase: "complete",
+                                    });
+                                } catch {
+                                    logger?.({
+                                        source: "producer",
+                                        operation: "close",
+                                        explicit: false,
+                                        phase: "ignored",
+                                    });
+
+                                    // The stream is already closed by the producer,
+                                    // Or cancelled by the consumer.
                                 }
                             },
                             (e) => {
+                                logger?.({
+                                    source: "producer",
+                                    operation: "error",
+                                    explicit: false,
+                                    phase: "start",
+                                });
+
                                 controller.error(e);
+
+                                logger?.({
+                                    source: "producer",
+                                    operation: "error",
+                                    explicit: false,
+                                    phase: "complete",
+                                });
                             },
                         );
                     }
                 },
                 pull: () => {
+                    logger?.({
+                        source: "consumer",
+                        operation: "pull",
+                        phase: "start",
+                    });
+
                     if (waterMarkLow) {
                         waterMarkLow.resolve();
-                        return;
-                    }
-                    if (strategy?.highWaterMark === 0) {
-                        this.#zeroHighWaterMarkAllowEnqueue = true;
+                    } else if (strategy?.highWaterMark === 0) {
+                        zeroHighWaterMarkAllowEnqueue = true;
                     }
+
+                    logger?.({
+                        source: "consumer",
+                        operation: "pull",
+                        phase: "complete",
+                    });
                 },
                 cancel: (reason) => {
+                    logger?.({
+                        source: "consumer",
+                        operation: "cancel",
+                        phase: "start",
+                    });
+
                     abortController.abort(reason);
-                    waterMarkLow?.reject(reason);
+                    // Resolve it on cancellation. `pull` will check `abortSignal.aborted` again.
+                    waterMarkLow?.resolve();
+
+                    logger?.({
+                        source: "consumer",
+                        operation: "cancel",
+                        phase: "complete",
+                    });
                 },
             },
             strategy,

package/src/stream.ts

@@ -1,11 +1,13 @@
 import type {
     AbortSignal,
+    ReadableStreamIteratorOptions,
     ReadableStream as ReadableStreamType,
     TransformStream as TransformStreamType,
     WritableStream as WritableStreamType,
 } from "./types.js";
 
 export * from "./types.js";
+export { ReadableStream };
 
 /** A controller object that allows you to abort one or more DOM requests as and when desired. */
 export interface AbortController {
@@ -17,7 +19,7 @@ export interface AbortController {
     /**
      * Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted.
      */
-    abort(reason?: any): void;
+    abort(reason?: unknown): void;
 }
 
 interface AbortControllerConstructor {
@@ -32,15 +34,73 @@ interface GlobalExtension {
     TransformStream: typeof TransformStreamType;
 }
 
-const Global = globalThis as unknown as GlobalExtension;
+export const { AbortController } = globalThis as unknown as GlobalExtension;
 
-export const AbortController = Global.AbortController;
+export type ReadableStream<T> = ReadableStreamType<T>;
+export type WritableStream<T> = WritableStreamType<T>;
+export type TransformStream<I, O> = TransformStreamType<I, O>;
 
-export type ReadableStream<T = any> = ReadableStreamType<T>;
-export const ReadableStream = Global.ReadableStream;
+const ReadableStream = /* #__PURE__ */ (() => {
+    const { ReadableStream } = globalThis as unknown as GlobalExtension;
 
-export type WritableStream<T = any> = WritableStreamType<T>;
-export const WritableStream = Global.WritableStream;
+    if (!ReadableStream.from) {
+        ReadableStream.from = function (iterable) {
+            const iterator =
+                Symbol.asyncIterator in iterable
+                    ? iterable[Symbol.asyncIterator]()
+                    : iterable[Symbol.iterator]();
 
-export type TransformStream<I = any, O = any> = TransformStreamType<I, O>;
-export const TransformStream = Global.TransformStream;
+            return new ReadableStream({
+                async pull(controller) {
+                    const result = await iterator.next();
+                    if (result.done) {
+                        controller.close();
+                        return;
+                    }
+                    controller.enqueue(result.value);
+                },
+                async cancel(reason) {
+                    await iterator.return?.(reason);
+                },
+            });
+        };
+    }
+
+    if (
+        !ReadableStream.prototype[Symbol.asyncIterator] ||
+        !ReadableStream.prototype.values
+    ) {
+        ReadableStream.prototype.values = async function* <R>(
+            this: ReadableStream<R>,
+            options?: ReadableStreamIteratorOptions,
+        ) {
+            const reader = this.getReader();
+            try {
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done) {
+                        return;
+                    }
+                    yield value;
+                }
+            } finally {
+                // Calling `iterator.return` will enter this `finally` block.
+                // We don't need to care about the parameter to `iterator.return`,
+                // it will be returned as the final `result.value` automatically.
+                if (!options?.preventCancel) {
+                    await reader.cancel();
+                }
+                reader.releaseLock();
+            }
+        };
+
+        ReadableStream.prototype[Symbol.asyncIterator] =
+            // eslint-disable-next-line @typescript-eslint/unbound-method
+            ReadableStream.prototype.values;
+    }
+
+    return ReadableStream;
+})();
+
+export const { WritableStream, TransformStream } =
+    globalThis as unknown as GlobalExtension;