@yume-chan/stream-extra 0.0.18 → 0.0.20

package/src/buffered.ts

@@ -1,25 +1,24 @@
+import type { AsyncExactReadable } from "@yume-chan/struct";
+import { ExactReadableEndedError } from "@yume-chan/struct";
+
 import { PushReadableStream } from "./push-readable.js";
-import {
-    type ReadableStream,
-    type ReadableStreamDefaultReader,
-} from "./stream.js";
+import type { ReadableStream, ReadableStreamDefaultReader } from "./stream.js";
 
-export class BufferedReadableStreamEndedError extends Error {
-    public constructor() {
-        super("Stream ended");
+const NOOP = () => {
+    // no-op
+};
 
-        // Fix Error's prototype chain when compiling to ES5
-        Object.setPrototypeOf(this, new.target.prototype);
-    }
-}
+export class BufferedReadableStream implements AsyncExactReadable {
+    #buffered: Uint8Array | undefined;
+    #bufferedOffset = 0;
+    #bufferedLength = 0;
 
-export class BufferedReadableStream {
-    private buffered: Uint8Array | undefined;
-    private bufferedOffset = 0;
-    private bufferedLength = 0;
+    #position = 0;
+    public get position() {
+        return this.#position;
+    }
 
     protected readonly stream: ReadableStream<Uint8Array>;
-
     protected readonly reader: ReadableStreamDefaultReader<Uint8Array>;
 
     public constructor(stream: ReadableStream<Uint8Array>) {
@@ -30,8 +29,9 @@ export class BufferedReadableStream {
     private async readSource() {
         const { done, value } = await this.reader.read();
         if (done) {
-            throw new BufferedReadableStreamEndedError();
+            throw new ExactReadableEndedError();
         }
+        this.#position += value.byteLength;
         return value;
     }
 
@@ -51,9 +51,9 @@ export class BufferedReadableStream {
             }
 
             if (array.byteLength > length) {
-                this.buffered = array;
-                this.bufferedOffset = length;
-                this.bufferedLength = array.byteLength - length;
+                this.#buffered = array;
+                this.#bufferedOffset = length;
+                this.#bufferedLength = array.byteLength - length;
                 return array.subarray(0, length);
             }
 
@@ -71,9 +71,9 @@ export class BufferedReadableStream {
             }
 
             if (array.byteLength > length) {
-                this.buffered = array;
-                this.bufferedOffset = length;
-                this.bufferedLength = array.byteLength - length;
+                this.#buffered = array;
+                this.#bufferedOffset = length;
+                this.#bufferedLength = array.byteLength - length;
                 result.set(array.subarray(0, length), index);
                 return result;
             }
@@ -91,20 +91,22 @@ export class BufferedReadableStream {
      * @param length
      * @returns
      */
-    public read(length: number): Uint8Array | Promise<Uint8Array> {
+    public 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) {
+        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.#bufferedOffset += length;
+                this.#bufferedLength -= length;
                 return array.subarray(offset, offset + length);
             }
 
-            this.buffered = undefined;
+            this.#buffered = undefined;
+            this.#bufferedLength = 0;
+            this.#bufferedOffset = 0;
             return this.readAsync(length, array.subarray(offset));
         }
 
@@ -117,10 +119,16 @@ export class BufferedReadableStream {
      * @returns A `ReadableStream`
      */
     public release(): ReadableStream<Uint8Array> {
-        if (this.buffered) {
+        if (this.#bufferedLength > 0) {
             return new PushReadableStream<Uint8Array>(async (controller) => {
                 // Put the remaining data back to the stream
-                await controller.enqueue(this.buffered!);
+                const buffered = this.#buffered!.subarray(this.#bufferedOffset);
+                await controller.enqueue(buffered);
+
+                controller.abortSignal.addEventListener("abort", () => {
+                    // NOOP: the reader might already be released
+                    this.reader.cancel().catch(NOOP);
+                });
 
                 // Manually pipe the stream
                 while (true) {

package/src/consumable.ts

@@ -0,0 +1,281 @@
+import { PromiseResolver } from "@yume-chan/async";
+
+import type { QueuingStrategy, 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>;
+
+    public readonly value: T;
+    public readonly consumed: Promise<void>;
+
+    public constructor(value: T) {
+        this.#task = createTask("Consumable");
+        this.value = value;
+        this.#resolver = new PromiseResolver<void>();
+        this.consumed = this.#resolver.promise;
+    }
+
+    public consume() {
+        this.#resolver.resolve();
+    }
+
+    public error(error: any) {
+        this.#resolver.reject(error);
+    }
+
+    public 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.consume();
+            return result;
+        } catch (e) {
+            this.#resolver.reject(e);
+            throw e;
+        }
+    }
+}
+
+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>> {
+    public constructor() {
+        super({
+            async transform(chunk, controller) {
+                await enqueue(controller, chunk);
+            },
+        });
+    }
+}
+
+export class UnwrapConsumableStream<T> extends TransformStream<
+    Consumable<T>,
+    T
+> {
+    public constructor() {
+        super({
+            transform(chunk, controller) {
+                controller.enqueue(chunk.value);
+                chunk.consume();
+            },
+        });
+    }
+}
+
+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>> {
+    public constructor(
+        source: ConsumableReadableStreamSource<T>,
+        strategy?: QueuingStrategy<T>
+    ) {
+        let wrappedController:
+            | ConsumableReadableStreamController<T>
+            | undefined;
+
+        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);
+                };
+            }
+        }
+
+        super(
+            {
+                async start(controller) {
+                    wrappedController = {
+                        async enqueue(chunk) {
+                            await enqueue(controller, chunk);
+                        },
+                        close() {
+                            controller.close();
+                        },
+                        error(reason) {
+                            controller.error(reason);
+                        },
+                    };
+
+                    await source.start?.(wrappedController);
+                },
+                async pull() {
+                    await source.pull?.(wrappedController!);
+                },
+                async cancel(reason) {
+                    await source.cancel?.(reason);
+                },
+            },
+            wrappedStrategy
+        );
+    }
+}
+
+export interface ConsumableWritableStreamSink<T> {
+    start?(): void | PromiseLike<void>;
+    write?(chunk: T): void | PromiseLike<void>;
+    abort?(reason: any): void | PromiseLike<void>;
+    close?(): void | PromiseLike<void>;
+}
+
+export class ConsumableWritableStream<T> extends WritableStream<Consumable<T>> {
+    public static async write<T>(
+        writer: WritableStreamDefaultWriter<Consumable<T>>,
+        value: T
+    ) {
+        const consumable = new Consumable(value);
+        await writer.write(consumable);
+        await consumable.consumed;
+    }
+
+    public 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);
+                };
+            }
+        }
+
+        super(
+            {
+                start() {
+                    return sink.start?.();
+                },
+                async write(chunk) {
+                    await chunk.tryConsume((value) => sink.write?.(value));
+                    chunk.consume();
+                },
+                abort(reason) {
+                    return sink.abort?.(reason);
+                },
+                close() {
+                    return sink.close?.();
+                },
+            },
+            wrappedStrategy
+        );
+    }
+}
+
+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>;
+}
+
+export class ConsumableTransformStream<I, O> extends TransformStream<
+    Consumable<I>,
+    Consumable<O>
+> {
+    public constructor(transformer: ConsumableTransformer<I, O>) {
+        let wrappedController:
+            | ConsumableReadableStreamController<O>
+            | undefined;
+
+        super({
+            async start(controller) {
+                wrappedController = {
+                    async enqueue(chunk) {
+                        await enqueue(controller, chunk);
+                    },
+                    close() {
+                        controller.terminate();
+                    },
+                    error(reason) {
+                        controller.error(reason);
+                    },
+                };
+
+                await transformer.start?.(wrappedController);
+            },
+            async transform(chunk) {
+                await chunk.tryConsume((value) =>
+                    transformer.transform?.(value, wrappedController!)
+                );
+                chunk.consume();
+            },
+            async flush() {
+                await transformer.flush?.(wrappedController!);
+            },
+        });
+    }
+}
+
+export class ConsumableInspectStream<T> extends TransformStream<
+    Consumable<T>,
+    Consumable<T>
+> {
+    public constructor(callback: (value: T) => void) {
+        super({
+            transform(chunk, controller) {
+                callback(chunk.value);
+                controller.enqueue(chunk);
+            },
+        });
+    }
+}

