@yume-chan/stream-extra 0.0.23 → 0.0.24

package/src/concat.ts

@@ -1,4 +1,5 @@
 import { PromiseResolver } from "@yume-chan/async";
+import { EMPTY_UINT8_ARRAY } 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 = EMPTY_UINT8_ARRAY;
                     break;
                 case 1:
                     result = this.#segments[0]!;

package/src/consumable.ts

@@ -5,30 +5,17 @@ import type {
     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;
-}
+import {
+    ReadableStream as NativeReadableStream,
+    WritableStream as NativeWritableStream,
+} from "./stream.js";
+import type { Task } from "./task.js";
+import { createTask } from "./task.js";
 
-interface GlobalExtension {
-    console: Console;
+function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
+    return typeof value === "object" && value !== null && "then" in value;
 }
 
-// `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>;
@@ -51,11 +38,23 @@ export class Consumable<T> {
         this.#resolver.reject(error);
     }
 
-    async tryConsume<U>(callback: (value: T) => U) {
+    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();
+            let result = this.#task.run(() => callback(this.value));
+            if (isPromiseLike(result)) {
+                result = result.then(
+                    (value) => {
+                        this.#resolver.resolve();
+                        return value;
+                    },
+                    (e) => {
+                        this.#resolver.reject(e);
+                        throw e;
+                    },
+                ) as U;
+            } else {
+                this.#resolver.resolve();
+            }
             return result;
         } catch (e) {
             this.#resolver.reject(e);
@@ -64,228 +63,143 @@ export class Consumable<T> {
     }
 }
 
-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);
-            },
-        });
+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 class UnwrapConsumableStream<T> extends TransformStream<
-    Consumable<T>,
-    T
-> {
-    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>> {
-    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);
-                };
-            }
+    export 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;
         }
 
-        super(
-            {
-                async start(controller) {
-                    wrappedController = {
-                        async enqueue(chunk) {
-                            await enqueue(controller, chunk);
-                        },
-                        close() {
-                            controller.close();
-                        },
-                        error(reason) {
-                            controller.error(reason);
-                        },
+        constructor(
+            sink: 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,
+                        );
                     };
+                }
+            }
 
-                    await source.start?.(wrappedController);
-                },
-                async pull() {
-                    await source.pull?.(wrappedController!);
-                },
-                async cancel(reason) {
-                    await source.cancel?.(reason);
+            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,
-        );
+                wrappedStrategy,
+            );
+        }
     }
-}
-
-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 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;
+    export interface ReadableStreamController<T> {
+        enqueue(chunk: T): Promise<void>;
+        close(): void;
+        error(reason: unknown): void;
     }
 
-    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(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,
-        );
+    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 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 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 class ConsumableTransformStream<I, O> extends TransformStream<
-    Consumable<I>,
-    Consumable<O>
-> {
-    constructor(transformer: ConsumableTransformer<I, O>) {
-        let wrappedController:
-            | ConsumableReadableStreamController<O>
-            | undefined;
+        constructor(
+            source: ReadableStreamSource<T>,
+            strategy?: QueuingStrategy<T>,
+        ) {
+            let wrappedController: ReadableStreamController<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);
+            super(
+                {
+                    async start(controller) {
+                        wrappedController = {
+                            async enqueue(chunk) {
+                                await ReadableStream.enqueue(controller, chunk);
+                            },
+                            close() {
+                                controller.close();
+                            },
+                            error(reason) {
+                                controller.error(reason);
+                            },
+                        };
+
+                        await source.start?.(wrappedController);
                     },
-                    close() {
-                        controller.terminate();
+                    async pull() {
+                        await source.pull?.(wrappedController!);
                     },
-                    error(reason) {
-                        controller.error(reason);
+                    async cancel(reason) {
+                        await source.cancel?.(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>
-> {
-    constructor(callback: (value: T) => void) {
-        super({
-            transform(chunk, controller) {
-                callback(chunk.value);
-                controller.enqueue(chunk);
-            },
-        });
+                },
+                wrappedStrategy,
+            );
+        }
     }
 }

package/src/distribution.ts

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

package/src/encoding.ts

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

package/src/index.ts

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