Fluent Streams is a JavaScript and TypeScript library that offers a rich API for lazily processing iterables such as arrays, sets, and more. At its core is the Stream, a lightweight, stateless wrapper around an iterable. The library also includes Optional, which represents a value that may or may not exist.
The library's primary goal is to provide an API that closely mirrors JavaScript's Array, while introducing a variety of additional, powerful methods inspired by libraries like Ramda and Underscore.
npm i fluent-streamsThe stream() function is the primary entry point for creating a stream from an iterable or generator function. Refer to the documentation for additional ways to create Stream or Optional.
import { abc, stream } from 'fluent-streams'
// Check if it's really a pangram
stream('The quick brown fox jumps over the lazy dog')
.filter(c => c !== ' ')
.map(c => c.toLowerCase())
.distinctBy(c => c)
.sort()
.equals(abc())
// => true, indeed a pangramNote that we created a stream from the string — this is possible because strings implement the iterable protocol, just like Arrays and Sets. More examples.
Fluent Streams is not the first library to offer this kind of functionality, but it stands out for several reasons:
- Prioritizes Standard Array and Iteration Protocols:
Streamfollows familiarArraynaming and method signatures, enabling seamless integration or removal.StreamandOptionalimplement theIterableprotocol, making them compatible with JavaScript constructs such asfor-ofloops and spread syntax.- The library is optimized for arrays. If the input is an array, it will iterate faster and consume less memory.
- Compact Size:
- Minified: 9.4 kB
- Gzipped: 3.2 kB
- Bundlephobia report
- Includes
Optional:- Clearly distinguishes between
nullorundefinedas a value, and the absence of a value. - Allows conversion of
Optionalback toStreamto continue the fluent pipeline.
- Clearly distinguishes between
- Extensive Testing:
- Over 200 tests rigorously cover 100% of the library's source code, validating various stream types in multiple combinations.
- Laziness and statelessness are also thoroughly tested.
Fluent Streams relies on widely available ES6+ features, such as generators, spread operators, for-of loops, and arrow functions. The library doesn't use newly available features, or features with limited availability. The library is shipped untranspiled to ES5.
Why? Modern language features have concise syntax, helping to minimize the bundle size.
While it is possible to transpile the library to ES5 and polyfill it, this is not recommended, as it may increase the library footprint in the bundle by 2.5 to 3 times.
The library demonstrates generally reasonable performance, though it is slightly slower in some benchmarks. This can be attributed to the following factors:
- Use of Generators. While they allow for iteration with very compact syntax, generators are typically slightly slower than simple iterators.
- Standard Iteration Protocol. Ensures compatibility with
for-ofloops, spread syntax, and other language features, though custom protocols can be faster at the cost of losing these benefits.
Fluent Streams was inspired by several great libraries:
This library is provided under the ISC license.