@qorejs/qore 0.7.0 → 0.7.2

package/dist/src/core/stream-buffer.js

@@ -0,0 +1,162 @@
+import { createDeferred } from './stream-backpressure.js';
+import { sleep } from '../shared/utils.js';
+export function createStreamBuffer({ enqueueChunk, fail, isTerminated, pressure, readCurrent, recordDrop, signal, updateBuffered, writeChunk }) {
+    const pendingWrites = [];
+    const spaceWaiters = [];
+    const scheduledPushes = new Set();
+    let scheduledPushError = null;
+    let drainPromise = null;
+    let lastPushAt = 0;
+    function releaseSpaceWaiters() {
+        if (pressure.buffer === Infinity) {
+            while (spaceWaiters.length > 0) {
+                spaceWaiters.shift()?.resolve(undefined);
+            }
+            return;
+        }
+        while (spaceWaiters.length > 0 && pendingWrites.length < pressure.buffer) {
+            spaceWaiters.shift()?.resolve(undefined);
+        }
+    }
+    function flush(result = readCurrent()) {
+        while (pendingWrites.length > 0) {
+            pendingWrites.shift()?.resolve(result);
+        }
+        updateBuffered(0);
+        releaseSpaceWaiters();
+        return result;
+    }
+    async function flushScheduled() {
+        while (scheduledPushes.size > 0) {
+            await Promise.allSettled(Array.from(scheduledPushes));
+        }
+        if (scheduledPushError !== null) {
+            throw scheduledPushError;
+        }
+        while (drainPromise) {
+            await drainPromise;
+        }
+        if (scheduledPushError !== null) {
+            throw scheduledPushError;
+        }
+    }
+    async function waitForNextWindow() {
+        if (pressure.interval <= 0 || lastPushAt === 0) {
+            return;
+        }
+        const remaining = pressure.interval - (Date.now() - lastPushAt);
+        if (remaining > 0) {
+            try {
+                await sleep(remaining, signal);
+            }
+            catch (error) {
+                if (!signal.aborted) {
+                    throw error;
+                }
+            }
+        }
+    }
+    function scheduleDrain() {
+        if (drainPromise || isTerminated()) {
+            return drainPromise;
+        }
+        drainPromise = (async () => {
+            try {
+                while (pendingWrites.length > 0 && !isTerminated() && !signal.aborted) {
+                    const entry = pendingWrites.shift();
+                    updateBuffered(pendingWrites.length);
+                    releaseSpaceWaiters();
+                    await waitForNextWindow();
+                    if (isTerminated() || signal.aborted) {
+                        entry.resolve(readCurrent());
+                        continue;
+                    }
+                    enqueueChunk(entry.chunk);
+                    const nextValue = writeChunk(entry.chunk);
+                    lastPushAt = Date.now();
+                    entry.resolve(nextValue);
+                }
+            }
+            finally {
+                drainPromise = null;
+                if (pendingWrites.length > 0 && !isTerminated() && !signal.aborted) {
+                    scheduleDrain();
+                }
+            }
+        })();
+        return drainPromise;
+    }
+    async function waitForBufferSpace() {
+        if (pressure.buffer === Infinity) {
+            return true;
+        }
+        while (!isTerminated() && !signal.aborted && pendingWrites.length >= pressure.buffer) {
+            const gate = createDeferred();
+            spaceWaiters.push(gate);
+            await gate.promise;
+        }
+        return !isTerminated() && !signal.aborted;
+    }
+    async function push(chunk) {
+        if (isTerminated() || signal.aborted) {
+            return readCurrent();
+        }
+        const writeTask = (async () => {
+            if (pressure.overflow === 'wait') {
+                const hasSpace = await waitForBufferSpace();
+                if (!hasSpace) {
+                    return readCurrent();
+                }
+            }
+            else if (pressure.buffer !== Infinity && pendingWrites.length >= pressure.buffer) {
+                if (pressure.overflow === 'drop-oldest' && pendingWrites.length > 0) {
+                    const droppedWrite = pendingWrites.shift();
+                    recordDrop();
+                    droppedWrite.resolve(readCurrent());
+                }
+                else if (pressure.overflow === 'drop-newest' || pressure.overflow === 'drop-oldest') {
+                    recordDrop();
+                    return readCurrent();
+                }
+                else if (pressure.overflow === 'error') {
+                    const overflowError = new Error('Qore stream backpressure buffer overflow');
+                    if (scheduledPushError === null) {
+                        scheduledPushError = overflowError;
+                    }
+                    fail(overflowError);
+                    return readCurrent();
+                }
+            }
+            if (isTerminated() || signal.aborted) {
+                return readCurrent();
+            }
+            const entry = createDeferred();
+            entry.chunk = chunk;
+            pendingWrites.push(entry);
+            updateBuffered(pendingWrites.length);
+            scheduleDrain();
+            return entry.promise;
+        })();
+        scheduledPushes.add(writeTask);
+        try {
+            return await writeTask;
+        }
+        catch (error) {
+            if (scheduledPushError === null) {
+                scheduledPushError = error;
+            }
+            if (!isTerminated() && !signal.aborted) {
+                fail(error);
+            }
+            return readCurrent();
+        }
+        finally {
+            scheduledPushes.delete(writeTask);
+        }
+    }
+    return {
+        flush,
+        flushScheduled,
+        push
+    };
+}

