@yume-chan/stream-extra 0.0.19 → 0.0.21

package/src/buffered-transform.ts

@@ -1,9 +1,7 @@
 import type { ValueOrPromise } from "@yume-chan/struct";
+import { StructEmptyError } from "@yume-chan/struct";
 
-import {
-    BufferedReadableStream,
-    BufferedReadableStreamEndedError,
-} from "./buffered.js";
+import { BufferedReadableStream } from "./buffered.js";
 import type { PushReadableStreamController } from "./push-readable.js";
 import { PushReadableStream } from "./push-readable.js";
 import type { ReadableWritablePair } from "./stream.js";
@@ -13,18 +11,18 @@ import { ReadableStream, WritableStream } from "./stream.js";
 export class BufferedTransformStream<T>
     implements ReadableWritablePair<T, Uint8Array>
 {
-    private _readable: ReadableStream<T>;
-    public get readable() {
-        return this._readable;
+    #readable: ReadableStream<T>;
+    get readable() {
+        return this.#readable;
     }
 
-    private _writable: WritableStream<Uint8Array>;
-    public get writable() {
-        return this._writable;
+    #writable: WritableStream<Uint8Array>;
+    get writable() {
+        return this.#writable;
     }
 
     constructor(
-        transform: (stream: BufferedReadableStream) => ValueOrPromise<T>
+        transform: (stream: BufferedReadableStream) => ValueOrPromise<T>,
     ) {
         // Convert incoming chunks to a `BufferedReadableStream`
         let sourceStreamController!: PushReadableStreamController<Uint8Array>;
@@ -32,19 +30,19 @@ export class BufferedTransformStream<T>
         const buffered = new BufferedReadableStream(
             new PushReadableStream<Uint8Array>((controller) => {
                 sourceStreamController = controller;
-            })
+            }),
         );
 
-        this._readable = new ReadableStream<T>({
+        this.#readable = new ReadableStream<T>({
             async pull(controller) {
                 try {
                     const value = await transform(buffered);
                     controller.enqueue(value);
                 } catch (e) {
-                    // Treat `BufferedReadableStreamEndedError` as a normal end.
+                    // Treat `StructEmptyError` as a normal end.
                     // If the `transform` method doesn't have enough data to return a value,
                     // it should throw another error to indicate that.
-                    if (e instanceof BufferedReadableStreamEndedError) {
+                    if (e instanceof StructEmptyError) {
                         controller.close();
                         return;
                     }
@@ -58,7 +56,7 @@ export class BufferedTransformStream<T>
             },
         });
 
-        this._writable = new WritableStream({
+        this.#writable = new WritableStream({
             async write(chunk) {
                 await sourceStreamController.enqueue(chunk);
             },

package/src/buffered.ts

@@ -1,43 +1,41 @@
+import type { AsyncExactReadable } from "@yume-chan/struct";
+import { ExactReadableEndedError } from "@yume-chan/struct";
+
 import { PushReadableStream } from "./push-readable.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;
-
-    private _position = 0;
-    public get position() {
-        return this._position;
+    #position = 0;
+    get position() {
+        return this.#position;
     }
 
     protected readonly stream: ReadableStream<Uint8Array>;
     protected readonly reader: ReadableStreamDefaultReader<Uint8Array>;
 
-    public constructor(stream: ReadableStream<Uint8Array>) {
+    constructor(stream: ReadableStream<Uint8Array>) {
         this.stream = stream;
         this.reader = stream.getReader();
     }
 
-    private async readSource() {
+    async #readSource() {
         const { done, value } = await this.reader.read();
         if (done) {
-            throw new BufferedReadableStreamEndedError();
+            throw new ExactReadableEndedError();
         }
-        this._position += value.byteLength;
+        this.#position += value.byteLength;
         return value;
     }
 
-    private async readAsync(length: number, initial?: Uint8Array) {
+    async #readAsync(length: number, initial?: Uint8Array) {
         let result: Uint8Array;
         let index: number;
 
@@ -47,15 +45,15 @@ export class BufferedReadableStream {
             index = initial.byteLength;
             length -= initial.byteLength;
         } else {
-            const array = await this.readSource();
+            const array = await this.#readSource();
             if (array.byteLength === length) {
                 return array;
             }
 
             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);
             }
 
@@ -66,16 +64,16 @@ export class BufferedReadableStream {
         }
 
         while (length > 0) {
-            const array = await this.readSource();
+            const array = await this.#readSource();
             if (array.byteLength === length) {
                 result.set(array, index);
                 return result;
             }
 
             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;
             }
@@ -93,24 +91,26 @@ export class BufferedReadableStream {
      * @param length
      * @returns
      */
-    public read(length: number): Uint8Array | Promise<Uint8Array> {
+    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;
-            return this.readAsync(length, array.subarray(offset));
+            this.#buffered = undefined;
+            this.#bufferedLength = 0;
+            this.#bufferedOffset = 0;
+            return this.#readAsync(length, array.subarray(offset));
         }
 
-        return this.readAsync(length);
+        return this.#readAsync(length);
     }
 
     /**
@@ -118,11 +118,17 @@ export class BufferedReadableStream {
      * all data from the wrapped stream.
      * @returns A `ReadableStream`
      */
-    public release(): ReadableStream<Uint8Array> {
-        if (this.buffered) {
+    release(): ReadableStream<Uint8Array> {
+        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) {
@@ -141,7 +147,7 @@ export class BufferedReadableStream {
         }
     }
 
-    public cancel(reason?: unknown) {
+    cancel(reason?: unknown) {
         return this.reader.cancel(reason);
     }
 }

package/src/concat.ts

@@ -0,0 +1,160 @@
+import { PromiseResolver } from "@yume-chan/async";
+
+import type { ReadableStreamDefaultController } from "./stream.js";
+import { ReadableStream, WritableStream } from "./stream.js";
+
+export interface ConcatStringReadableStream
+    extends ReadableStream<string>,
+        Promise<string> {}
+
+// `TransformStream` only calls its `source.flush` method when its `readable` is being read.
+// If the user want to use the `Promise` interface, the `flush` method will never be called,
+// so the `PromiseResolver` will never be resolved.
+// Thus we need to implement our own `TransformStream` using a `WritableStream` and a `ReadableStream`.
+
+/**
+ * A `TransformStream` that concatenates strings.
+ *
+ * Its `readable` is also a `Promise<string>`, so it's possible to `await` it to get the result.
+ *
+ * ```ts
+ * const result: string = await readable.pipeThrough(new ConcatStringStream());
+ * ```
+ */
+export class ConcatStringStream {
+    // PERF: rope (concat strings) is faster than `[].join('')`
+    #result = "";
+
+    #resolver = new PromiseResolver<string>();
+
+    #writable = new WritableStream<string>({
+        write: (chunk) => {
+            this.#result += chunk;
+        },
+        close: () => {
+            this.#resolver.resolve(this.#result);
+            this.#readableController.enqueue(this.#result);
+            this.#readableController.close();
+        },
+        abort: (reason) => {
+            this.#resolver.reject(reason);
+            this.#readableController.error(reason);
+        },
+    });
+    get writable(): WritableStream<string> {
+        return this.#writable;
+    }
+
+    #readableController!: ReadableStreamDefaultController<string>;
+    #readable = new ReadableStream<string>({
+        start: (controller) => {
+            this.#readableController = controller;
+        },
+    }) as ConcatStringReadableStream;
+    get readable(): ConcatStringReadableStream {
+        return this.#readable;
+    }
+
+    constructor() {
+        void Object.defineProperties(this.#readable, {
+            then: {
+                get: () =>
+                    this.#resolver.promise.then.bind(this.#resolver.promise),
+            },
+            catch: {
+                get: () =>
+                    this.#resolver.promise.catch.bind(this.#resolver.promise),
+            },
+            finally: {
+                get: () =>
+                    this.#resolver.promise.finally.bind(this.#resolver.promise),
+            },
+        });
+    }
+}
+
+export interface ConcatBufferReadableStream
+    extends ReadableStream<Uint8Array>,
+        Promise<Uint8Array> {}
+
+/**
+ * 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.
+ */
+export class ConcatBufferStream {
+    #segments: Uint8Array[] = [];
+
+    #resolver = new PromiseResolver<Uint8Array>();
+
+    #writable = new WritableStream<Uint8Array>({
+        write: (chunk) => {
+            this.#segments.push(chunk);
+        },
+        close: () => {
+            let result: Uint8Array;
+            let offset = 0;
+            switch (this.#segments.length) {
+                case 0:
+                    result = new Uint8Array(0);
+                    break;
+                case 1:
+                    result = this.#segments[0]!;
+                    break;
+                default:
+                    result = new Uint8Array(
+                        this.#segments.reduce(
+                            (prev, item) => prev + item.length,
+                            0,
+                        ),
+                    );
+                    for (const segment of this.#segments) {
+                        result.set(segment, offset);
+                        offset += segment.length;
+                    }
+                    break;
+            }
+
+            this.#resolver.resolve(result);
+            this.#readableController.enqueue(result);
+            this.#readableController.close();
+        },
+        abort: (reason) => {
+            this.#resolver.reject(reason);
+            this.#readableController.error(reason);
+        },
+    });
+    get writable(): WritableStream<Uint8Array> {
+        return this.#writable;
+    }
+
+    #readableController!: ReadableStreamDefaultController<Uint8Array>;
+    #readable = new ReadableStream<Uint8Array>({
+        start: (controller) => {
+            this.#readableController = controller;
+        },
+    }) as ConcatBufferReadableStream;
+    get readable(): ConcatBufferReadableStream {
+        return this.#readable;
+    }
+
+    constructor() {
+        void Object.defineProperties(this.#readable, {
+            then: {
+                get: () =>
+                    this.#resolver.promise.then.bind(this.#resolver.promise),
+            },
+            catch: {
+                get: () =>
+                    this.#resolver.promise.catch.bind(this.#resolver.promise),
+            },
+            finally: {
+                get: () =>
+                    this.#resolver.promise.finally.bind(this.#resolver.promise),
+            },
+        });
+    }
+}

