@yume-chan/stream-extra 0.0.24 → 1.0.0

package/src/maybe-consumable.ts

@@ -1,101 +1,5 @@
-import { Consumable } from "./consumable.js";
-import type {
-    QueuingStrategy,
-    WritableStreamDefaultController,
-} from "./stream.js";
-import {
-    WritableStream as NativeWritableStream,
-    TransformStream,
-} from "./stream.js";
+import type { Consumable } from "./consumable.js";
 
 export type MaybeConsumable<T> = T | Consumable<T>;
 
-export namespace MaybeConsumable {
-    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 class UnwrapStream<T> extends TransformStream<
-        MaybeConsumable<T>,
-        T
-    > {
-        constructor() {
-            super({
-                transform(chunk, controller) {
-                    MaybeConsumable.tryConsume(chunk, (chunk) => {
-                        controller.enqueue(chunk as T);
-                    });
-                },
-            });
-        }
-    }
-
-    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 MaybeConsumable.tryConsume(chunk, (chunk) =>
-                            sink.write?.(chunk as T, controller),
-                        );
-                    },
-                    abort(reason) {
-                        return sink.abort?.(reason);
-                    },
-                    close() {
-                        return sink.close?.();
-                    },
-                },
-                wrappedStrategy,
-            );
-        }
-    }
-}
+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 {
@@ -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<out T> = ReadableStreamType<T>;
-export const ReadableStream = Global.ReadableStream;
+const ReadableStream = /* #__PURE__ */ (() => {
+    const { ReadableStream } = globalThis as unknown as GlobalExtension;
 
-export type WritableStream<in T> = 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, O> = 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;

package/src/struct-deserialize.ts

@@ -1,12 +1,9 @@
-import type Struct from "@yume-chan/struct";
-import type { StructValueType } from "@yume-chan/struct";
+import type { StructLike } from "@yume-chan/struct";
 
 import { BufferedTransformStream } from "./buffered-transform.js";
 
-export class StructDeserializeStream<
-    T extends Struct<object, PropertyKey, object, unknown>,
-> extends BufferedTransformStream<StructValueType<T>> {
-    constructor(struct: T) {
+export class StructDeserializeStream<T> extends BufferedTransformStream<T> {
+    constructor(struct: StructLike<T>) {
         super((stream) => {
             return struct.deserialize(stream) as never;
         });

package/src/struct-serialize.ts

@@ -1,10 +1,10 @@
-import type Struct from "@yume-chan/struct";
+import type { StructInit, StructLike } from "@yume-chan/struct";
 
 import { TransformStream } from "./stream.js";
 
 export class StructSerializeStream<
-    T extends Struct<object, PropertyKey, object, unknown>,
-> extends TransformStream<T["TInit"], Uint8Array> {
+    T extends StructLike<unknown>,
+> extends TransformStream<StructInit<T>, Uint8Array> {
     constructor(struct: T) {
         super({
             transform(chunk, controller) {

package/src/task.ts

@@ -12,10 +12,10 @@ interface GlobalExtension {
 
 // `createTask` allows browser DevTools to track the call stack across async boundaries.
 const { console } = globalThis as unknown as GlobalExtension;
-export const createTask: (name: string) => Task =
+export const createTask: (name: string) => Task = /* #__PURE__ */ (() =>
     console?.createTask?.bind(console) ??
     (() => ({
         run(callback) {
             return callback();
         },
-    }));
+    })))();

package/src/try-close.ts

@@ -0,0 +1,44 @@
+import type { BufferedReadableStream } from "./buffered.js";
+import type { PushReadableStreamController } from "./push-readable.js";
+import type {
+    ReadableStream,
+    ReadableStreamDefaultController,
+    ReadableStreamDefaultReader,
+    WritableStreamDefaultWriter,
+} from "./stream.js";
+
+export function tryClose(
+    controller: PushReadableStreamController<unknown>,
+): boolean;
+export function tryClose(
+    controller: ReadableStreamDefaultController<unknown>,
+): boolean;
+export function tryClose(writer: WritableStreamDefaultWriter<never>): boolean;
+export function tryClose(controller: { close(): void }) {
+    try {
+        controller.close();
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+export async function tryCancel(
+    stream: ReadableStream<unknown>,
+): Promise<boolean>;
+export async function tryCancel(
+    stream: BufferedReadableStream,
+): Promise<boolean>;
+export async function tryCancel(
+    reader: ReadableStreamDefaultReader<unknown>,
+): Promise<boolean>;
+export async function tryCancel(stream: {
+    cancel(): Promise<void>;
+}): Promise<boolean> {
+    try {
+        await stream.cancel();
+        return true;
+    } catch {
+        return false;
+    }
+}

package/src/types.ts

@@ -242,7 +242,7 @@ export declare class ReadableStream<out R> implements AsyncIterable<R> {
      * such as an array, an async generator, or a Node.js readable stream.
      */
     static from<R>(
-        asyncIterable: Iterable<R> | AsyncIterable<R> | ReadableStreamLike<R>,
+        asyncIterable: Iterable<R> | AsyncIterable<R>,
     ): ReadableStream<R>;
 }
 
@@ -253,7 +253,7 @@ export declare class ReadableStream<out R> implements AsyncIterable<R> {
  */
 export declare interface ReadableStreamAsyncIterator<R>
     extends AsyncIterableIterator<R> {
-    next(): Promise<IteratorResult<R, undefined>>;
+    next(): Promise<IteratorResult<R, void>>;
     return(value?: R): Promise<IteratorResult<R>>;
 }
 

package/src/wrap-readable.ts

@@ -1,4 +1,4 @@
-import type { ValueOrPromise } from "@yume-chan/struct";
+import type { MaybePromiseLike } from "@yume-chan/async";
 
 import type {
     QueuingStrategy,
@@ -9,12 +9,13 @@ import { ReadableStream } from "./stream.js";
 
 export type WrapReadableStreamStart<T> = (
     controller: ReadableStreamDefaultController<T>,
-) => ValueOrPromise<ReadableStream<T>>;
+) => MaybePromiseLike<ReadableStream<T>>;
 
 export interface ReadableStreamWrapper<T> {
     start: WrapReadableStreamStart<T>;
-    cancel?(reason?: unknown): ValueOrPromise<void>;
-    close?(): ValueOrPromise<void>;
+    cancel?: (reason?: unknown) => MaybePromiseLike<void>;
+    close?: () => MaybePromiseLike<void>;
+    error?: (reason?: unknown) => MaybePromiseLike<void>;
 }
 
 function getWrappedReadableStream<T>(
@@ -57,27 +58,32 @@ export class WrapReadableStream<T> extends ReadableStream<T> {
         super(
             {
                 start: async (controller) => {
-                    // `start` is invoked before `ReadableStream`'s constructor finish,
-                    // so using `this` synchronously causes
-                    // "Must call super constructor in derived class before accessing 'this' or returning from derived constructor".
-                    // Queue a microtask to avoid this.
-                    await Promise.resolve();
-
-                    this.readable = await getWrappedReadableStream(
+                    const readable = await getWrappedReadableStream(
                         wrapper,
                         controller,
                     );
+                    // `start` is called in `super()`, so can't use `this` synchronously.
+                    // but it's fine after the first `await`
+                    this.readable = readable;
                     this.#reader = this.readable.getReader();
                 },
                 pull: async (controller) => {
-                    const result = await this.#reader.read();
-                    if (result.done) {
+                    const { done, value } = await this.#reader
+                        .read()
+                        .catch((e) => {
+                            if ("error" in wrapper) {
+                                wrapper.error(e);
+                            }
+                            throw e;
+                        });
+
+                    if (done) {
                         controller.close();
                         if ("close" in wrapper) {
                             await wrapper.close?.();
                         }
                     } else {
-                        controller.enqueue(result.value);
+                        controller.enqueue(value);
                     }
                 },
                 cancel: async (reason) => {