package/dist/src/core/stream-iterator.d.ts

@@ -0,0 +1,6 @@
+import type { AsyncQueue } from './stream-queue.js';
+import type { QoreStream } from './stream-types.js';
+export type IterableStream<TChunk, TValue> = QoreStream<TChunk, TValue> & {
+    [Symbol.asyncIterator](): AsyncIterableIterator<TChunk>;
+};
+export declare function attachStreamIterator<TChunk, TValue>(readable: IterableStream<TChunk, TValue>, queue: AsyncQueue<TChunk>, shouldAbortOnReturn: () => boolean, abort: (reason?: unknown) => TValue): void;

package/dist/src/core/stream-iterator.js

@@ -0,0 +1,14 @@
+export function attachStreamIterator(readable, queue, shouldAbortOnReturn, abort) {
+    readable[Symbol.asyncIterator] = async function* () {
+        try {
+            for await (const chunk of queue) {
+                yield chunk;
+            }
+        }
+        finally {
+            if (shouldAbortOnReturn()) {
+                abort('Stream consumer disposed');
+            }
+        }
+    };
+}

package/dist/src/core/stream-lifecycle.d.ts

@@ -0,0 +1,10 @@
+export interface StreamLifecycle<TValue> {
+    isTerminated(): boolean;
+    markTerminated(): boolean;
+    setCleanup(cleanup: () => TValue | void): void;
+    stop(finalizer: () => TValue, cleanup?: () => TValue | void): TValue;
+}
+export declare function createStreamLifecycle<TValue>({ closeQueue, readCurrent }: {
+    closeQueue(): void;
+    readCurrent(): TValue;
+}): StreamLifecycle<TValue>;

package/dist/src/core/stream-lifecycle.js

@@ -0,0 +1,28 @@
+export function createStreamLifecycle({ closeQueue, readCurrent }) {
+    let terminated = false;
+    let activeCleanup = readCurrent;
+    return {
+        isTerminated() {
+            return terminated;
+        },
+        markTerminated() {
+            if (terminated) {
+                return false;
+            }
+            terminated = true;
+            return true;
+        },
+        setCleanup(cleanup) {
+            activeCleanup = cleanup;
+        },
+        stop(finalizer, cleanup = activeCleanup) {
+            if (terminated) {
+                return readCurrent();
+            }
+            terminated = true;
+            cleanup();
+            closeQueue();
+            return finalizer();
+        }
+    };
+}

package/dist/src/core/stream-queue.d.ts