package/src/distribution.ts

@@ -0,0 +1,113 @@
+import { ConsumableTransformStream } from "./consumable.js";
+
+/**
+ * Splits or combines buffers to specified size.
+ */
+export class BufferCombiner {
+    #capacity: number;
+    readonly #buffer: Uint8Array;
+    #offset: number;
+    #available: number;
+
+    public constructor(size: number) {
+        this.#capacity = size;
+        this.#buffer = new Uint8Array(size);
+        this.#offset = 0;
+        this.#available = size;
+    }
+
+    /**
+     * Pushes data to the combiner.
+     * @param data The input data to be split or combined.
+     * @returns
+     * A generator that yields buffers of specified size.
+     * It may yield the same buffer multiple times, consume the data before calling `next`.
+     */
+    public *push(data: Uint8Array): Generator<Uint8Array, void, void> {
+        let offset = 0;
+        let available = data.byteLength;
+
+        if (this.#offset !== 0) {
+            if (available >= this.#available) {
+                this.#buffer.set(
+                    data.subarray(0, this.#available),
+                    this.#offset
+                );
+                offset += this.#available;
+                available -= this.#available;
+
+                yield this.#buffer;
+                this.#offset = 0;
+                this.#available = this.#capacity;
+
+                if (available === 0) {
+                    return;
+                }
+            } else {
+                this.#buffer.set(data, this.#offset);
+                this.#offset += available;
+                this.#available -= available;
+                return;
+            }
+        }
+
+        while (available >= this.#capacity) {
+            const end = offset + this.#capacity;
+            yield data.subarray(offset, end);
+            offset = end;
+            available -= this.#capacity;
+        }
+
+        if (available > 0) {
+            this.#buffer.set(data.subarray(offset), this.#offset);
+            this.#offset += available;
+            this.#available -= available;
+        }
+    }
+
+    public flush(): Uint8Array | undefined {
+        if (this.#offset === 0) {
+            return undefined;
+        }
+
+        const output = this.#buffer.subarray(0, this.#offset);
+        this.#offset = 0;
+        this.#available = this.#capacity;
+        return output;
+    }
+}
+
+export class DistributionStream extends ConsumableTransformStream<
+    Uint8Array,
+    Uint8Array
+> {
+    public 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;
+                    }
+                }
+            },
+            async flush(controller) {
+                if (combiner) {
+                    const data = combiner.flush();
+                    if (data) {
+                        await controller.enqueue(data);
+                    }
+                }
+            },
+        });
+    }
+}

