@yume-chan/stream-extra 2.5.3 → 3.0.0-beta.0

package/src/global/timer.ts

@@ -0,0 +1,18 @@
+import { getGlobalValue } from "./utils.js";
+
+interface TimerHandler {
+    (...args: unknown[]): void;
+}
+
+interface SetTimeoutFunction {
+    (handler: TimerHandler, timeout?: number, ...args: unknown[]): number;
+}
+
+interface ClearTimeoutFunction {
+    (timeoutId: number): void;
+}
+
+export const setTimeout =
+    getGlobalValue<SetTimeoutFunction>("setTimeout") ?? (() => {});
+export const clearTimeout =
+    getGlobalValue<ClearTimeoutFunction>("clearTimeout") ?? (() => {});

package/src/global/utils.ts

@@ -0,0 +1,14 @@
+export type GlobalPrototypeOr<K extends string, Or> =
+    typeof globalThis extends Record<K, { prototype: infer T }> ? T : Or;
+
+export type GlobalValueOr<
+    K extends string,
+    Or,
+> = (typeof globalThis extends Record<K, infer T> ? T : Or) & {
+    __keepAlias?: never;
+};
+
+/** #__NO_SIDE_EFFECTS__ */
+export function getGlobalValue<T>(key: string) {
+    return (globalThis as unknown as Record<string, T>)[key]!;
+}

package/src/index.ts

@@ -4,15 +4,15 @@ export * from "./concat.js";
 export * from "./consumable.js";
 export * from "./distribution.js";
 export * from "./duplex.js";
-export * from "./encoding.js";
+export * from "./global/index.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-queue.js";
 export * from "./task.js";
 export * from "./try-close.js";
 export * from "./wrap-readable.js";

package/src/inspect.ts

