use-array-stream

react-use-stream

A React hook for Java Stream-inspired chainable operations with parallel execution, set utilities, numeric helpers, and developer-friendly utilities.

Installation

npm install react-use-stream

## Features

- Map, filter, flatMap, reduce
- Distinct, sorting, chunking
- Parallel async operations (parallelMap, parallelFilter, partitionBy)
- Advanced set operations: diff (difference), common (intersection), sampling
- Statistical utilities: sum, average, min, max
- Fluent API, eagerly/easily chainable

Methods

Method	Description	Example
map(fn)	Transform each element	useStream([1,2,3]).map(x => x * 2).toArray(); // [2,4,6]
filter(fn)	Filter by predicate	useStream([1,2,3,4]).filter(x => x % 2 === 0).toArray(); // [2,4]
flatMap(fn)	Map and flatten	useStream([1,2]).flatMap(x => [x, x * 10]).toArray(); // [1,10,2,20]
distinct()	Remove duplicates	useStream([1,2,2,3]).distinct().toArray(); // [1,2,3]
distinctBy(fn)	Unique by key	useStream([{id:1},{id:2},{id:1}]).distinctBy(x => x.id).toArray(); // [{id:1},{id:2}]
sorted(fn?)	Sort elements	useStream([3,1,2]).sorted().toArray(); // [1,2,3]
sortBy(fn, asc?)	Sort by key	useStream([{val:3},{val:1}]).sortBy(x => x.val).toArray(); // [{val:1},{val:3}]
limit(n)	Take first n elements	useStream([1,2,3,4]).limit(2).toArray(); // [1,2]
skip(n)	Skip first n elements	useStream([1,2,3,4]).skip(2).toArray(); // [3,4]
parallelMap(fn)	Async map in parallel	await useStream([1,2,3]).parallelMap(async x => x * 2)
parallelFilter(fn)	Async filter in parallel	await useStream([1,2,3,4]).parallelFilter(async x => x % 2 === 0)
partitionBy(fn)	Partition async	await useStream([1,2,3,4]).partitionBy(async x => x % 2 === 0)
reduce(fn, init)	Reduce to single value	useStream([1,2,3]).reduce((a, x) => a + x, 0); // 6
toArray()	Get array	useStream([1,2,3]).toArray(); // [1,2,3]
diff(arr)	Array difference	useStream([1,2,3,4]).diff([3,4,5]).toArray(); // [1,2]
diffBy(arr, fn)	Difference by key	useStream([{id:1},{id:2}]).diffBy([{id:2}], x => x.id).toArray(); // [{id:1}]
common(arr)	Array intersection	useStream([1,2,3]).common([2,3,4]).toArray(); // [2,3]
commonBy(arr, fn)	Intersection by key	useStream([{id:1},{id:2}]).commonBy([{id:2}], x => x.id).toArray(); // [{id:2}]
chunk(n)	Split into chunks	useStream([1,2,3,4]).chunk(2).toArray(); // [[1,2],[3,4]]
shuffle()	Randomize order	useStream([1,2,3]).shuffle().toArray(); // random order
tap(fn)	Side-effect on each element	useStream([1,2]).tap(console.log).toArray();
first()	Get first element	useStream([1,2,3]).first(); // 1
last()	Get last element	useStream([1,2,3]).last(); // 3
sample(n)	Random n elements	useStream([1,2,3,4]).sample(2); // random 2 elements
find(fn)	Find one by predicate	useStream([1,2,3]).find(x => x > 1); // 2
findAll(fn)	Find all by predicate	useStream([1,2,3,4]).findAll(x => x % 2 === 0).toArray(); // [2,4]
includes(val)	Check if included	useStream([1,2,3]).includes(2); // true
some(fn)	Any match?	useStream([1,2,3]).some(x => x > 2); // true
every(fn)	All match?	useStream([1,2,3]).every(x => x > 0); // true
asType()	Cast stream type	useStream([1,2,3]).asType<string>();
sum()	Sum elements	useStream([1,2,3]).sum(); // 6
average()	Average elements	useStream([1,2,3]).average(); // 2
min()	Minimum value	useStream([1,2,3]).min(); // 1
max()	Maximum value	useStream([1,2,3]).max(); // 3

Examples

// Parallel Map
async function exampleParallelMap() {
const items = ;
const result = await useStream(items)
.parallelMap(async x => {
await new Promise(res => setTimeout(res, 1000)); // simulated delay
return x * 2;
});
console.log(result.toArray()); //
}

// Parallel Filter
async function exampleParallelFilter() {
const items = ;
const filtered = await useStream(items)
.parallelFilter(async x => {
await new Promise(res => setTimeout(res, 500));
return x % 2 === 0;
});
console.log(filtered.toArray()); //
}

// Partition By
async function examplePartitionBy() {
const items = ;
const partitioned = await useStream(items)
.partitionBy(async x => {
await new Promise(res => setTimeout(res, 300));
return x % 2 === 0;
});
console.log(partitioned); // { true: , false: }
}

Parallel Execution Notes

- `parallelMap`, `parallelFilter`, and `partitionBy` execute asynchronous operations concurrently for improved throughput.
- Large arrays are broken into manageable chunks to improve performance and memory usage.

TypeScript Types

Below is a type table of the core API:

Method	Type Signature
map	<U>(fn: (item: T, i: number) => MaybePromise<U>) => Stream<U>
filter	(fn: (item: T, i: number) => MaybePromise<boolean>) => Stream<T>
flatMap	`(fn: (item: T, i: number) => MaybePromise<U[]
distinct	() => Stream<T>
distinctBy	(fn: (item: T) => any) => Stream<T>
sorted	(compareFn?: (a: T, b: T) => number) => Stream<T>
sortBy	(fn: (item: T) => any, ascending?: boolean) => Stream<T>
limit	(count: number) => Stream<T>
skip	(count: number) => Stream<T>
parallelMap	<U>(fn: (item: T, i: number) => MaybePromise<U>) => Promise<Stream<U>>
parallelFilter	(fn: (item: T, i: number) => MaybePromise<boolean>) => Promise<Stream<T>>
partitionBy	(fn: (item: T) => MaybePromise<boolean>) => Promise<{ true: T[]; false: T[] }>
reduce	<U>(fn: (acc: U, item: T, i: number) => U, init: U) => U
toArray	() => T[]
diff	(otherArray: T[]) => Stream<T>
diffBy	(otherArray: T[], fn: (item: T) => any) => Stream<T>
common	(otherArray: T[]) => Stream<T>
commonBy	(otherArray: T[], fn: (item: T) => any) => Stream<T>
chunk	(size: number) => Stream<T[]>
shuffle	() => Stream<T>
tap	(fn: (item: T, i: number) => void) => Stream<T>
first	() => T | undefined
last	() => T | undefined
sample	(n: number) => T[]
find	(fn: (item: T, i: number) => boolean) => T | undefined
findAll	(fn: (item: T, i: number) => boolean) => Stream<T>
includes	(value: T) => boolean
some	(fn: (item: T, i: number) => boolean) => boolean
every	(fn: (item: T, i: number) => boolean) => boolean
asType	<U>() => Stream<U>
sum	() => number
average	() => number
min	() => number
max	() => number

## License
MIT © 2025