Provides LINQ-like fluent api operations for iterables and async iterables (ES2018+).
npm install fluent-iterable!CI
Provides fluent api operations on iterables and async iterables - similar to what defined on arrays. Especially useful until relevant ESNext features are being delivered.
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
Install from Node Package Manager: npm i fluent-iterable
Add the following code to your index file (ts example):
``typescript
import fluent, { FluentIterable } from 'fluent-iterable';
const numbers: number[] = [3, 1, 8, 6, 9, 2];
const iterable: FluentIterable
console.log(The largest even number is: ${iterable.filter(n => n % 2 === 0).max()});`
Click here for the Full API Reference.
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().
`typescript
import fetch from 'node-fetch';
import fluent, { fluentAsync, FluentIterable, FluentAsyncIterable } from 'fluent-iterable';
const iterableOfArray: FluentIterable
function* naiveFibonacci(): Iterable
yield 0;
yield 1;
let x = 0;
let y = 1;
while (true) {
y = x + y;
x = y - x;
yield y;
}
}
const iterableOfGenerator: FluentIterable
async function* emails(): AsyncIterable
let page = 1;
while (true) {
const res = await fetch(https://reqres.in/api/users?page=${page});
if (!res.ok) {
break;
}
yield* (await res.json()).data.map(user => user.email);
}
}
const asyncIterableOfEmails: FluentAsyncIterable
`
Once you have an instance of a fluent iterable, you can start chaining any of the supported operations to express what you need, like:
`typescript
...
interface ChatMessage {
id: number;
from: string;
to: string;
body: string;
}
...
function getAllMessages(iterable: FluentAsyncIterable
return iterable.map(chatMessage => chatMessage.body);
}
function getAllUsers(iterable: FluentAsyncIterable
return iterable
.flatten(chatMessage => [ chatMessage.from, chatMessage.to ]) // convert the message entries into arrays of sender and recipient and flatten them
.distinct(); // yield the users only once
}
function getNumberOfUsers(iterable: FluentAsyncIterable
return getAllUsers(iterable).count();
}
async function getMostActiveUser(iterable: FluentAsyncIterable
const maxGroup: FluentGroup
.group(chatMessage => chatMessage.from) // group the messages by their sender
.max(chatMessage => chatMessage.values.count()); // find one of the groups which has the most messages
return maxGroup.key;
}
async function hasUserSentEmptyMessage(iterable: FluentAsyncIterable
return await iterable
.any(chatMessage => chatMessage.from === user && chatMessage.body.length === 0); // will stop reading elements as soon as found one which satisfying the condition
}
async function createBackupSequential(iterable: FluentAsyncIterable
await iterable
.execute(chatMessage => console.log(Backing up message ${chatMessage.id}.)) // log progress w/o modifying the iterable
.forEachAsync(chatMessage => fetch(BACKUP_URL, { // execute the asynchronous backup operation against all elements one-by-one
method: 'post',
body: JSON.stringify(chatMessage),
headers: { 'Content-Type': 'application/json' },
}));
}
async function createBackupParallel(iterable: FluentAsyncIterable
const promises = iterable
.execute(chatMessage => console.log(Backing up message ${chatMessage.id}.)) // log progress w/o modifying the iterable`
.map(chatMessage => fetch(BACKUP_URL, { // translate all elements into a promise of their asynchronous backup operation
method: 'post',
body: JSON.stringify(chatMessage),
headers: { 'Content-Type': 'application/json' },
}));
await Promise.all(promises);
}
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:
`typescript
import fluent, { interval } from 'fluent-iterable';
const numbers: Iterable
const iterable: FluentIterable
for (const number of iterable.take(10)) { // generate the first 10 numbers one-by-one
console.log(number);
} // 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.
`typescript
import { fluentAsync, depaginate, Page, Pager } from 'fluent-iterable';
interface Data { .. } // The type of the data stored in the paginated resource
type NextPageToken = ..; // 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[] }
async function getFirstPage(): Promise
async function getPage(nextPageToken: NextPageToken): Promise
const pager: Pager
const allItems: AsyncIterable = depaginate(pager); // as long as you keep read items from this it will keep requesting pages to fulfil the reads
const firstItems: FluentAsyncIterable = fluentAsync(depaginate(pager)).take(10); // 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
`
#### Playing with Fibonacci generator
`typescript
import fluent from 'fluent-iterable';
function* naiveFibonacci(): Iterable
yield 0;
yield 1;
let x = 0;
let y = 1;
while (true) {
y = x + y;
x = y - x;
yield y;
}
}
// What is the sum of the first 100 fibonacci numbers?
console.log(
fluent(naiveFibonacci())
.takeWhile(n => n < 100)
.sum()
);
// How many fibonacci numbers are there between 1K and 1M?
console.log(
fluent(naiveFibonacci())
.skipWhile(n => n < 1000)
.takeWhile(n => n < 1000000)
.count()
);
// What are the 10th to 20th fibonacci numbers?
console.log(
fluent(naiveFibonacci())
.skip(9)
.take(10)
.toArray()
);
// What are the halves of the first 20 even fibonacci numbers?
console.log(
fluent(naiveFibonacci())
.filter(n => n % 2 === 0)
.take(20)
.map(n => n / 2)
.toArray()
);
`
#### Playing with object arrays
`typescript
import fluent from 'fluent-iterable';
enum Gender {
Male = 'Male',
Female = 'Female',
NonBinary = 'NonBinary',
}
interface Person {
name: string;
gender?: Gender;
emails: string[];
}
const people: Person[] = [
{
name: 'Adam',
gender: Gender.Male,
emails: ['adam@adam.com'],
},
{
name: 'Christine',
gender: Gender.Female,
emails: [],
},
{
name: 'Sebastian',
emails: ['sebastian@sebastian.com', 'sebastian@corp.com'],
},
{
name: 'Alex',
gender: Gender.Female,
emails: ['alex@alex.com'],
},
];
// Log all the names!
for (const name of fluent(people).map(p => p.name)) {
console.log(name);
}
// Log all the emails!
console.log(
fluent(people)
.flatten(p => p.emails)
.toArray()
);
// Are there any persons without gender specified?
console.log(fluent(people).any(p => !p.gender));
// Are all the persons have at least one email?
console.log(fluent(people).all(p => p.emails.length > 0));
// Who is the last female?
console.log(fluent(people).last(p => p.gender === Gender.Female));
// Who is the last one in lexicographical order?
console.log(
fluent(people)
.sort((a, b) => a.name.localeCompare(b.name))
.last()
);
// Log all persons grouped by gender!
console.log(
fluent(people)
.group(p => p.gender)
.map(
grp =>
${fluent(grp.values)
.map(p => p.name)
.toArray()
.join(', ')} is/are ${grp.key}
)
.reduce((current, next) => , '')`
);
#### Playing with remote
`typescript
import fetch from 'node-fetch';
import { fluentAsync, Pager } from 'fluent-iterable';
interface Data {
id: number;
email: string;
avatar: string;
}
const pager: Pager
const page = token || 1;
const res = await fetch(https://reqres.in/api/users?page=${page});
return {
results: res.ok ? (await res.json()).data : undefined,
nextPageToken: page + 1,
};
};
// Get the first 10 emails sorted!
fluentAsync(depaginate(pager))
.map(data => data.email)
.take(10)
.sort()
.forEach(res => console.log(res))
.then(() => console.log('done'));
`
#### Bonus: How to Scan DynamoDB like a pro
`typescript
import { DynamoDB } from 'aws-sdk';
import { Key } from 'aws-sdk/clients/dynamodb';
import { depaginate, fluentAsync, Pager } from 'fluent-iterable';
async function *scan
input: DynamoDB.DocumentClient.ScanInput
): AsyncIterable
const ddb = new DynamoDB.DocumentClient(..);
const pager: Pager
const result = await ddb
.scan(input)
.promise();
return {
nextPageToken: result.LastEvaluatedKey,
results: result.Items as TData[],
};
};
yield* depaginate(pager);
}
// and use it like this:
const productsParams: DynamoDB.DocumentClient.ScanInput = {
TableName : 'ProductTable',
FilterExpression : '#shoename = :shoename', // optional
ExpressionAttributeValues : {':shoename' : 'yeezys'}, // optional
ExpressionAttributeNames: { '#shoename': 'name' } // optional
};
async function printProducts(count: number) {
for await (const product of fluentAsync(scan(productsParams)).take(count)) {
console.dir(product);
}
}
``
Licensed under MIT.