@@ -1,12 +1,26 @@
-import { TransformStream } from "./stream.js";
+import type { MaybePromiseLike } from "@yume-chan/async";
+
+import { TransformStream } from "./global/index.js";
 
 export class InspectStream<T> extends TransformStream<T, T> {
-    constructor(callback: (value: T) => void) {
+    constructor(
+        write: (value: T) => MaybePromiseLike<undefined>,
+        extras?: {
+            close?: (() => void) | undefined;
+            cancel?: (() => void) | undefined;
+        },
+    ) {
         super({
-            transform(chunk, controller) {
-                callback(chunk);
+            async transform(chunk, controller) {
+                await write(chunk);
                 controller.enqueue(chunk);
             },
+            flush() {
+                extras?.close?.();
+            },
+            cancel() {
+                extras?.cancel?.();
+            },
         });
     }
 }

package/src/maybe-consumable/wrap-writable.ts

@@ -1,5 +1,5 @@
+import { WritableStream } from "../global/index.js";
 import type { MaybeConsumable } from "../maybe-consumable.js";
-import { WritableStream } from "../stream.js";
 
 import { tryConsume } from "./utils.js";
 

package/src/maybe-consumable/writable.ts

@@ -1,10 +1,10 @@
 import { Consumable } from "../consumable.js";
-import type { MaybeConsumable } from "../maybe-consumable.js";
 import type {
     QueuingStrategy,
     WritableStreamDefaultController,
-} from "../stream.js";
-import { WritableStream } from "../stream.js";
+} from "../global/index.js";
+import { WritableStream } from "../global/index.js";
+import type { MaybeConsumable } from "../maybe-consumable.js";
 
 import { tryConsume } from "./utils.js";
 

package/src/pipe-from.ts

@@ -1,5 +1,5 @@
-import type { ReadableWritablePair } from "./stream.js";
-import { WritableStream } from "./stream.js";
+import type { ReadableWritablePair } from "./global/index.js";
+import { WritableStream } from "./global/index.js";
 
 /**
  * Pipe `pair.readable` to `writable`, then returns `pair.writable`.

package/src/push-readable.ts

@@ -1,12 +1,35 @@
-import { PromiseResolver } from "@yume-chan/async";
+import type { MaybePromise } from "@yume-chan/async";
+import { isPromiseLike, PromiseResolver } from "@yume-chan/async";
 
-import type { AbortSignal, QueuingStrategy } from "./stream.js";
-import { AbortController, ReadableStream } from "./stream.js";
+import type {
+    AbortSignal,
+    QueuingStrategy,
+    ReadableStreamDefaultController,
+} from "./global/index.js";
+import { AbortController, ReadableStream } from "./global/index.js";
+import { TaskQueue } from "./task-queue.js";
 
 export interface PushReadableStreamController<T> {
     abortSignal: AbortSignal;
 
-    enqueue(chunk: T): Promise<void>;
+    /**
+     * Enqueue `chunk` into the stream.
+     *
+     * - If the stream is already cancelled by consumer before calling `enqueue`,
+     * the call will return `false`.
+     * - If the stream is already closed or errored by producer before calling `enqueue`,
+     * the call will throw an error.
+     * - If the stream has enough buffer space, the call will return `true`.
+     *
+     * Otherwise it returns a `Promise`:
+     *
+     * - If the stream is cancelled by consumer, or closed or errored by producer,
+     *   while the `Promise` is pending, the `Promise` will be resolved to `false`.
+     * - When the stream has enough buffer space, the `Promise` will be resolved to `true`.
+     *
+     * @param chunk The value to be enqueued
+     */
+    enqueue(chunk: T): Promise<boolean>;
 
     close(): void;
 
@@ -51,216 +74,220 @@ export class PushReadableStream<T> extends ReadableStream<T> {
         strategy?: QueuingStrategy<T>,
         logger?: PushReadableLogger<T>,
     ) {
-        let waterMarkLow: PromiseResolver<void> | undefined;
+        let controller!: ReadableStreamDefaultController<T>;
+        const tasks = new TaskQueue();
+
         let zeroHighWaterMarkAllowEnqueue = false;
+        // Resolves when consumer calls `reader.read`.
+        // Rejects when producer calls `controller.close` or `controller.error`,
+        // or consumer calls `reader.cancel`.
+        let waterMarkLow: PromiseResolver<undefined> | undefined;
+
         const abortController = new AbortController();
+        // Whether either the consumer has called `stream.cancel()`,
+        // or the producer has called `controller.close` or `controller.error`.
+        let stopped = false;
+
+        const enqueue = (chunk: T): MaybePromise<boolean> => {
+            logger?.({
+                source: "producer",
+                operation: "enqueue",
+                value: chunk,
+                phase: "start",
+            });
+
+            if (abortController.signal.aborted) {
+                // In original `ReadableStream`, calling `enqueue` or `close`
+                // on an cancelled stream will throw an error,
+                //
+                // But in `PushReadableStream`, `enqueue` is an async function,
+                // the producer can't just check `abortSignal.aborted`
+                // before calling `enqueue`, as it might change when waiting
+                // for the backpressure to be reduced.
+                //
+                // So IMO it's better to handle this for the producer
+                // by simply ignoring the `enqueue` call.
+                //
+                // Note that we check `abortSignal.aborted` instead of `stopped`,
+                // as it's not allowed for the producer to call `enqueue` after
+                // they called `close` or `error`.
+                //
+                // Obviously, the producer should listen to the `abortSignal` and
+                // stop producing, but most pushing data sources don't support that.
+                logger?.({
+                    source: "producer",
+                    operation: "enqueue",
+                    value: chunk,
+                    phase: "ignored",
+                });
+                return false;
+            }
+
+            if (controller.desiredSize === null) {
+                // `desiredSize` being `null` means the stream is in error state,
+                // `controller.enqueue` will throw an error for us.
+                controller.enqueue(chunk);
+                // istanbul ignore next
+                throw new Error("unreachable");
+            }
+
+            if (zeroHighWaterMarkAllowEnqueue) {
+                // When `highWaterMark` is set to `0`,
+                // `controller.desiredSize` will always be `0`,
+                // even if the consumer has called `reader.read()`.
+                // (in this case, each `reader.read()`/`pull`
+                // should allow one `enqueue` of any size)
+                //
+                // If the consumer has already called `reader.read()`,
+                // before the producer tries to `enqueue`,
+                // `controller.desiredSize` is `0` and normal `waterMarkLow` signal
+                // will never trigger,
+                // (because `ReadableStream` prevents reentrance of `pull`)
+                // The stream will stuck.
+                //
+                // So we need a special signal for this case.
+                zeroHighWaterMarkAllowEnqueue = false;
+                controller.enqueue(chunk);
+                logger?.({
+                    source: "producer",
+                    operation: "enqueue",
+                    value: chunk,
+                    phase: "complete",
+                });
+                return true;
+            }
+
+            if (controller.desiredSize <= 0) {
+                logger?.({
+                    source: "producer",
+                    operation: "enqueue",
+                    value: chunk,
+                    phase: "waiting",
+                });
+
+                waterMarkLow = new PromiseResolver<undefined>();
+                return waterMarkLow.promise.then(
+                    (): boolean => {
+                        controller.enqueue(chunk);
+                        logger?.({
+                            source: "producer",
+                            operation: "enqueue",
+                            value: chunk,
+                            phase: "complete",
+                        });
+                        return true;
+                    },
+                    (): boolean => {
+                        // Only ignore this in-flight `enqueue` call
+                        // future calls will trigger `desiredSize === null` and throw
+                        logger?.({
+                            source: "producer",
+                            operation: "enqueue",
+                            value: chunk,
+                            phase: "ignored",
+                        });
+                        return false;
+                    },
+                );
+            }
+
+            controller.enqueue(chunk);
+            logger?.({
+                source: "producer",
+                operation: "enqueue",
+                value: chunk,
+                phase: "complete",
+            });
+            return true;
+        };
+
+        const close = (explicit: boolean) => {
+            logger?.({
+                source: "producer",
+                operation: "close",
+                explicit,
+                phase: "start",
+            });
+
+            // Allow calling `controller.close` on cancelled stream as `enqueue` does
+            // Ignore implicit close on any stopped state
+            // But don't allow calling `controller.close` multiple times
+            if (abortController.signal.aborted || (stopped && !explicit)) {
+                logger?.({
+                    source: "producer",
+                    operation: "close",
+                    explicit,
+                    phase: "ignored",
+                });
+                return;
+            }
+
+            // This will throw for us if the stream is not in `readable` state
+            controller.close();
+
+            stopped = true;
+            // Wake up pending `enqueue`
+            waterMarkLow?.reject();
+
+            logger?.({
+                source: "producer",
+                operation: "close",
+                explicit,
+                phase: "complete",
+            });
+        };
+
+        const error = (error: unknown, explicit: boolean) => {
+            logger?.({
+                source: "producer",
+                operation: "error",
+                explicit,
+                phase: "start",
+            });
+
+            stopped = true;
+            // `controller.error` won't throw on closed/errored/cancelled stream
+            // so don't need any checks
+            controller.error(error);
+            // Wake up pending `enqueue`
+            waterMarkLow?.reject();
+
+            logger?.({
+                source: "producer",
+                operation: "error",
+                explicit,
+                phase: "complete",
+            });
+        };
 
         super(
             {
-                start: (controller) => {
+                start: (controller_) => {
+                    controller = controller_;
+
                     const result = source({
                         abortSignal: abortController.signal,
-                        enqueue: async (chunk) => {
-                            logger?.({
-                                source: "producer",
-                                operation: "enqueue",
-                                value: chunk,
-                                phase: "start",
-                            });
-
-                            if (abortController.signal.aborted) {
-                                // In original `ReadableStream`, calling `enqueue` or `close`
-                                // on an cancelled stream will throw an error,
-                                //
-                                // But in `PushReadableStream`, `enqueue` is an async function,
-                                // the producer can't just check `abortSignal.aborted`
-                                // before calling `enqueue`, as it might change when waiting
-                                // for the backpressure to be reduced.
-                                //
-                                // So IMO it's better to handle this for the producer
-                                // by simply ignoring the `enqueue` call.
-                                //
-                                // Note that we check `abortSignal.aborted` instead of `stopped`,
-                                // as it's not allowed for the producer to call `enqueue` after
-                                // they called `close` or `error`.
-                                //
-                                // Obviously, the producer should listen to the `abortSignal` and
-                                // stop producing, but most pushing data sources don't support that.
-                                logger?.({
-                                    source: "producer",
-                                    operation: "enqueue",
-                                    value: chunk,
-                                    phase: "ignored",
-                                });
-                                return;
-                            }
-
-                            if (controller.desiredSize === null) {
-                                // `desiredSize` being `null` means the stream is in error state,
-                                // `controller.enqueue` will throw an error for us.
-                                controller.enqueue(chunk);
-                                // istanbul ignore next
-                                return;
-                            }
-
-                            if (zeroHighWaterMarkAllowEnqueue) {
-                                // When `highWaterMark` is set to `0`,
-                                // `controller.desiredSize` will always be `0`,
-                                // even if the consumer has called `reader.read()`.
-                                // (in this case, each `reader.read()`/`pull`
-                                // should allow one `enqueue` of any size)
-                                //
-                                // If the consumer has already called `reader.read()`,
-                                // before the producer tries to `enqueue`,
-                                // `controller.desiredSize` is `0` and normal `waterMarkLow` signal
-                                // will never trigger,
-                                // (because `ReadableStream` prevents reentrance of `pull`)
-                                // The stream will stuck.
-                                //
-                                // So we need a special signal for this case.
-                                zeroHighWaterMarkAllowEnqueue = false;
-                                controller.enqueue(chunk);
-                                logger?.({
-                                    source: "producer",
-                                    operation: "enqueue",
-                                    value: chunk,
-                                    phase: "complete",
-                                });
-                                return;
-                            }
-
-                            if (controller.desiredSize <= 0) {
-                                logger?.({
-                                    source: "producer",
-                                    operation: "enqueue",
-                                    value: chunk,
-                                    phase: "waiting",
-                                });
-
-                                waterMarkLow = new PromiseResolver<void>();
-                                await waterMarkLow.promise;
-
-                                // Recheck consumer cancellation after async operations.
-                                if (abortController.signal.aborted) {
-                                    logger?.({
-                                        source: "producer",
-                                        operation: "enqueue",
-                                        value: chunk,
-                                        phase: "ignored",
-                                    });
-                                    return;
-                                }
-                            }
-
-                            controller.enqueue(chunk);
-                            logger?.({
-                                source: "producer",
-                                operation: "enqueue",
-                                value: chunk,
-                                phase: "complete",
-                            });
-                        },
+                        enqueue: async (chunk) =>
+                            // Run `enqueue`s in serial
+                            // Use `async/await` to always return a `Promise`
+                            await tasks.enqueue(() => enqueue(chunk)),
                         close() {
-                            logger?.({
-                                source: "producer",
-                                operation: "close",
-                                explicit: true,
-                                phase: "start",
-                            });
-
-                            // Since `enqueue` on an cancelled stream won't throw an error,
-                            // so does `close`.
-                            if (abortController.signal.aborted) {
-                                logger?.({
-                                    source: "producer",
-                                    operation: "close",
-                                    explicit: true,
-                                    phase: "ignored",
-                                });
-                                return;
-                            }
-
-                            controller.close();
-                            logger?.({
-                                source: "producer",
-                                operation: "close",
-                                explicit: true,
-                                phase: "complete",
-                            });
+                            close(true);
                         },
                         error(e) {
-                            logger?.({
-                                source: "producer",
-                                operation: "error",
-                                explicit: true,
-                                phase: "start",
-                            });
-
-                            // Calling `error` on an already closed or errored stream is a no-op.
-                            controller.error(e);
-
-                            logger?.({
-                                source: "producer",
-                                operation: "error",
-                                explicit: true,
-                                phase: "complete",
-                            });
+                            error(e, true);
                         },
                     });
 
-                    if (result && "then" in result) {
+                    if (!stopped && isPromiseLike(result)) {
                         // If `source` returns a `Promise`,
                         // close the stream when the `Promise` is resolved,
                         // and error the stream when the `Promise` is rejected.
                         // The producer can return a never-settling `Promise`
                         // to disable this behavior.
                         result.then(
-                            () => {
-                                logger?.({
-                                    source: "producer",
-                                    operation: "close",
-                                    explicit: false,
-                                    phase: "start",
-                                });
-
-                                try {
-                                    controller.close();
-
-                                    logger?.({
-                                        source: "producer",
-                                        operation: "close",
-                                        explicit: false,
-                                        phase: "complete",
-                                    });
-                                } catch {
-                                    logger?.({
-                                        source: "producer",
-                                        operation: "close",
-                                        explicit: false,
-                                        phase: "ignored",
-                                    });
-
-                                    // The stream is already closed by the producer,
-                                    // Or cancelled by the consumer.
-                                }
-                            },
-                            (e) => {
-                                logger?.({
-                                    source: "producer",
-                                    operation: "error",
-                                    explicit: false,
-                                    phase: "start",
-                                });
-
-                                controller.error(e);
-
-                                logger?.({
-                                    source: "producer",
-                                    operation: "error",
-                                    explicit: false,
-                                    phase: "complete",
-                                });
-                            },
+                            () => close(false),
+                            (e) => error(e, false),
                         );
                     }
                 },
@@ -272,7 +299,8 @@ export class PushReadableStream<T> extends ReadableStream<T> {
                     });
 
                     if (waterMarkLow) {
-                        waterMarkLow.resolve();
+                        waterMarkLow.resolve(undefined);
+                        waterMarkLow = undefined;
                     } else if (strategy?.highWaterMark === 0) {
                         zeroHighWaterMarkAllowEnqueue = true;
                     }
@@ -290,9 +318,9 @@ export class PushReadableStream<T> extends ReadableStream<T> {
                         phase: "start",
                     });
 
+                    stopped = true;
                     abortController.abort(reason);
-                    // Resolve it on cancellation. `pull` will check `abortSignal.aborted` again.
-                    waterMarkLow?.resolve();
+                    waterMarkLow?.reject();
 
                     logger?.({
                         source: "consumer",

package/src/split-string.ts

@@ -1,12 +1,42 @@
-import { TransformStream } from "./stream.js";
+import type { TransformStreamDefaultController } from "./global/index.js";
+import { TransformStream } from "./global/index.js";
 
 export class SplitStringStream extends TransformStream<string, string> {
-    constructor(separator: string) {
+    constructor(
+        separator: string,
+        options?: {
+            trim?: boolean | undefined;
+            trimEnd?: boolean | undefined;
+            skipEmpty?: boolean | undefined;
+        },
+    ) {
         let remaining: string | undefined = undefined;
+        const separatorLength = separator.length;
+        if (separatorLength === 0) {
+            throw new Error("separator must not be empty");
+        }
+
+        const trim = !!options?.trim;
+        const trimEnd = !!options?.trimEnd;
+        const skipEmpty = !!options?.skipEmpty;
+        const enqueue = (
+            controller: TransformStreamDefaultController<string>,
+            value: string,
+        ) => {
+            if (trim) {
+                value = value.trim();
+            } else if (trimEnd) {
+                value = value.trimEnd();
+            }
+
+            if (value || !skipEmpty) {
+                controller.enqueue(value);
+            }
+        };
 
         super({
             transform(chunk, controller) {
-                if (remaining) {
+                if (remaining !== undefined) {
                     chunk = remaining + chunk;
                     remaining = undefined;
                 }
@@ -15,17 +45,21 @@ export class SplitStringStream extends TransformStream<string, string> {
                 while (start < chunk.length) {
                     const index = chunk.indexOf(separator, start);
                     if (index === -1) {
+                        // `remaining` can't be an empty string
+                        // because `start` is less than `chunk.length`
                         remaining = chunk.substring(start);
                         break;
                     }
 
-                    controller.enqueue(chunk.substring(start, index));
-                    start = index + 1;
+                    const value = chunk.substring(start, index);
+                    enqueue(controller, value);
+
+                    start = index + separatorLength;
                 }
             },
             flush(controller) {
-                if (remaining) {
-                    controller.enqueue(remaining);
+                if (remaining !== undefined) {
+                    enqueue(controller, remaining);
                 }
             },
         });

package/src/struct-deserialize.ts

@@ -5,7 +5,7 @@ import { BufferedTransformStream } from "./buffered-transform.js";
 export class StructDeserializeStream<T> extends BufferedTransformStream<T> {
     constructor(struct: StructDeserializer<T>) {
         super((stream) => {
-            return struct.deserialize(stream) as never;
+            return struct.deserialize(stream);
         });
     }
 }