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 | <U>(fn: (item: T, i: number) => MaybePromise<U[] | U>) => Stream<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