@yume-chan/stream-extra 2.6.1 → 3.0.0-beta.1

package/src/buffered-transform.ts

@@ -2,18 +2,19 @@ import type { MaybePromiseLike } from "@yume-chan/async";
 import { StructEmptyError } from "@yume-chan/struct";
 
 import { BufferedReadableStream } from "./buffered.js";
-import type { PushReadableStreamController } from "./push-readable.js";
-import { PushReadableStream } from "./push-readable.js";
 import type {
     ReadableWritablePair,
     WritableStreamDefaultController,
-} from "./stream.js";
-import { ReadableStream, WritableStream } from "./stream.js";
+} from "./global/index.js";
+import { ReadableStream, WritableStream } from "./global/index.js";
+import type { PushReadableStreamController } from "./push-readable.js";
+import { PushReadableStream } from "./push-readable.js";
 
 // TODO: BufferedTransformStream: find better implementation
-export class BufferedTransformStream<T>
-    implements ReadableWritablePair<T, Uint8Array>
-{
+export class BufferedTransformStream<T> implements ReadableWritablePair<
+    T,
+    Uint8Array
+> {
     #readable: ReadableStream<T>;
     get readable() {
         return this.#readable;
@@ -29,15 +30,28 @@ export class BufferedTransformStream<T>
     ) {
         // Convert incoming chunks to a `BufferedReadableStream`
         let bufferedStreamController!: PushReadableStreamController<Uint8Array>;
-
-        let writableStreamController!: WritableStreamDefaultController;
-
         const buffered = new BufferedReadableStream(
             new PushReadableStream<Uint8Array>((controller) => {
                 bufferedStreamController = controller;
             }),
         );
 
+        let writableStreamController!: WritableStreamDefaultController;
+        this.#writable = new WritableStream({
+            start(controller) {
+                writableStreamController = controller;
+            },
+            async write(chunk) {
+                await bufferedStreamController.enqueue(chunk);
+            },
+            abort() {
+                bufferedStreamController.close();
+            },
+            close() {
+                bufferedStreamController.close();
+            },
+        });
+
         this.#readable = new ReadableStream<T>({
             async pull(controller) {
                 try {
@@ -62,20 +76,5 @@ export class BufferedTransformStream<T>
                 return writableStreamController.error(reason);
             },
         });
-
-        this.#writable = new WritableStream({
-            start(controller) {
-                writableStreamController = controller;
-            },
-            async write(chunk) {
-                await bufferedStreamController.enqueue(chunk);
-            },
-            abort() {
-                bufferedStreamController.close();
-            },
-            close() {
-                bufferedStreamController.close();
-            },
-        });
     }
 }

package/src/buffered.ts

@@ -2,8 +2,11 @@ import type { MaybePromiseLike } from "@yume-chan/async";
 import type { AsyncExactReadable } from "@yume-chan/struct";
 import { bipedal, ExactReadableEndedError } from "@yume-chan/struct";
 
+import type {
+    ReadableStream,
+    ReadableStreamDefaultReader,
+} from "./global/index.js";
 import { PushReadableStream } from "./push-readable.js";
