from-array

(no submodules)

Purpose

Converts a JavaScript array into a WHATWG ReadableStream. Each array element is enqueued as a separate chunk in index order. The stream is closed automatically after all elements are pushed. This factory is the simplest entry point for creating a stream from in-memory data and is the building block for test fixtures and benchmark pipelines throughout the package.

The highWaterMark option controls the WHATWG backpressure queue depth. Keeping it at the default (1) applies maximum backpressure, ensuring the consumer controls the pull rate. Higher values pre-buffer more chunks, which is useful when the consumer is consistently slower than the source.

Features

Converts any T[] to ReadableStream<T>
AbortSignal support: errors the stream immediately when the signal fires
Configurable highWaterMark via ReadableOptions
Zero external runtime dependencies

Usage: Basic Example

import { fromArray } from "@suaveplan/streams/readable/from-array/from-array";

const stream = fromArray([1, 2, 3]);
const reader = stream.getReader();

let result;
while (!(result = await reader.read()).done) {
  console.log(result.value); // 1, 2, 3
}

Usage: Advanced Example

import { fromArray } from "@suaveplan/streams/readable/from-array/from-array";
import { mapStream } from "@suaveplan/streams/transforms/map-stream/map-stream";
import { toArray } from "@suaveplan/streams/sinks/to-array/to-array";

const ac = new AbortController();
const stream = fromArray(["a", "b", "c"], { signal: ac.signal, highWaterMark: 4 });
const result = await toArray(stream.pipeThrough(mapStream((x) => x.toUpperCase())));
console.log(result); // ["A", "B", "C"]

// Cancellation: abort mid-flight
const longStream = fromArray(new Array(1_000_000).fill(0), { signal: ac.signal });
ac.abort();
const reader = longStream.getReader();
const { done } = await reader.read().catch(() => ({ done: true }));
console.log(done); // true (stream was aborted)

API Reference

`fromArray<T>(items: T[], options?: ReadableOptions): ReadableStream<T>`

Parameters:

items — the source array; elements are enqueued in insertion order.
options.signal — optional AbortSignal; errors the stream on abort.
options.highWaterMark — WHATWG queue depth (default: 1).

Returns: ReadableStream<T> that emits each element and then closes.

Throws: never directly; the stream's reader will throw the abort reason when the signal fires.

Implementation Notes

The pull callback checks signal.aborted on every pull cycle rather than using an abort event listener. This avoids the need to clean up listeners and keeps the implementation leak-free. When the signal fires between two pull cycles the worst case is one additional chunk being enqueued before the abort is detected — this is acceptable because WHATWG streams do not guarantee atomic cancellation at the chunk boundary.

3.0 KiB Raw Blame History