package/src/duplex.ts

@@ -1,14 +1,18 @@
 import { PromiseResolver } from "@yume-chan/async";
-import { type ValueOrPromise } from "@yume-chan/struct";
+import type { ValueOrPromise } from "@yume-chan/struct";
 
-import {
-    WritableStream,
-    type ReadableStream,
-    type ReadableStreamDefaultController,
-    type WritableStreamDefaultWriter,
+import type {
+    ReadableStream,
+    ReadableStreamDefaultController,
+    WritableStreamDefaultWriter,
 } from "./stream.js";
+import { WritableStream } from "./stream.js";
 import { WrapReadableStream } from "./wrap-readable.js";
 
+const NOOP = () => {
+    // no-op
+};
+
 export interface DuplexStreamFactoryOptions {
     /**
      * Callback when any `ReadableStream` is cancelled (the user doesn't need any more data),
@@ -42,33 +46,33 @@ export interface DuplexStreamFactoryOptions {
  * when any of them is closed, all other streams will be closed as well.
  */
 export class DuplexStreamFactory<R, W> {
-    private readableControllers: ReadableStreamDefaultController<R>[] = [];
-    private writers: WritableStreamDefaultWriter<W>[] = [];
+    #readableControllers: ReadableStreamDefaultController<R>[] = [];
+    #writers: WritableStreamDefaultWriter<W>[] = [];
 
-    private _writableClosed = false;
+    #writableClosed = false;
     public get writableClosed() {
-        return this._writableClosed;
+        return this.#writableClosed;
     }
 
-    private _closed = new PromiseResolver<void>();
+    #closed = new PromiseResolver<void>();
     public get closed() {
-        return this._closed.promise;
+        return this.#closed.promise;
     }
 
-    private options: DuplexStreamFactoryOptions;
+    readonly #options: DuplexStreamFactoryOptions;
 
     public constructor(options?: DuplexStreamFactoryOptions) {
-        this.options = options ?? {};
+        this.#options = options ?? {};
     }
 
     public wrapReadable(readable: ReadableStream<R>): WrapReadableStream<R> {
         return new WrapReadableStream<R>({
             start: (controller) => {
-                this.readableControllers.push(controller);
+                this.#readableControllers.push(controller);
                 return readable;
             },
             cancel: async () => {
-                // cancel means the local peer closes the connection first.
+                // cancel means the local peer wants to close the connection.
                 await this.close();
             },
             close: async () => {
@@ -80,13 +84,12 @@ export class DuplexStreamFactory<R, W> {
 
     public createWritable(stream: WritableStream<W>): WritableStream<W> {
         const writer = stream.getWriter();
-        this.writers.push(writer);
+        this.#writers.push(writer);
 
         // `WritableStream` has no way to tell if the remote peer has closed the connection.
         // So it only triggers `close`.
         return new WritableStream<W>({
             write: async (chunk) => {
-                await writer.ready;
                 await writer.write(chunk);
             },
             abort: async (reason) => {
@@ -94,45 +97,43 @@ export class DuplexStreamFactory<R, W> {
                 await this.close();
             },
             close: async () => {
-                await writer.close().catch((e) => {
-                    void e;
-                });
+                // NOOP: the writer is already closed
+                await writer.close().catch(NOOP);
                 await this.close();
             },
         });
     }
 
     public async close() {
-        if (this._writableClosed) {
+        if (this.#writableClosed) {
             return;
         }
-        this._writableClosed = true;
+        this.#writableClosed = true;
 
         // Call `close` first, so it can still write data to `WritableStream`s.
-        if ((await this.options.close?.()) !== false) {
+        if ((await this.#options.close?.()) !== false) {
             // `close` can return `false` to disable automatic `dispose`.
             await this.dispose();
         }
 
-        for (const writer of this.writers) {
-            await writer.close().catch((e) => {
-                void e;
-            });
+        for (const writer of this.#writers) {
+            // NOOP: the writer is already closed
+            writer.close().catch(NOOP);
         }
     }
 
     public async dispose() {
-        this._writableClosed = true;
-        this._closed.resolve();
+        this.#writableClosed = true;
+        this.#closed.resolve();
 
-        for (const controller of this.readableControllers) {
+        for (const controller of this.#readableControllers) {
             try {
                 controller.close();
-            } catch (e) {
-                void e;
+            } catch {
+                // ignore
             }
         }
 
-        await this.options.dispose?.();
+        await this.#options.dispose?.();
     }
 }

package/src/gather-string.ts

@@ -1,14 +1,16 @@
 import { WritableStream } from "./stream.js";
 
-export class GatherStringStream extends WritableStream<string>{
+export class GatherStringStream extends WritableStream<string> {
     // PERF: rope (concat strings) is faster than `[].join('')`
-    private _result = '';
-    public get result() { return this._result; }
+    #result = "";
+    public get result() {
+        return this.#result;
+    }
 
     public constructor() {
         super({
             write: (chunk) => {
-                this._result += chunk;
+                this.#result += chunk;
             },
         });
     }