-import type { ReadableStream, ReadableStreamDefaultReader } from "./stream.js";
 import { tryCancel } from "./try-close.js";
 
 export class BufferedReadableStream implements AsyncExactReadable {

package/src/concat.ts

@@ -1,162 +1,205 @@
 import { PromiseResolver } from "@yume-chan/async";
 import { EmptyUint8Array } from "@yume-chan/struct";
 
-import type { ReadableStreamDefaultController } from "./stream.js";
-import { ReadableStream, WritableStream } from "./stream.js";
-
-export interface ConcatStringReadableStream
-    extends ReadableStream<string>,
-        Promise<string> {}
+import type { ReadableWritablePair } from "./global/index.js";
+import { ReadableStream, WritableStream } from "./global/index.js";
 
 // `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,
+// If the user wants 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`.
+export class AccumulateStream<
+    Input,
+    Output,
+    Accumulated = Output,
+> implements ReadableWritablePair<Output, Input> {
+    #current: Accumulated;
 
-/**
- * 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 = "";
+    #write: (chunk: Input, current: Accumulated) => Accumulated;
+    #finalize: (current: Accumulated) => Output;
 
-    #resolver = new PromiseResolver<string>();
+    #resolver = new PromiseResolver<Output>();
 
-    #writable = new WritableStream<string>({
+    #writable = new WritableStream<Input>({
         write: (chunk) => {
-            this.#result += chunk;
+            try {
+                this.#current = this.#write(chunk, this.#current);
+            } catch (e) {
+                this.#resolver.reject(e);
+                throw e;
+            }
         },
         close: () => {
-            this.#resolver.resolve(this.#result);
-            this.#readableController.enqueue(this.#result);
-            this.#readableController.close();
+            try {
+                const output = this.#finalize(this.#current);
+                this.#resolver.resolve(output);
+            } catch (e) {
+                this.#resolver.reject(e);
+                throw e;
+            }
         },
         abort: (reason) => {
             this.#resolver.reject(reason);
-            this.#readableController.error(reason);
         },
     });
-    get writable(): WritableStream<string> {
+    get writable() {
         return this.#writable;
     }
 
-    #readableController!: ReadableStreamDefaultController<string>;
-    #readable = new ReadableStream<string>({
-        start: (controller) => {
-            this.#readableController = controller;
+    #readable = new ReadableStream<Output>(
+        {
+            pull: async (controller) => {
+                const output = await this.#resolver.promise;
+                controller.enqueue(output);
+                controller.close();
+            },
+            // Ignore `abort` event since the user might use the `Promise` interface.
         },
-    }) as ConcatStringReadableStream;
-    get readable(): ConcatStringReadableStream {
+        // `highWaterMark: 0` makes the `pull` method
+        // only be called when the `ReadableStream` is being read.
+        // If the user only uses the `Promise` interface,
+        // it's unnecessary to run the `pull` method.
+        { highWaterMark: 0 },
+    ) as ReadableStream<Output> &
+        Omit<Promise<Output>, typeof Symbol.toStringTag>;
+    get readable() {
         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),
-            },
-        });
+    constructor(
+        initial: Accumulated,
+        write: (chunk: Input, current: Accumulated) => Accumulated,
+        finalize: (current: Accumulated) => Output,
+    ) {
+        this.#current = initial;
+        this.#write = write;
+        this.#finalize = finalize;
+
+        // biome-ignore lint/suspicious/noThenProperty: This object is intentionally thenable
+        this.#readable.then = (onfulfilled, onrejected) => {
+            return this.#resolver.promise.then(onfulfilled, onrejected);
+        };
+        // biome-ignore lint/suspicious/noThenProperty: This object is intentionally thenable
+        this.#readable.catch = (onrejected) => {
+            return this.#resolver.promise.catch(onrejected);
+        };
+        // biome-ignore lint/suspicious/noThenProperty: This object is intentionally thenable
+        this.#readable.finally = (onfinally) => {
+            return this.#resolver.promise.finally(onfinally);
+        };
     }
 }
 
-export interface ConcatBufferReadableStream
-    extends ReadableStream<Uint8Array>,
-        Promise<Uint8Array> {}
+/**
+ * A `TransformStream` that concatenates strings.
+ *
+ * Its `readable` is also a Promise-like, that can be `await`ed to get the result.
+ *
+ * ```ts
+ * const result: string = await readable.pipeThrough(new ConcatStringStream());
+ * ```
+ */
+export class ConcatStringStream extends AccumulateStream<string, string> {
+    constructor() {
+        // PERF: rope (concat strings) is faster than `[].join('')`
+        super(
+            "",
+            (chunk, current) => current + chunk,
+            (output) => output,
+        );
+    }
+}
 
 /**
- * A `TransformStream` that concatenates `Uint8Array`s.
+ * Concatenate all chunks into a single `Uint8Array`.
  *
- * If you want to decode the result as string,
- * 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.
+ * If there is only one chunk, it will be returned directly.
+ * @param chunks An array of `Uint8Array`s to concatenate
+ * @returns An `Uint8Array` containing all chunks. If there is only one chunk, it will be returned directly.
  */
-export class ConcatBufferStream {
-    #segments: Uint8Array[] = [];
+export function concatUint8Arrays(chunks: readonly Uint8Array[]): Uint8Array {
+    switch (chunks.length) {
+        case 0:
+            return EmptyUint8Array;
+        case 1:
+            return chunks[0]!;
+    }
 
-    #resolver = new PromiseResolver<Uint8Array>();
+    const length = chunks.reduce((a, b) => a + b.length, 0);
+    const output = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        output.set(chunk, offset);
+        offset += chunk.length;
+    }
+    return output;
+}
 
-    #writable = new WritableStream<Uint8Array>({
-        write: (chunk) => {
-            this.#segments.push(chunk);
-        },
-        close: () => {
-            let result: Uint8Array;
-            let offset = 0;
-            switch (this.#segments.length) {
-                case 0:
-                    result = EmptyUint8Array;
-                    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;
-            }
+export function toUint8Array(
+    buffer: ArrayBufferLike | ArrayBufferView<ArrayBufferLike>,
+): Uint8Array {
+    if (buffer instanceof Uint8Array) {
+        return buffer;
+    }
+    if (ArrayBuffer.isView(buffer)) {
+        return new Uint8Array(
+            buffer.buffer,
+            buffer.byteOffset,
+            buffer.byteLength,
+        );
+    }
+    return new Uint8Array(buffer);
+}
 
-            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;
+export function concatBuffers(
+    buffers: readonly (ArrayBufferLike | ArrayBufferView<ArrayBufferLike>)[],
+): Uint8Array {
+    switch (buffers.length) {
+        case 0:
+            return EmptyUint8Array;
+        case 1:
+            return toUint8Array(buffers[0]!);
     }
 
-    #readableController!: ReadableStreamDefaultController<Uint8Array>;
-    #readable = new ReadableStream<Uint8Array>({
-        start: (controller) => {
-            this.#readableController = controller;
-        },
-    }) as ConcatBufferReadableStream;
-    get readable(): ConcatBufferReadableStream {
-        return this.#readable;
+    const length = buffers.reduce((a, b) => a + b.byteLength, 0);
+    const output = new Uint8Array(length);
+    let offset = 0;
+    for (const buffer of buffers) {
+        output.set(toUint8Array(buffer), offset);
+        offset += buffer.byteLength;
     }
+    return output;
+}
 
+/**
+ * A `TransformStream` that concatenates `Uint8Array`s.
+ *
+ * Its `readable` is also a Promise-like, that can be `await`ed to get the result.
+ *
+ * To convert a `ReadableStream<Uint8Array>` to a string,
+ * prefer `.pipeThrough(new TextDecoderStream()).pipeThrough(new ConcatStringStream())`,
+ * to `.pipeThrough(new ConcatBufferStream()).pipeThrough(new TextDecoderStream())`.
+ * Because of JavaScript engine optimizations,
+ * concatenating strings is faster than concatenating `Uint8Array`s.
+ */
+export class ConcatBufferStream extends AccumulateStream<
+    Uint8Array,
+    Uint8Array,
+    Uint8Array[]
+> {
     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),
+        super(
+            [],
+            (chunk, current) => {
+                current.push(chunk);
+                return current;
             },
-            finally: {
-                get: () =>
-                    this.#resolver.promise.finally.bind(this.#resolver.promise),
+            (current) => {
+                const result = concatUint8Arrays(current);
+                // `current` is no longer needed. Clear it to free memory.
+                current.length = 0;
+                return result;
             },
-        });
+        );
     }
 }

