@yume-chan/stream-extra 0.0.17 → 0.0.19

package/src/distribution.ts

@@ -0,0 +1,113 @@
+import { ConsumableTransformStream } from "./consumable.js";
+
+/**
+ * Splits or combines buffers to specified size.
+ */
+export class BufferCombiner {
+    private _capacity: number;
+    private readonly _buffer: Uint8Array;
+    private _offset: number;
+    private _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,15 +1,25 @@
 import { PromiseResolver } from "@yume-chan/async";
 import type { ValueOrPromise } from "@yume-chan/struct";
-import { WritableStream, type ReadableStream, type ReadableStreamDefaultController, type WritableStreamDefaultWriter } from "./stream.js";
+
+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),
      * or `WritableStream` is ended (the user won't produce any more data),
      * or `DuplexStreamFactory#close` is called.
      *
-     * Usually you want to let the other peer know that the duplex stream should be clsoed.
+     * Usually you want to let the other peer know that the duplex stream should be closed.
      *
      * `dispose` will automatically be called after `close` completes,
      * but if you want to wait another peer for a close confirmation and call
@@ -40,10 +50,14 @@ export class DuplexStreamFactory<R, W> {
     private writers: WritableStreamDefaultWriter<W>[] = [];
 
     private _writableClosed = false;
-    public get writableClosed() { return this._writableClosed; }
+    public get writableClosed() {
+        return this._writableClosed;
+    }
 
     private _closed = new PromiseResolver<void>();
-    public get closed() { return this._closed.promise; }
+    public get closed() {
+        return this._closed.promise;
+    }
 
     private options: DuplexStreamFactoryOptions;
 
@@ -58,7 +72,7 @@ export class DuplexStreamFactory<R, W> {
                 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 () => {
@@ -76,7 +90,6 @@ export class DuplexStreamFactory<R, W> {
         // So it only triggers `close`.
         return new WritableStream<W>({
             write: async (chunk) => {
-                await writer.ready;
                 await writer.write(chunk);
             },
             abort: async (reason) => {
@@ -84,7 +97,7 @@ export class DuplexStreamFactory<R, W> {
                 await this.close();
             },
             close: async () => {
-                try { await writer.close(); } catch { }
+                await writer.close().catch(NOOP);
                 await this.close();
             },
         });
@@ -97,13 +110,13 @@ export class DuplexStreamFactory<R, W> {
         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) {
-            try { await writer.close(); } catch { }
+            await writer.close().catch(NOOP);
         }
     }
 
@@ -112,7 +125,11 @@ export class DuplexStreamFactory<R, W> {
         this._closed.resolve();
 
         for (const controller of this.readableControllers) {
-            try { controller.close(); } catch { }
+            try {
+                controller.close();
+            } catch {
+                // ignore
+            }
         }
 
         await this.options.dispose?.();

package/src/gather-string.ts

@@ -1,9 +1,11 @@
 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; }
+    private _result = "";
+    public get result() {
+        return this._result;
+    }
 
     public constructor() {
         super({

package/src/index.ts

@@ -1,15 +1,16 @@
-export * from './buffered-transform.js';
-export * from './buffered.js';
-export * from './chunk.js';
-export * from './decode-utf8.js';
-export * from './duplex.js';
-export * from './gather-string.js';
-export * from './inspect.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 './wrap-readable.js';
-export * from './wrap-writable.js';
+export * from "./buffered-transform.js";
+export * from "./buffered.js";
+export * from "./consumable.js";
+export * from "./decode-utf8.js";
+export * from "./distribution.js";
+export * from "./duplex.js";
+export * from "./gather-string.js";
+export * from "./inspect.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 "./wrap-readable.js";
+export * from "./wrap-writable.js";

package/src/inspect.ts

@@ -6,7 +6,7 @@ export class InspectStream<T> extends TransformStream<T, T> {
             transform(chunk, controller) {
                 callback(chunk);
                 controller.enqueue(chunk);
-            }
+            },
         });
     }
 }

package/src/pipe-from.ts

@@ -1,27 +1,28 @@
-import { WritableStream, type ReadableWritablePair } from "./stream.js";
+import type { ReadableWritablePair } from "./stream.js";
+import { WritableStream } from "./stream.js";
 
 /**
- * Create a new `WritableStream` that, when written to, will write that chunk to
- * `pair.writable`, when pipe `pair.readable` to `writable`.
+ * Pipe `pair.readable` to `writable`, then returns `pair.writable`.
  *
- * It's the opposite of `ReadableStream.pipeThrough`.
+ * This is the opposite of `ReadableStream#pipeThrough()`.
  *
  * @param writable The `WritableStream` to write to.
  * @param pair A `TransformStream` that converts chunks.
- * @returns A new `WritableStream`.
+ * @returns `pair`'s `writable` stream.
  */
-export function pipeFrom<W, T>(writable: WritableStream<W>, pair: ReadableWritablePair<W, T>) {
+export function pipeFrom<W, T>(
+    writable: WritableStream<W>,
+    pair: ReadableWritablePair<W, T>
+) {
     const writer = pair.writable.getWriter();
-    const pipe = pair.readable
-        .pipeTo(writable);
+    const pipe = pair.readable.pipeTo(writable);
     return new WritableStream<T>({
         async write(chunk) {
-            await writer.ready;
             await writer.write(chunk);
         },
         async close() {
             await writer.close();
             await pipe;
-        }
+        },
     });
 }

package/src/push-readable.ts

@@ -1,5 +1,7 @@
-import { PromiseResolver } from '@yume-chan/async';
-import { AbortController, AbortSignal, QueuingStrategy, ReadableStream } from "./stream.js";
+import { PromiseResolver } from "@yume-chan/async";
+
+import type { AbortSignal, QueuingStrategy } from "./stream.js";
+import { AbortController, ReadableStream } from "./stream.js";
 
 export interface PushReadableStreamController<T> {
     abortSignal: AbortSignal;
@@ -8,55 +10,84 @@ export interface PushReadableStreamController<T> {
 
     close(): void;
 
-    error(e?: any): void;
+    error(e?: unknown): void;
 }
 
-export type PushReadableStreamSource<T> = (controller: PushReadableStreamController<T>) => void;
+export type PushReadableStreamSource<T> = (
+    controller: PushReadableStreamController<T>
+) => void | Promise<void>;
 
 export class PushReadableStream<T> extends ReadableStream<T> {
-    public constructor(source: PushReadableStreamSource<T>, strategy?: QueuingStrategy<T>) {
+    /**
+     * Create a new `PushReadableStream` from a source.
+     *
+     * @param source If `source` returns a `Promise`, the stream will be closed
+     * when the `Promise` is resolved, and be errored when the `Promise` is rejected.
+     * @param strategy
+     */
+    public constructor(
+        source: PushReadableStreamSource<T>,
+        strategy?: QueuingStrategy<T>
+    ) {
         let waterMarkLow: PromiseResolver<void> | undefined;
-        const canceled: AbortController = new AbortController();
-
-        super({
-            start: (controller) => {
-                source({
-                    abortSignal: canceled.signal,
-                    async enqueue(chunk) {
-                        if (canceled.signal.aborted) {
-                            // If the stream is already cancelled,
-                            // throw immediately.
-                            throw canceled.signal.reason ?? new Error('Aborted');
-                        }
-
-                        // Only when the stream is errored, `desiredSize` will be `null`.
-                        // But since `null <= 0` is `true`
-                        // (`null <= 0` is evaluated as `!(null > 0)` => `!false` => `true`),
-                        // not handling it will cause a deadlock.
-                        if ((controller.desiredSize ?? 1) <= 0) {
-                            waterMarkLow = new PromiseResolver<void>();
-                            await waterMarkLow.promise;
-                        }
-
-                        // `controller.enqueue` will throw error for us
-                        // if the stream is already errored.
-                        controller.enqueue(chunk);
-                    },
-                    close() {
-                        controller.close();
-                    },
-                    error(e) {
-                        controller.error(e);
-                    },
-                });
-            },
-            pull: () => {
-                waterMarkLow?.resolve();
-            },
-            cancel: async (reason) => {
-                canceled.abort(reason);
-                waterMarkLow?.reject(reason);
+        const canceled = new AbortController();
+
+        super(
+            {
+                start: (controller) => {
+                    const result = source({
+                        abortSignal: canceled.signal,
+                        async enqueue(chunk) {
+                            if (canceled.signal.aborted) {
+                                // If the stream is already cancelled,
+                                // throw immediately.
+                                throw (
+                                    canceled.signal.reason ??
+                                    new Error("Aborted")
+                                );
+                            }
+
+                            // Only when the stream is errored, `desiredSize` will be `null`.
+                            // But since `null <= 0` is `true`
+                            // (`null <= 0` is evaluated as `!(null > 0)` => `!false` => `true`),
+                            // not handling it will cause a deadlock.
+                            if ((controller.desiredSize ?? 1) <= 0) {
+                                waterMarkLow = new PromiseResolver<void>();
+                                await waterMarkLow.promise;
+                            }
+
+                            // `controller.enqueue` will throw error for us
+                            // if the stream is already errored.
+                            controller.enqueue(chunk);
+                        },
+                        close() {
+                            controller.close();
+                        },
+                        error(e) {
+                            controller.error(e);
+                        },
+                    });
+
+                    if (result && "then" in result) {
+                        result.then(
+                            () => {
+                                controller.close();
+                            },
+                            (e) => {
+                                controller.error(e);
+                            }
+                        );
+                    }
+                },
+                pull: () => {
+                    waterMarkLow?.resolve();
+                },
+                cancel: (reason) => {
+                    canceled.abort(reason);
+                    waterMarkLow?.reject(reason);
+                },
             },
-        }, strategy);
+            strategy
+        );
     }
 }

package/src/split-string.ts

@@ -1,6 +1,9 @@
 import { TransformStream } from "./stream.js";
 
-function* split(input: string, separator: string): Generator<string, void, void> {
+function* split(
+    input: string,
+    separator: string
+): Generator<string, void, void> {
     let start = 0;
 
     while (true) {
@@ -23,7 +26,7 @@ export class SplitStringStream extends TransformStream<string, string> {
                 for (const part of split(chunk, separator)) {
                     controller.enqueue(part);
                 }
-            }
+            },
         });
     }
 }

package/src/stream.ts

@@ -1,22 +1,64 @@
 import type { AbortSignal } from "web-streams-polyfill";
-export * from 'web-streams-polyfill';
+import {
+    ReadableStream as ReadableStreamPolyfill,
+    TransformStream as TransformStreamPolyfill,
+    WritableStream as WritableStreamPolyfill,
+} from "web-streams-polyfill";
+export * from "web-streams-polyfill";
 
 /** A controller object that allows you to abort one or more DOM requests as and when desired. */
 export interface AbortController {
     /**
      * Returns the AbortSignal object associated with this object.
      */
-
     readonly signal: AbortSignal;
+
     /**
      * Invoking this method will set this object's AbortSignal's aborted flag and signal to any observers that the associated activity is to be aborted.
      */
     abort(reason?: any): void;
 }
 
-export let AbortController: {
+interface AbortControllerConstructor {
     prototype: AbortController;
-    new(): AbortController;
-};
+    new (): AbortController;
+}
+
+interface GlobalExtension {
+    AbortController: AbortControllerConstructor;
+    ReadableStream: typeof ReadableStreamPolyfill;
+    WritableStream: typeof WritableStreamPolyfill;
+    TransformStream: typeof TransformStreamPolyfill;
+}
+
+const GLOBAL = globalThis as unknown as GlobalExtension;
 
-({ AbortController } = globalThis as any);
+export const AbortController = GLOBAL.AbortController;
+
+export type ReadableStream<R = any> = ReadableStreamPolyfill<R>;
+export let ReadableStream = ReadableStreamPolyfill;
+
+export type WritableStream<W = any> = WritableStreamPolyfill<W>;
+export let WritableStream = WritableStreamPolyfill;
+
+export type TransformStream<I = any, O = any> = TransformStreamPolyfill<I, O>;
+export let TransformStream = TransformStreamPolyfill;
+
+if (GLOBAL.ReadableStream && GLOBAL.WritableStream && GLOBAL.TransformStream) {
+    // Use browser native implementation
+    ReadableStream = GLOBAL.ReadableStream;
+    WritableStream = GLOBAL.WritableStream;
+    TransformStream = GLOBAL.TransformStream;
+} else {
+    // TODO: enable loading Node.js stream implementation when bundler supports Top Level Await
+    // try {
+    //     // Use Node.js native implementation
+    //     const MODULE_NAME = "node:stream/web";
+    //     const StreamWeb = (await import(MODULE_NAME)) as GlobalExtension;
+    //     ReadableStream = StreamWeb.ReadableStream;
+    //     WritableStream = StreamWeb.WritableStream;
+    //     TransformStream = StreamWeb.TransformStream;
+    // } catch {
+    //     // ignore
+    // }
+}

package/src/struct-deserialize.ts

@@ -1,12 +1,14 @@
 import type Struct from "@yume-chan/struct";
 import type { StructValueType } from "@yume-chan/struct";
-import { BufferedTransformStream } from './buffered-transform.js';
 
-export class StructDeserializeStream<T extends Struct<any, any, any, any>>
-    extends BufferedTransformStream<StructValueType<T>> {
+import { BufferedTransformStream } from "./buffered-transform.js";
+
+export class StructDeserializeStream<
+    T extends Struct<any, any, any, any>
+> extends BufferedTransformStream<StructValueType<T>> {
     public constructor(struct: T) {
         super((stream) => {
-            return struct.deserialize(stream)
+            return struct.deserialize(stream);
         });
     }
 }

package/src/struct-serialize.ts

@@ -1,8 +1,10 @@
 import type Struct from "@yume-chan/struct";
+
 import { TransformStream } from "./stream.js";
 
-export class StructSerializeStream<T extends Struct<any, any, any, any>>
-    extends TransformStream<T['TInit'], Uint8Array>{
+export class StructSerializeStream<
+    T extends Struct<any, any, any, any>
+> extends TransformStream<T["TInit"], Uint8Array> {
     constructor(struct: T) {
         super({
             transform(chunk, controller) {

package/src/wrap-readable.ts

@@ -1,21 +1,31 @@
 import type { ValueOrPromise } from "@yume-chan/struct";
-import { ReadableStream, ReadableStreamDefaultController, ReadableStreamDefaultReader } from "./stream.js";
 
-export type WrapReadableStreamStart<T> = (controller: ReadableStreamDefaultController<T>) => ValueOrPromise<ReadableStream<T>>;
+import type {
+    ReadableStreamDefaultController,
+    ReadableStreamDefaultReader,
+} from "./stream.js";
+import { ReadableStream } from "./stream.js";
+
+export type WrapReadableStreamStart<T> = (
+    controller: ReadableStreamDefaultController<T>
+) => ValueOrPromise<ReadableStream<T>>;
 
 export interface ReadableStreamWrapper<T> {
     start: WrapReadableStreamStart<T>;
-    cancel?(reason?: any): ValueOrPromise<void>;
+    cancel?(reason?: unknown): ValueOrPromise<void>;
     close?(): ValueOrPromise<void>;
 }
 
 function getWrappedReadableStream<T>(
-    wrapper: ReadableStream<T> | WrapReadableStreamStart<T> | ReadableStreamWrapper<T>,
+    wrapper:
+        | ReadableStream<T>
+        | WrapReadableStreamStart<T>
+        | ReadableStreamWrapper<T>,
     controller: ReadableStreamDefaultController<T>
 ) {
-    if ('start' in wrapper) {
+    if ("start" in wrapper) {
         return wrapper.start(controller);
-    } else if (typeof wrapper === 'function') {
+    } else if (typeof wrapper === "function") {
         return wrapper(controller);
     } else {
         // Can't use `wrapper instanceof ReadableStream`
@@ -31,12 +41,17 @@ function getWrappedReadableStream<T>(
  * 2. Synchronously create a `ReadableStream` by asynchronously return another `ReadableStream`.
  * 3. Convert native `ReadableStream`s to polyfilled ones so they can `pipe` between.
  */
-export class WrapReadableStream<T> extends ReadableStream<T>{
+export class WrapReadableStream<T> extends ReadableStream<T> {
     public readable!: ReadableStream<T>;
 
     private reader!: ReadableStreamDefaultReader<T>;
 
-    public constructor(wrapper: ReadableStream<T> | WrapReadableStreamStart<T> | ReadableStreamWrapper<T>) {
+    public constructor(
+        wrapper:
+            | ReadableStream<T>
+            | WrapReadableStreamStart<T>
+            | ReadableStreamWrapper<T>
+    ) {
         super({
             start: async (controller) => {
                 // `start` is invoked before `ReadableStream`'s constructor finish,
@@ -45,12 +60,15 @@ export class WrapReadableStream<T> extends ReadableStream<T>{
                 // Queue a microtask to avoid this.
                 await Promise.resolve();
 
-                this.readable = await getWrappedReadableStream(wrapper, controller);
+                this.readable = await getWrappedReadableStream(
+                    wrapper,
+                    controller
+                );
                 this.reader = this.readable.getReader();
             },
             cancel: async (reason) => {
                 await this.reader.cancel(reason);
-                if ('cancel' in wrapper) {
+                if ("cancel" in wrapper) {
                     await wrapper.cancel?.(reason);
                 }
             },
@@ -58,13 +76,13 @@ export class WrapReadableStream<T> extends ReadableStream<T>{
                 const result = await this.reader.read();
                 if (result.done) {
                     controller.close();
-                    if ('close' in wrapper) {
+                    if ("close" in wrapper) {
                         await wrapper.close?.();
                     }
                 } else {
                     controller.enqueue(result.value);
                 }
-            }
+            },
         });
     }
 }