@yume-chan/stream-extra 0.0.23 → 1.0.0

package/src/buffered.ts

@@ -1,15 +1,15 @@
+import type { MaybePromiseLike } from "@yume-chan/async";
 import type { AsyncExactReadable } from "@yume-chan/struct";
-import { ExactReadableEndedError } from "@yume-chan/struct";
+import { bipedal, ExactReadableEndedError } from "@yume-chan/struct";
 
 import { PushReadableStream } from "./push-readable.js";
 import type { ReadableStream, ReadableStreamDefaultReader } from "./stream.js";
-
-const NOOP = () => {
-    // no-op
-};
+import { tryCancel } from "./try-close.js";
 
 export class BufferedReadableStream implements AsyncExactReadable {
     #buffered: Uint8Array | undefined;
+    // PERF: `subarray` is slow
+    // don't use it until absolutely necessary
     #bufferedOffset = 0;
     #bufferedLength = 0;
 
@@ -26,99 +26,124 @@ export class BufferedReadableStream implements AsyncExactReadable {
         this.reader = stream.getReader();
     }
 
-    async #readSource() {
+    #readBuffered(length: number) {
+        if (!this.#buffered) {
+            return undefined;
+        }
+
+        const value = this.#buffered.subarray(
+            this.#bufferedOffset,
+            this.#bufferedOffset + length,
+        );
+
+        // PERF: Synchronous path for reading from internal buffer
+        if (this.#bufferedLength > length) {
+            this.#position += length;
+            this.#bufferedOffset += length;
+            this.#bufferedLength -= length;
+            return value;
+        }
+
+        this.#position += this.#bufferedLength;
+        this.#buffered = undefined;
+        this.#bufferedOffset = 0;
+        this.#bufferedLength = 0;
+        return value;
+    }
+
+    async #readSource(length: number): Promise<Uint8Array> {
         const { done, value } = await this.reader.read();
         if (done) {
             throw new ExactReadableEndedError();
         }
+
+        if (value.length > length) {
+            this.#buffered = value;
+            this.#bufferedOffset = length;
+            this.#bufferedLength = value.length - length;
+            this.#position += length;
+            return value.subarray(0, length);
+        }
+
+        this.#position += value.length;
         return value;
     }
 
-    async #readAsync(length: number, initial?: Uint8Array) {
-        let result: Uint8Array;
-        let index: number;
+    iterateExactly(
+        length: number,
+    ): Iterator<MaybePromiseLike<Uint8Array>, void, void> {
+        let state = this.#buffered ? 0 : 1;
+        return {
+            next: () => {
+                switch (state) {
+                    case 0: {
+                        const value = this.#readBuffered(length)!;
+                        if (value.length === length) {
+                            state = 2;
+                        } else {
+                            length -= value.length;
+                            state = 1;
+                        }
+                        return { done: false, value };
+                    }
+                    case 1:
+                        state = 3;
+                        return {
+                            done: false,
+                            value: this.#readSource(length).then((value) => {
+                                if (value.length === length) {
+                                    state = 2;
+                                } else {
+                                    length -= value.length;
+                                    state = 1;
+                                }
+                                return value;
+                            }),
+                        };
+                    case 2:
+                        return { done: true, value: undefined };
+                    case 3:
+                        throw new Error(
+                            "Can't call `next` before previous Promise resolves",
+                        );
+                    default:
+                        throw new Error("unreachable");
+                }
+            },
+        };
+    }
 