@@ -0,0 +1,17 @@
+interface QueueWaiter<T> {
+    resolve(result: IteratorResult<T>): void;
+    reject(reason?: unknown): void;
+}
+export declare class AsyncQueue<T> implements AsyncIterableIterator<T> {
+    values: T[];
+    waiters: QueueWaiter<T>[];
+    closed: boolean;
+    error: Error | null;
+    push(value: T): void;
+    close(): void;
+    fail(error: unknown): void;
+    next(): Promise<IteratorResult<T>>;
+    return(): Promise<IteratorResult<T>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<T>;
+}
+export {};

package/dist/src/core/stream-queue.js

@@ -0,0 +1,62 @@
+import { normalizeError } from '../shared/utils.js';
+// Bridge producer pushes and async iteration with a minimal internal queue.
+export class AsyncQueue {
+    values = [];
+    waiters = [];
+    closed = false;
+    error = null;
+    push(value) {
+        if (this.closed) {
+            return;
+        }
+        const waiter = this.waiters.shift();
+        if (waiter) {
+            waiter.resolve({ value, done: false });
+            return;
+        }
+        this.values.push(value);
+    }
+    close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        while (this.waiters.length > 0) {
+            const waiter = this.waiters.shift();
+            waiter?.resolve({ value: undefined, done: true });
+        }
+    }
+    fail(error) {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        this.error = normalizeError(error);
+        while (this.waiters.length > 0) {
+            const waiter = this.waiters.shift();
+            waiter?.reject(this.error);
+        }
+    }
+    next() {
+        if (this.values.length > 0) {
+            const value = this.values.shift();
+            return Promise.resolve({ value, done: false });
+        }
+        if (this.closed) {
+            if (this.error) {
+                return Promise.reject(this.error);
+            }
+            return Promise.resolve({ value: undefined, done: true });
+        }
+        return new Promise((resolve, reject) => {
+            this.waiters.push({ resolve, reject });
+        });
+    }
+    return() {
+        this.close();
+        return Promise.resolve({ value: undefined, done: true });
+    }
+    [Symbol.asyncIterator]() {
+        return this;
+    }
+}

package/dist/src/core/stream-runtime.d.ts

@@ -0,0 +1,2 @@
+import type { QoreStream, StreamInput, StreamOptions } from './stream-types.js';
+export declare function createStream<TChunk, TValue = string>(sourceOrSetup: StreamInput<TChunk, TValue>, options?: StreamOptions<TChunk, TValue>): QoreStream<TChunk, TValue>;

package/dist/src/core/stream-runtime.js