package/src/consumable.ts

@@ -11,12 +11,12 @@ interface Console {
     createTask(name: string): Task;
 }
 
-interface GlobalEx {
+interface GlobalExtension {
     console: Console;
 }
 
 // `createTask` allows browser DevTools to track the call stack across async boundaries.
-const { console } = globalThis as unknown as GlobalEx;
+const { console } = globalThis as unknown as GlobalExtension;
 const createTask: Console["createTask"] =
     console.createTask?.bind(console) ??
     (() => ({
@@ -26,35 +26,35 @@ const createTask: Console["createTask"] =
     }));
 
 export class Consumable<T> {
-    private readonly task: Task;
-    private readonly resolver: PromiseResolver<void>;
+    readonly #task: Task;
+    readonly #resolver: PromiseResolver<void>;
 
-    public readonly value: T;
-    public readonly consumed: Promise<void>;
+    readonly value: T;
+    readonly consumed: Promise<void>;
 
-    public constructor(value: T) {
-        this.task = createTask("Consumable");
+    constructor(value: T) {
+        this.#task = createTask("Consumable");
         this.value = value;
-        this.resolver = new PromiseResolver<void>();
-        this.consumed = this.resolver.promise;
+        this.#resolver = new PromiseResolver<void>();
+        this.consumed = this.#resolver.promise;
     }
 
-    public consume() {
-        this.resolver.resolve();
+    consume() {
+        this.#resolver.resolve();
     }
 
-    public error(error: any) {
-        this.resolver.reject(error);
+    error(error: any) {
+        this.#resolver.reject(error);
     }
 
-    public async tryConsume<U>(callback: (value: T) => U) {
+    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));
+            const result = await this.#task.run(() => callback(this.value));
             this.consume();
             return result;
         } catch (e) {
-            this.resolver.reject(e);
+            this.#resolver.reject(e);
             throw e;
         }
     }
@@ -62,7 +62,7 @@ export class Consumable<T> {
 
 async function enqueue<T>(
     controller: { enqueue: (chunk: Consumable<T>) => void },
-    chunk: T
+    chunk: T,
 ) {
     const output = new Consumable(chunk);
     controller.enqueue(output);
@@ -70,7 +70,7 @@ async function enqueue<T>(
 }
 
 export class WrapConsumableStream<T> extends TransformStream<T, Consumable<T>> {
-    public constructor() {
+    constructor() {
         super({
             async transform(chunk, controller) {
                 await enqueue(controller, chunk);
@@ -83,7 +83,7 @@ export class UnwrapConsumableStream<T> extends TransformStream<
     Consumable<T>,
     T
 > {
-    public constructor() {
+    constructor() {
         super({
             transform(chunk, controller) {
                 controller.enqueue(chunk.value);
@@ -101,18 +101,18 @@ export interface ConsumableReadableStreamController<T> {
 
 export interface ConsumableReadableStreamSource<T> {
     start?(
-        controller: ConsumableReadableStreamController<T>
+        controller: ConsumableReadableStreamController<T>,
     ): void | PromiseLike<void>;
     pull?(
-        controller: ConsumableReadableStreamController<T>
+        controller: ConsumableReadableStreamController<T>,
     ): void | PromiseLike<void>;
     cancel?(reason: any): void | PromiseLike<void>;
 }
 
 export class ConsumableReadableStream<T> extends ReadableStream<Consumable<T>> {
-    public constructor(
+    constructor(
         source: ConsumableReadableStreamSource<T>,
-        strategy?: QueuingStrategy<T>
+        strategy?: QueuingStrategy<T>,
     ) {
         let wrappedController:
             | ConsumableReadableStreamController<T>
@@ -155,7 +155,7 @@ export class ConsumableReadableStream<T> extends ReadableStream<Consumable<T>> {
                     await source.cancel?.(reason);
                 },
             },
-            wrappedStrategy
+            wrappedStrategy,
         );
     }
 }
@@ -168,18 +168,18 @@ export interface ConsumableWritableStreamSink<T> {
 }
 
 export class ConsumableWritableStream<T> extends WritableStream<Consumable<T>> {
-    public static async write<T>(
+    static async write<T>(
         writer: WritableStreamDefaultWriter<Consumable<T>>,
-        value: T
+        value: T,
     ) {
         const consumable = new Consumable(value);
         await writer.write(consumable);
         await consumable.consumed;
     }
 
-    public constructor(
+    constructor(
         sink: ConsumableWritableStreamSink<T>,
-        strategy?: QueuingStrategy<T>
+        strategy?: QueuingStrategy<T>,
     ) {
         let wrappedStrategy: QueuingStrategy<Consumable<T>> | undefined;
         if (strategy) {
@@ -210,21 +210,21 @@ export class ConsumableWritableStream<T> extends WritableStream<Consumable<T>> {
                     return sink.close?.();
                 },
             },
-            wrappedStrategy
+            wrappedStrategy,
         );
     }
 }
 
 export interface ConsumableTransformer<I, O> {
     start?(
-        controller: ConsumableReadableStreamController<O>
+        controller: ConsumableReadableStreamController<O>,
     ): void | PromiseLike<void>;
     transform?(
         chunk: I,
-        controller: ConsumableReadableStreamController<O>
+        controller: ConsumableReadableStreamController<O>,
     ): void | PromiseLike<void>;
     flush?(
-        controller: ConsumableReadableStreamController<O>
+        controller: ConsumableReadableStreamController<O>,
     ): void | PromiseLike<void>;
 }
 
@@ -232,7 +232,7 @@ export class ConsumableTransformStream<I, O> extends TransformStream<
     Consumable<I>,
     Consumable<O>
 > {
-    public constructor(transformer: ConsumableTransformer<I, O>) {
+    constructor(transformer: ConsumableTransformer<I, O>) {
         let wrappedController:
             | ConsumableReadableStreamController<O>
             | undefined;
@@ -254,8 +254,9 @@ export class ConsumableTransformStream<I, O> extends TransformStream<
                 await transformer.start?.(wrappedController);
             },
             async transform(chunk) {
-                await chunk.tryConsume((value) =>
-                    transformer.transform?.(value, wrappedController!)
+                await chunk.tryConsume(
+                    (value) =>
+                        transformer.transform?.(value, wrappedController!),
                 );
                 chunk.consume();
             },
@@ -270,7 +271,7 @@ export class ConsumableInspectStream<T> extends TransformStream<
     Consumable<T>,
     Consumable<T>
 > {
-    public constructor(callback: (value: T) => void) {
+    constructor(callback: (value: T) => void) {
         super({
             transform(chunk, controller) {
                 callback(chunk.value);

package/src/decode-utf8.ts

@@ -3,7 +3,7 @@ import { decodeUtf8 } from "@yume-chan/struct";
 import { TransformStream } from "./stream.js";
 
 export class DecodeUtf8Stream extends TransformStream<Uint8Array, string> {
-    public constructor() {
+    constructor() {
         super({
             transform(chunk, controller) {
                 controller.enqueue(decodeUtf8(chunk));