Provides fluent api operations on iterables and async iterables - similar to what defined on arrays. Especially useful until relevant ESNext features are being delivered.
Description
The library provides the common transformation, filtering and aggregation operations on iterables and async iterables. Supported operations include:
- Item-by-item transformations like map, withIndex
- Group transformations like flatten, group, partition, repeat, sort
- Extending operations like append, prepend, concat
- Narrowing operations like filter, take, skip, distinct, first, last
- Aggregating operations like reduce, toArray, toObject, join
- Numeric aggregating operations like count, max, min, sum, avg
- Logical aggregating operations like all, any, contains
- Execution operations like execute, forEach
Quick start guide
Install from Node Package Manager: npm i fluent-iterable
Add the following code to your index file (ts example):
; ;; console.log`The largest even number is: `;
Usage
Click here for the Full API Reference.
Basics
ECMAScript introduced support for iterables and generator functions with version ES6 and their asynchronous counterparts with version ES2018. It has introduced an abstraction over sequential iterators (arrays, maps, generators, etc), enabling us to implement solutions regardless of the actual type of the iterable collection. It is especially powerful when using in tandem with generator functions to avoid storing all items in memory when its avoidable. The API provided by fluent-iterable reads the elements of the underlying iterable only when needed and stops reading elements as soon as the result is determined.
To get started with the fluent API, you need to translate the iterable (can be any object with Symbol iterator or asyncIterator defined) into either a FluentIterable using fluent() or a FluentAsyncIterable using fluentAsync().
;; ; ; ;
Once you have an instance of a fluent iterable, you can start chaining any of the supported operations to express what you need, like:
... ...
Utils
The API provides some utility functions to help working with iterables.
Interval
The interval() function generates a continuous and unique sequence of numbers. If no arguments provided, the sequence starts at zero and generates infinite numbers.
Note: remember, generator functions are state machines, calling the function will not actually generate the numbers. They are generated on the fly until new number are being read from it:
; ;; for of iterable.take10 // close the generator // this function would cause an infinite loop:// for (const number of iterable.take(10)) { // generate infinite number of numbers one-by-one// console.log(number);// }
Depaginator
The depaginate() is a handy little generator function when it comes down to dealing paginated resources. It is designed to translate the paginated resource into a non-paginated iterable of elements. The function takes one parameter of type Pager, which defines how to retrieve a single page from the resource.
; // The type of the data stored in the paginated resource; // The type of the next page token (e.g. page number, DDB token string, etc) // These functions return a page of items from the resource in the form of { nextPageToken: NextPageToken, results: Data[] } ; ; // as long as you keep read items from this it will keep requesting pages to fulfil the reads; // you can read up to 10 items from this and it will request exactly as many pages as necessary to fulfill the reads // ... you get the picture
Examples
Playing with Fibonacci generator
; // What is the sum of the first 100 fibonacci numbers?console.log fluentnaiveFibonacci .takeWhilen < 100 .sum; // How many fibonacci numbers are there between 1K and 1M?console.log fluentnaiveFibonacci .skipWhilen < 1000 .takeWhilen < 1000000 .count; // What are the 10th to 20th fibonacci numbers?console.log fluentnaiveFibonacci .skip9 .take10 .toArray; // What are the halves of the first 20 even fibonacci numbers?console.log fluentnaiveFibonacci .filtern % 2 === 0 .take20 .mapn / 2 .toArray;
Playing with object arrays
; ; // Log all the names!for of fluentpeople.mapp.name // Log all the emails!console.log fluentpeople .flattenp.emails .toArray; // Are there any persons without gender specified?console.logfluentpeople.any!p.gender; // Are all the persons have at least one email?console.logfluentpeople.allp.emails.length > 0; // Who is the last female?console.logfluentpeople.lastp.gender === Gender.Female; // Who is the last one in lexicographical order?console.log fluentpeople .sorta.name.localeCompareb.name .last; // Log all persons grouped by gender!console.log fluentpeople .groupp.gender .map .reduce`\n`, '';
Playing with remote
;; ; // Get the first 10 emails sorted!fluentAsyncdepaginatepager .mapdata.email .take10 .sort .forEachconsole.logres .thenconsole.log'done';
Bonus: How to Scan DynamoDB like a pro
;;; // and use it like this: ;
License
Licensed under MIT.