@@ -0,0 +1,127 @@
+import { signal as createSignal } from './signal.js';
+import { createResponse } from './response.js';
+import { normalizeBackpressure } from './stream-backpressure.js';
+import { createStreamBuffer } from './stream-buffer.js';
+import { attachStreamIterator } from './stream-iterator.js';
+import { createStreamLifecycle } from './stream-lifecycle.js';
+import { AsyncQueue } from './stream-queue.js';
+import { startSource } from './stream-source.js';
+import { createReadableArraySignal, createReadableSignal, reduceText } from './stream-state.js';
+import { normalizeError } from '../shared/utils.js';
+// Create the core stream primitive: a read-only signal plus async iterable plus lifecycle state.
+export function createStream(sourceOrSetup, options = {}) {
+    const { seed = '', reduce = reduceText, backpressure = null } = options;
+    const pressure = normalizeBackpressure(backpressure);
+    const state = createResponse({ seed, reduce });
+    const queue = new AsyncQueue();
+    const readable = createReadableSignal(state.value);
+    const buffered = createSignal(0);
+    const dropped = createSignal(0);
+    const lifecycle = createStreamLifecycle({
+        closeQueue: () => queue.close(),
+        readCurrent: () => readable.peek()
+    });
+    let activeSignal = null;
+    const run = state.run(async ({ signal: runtimeSignal, push, complete, fail, abort }) => {
+        activeSignal = runtimeSignal;
+        function failStream(error) {
+            if (lifecycle.isTerminated()) {
+                return state.error.peek() ?? normalizeError(error);
+            }
+            lifecycle.markTerminated();
+            buffer.flush();
+            queue.fail(error);
+            return fail(error);
+        }
+        const buffer = createStreamBuffer({
+            enqueueChunk: (chunk) => queue.push(chunk),
+            fail: failStream,
+            isTerminated: lifecycle.isTerminated,
+            pressure,
+            readCurrent: () => readable.peek(),
+            recordDrop: () => dropped(dropped.peek() + 1),
+            signal: runtimeSignal,
+            updateBuffered: (count) => buffered(count),
+            writeChunk: push
+        });
+        lifecycle.setCleanup(buffer.flush);
+        // Wrap the response lifecycle so streams can push, fail, or abort through one surface.
+        const controller = {
+            get signal() {
+                return runtimeSignal;
+            },
+            // Queue chunks first, then let the serialized drain loop move them into state/UI.
+            async push(chunk) {
+                return buffer.push(chunk);
+            },
+            // Mark the stream as gracefully finished.
+            done() {
+                return lifecycle.stop(() => complete());
+            },
+            // Surface producer failures to both async consumers and signal readers.
+            fail(error) {
+                return failStream(error);
+            },
+            // Abort the stream and preserve the partial value already accumulated.
+            abort(reason = 'Stream aborted') {
+                return lifecycle.stop(() => abort(reason));
+            }
+        };
+        try {
+            await startSource(sourceOrSetup, controller);
+            await buffer.flushScheduled();
+            if (!lifecycle.isTerminated() && runtimeSignal.aborted) {
+                controller.abort(runtimeSignal.reason ?? 'Stream aborted');
+                return readable.peek();
+            }
+            if (!lifecycle.isTerminated()) {
+                controller.done();
+            }
+            return readable.peek();
+        }
+        catch (error) {
+            const terminalStatus = state.status.peek();
+            if (runtimeSignal.aborted || terminalStatus === 'aborted') {
+                return readable.peek();
+            }
+            if (lifecycle.isTerminated() && terminalStatus !== 'error') {
+                return readable.peek();
+            }
+            throw error;
+        }
+    });
+    // Keep async consumers in sync with failures that surface after startup.
+    run.catch((error) => {
+        if (!queue.closed) {
+            queue.fail(error);
+        }
+    });
+    attachStreamState(readable, state, buffered, dropped, run, lifecycle.stop);
+    // Expose the current AbortSignal so advanced integrations can observe cancellation.
+    Object.defineProperty(readable, 'signal', {
+        enumerable: true,
+        get() {
+            return activeSignal;
+        }
+    });
+    attachStreamIterator(readable, queue, () => !lifecycle.isTerminated() && !state.aborted(), (reason) => readable.abort(reason));
+    return readable;
+}
+function attachStreamState(readable, state, buffered, dropped, run, stopStream) {
+    readable.status = createReadableSignal(state.status);
+    readable.error = createReadableSignal(state.error);
+    readable.chunks = createReadableArraySignal(state.chunks);
+    readable.startedAt = createReadableSignal(state.startedAt);
+    readable.finishedAt = createReadableSignal(state.finishedAt);
+    readable.pending = state.pending;
+    readable.streaming = state.streaming;
+    readable.completed = state.completed;
+    readable.failed = state.failed;
+    readable.aborted = state.aborted;
+    readable.chunkCount = state.chunkCount;
+    readable.snapshot = state.snapshot;
+    readable.buffered = createReadableSignal(buffered);
+    readable.dropped = createReadableSignal(dropped);
+    readable.ready = run;
+    readable.abort = (reason) => stopStream(() => state.abort(reason));
+}

package/dist/src/core/stream-source.d.ts

@@ -0,0 +1,2 @@
+import type { StreamController, StreamInput } from './stream-types.js';
+export declare function startSource<TChunk, TValue>(sourceOrSetup: StreamInput<TChunk, TValue>, controller: StreamController<TChunk, TValue>): Promise<void>;