+    readExactly = bipedal(function* (
+        this: BufferedReadableStream,
+        then,
+        length: number,
+    ) {
+        let result: Uint8Array | undefined;
+        let index = 0;
+
+        const initial = this.#readBuffered(length);
         if (initial) {
+            if (initial.length === length) {
+                return initial;
+            }
+
             result = new Uint8Array(length);
-            result.set(initial);
-            index = initial.length;
+            result.set(initial, index);
+            index += initial.length;
             length -= initial.length;
         } else {
-            const array = await this.#readSource();
-            if (array.length === length) {
-                this.#position += length;
-                return array;
-            }
-
-            if (array.length > length) {
-                this.#buffered = array;
-                this.#bufferedOffset = length;
-                this.#bufferedLength = array.length - length;
-                this.#position += length;
-                return array.subarray(0, length);
-            }
-
             result = new Uint8Array(length);
-            result.set(array);
-            index = array.length;
-            length -= array.length;
-            this.#position += array.length;
         }
 
         while (length > 0) {
-            const array = await this.#readSource();
-            if (array.length === length) {
-                result.set(array, index);
-                this.#position += length;
-                return result;
-            }
-
-            if (array.length > length) {
-                this.#buffered = array;
-                this.#bufferedOffset = length;
-                this.#bufferedLength = array.length - length;
-                result.set(array.subarray(0, length), index);
-                this.#position += length;
-                return result;
-            }
-
-            result.set(array, index);
-            index += array.length;
-            length -= array.length;
-            this.#position += array.length;
+            const value = yield* then(this.#readSource(length));
+            result.set(value, index);
+            index += value.length;
+            length -= value.length;
         }
 
         return result;
-    }
-
-    /**
-     *
-     * @param length
-     * @returns
-     */
-    readExactly(length: number): Uint8Array | Promise<Uint8Array> {
-        // PERF: Add a synchronous path for reading from internal buffer
-        if (this.#buffered) {
-            const array = this.#buffered;
-            const offset = this.#bufferedOffset;
-            if (this.#bufferedLength > length) {
-                // PERF: `subarray` is slow
-                // don't use it until absolutely necessary
-                this.#bufferedOffset += length;
-                this.#bufferedLength -= length;
-                this.#position += length;
-                return array.subarray(offset, offset + length);
-            }
-
-            this.#buffered = undefined;
-            this.#bufferedLength = 0;
-            this.#bufferedOffset = 0;
-            this.#position += array.length - offset;
-            return this.#readAsync(length, array.subarray(offset));
-        }
-
-        return this.#readAsync(length);
-    }
+    });
 
     /**
      * Return a readable stream with unconsumed data (if any) and
@@ -133,8 +158,7 @@ export class BufferedReadableStream implements AsyncExactReadable {
                 await controller.enqueue(buffered);
 
                 controller.abortSignal.addEventListener("abort", () => {
-                    // NOOP: the reader might already be released
-                    this.reader.cancel().catch(NOOP);
+                    void tryCancel(this.reader);
                 });
 
                 // Manually pipe the stream
@@ -142,9 +166,9 @@ export class BufferedReadableStream implements AsyncExactReadable {
                     const { done, value } = await this.reader.read();
                     if (done) {
                         return;
-                    } else {
-                        await controller.enqueue(value);
                     }
+
+                    await controller.enqueue(value);
                 }
             });
         } else {

package/src/concat.ts

@@ -1,4 +1,5 @@
 import { PromiseResolver } from "@yume-chan/async";
+import { EmptyUint8Array } from "@yume-chan/struct";
 
 import type { ReadableStreamDefaultController } from "./stream.js";
 import { ReadableStream, WritableStream } from "./stream.js";
@@ -81,9 +82,10 @@ export interface ConcatBufferReadableStream
  * A `TransformStream` that concatenates `Uint8Array`s.
  *
  * If you want to decode the result as string,
- * prefer `.pipeThrough(new DecodeUtf8Stream()).pipeThrough(new ConcatStringStream())`,
- * than `.pipeThough(new ConcatBufferStream()).pipeThrough(new DecodeUtf8Stream())`,
- * because concatenating strings is faster than concatenating `Uint8Array`s.
+ * prefer `.pipeThrough(new TextDecoderStream()).pipeThrough(new ConcatStringStream())`,
+ * than `.pipeThough(new ConcatBufferStream()).pipeThrough(new TextDecoderStream())`,
+ * because of JavaScript engine optimizations,
+ * concatenating strings is faster than concatenating `Uint8Array`s.
  */
 export class ConcatBufferStream {
     #segments: Uint8Array[] = [];
@@ -99,7 +101,7 @@ export class ConcatBufferStream {
             let offset = 0;
             switch (this.#segments.length) {
                 case 0:
-                    result = new Uint8Array(0);
+                    result = EmptyUint8Array;
                     break;
                 case 1:
                     result = this.#segments[0]!;

package/src/consumable.ts

@@ -1,125 +1,85 @@
-import { PromiseResolver } from "@yume-chan/async";
+import { PromiseResolver, isPromiseLike } from "@yume-chan/async";
 
 import type {
     QueuingStrategy,
     WritableStreamDefaultController,
     WritableStreamDefaultWriter,
 } from "./stream.js";
-import { ReadableStream, TransformStream, WritableStream } from "./stream.js";
-
-interface Task {
-    run<T>(callback: () => T): T;
-}
-
-interface Console {
-    createTask(name: string): Task;
-}
-
-interface GlobalExtension {
-    console: Console;
-}
-
-// `createTask` allows browser DevTools to track the call stack across async boundaries.
-const { console } = globalThis as unknown as GlobalExtension;
-const createTask: Console["createTask"] =
-    console.createTask?.bind(console) ??
-    (() => ({
-        run(callback) {
-            return callback();
-        },
-    }));
-
-export class Consumable<T> {
-    readonly #task: Task;
-    readonly #resolver: PromiseResolver<void>;
-
-    readonly value: T;
-    readonly consumed: Promise<void>;
-
-    constructor(value: T) {
-        this.#task = createTask("Consumable");
-        this.value = value;
-        this.#resolver = new PromiseResolver<void>();
-        this.consumed = this.#resolver.promise;
-    }
-
-    consume() {
-        this.#resolver.resolve();
-    }
+import {
+    ReadableStream as NativeReadableStream,
+    WritableStream as NativeWritableStream,
+} from "./stream.js";
+import type { Task } from "./task.js";
+import { createTask } from "./task.js";
 
-    error(error: unknown) {
-        this.#resolver.reject(error);
+// Workaround https://github.com/evanw/esbuild/issues/3923
+class WritableStream<in T> extends NativeWritableStream<Consumable<T>> {
+    static async write<T>(
+        writer: WritableStreamDefaultWriter<Consumable<T>>,
+        value: T,
+    ) {
+        const consumable = new Consumable(value);
+        await writer.write(consumable);
+        await consumable.consumed;
     }
 
-    async tryConsume<U>(callback: (value: T) => U) {
-        try {
-            // eslint-disable-next-line @typescript-eslint/await-thenable
-            const result = await this.#task.run(() => callback(this.value));
-            this.#resolver.resolve();
-            return result;
-        } catch (e) {
-            this.#resolver.reject(e);
-            throw e;
+    constructor(
+        sink: Consumable.WritableStreamSink<T>,
+        strategy?: QueuingStrategy<T>,
+    ) {
+        let wrappedStrategy: QueuingStrategy<Consumable<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,
+                    );
+                };
+            }
         }
-    }
-}
-
-async function enqueue<T>(
-    controller: { enqueue: (chunk: Consumable<T>) => void },
-    chunk: T,
-) {
-    const output = new Consumable(chunk);
-    controller.enqueue(output);
-    await output.consumed;
-}
 
-export class WrapConsumableStream<T> extends TransformStream<T, Consumable<T>> {
-    constructor() {
-        super({
-            async transform(chunk, controller) {
-                await enqueue(controller, chunk);
+        super(
+            {
+                start(controller) {
+                    return sink.start?.(controller);
+                },
+                async write(chunk, controller) {
+                    await chunk.tryConsume((chunk) =>
+                        sink.write?.(chunk, controller),
+                    );
+                },
+                abort(reason) {
+                    return sink.abort?.(reason);
+                },
+                close() {
+                    return sink.close?.();
+                },
             },
-        });
+            wrappedStrategy,
+        );
     }
 }
 
-export class UnwrapConsumableStream<T> extends TransformStream<
-    Consumable<T>,
-    T
-> {
-    constructor() {
-        super({
-            transform(chunk, controller) {
-                controller.enqueue(chunk.value);
-                chunk.consume();
-            },
-        });
+class ReadableStream<T> extends NativeReadableStream<Consumable<T>> {
+    static async enqueue<T>(
+        controller: { enqueue: (chunk: Consumable<T>) => void },
+        chunk: T,
+    ) {
+        const output = new Consumable(chunk);
+        controller.enqueue(output);
+        await output.consumed;
     }
-}
 
-export interface ConsumableReadableStreamController<T> {
-    enqueue(chunk: T): Promise<void>;
-    close(): void;
-    error(reason: any): void;
-}
-
-export interface ConsumableReadableStreamSource<T> {
-    start?(
-        controller: ConsumableReadableStreamController<T>,
-    ): void | PromiseLike<void>;
-    pull?(
-        controller: ConsumableReadableStreamController<T>,
-    ): void | PromiseLike<void>;
-    cancel?(reason: any): void | PromiseLike<void>;
-}
-
-export class ConsumableReadableStream<T> extends ReadableStream<Consumable<T>> {
     constructor(
-        source: ConsumableReadableStreamSource<T>,
+        source: Consumable.ReadableStreamSource<T>,
         strategy?: QueuingStrategy<T>,
     ) {
         let wrappedController:
-            | ConsumableReadableStreamController<T>
+            | Consumable.ReadableStreamController<T>
             | undefined;
 
         let wrappedStrategy: QueuingStrategy<Consumable<T>> | undefined;
@@ -140,7 +100,7 @@ export class ConsumableReadableStream<T> extends ReadableStream<Consumable<T>> {
                 async start(controller) {
                     wrappedController = {
                         async enqueue(chunk) {
-                            await enqueue(controller, chunk);
+                            await ReadableStream.enqueue(controller, chunk);
                         },
                         close() {
                             controller.close();
@@ -164,128 +124,87 @@ export class ConsumableReadableStream<T> extends ReadableStream<Consumable<T>> {
     }
 }
 
-export interface ConsumableWritableStreamSink<T> {
-    start?(
-        controller: WritableStreamDefaultController,
-    ): void | PromiseLike<void>;
-    write?(
-        chunk: T,
-        controller: WritableStreamDefaultController,
-    ): void | PromiseLike<void>;
-    abort?(reason: any): void | PromiseLike<void>;
-    close?(): void | PromiseLike<void>;
-}
+export class Consumable<T> {
+    static readonly WritableStream = WritableStream;
 
-export class ConsumableWritableStream<T> extends WritableStream<Consumable<T>> {
-    static async write<T>(
-        writer: WritableStreamDefaultWriter<Consumable<T>>,
-        value: T,
-    ) {
-        const consumable = new Consumable(value);
-        await writer.write(consumable);
-        await consumable.consumed;
-    }
+    static readonly ReadableStream = ReadableStream;
 
-    constructor(
-        sink: ConsumableWritableStreamSink<T>,
-        strategy?: QueuingStrategy<T>,
-    ) {
-        let wrappedStrategy: QueuingStrategy<Consumable<T>> | undefined;
-        if (strategy) {
-            wrappedStrategy = {};
-            if ("highWaterMark" in strategy) {
-                wrappedStrategy.highWaterMark = strategy.highWaterMark;
-            }
-            if ("size" in strategy) {
-                wrappedStrategy.size = (chunk) => {
-                    return strategy.size!(chunk.value);
-                };
-            }
-        }
+    readonly #task: Task;
+    readonly #resolver: PromiseResolver<void>;
 
-        super(
-            {
-                start(controller) {
-                    return sink.start?.(controller);
-                },
-                async write(chunk, controller) {
-                    await chunk.tryConsume((value) =>
-                        sink.write?.(value, controller),
-                    );
-                },
-                abort(reason) {
-                    return sink.abort?.(reason);
-                },
-                close() {
-                    return sink.close?.();
-                },
-            },
-            wrappedStrategy,
-        );
+    readonly value: T;
+    readonly consumed: Promise<void>;
+
+    constructor(value: T) {
+        this.#task = createTask("Consumable");
+        this.value = value;
+        this.#resolver = new PromiseResolver<void>();
+        this.consumed = this.#resolver.promise;
     }
-}
 
-export interface ConsumableTransformer<I, O> {
-    start?(
-        controller: ConsumableReadableStreamController<O>,
-    ): void | PromiseLike<void>;
-    transform?(
-        chunk: I,
-        controller: ConsumableReadableStreamController<O>,
-    ): void | PromiseLike<void>;
-    flush?(
-        controller: ConsumableReadableStreamController<O>,
-    ): void | PromiseLike<void>;
-}
+    consume() {
+        this.#resolver.resolve();
+    }
 
-export class ConsumableTransformStream<I, O> extends TransformStream<
-    Consumable<I>,
-    Consumable<O>
-> {
-    constructor(transformer: ConsumableTransformer<I, O>) {
-        let wrappedController:
-            | ConsumableReadableStreamController<O>
-            | undefined;
+    error(error: unknown) {
+        this.#resolver.reject(error);
+    }
 
-        super({
-            async start(controller) {
-                wrappedController = {
-                    async enqueue(chunk) {
-                        await enqueue(controller, chunk);
-                    },
-                    close() {
-                        controller.terminate();
+    tryConsume<U>(callback: (value: T) => U) {
+        try {
+            let result = this.#task.run(() => callback(this.value));
+            if (isPromiseLike(result)) {
+                result = result.then(
+                    (value) => {
+                        this.#resolver.resolve();
+                        return value;
                     },
-                    error(reason) {
-                        controller.error(reason);
+                    (e) => {
+                        this.#resolver.reject(e);
+                        throw e;
                     },
-                };
-
-                await transformer.start?.(wrappedController);
-            },
-            async transform(chunk) {
-                await chunk.tryConsume((value) =>
-                    transformer.transform?.(value, wrappedController!),
-                );
-                chunk.consume();
-            },
-            async flush() {
-                await transformer.flush?.(wrappedController!);
-            },
-        });
+                ) as U;
+            } else {
+                this.#resolver.resolve();
+            }
+            return result;
+        } catch (e) {
+            this.#resolver.reject(e);
+            throw e;
+        }
     }
 }
 
-export class ConsumableInspectStream<T> extends TransformStream<
-    Consumable<T>,
-    Consumable<T>
-> {
-    constructor(callback: (value: T) => void) {
-        super({
-            transform(chunk, controller) {
-                callback(chunk.value);
-                controller.enqueue(chunk);
-            },
-        });
+export namespace Consumable {
+    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 type WritableStream<in T> = typeof Consumable.WritableStream<T>;
+
+    export interface ReadableStreamController<T> {
+        enqueue(chunk: T): Promise<void>;
+        close(): void;
+        error(reason: unknown): void;
     }
+
+    export interface ReadableStreamSource<T> {
+        start?(
+            controller: ReadableStreamController<T>,
+        ): void | PromiseLike<void>;
+        pull?(
+            controller: ReadableStreamController<T>,
+        ): void | PromiseLike<void>;
+        cancel?(reason: unknown): void | PromiseLike<void>;
+    }
+
+    export type ReadableStream<T> = typeof Consumable.ReadableStream<T>;
 }