package/src/consumable/readable.ts

@@ -1,6 +1,6 @@
 import { Consumable } from "../consumable.js";
-import type { QueuingStrategy } from "../stream.js";
-import { ReadableStream } from "../stream.js";
+import type { QueuingStrategy } from "../global/index.js";
+import { ReadableStream } from "../global/index.js";
 
 export interface ConsumableReadableStreamController<T> {
     enqueue(chunk: T): Promise<void>;

package/src/consumable/wrap-byte-readable.ts

@@ -1,5 +1,5 @@
 import type { Consumable } from "../consumable.js";
-import { ReadableStream } from "../stream.js";
+import { ReadableStream } from "../global/index.js";
 
 import { ConsumableReadableStream } from "./readable.js";
 
@@ -9,21 +9,34 @@ export class ConsumableWrapByteReadableStream extends ReadableStream<
     constructor(
         stream: ReadableStream<Uint8Array>,
         chunkSize: number,
-        min?: number,
+        options?: {
+            min?: number | undefined;
+            onRead?: ((size: number) => void) | undefined;
+        },
     ) {
         const reader = stream.getReader({ mode: "byob" });
-        let array = new Uint8Array(chunkSize);
+        let buffer = new ArrayBuffer(chunkSize);
         super({
             async pull(controller) {
-                const { done, value } = await reader.read(array, { min });
+                const { done, value } = await reader.read(
+                    new Uint8Array(buffer),
+                    {
+                        min: options?.min,
+                    },
+                );
+
+                // `value` might be defined even when `done` is true
+                if (value) {
+                    await ConsumableReadableStream.enqueue(controller, value);
+                    options?.onRead?.(value.byteLength);
+                }
+
                 if (done) {
                     controller.close();
                     return;
                 }
 
-                await ConsumableReadableStream.enqueue(controller, value);
-
-                array = new Uint8Array(value.buffer);
+                buffer = value.buffer;
             },
             cancel(reason) {
                 return reader.cancel(reason);

package/src/consumable/wrap-writable.ts

@@ -1,5 +1,5 @@
 import type { Consumable } from "../consumable.js";
-import { WritableStream } from "../stream.js";
+import { WritableStream } from "../global/index.js";
 
 export class ConsumableWrapWritableStream<in T> extends WritableStream<
     Consumable<T>

package/src/consumable/writable.ts

@@ -3,8 +3,8 @@ import type {
     QueuingStrategy,
     WritableStreamDefaultController,
     WritableStreamDefaultWriter,
-} from "../stream.js";
-import { WritableStream } from "../stream.js";
+} from "../global/index.js";
+import { WritableStream } from "../global/index.js";
 
 export interface ConsumableWritableStreamSink<in T> {
     start?(

package/src/consumable.ts

@@ -14,12 +14,20 @@ import {
 import type { Task } from "./task.js";
 import { createTask } from "./task.js";
 
+const Brand = Symbol.for("Consumable.brand");
+
 export class Consumable<T> {
     static readonly WritableStream = ConsumableWritableStream;
     static readonly WrapWritableStream = ConsumableWrapWritableStream;
     static readonly ReadableStream = ConsumableReadableStream;
     static readonly WrapByteReadableStream = ConsumableWrapByteReadableStream;
 
+    readonly [Brand] = true;
+
+    static [Symbol.hasInstance](value: unknown) {
+        return !!(value as Consumable<unknown> | undefined)?.[Brand];
+    }
+
     readonly #task: Task;
     readonly #resolver: PromiseResolver<void>;
 

package/src/distribution.ts

@@ -1,6 +1,6 @@
 import { Consumable } from "./consumable.js";
+import { TransformStream } from "./global/index.js";
 import { MaybeConsumable } from "./maybe-consumable.js";
-import { TransformStream } from "./stream.js";
 
 /**
  * Splits or combines buffers to specified size.

package/src/duplex.ts

@@ -6,8 +6,8 @@ import type {
     ReadableStream,
     ReadableStreamDefaultController,
     WritableStreamDefaultWriter,
-} from "./stream.js";
-import { WritableStream } from "./stream.js";
+} from "./global/index.js";
+import { WritableStream } from "./global/index.js";
 import { tryClose } from "./try-close.js";
 import { WrapReadableStream } from "./wrap-readable.js";
 

package/src/global/abort-signal.ts

@@ -0,0 +1,129 @@
+import type {
+    AddEventListenerOptions,
+    Event,
+    EventListenerOptions,
+    EventListenerOrEventListenerObject,
+} from "./event.js";
+import type { GlobalPrototypeOr, GlobalValueOr } from "./utils.js";
+import { getGlobalValue } from "./utils.js";
+
+interface AbortSignalEventMap {
+    abort: Event;
+}
+
+/**
+ * The **`AbortSignal`** interface represents a signal object that allows you to communicate with an asynchronous operation (such as a fetch request) and abort it if required via an AbortController object.
+ *
+ * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal)
+ */
+interface _AbortSignal {
+    /**
+     * The **`aborted`** read-only property returns a value that indicates whether the asynchronous operations the signal is communicating with are aborted (true) or not (false).
+     *
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/aborted)
+     */
+    readonly aborted: boolean;
+    /** [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/abort_event) */
+    onabort: ((this: AbortSignal, ev: Event) => void) | null;
+    /**
+     * The **`reason`** read-only property returns a JavaScript value that indicates the abort reason.
+     *
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/reason)
+     */
+    readonly reason: unknown;
+    /**
+     * The **`throwIfAborted()`** method throws the signal's abort reason if the signal has been aborted; otherwise it does nothing.
+     *
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/throwIfAborted)
+     */
+    throwIfAborted(): void;
+    addEventListener<K extends keyof AbortSignalEventMap>(
+        type: K,
+        listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => void,
+        options?: boolean | AddEventListenerOptions,
+    ): void;
+    addEventListener(
+        type: string,
+        listener: EventListenerOrEventListenerObject,
+        options?: boolean | AddEventListenerOptions,
+    ): void;
+    removeEventListener<K extends keyof AbortSignalEventMap>(
+        type: K,
+        listener: (this: AbortSignal, ev: AbortSignalEventMap[K]) => void,
+        options?: boolean | EventListenerOptions,
+    ): void;
+    removeEventListener(
+        type: string,
+        listener: EventListenerOrEventListenerObject,
+        options?: boolean | EventListenerOptions,
+    ): void;
+}
+
+export type AbortSignal = GlobalPrototypeOr<"AbortSignal", _AbortSignal>;
+
+interface _AbortSignalConstructor {
+    /**
+     * The **`AbortSignal.abort()`** static method returns an AbortSignal that is already set as aborted (and which does not trigger an abort event).
+     *
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/abort_static)
+     */
+    abort(reason?: unknown): AbortSignal;
+    /**
+     * The **`AbortSignal.any()`** static method takes an iterable of abort signals and returns an AbortSignal. The returned abort signal is aborted when any of the input iterable abort signals are aborted. The abort reason will be set to the reason of the first signal that is aborted. If any of the given abort signals are already aborted then so will be the returned AbortSignal.
+     *
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/any_static)
+     */
+    any(signals: Iterable<AbortSignal>): AbortSignal;
+    /**
+     * The **`AbortSignal.timeout()`** static method returns an AbortSignal that will automatically abort after a specified time.
+     *
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortSignal/timeout_static)
+     */
+    timeout(milliseconds: number): AbortSignal;
+}
+
+type AbortSignalConstructor = GlobalValueOr<
+    "AbortSignal",
+    _AbortSignalConstructor
+>;
+
+export const AbortSignal =
+    getGlobalValue<AbortSignalConstructor>("AbortSignal");
+
+/**
+ * The **`AbortController`** interface represents a controller object that allows you to abort one or more Web requests as and when desired.
+ *
+ * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController)
+ */
+interface _AbortController {
+    /**
+     * The **`signal`** read-only property of the AbortController interface returns an AbortSignal object instance, which can be used to communicate with/abort an asynchronous operation as desired.
+     *
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController/signal)
+     */
+    readonly signal: AbortSignal;
+    /**
+     * The **`abort()`** method of the AbortController interface aborts an asynchronous operation before it has completed. This is able to abort fetch requests, the consumption of any response bodies, or streams.
+     *
+     * [MDN Reference](https://developer.mozilla.org/docs/Web/API/AbortController/abort)
+     */
+    abort(reason?: unknown): void;
+}
+
+export type AbortController = GlobalPrototypeOr<
+    "AbortController",
+    _AbortController
+>;
+
+interface _AbortControllerConstructor {
+    prototype: AbortController;
+    new (): AbortController;
+}
+
+type AbortControllerConstructor = GlobalValueOr<
+    "AbortController",
+    _AbortControllerConstructor
+>;
+
+export const AbortController =
+    getGlobalValue<AbortControllerConstructor>("AbortController");