package/dist/src/core/stream-source.js

@@ -0,0 +1,28 @@
+import { toAsyncIterable } from './iterable.js';
+// Distinguish a setup callback from callable stream or signal-like values.
+function isSetupFunction(sourceOrSetup) {
+    const callableSource = sourceOrSetup;
+    return typeof sourceOrSetup === 'function'
+        && typeof callableSource[Symbol.asyncIterator] !== 'function'
+        && typeof callableSource.peek !== 'function';
+}
+// Pipe any async iterable-like source into the controller, honoring aborts and pacing.
+async function pipeSource(source, controller) {
+    for await (const chunk of toAsyncIterable(source)) {
+        if (controller.signal.aborted) {
+            break;
+        }
+        await controller.push(chunk);
+    }
+}
+// Accept either a setup callback or a pre-existing iterable source.
+export async function startSource(sourceOrSetup, controller) {
+    if (isSetupFunction(sourceOrSetup)) {
+        const maybeSource = await sourceOrSetup(controller);
+        if (maybeSource !== undefined) {
+            await pipeSource(maybeSource, controller);
+        }
+        return;
+    }
+    await pipeSource(sourceOrSetup, controller);
+}

package/dist/src/core/stream-state.d.ts

@@ -0,0 +1,4 @@
+import type { ReadonlySignal } from './signal.js';
+export declare function createReadableSignal<T>(sourceSignal: ReadonlySignal<T>): ReadonlySignal<T>;
+export declare function createReadableArraySignal<T>(sourceSignal: ReadonlySignal<T[]>): ReadonlySignal<T[]>;
+export declare function reduceText(currentValue: string, chunk: unknown): string;

package/dist/src/core/stream-state.js

@@ -0,0 +1,20 @@
+// Expose a response value as a read-only signal surface.
+export function createReadableSignal(sourceSignal) {
+    const read = (() => sourceSignal());
+    read.peek = () => sourceSignal.peek();
+    read.subscribe = (listener, options) => sourceSignal.subscribe(listener, options);
+    return read;
+}
+// Arrays are copied at the public stream boundary so readers cannot mutate internal chunk state.
+export function createReadableArraySignal(sourceSignal) {
+    const read = (() => [...sourceSignal()]);
+    read.peek = () => [...sourceSignal.peek()];
+    read.subscribe = (listener, options) => sourceSignal.subscribe((value) => {
+        listener([...value]);
+    }, options);
+    return read;
+}
+// Text streams concatenate chunks by default so they can drive text nodes directly.
+export function reduceText(currentValue, chunk) {
+    return currentValue + String(chunk ?? '');
+}

package/dist/src/core/stream-types.d.ts

