Dev release 0.4.10 (#9)

* Added flatMap operator.

CHANGELOG.md

@@ -23,6 +23,12 @@ cfr. [keepachangelog.com](https://keepachangelog.com/en/1.1.0/)
 
 ### Security
 
+## version 0.4.10 (2024-08-29)
+
+### Added
+
+- flatMap operator
+
 ## version 0.4.9 (2024-08-27)
 
 ### Added

src/operators/general/distribute.ts

@@ -8,8 +8,8 @@ import { isPromise } from "../../util/index.js";
  * The child iterator depends on the 'category' that is determined by the first element
  * of the tuple.
  *
- * Imagine things like: I need to calculate the averages 'per schoolyear'.
- * That would mean, categorize per schoolyear, and then calculate the average
+ * Imagine things like: I need to calculate the averages 'per year'.
+ * That would mean, categorize per year, and then calculate the average
  * of the inner iterators by using a map after distribute.
  *
  * If you are not going to use all output iterators, make sure to filter out
@@ -30,8 +30,8 @@ import { isPromise } from "../../util/index.js";
  *  - It could make sense to create a version that can handle multiple categories per value.
  *    Like for instance: divisible by 2, divisible by 3, divisible by 5, etc.
  *    where some values can be in multiple categories.
- *    This could also be done by making a categorize operator that can produce multiple tuples
- *    for each input, which would keep this operator simple.
+ *    This could also be done by using a flatMap to categorize the values into multiple categories
+ *    for each input, which keeps this operator simple.
  *
  * ```
  * ┌───────────────────────────────────────────────────────────┐
@@ -58,25 +58,41 @@ import { isPromise } from "../../util/index.js";
  *
  * @example
  * ```typescript
- * await pipe(
- *        itr8ange(1, 1000),
- *        map( (v) => [ v % 2 === 0 ? 'even' : 'odd', v ] as [string, number] ), // add the category to the value
- *        // adding the category first allows us to easily filter out categories we don't need
- *        distribute(),
- *        map(([category, iterator]) => ({
- *          category,
- *          values: pipe(
- *            iterator,
- *            take(2),
- *            toArray,
- *          ),
- *        })),
+ *  // one value has one category
+ *  pipe(
+ *    itr8ange(1, 1000),
+ *    map( (v) => [ v % 2 === 0 ? 'even' : 'odd', v ] as [string, number] ), // add the category to the value
+ *    // adding the category first allows us to easily filter out categories we don't need
+ *    distribute(),
+ *    map(([category, iterator]) => ({
+ *      category,
+ *      values: pipe(
+ *        iterator,
+ *        take(2),
  *        itr8ToArray,
- *      )
+ *      ),
+ *    })),
+ *    itr8ToArray,
+ *  )
  * // => [
  * //   { category: 'odd', values: [ 1, 3 ] },
  * //   { category: 'even', values:  [ 2, 4 ] },
  * // ]
+ *
+ * // one value has multiple categories (divisible by 2, 3, 4)
+ * pipe(
+ *  itr8Range(1, 1000),
+ *  flatMap(function* (v) {
+ *    if (v % 2 === 0) yield ['divisable by 2', v]; // 2, 4, 6, 8, 10, ...
+ *    if (v % 3 === 0) yield ['divisible by 3', v]; //  3,   6,   9, 12, 15, ...
+ *    if (v % 4 === 0) yield ['divisible by 4', v]; //    4,    8,   12,   16, ...
+ *   }),
+ *  distribute(),
+ *  map(([category, iterator]) => ({
+ *    category,
+ *    values: itr8ToArray(iterator),
+ *  }),
+ * );
  * ```
  *
  * @category operators/general