@@ -0,0 +1,61 @@
+import type { ReadonlySignal } from './signal.js';
+import type { GlobalAbortSignal, MaybePromise, ResponseSnapshot, ResponseState, ResponseStatus, SourceLike } from './response.js';
+export type OverflowStrategy = 'wait' | 'drop-oldest' | 'drop-newest' | 'error';
+export interface BackpressureOptions {
+    interval?: number;
+    buffer?: number;
+    overflow?: OverflowStrategy;
+}
+export interface NormalizedBackpressure {
+    interval: number;
+    buffer: number;
+    overflow: OverflowStrategy;
+}
+export interface Deferred<T> {
+    promise: Promise<T>;
+    resolve(value: T | PromiseLike<T>): void;
+    reject(reason?: unknown): void;
+}
+export interface StreamOptions<TChunk = unknown, TValue = string> {
+    seed?: TValue;
+    reduce?: (currentValue: TValue, chunk: TChunk, index: number) => TValue;
+    backpressure?: number | BackpressureOptions | null;
+}
+export interface StreamController<TChunk = unknown, TValue = string> {
+    readonly signal: GlobalAbortSignal;
+    push(chunk: TChunk): Promise<TValue>;
+    done(): TValue;
+    fail(error?: unknown): Error | TValue;
+    abort(reason?: unknown): TValue;
+}
+export type StreamSetup<TChunk, TValue> = (controller: StreamController<TChunk, TValue>) => MaybePromise<void | SourceLike<TChunk>>;
+export type StreamInput<TChunk, TValue> = SourceLike<TChunk> | StreamSetup<TChunk, TValue>;
+export interface QoreStream<TChunk = unknown, TValue = string> extends ReadonlySignal<TValue>, AsyncIterable<TChunk> {
+    status: ReadonlySignal<ResponseStatus>;
+    error: ReadonlySignal<Error | null>;
+    chunks: ReadonlySignal<TChunk[]>;
+    startedAt: ReadonlySignal<number | null>;
+    finishedAt: ReadonlySignal<number | null>;
+    pending: ReadonlySignal<boolean>;
+    streaming: ReadonlySignal<boolean>;
+    completed: ReadonlySignal<boolean>;
+    failed: ReadonlySignal<boolean>;
+    aborted: ReadonlySignal<boolean>;
+    chunkCount: ReadonlySignal<number>;
+    buffered: ReadonlySignal<number>;
+    dropped: ReadonlySignal<number>;
+    snapshot(): ResponseSnapshot<TChunk, TValue>;
+    ready: Promise<TValue>;
+    abort(reason?: unknown): TValue;
+    readonly signal?: GlobalAbortSignal | null;
+}
+export interface StreamFactory {
+    <TChunk = unknown>(sourceOrSetup: StreamInput<TChunk, string>, options?: StreamOptions<TChunk, string>): QoreStream<TChunk, string>;
+    create<TChunk, TValue = string>(sourceOrSetup: StreamInput<TChunk, TValue>, options?: StreamOptions<TChunk, TValue>): QoreStream<TChunk, TValue>;
+    text<TChunk = unknown>(sourceOrSetup: StreamInput<TChunk, string>, options?: StreamOptions<TChunk, string>): QoreStream<TChunk, string>;
+    list<TChunk>(sourceOrSetup: StreamInput<TChunk, TChunk[]>, options?: StreamOptions<TChunk, TChunk[]>): QoreStream<TChunk, TChunk[]>;
+    latest<TChunk>(sourceOrSetup: StreamInput<TChunk, TChunk | null>, options?: StreamOptions<TChunk, TChunk | null>): QoreStream<TChunk, TChunk | null>;
+    withBackpressure<TChunk = unknown, TValue = string>(sourceOrSetup: StreamInput<TChunk, TValue>, backpressure: number | BackpressureOptions, options?: StreamOptions<TChunk, TValue>): QoreStream<TChunk, TValue>;
+    paced<TChunk = unknown, TValue = string>(sourceOrSetup: StreamInput<TChunk, TValue>, interval: number, options?: StreamOptions<TChunk, TValue>): QoreStream<TChunk, TValue>;
+}
+export type StreamResponseState<TChunk, TValue> = ResponseState<TChunk, TValue>;

package/dist/src/core/stream-types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/core/stream.d.ts

@@ -0,0 +1,11 @@
+import type { MaybePromise, SourceLike } from './response.js';
+import type { QoreStream, StreamFactory, StreamOptions } from './stream-types.js';
+export declare const stream: StreamFactory;
+export declare function from<TChunk, TValue = string>(source: SourceLike<TChunk>, options?: StreamOptions<TChunk, TValue> & {
+    delay?: number;
+}): QoreStream<TChunk, TValue>;
+export declare function mapStream<TInput, TOutput, TValue = string>(source: SourceLike<TInput>, mapper: (chunk: TInput, index: number) => MaybePromise<TOutput>, options?: StreamOptions<TOutput, TValue>): QoreStream<TOutput, TValue>;
+export declare function scanStream<TInput, TOutput>(source: SourceLike<TInput>, reducer: (currentValue: TOutput, chunk: TInput, index: number) => MaybePromise<TOutput>, seed: TOutput, options?: Omit<StreamOptions<TOutput, TOutput>, 'seed' | 'reduce'>): QoreStream<TOutput, TOutput>;
+export { createStream } from './stream-runtime.js';
+export type { BackpressureOptions, QoreStream, StreamController, StreamFactory, StreamInput, StreamOptions, StreamSetup } from './stream-types.js';
+export { toAsyncIterable } from './iterable.js';

package/dist/src/core/stream.js

@@ -0,0 +1,90 @@
+import { toAsyncIterable } from './iterable.js';
+import { createStream } from './stream-runtime.js';
+import { reduceText } from './stream-state.js';
+import { sleep } from '../shared/utils.js';
+const streamFactory = ((sourceOrSetup, options = {}) => createStream(sourceOrSetup, {
+    seed: '',
+    reduce: reduceText,
+    ...options
+}));
+// Alias the generic constructor for advanced callers that provide custom reducers.
+streamFactory.create = createStream;
+// Convenience constructor for explicit text streams.
+streamFactory.text = (sourceOrSetup, options = {}) => createStream(sourceOrSetup, {
+    seed: '',
+    reduce: reduceText,
+    ...options
+});
+// Convenience constructor for streams that accumulate every chunk into an array.
+streamFactory.list = (sourceOrSetup, options = {}) => createStream(sourceOrSetup, {
+    seed: [],
+    reduce: (currentValue, chunk) => [...currentValue, chunk],
+    ...options
+});
+// Convenience constructor for streams that only expose the latest chunk as current value.
+streamFactory.latest = (sourceOrSetup, options = {}) => createStream(sourceOrSetup, {
+    seed: null,
+    reduce: (_, chunk) => chunk,
+    ...options
+});
+// Attach backpressure behavior without changing the reducer semantics.
+streamFactory.withBackpressure = (sourceOrSetup, backpressure, options = {}) => createStream(sourceOrSetup, {
+    ...options,
+    backpressure: typeof options.backpressure === 'object' && options.backpressure !== null && typeof backpressure === 'object'
+        ? { ...options.backpressure, ...backpressure }
+        : backpressure
+});
+// Shorthand for the first backpressure primitive: minimum interval between chunks.
+streamFactory.paced = (sourceOrSetup, interval, options = {}) => streamFactory.withBackpressure(sourceOrSetup, { interval }, options);
+// Create a text-accumulating stream by default.
+export const stream = streamFactory;
+// Turn any iterable or async iterable into a stream, optionally adding source delay.
+export function from(source, options = {}) {
+    const { delay = 0, ...streamOptions } = options;
+    return createStream(async (controller) => {
+        for await (const chunk of toAsyncIterable(source)) {
+            if (controller.signal.aborted) {
+                break;
+            }
+            if (delay > 0) {
+                await sleep(delay, controller.signal);
+            }
+            await controller.push(chunk);
+        }
+    }, streamOptions);
+}
+// Map source chunks into a new stream while preserving stream semantics.
+export function mapStream(source, mapper, options = {}) {
+    return createStream(async (controller) => {
+        let index = 0;
+        for await (const chunk of toAsyncIterable(source)) {
+            if (controller.signal.aborted) {
+                break;
+            }
+            await controller.push(await mapper(chunk, index));
+            index += 1;
+        }
+    }, options);
+}
+// Emit a running reduction so each chunk sees the accumulated state so far.
+export function scanStream(source, reducer, seed, options = {}) {
+    return createStream(async (controller) => {
+        let index = 0;
+        let current = seed;
+        for await (const chunk of toAsyncIterable(source)) {
+            if (controller.signal.aborted) {
+                break;
+            }
+            current = await reducer(current, chunk, index);
+            await controller.push(current);
+            index += 1;
+        }
+    }, {
+        seed,
+        reduce: (_, chunk) => chunk,
+        ...options
+    });
+}
+// Re-export the iterable helper so integrations can normalize external sources.
+export { createStream } from './stream-runtime.js';
+export { toAsyncIterable } from './iterable.js';