iterable-linq-utility 0.7.0 → 0.9.0

package/README.md

@@ -59,6 +59,26 @@ pnpm bench chains                 # only the chains
 BENCH_TIME=1000 pnpm bench        # more time for each case (default 500 ms): more samples, less noise
 ```
 
+### Report
+
+A pull request that adds an operation or changes its performance pastes the report in its description, as it is:
+
+```sh
+pnpm bench:report functions/sum                       # the same filter as pnpm bench
+BENCH_HOST="MacBook Pro M3" pnpm bench:report functions/sum   # names the host, which a container cannot see
+```
+
+```text
+Environment: Alpine Linux v3.24 (Docker), arm64, 12 cores, CPU unknown · host MacBook Pro M3 · Node v24.20.0 · Vitest 5.0.2 · BENCH_TIME 500 ms · commit 2fba44d
+
+| case | variant | ops/s | mean (ms) | p75 (ms) | p99 (ms) | rme | vs native |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| sum/map | native | 567 | 1.79 | 1.76 | 3.64 | ±2.5% | — |
+| sum/map | chain | 855 | 1.2 | 1.26 | 1.76 | ±1.8% | +51% |
+```
+
+`vs native` compares the ops/s with the `native` case of the same group. When a baseline exists, a `vs baseline` column compares them with it. [ADR 0021](docs/decisions/0021-benchmark-standards.md) explains the format.
+
 ### Find regressions
 
 A baseline is a saved run. Each table shows it as extra rows, marked `(baseline)`, next to the new run.
@@ -68,6 +88,7 @@ git switch main
 pnpm bench:baseline               # saves every result in .bench/
 git switch my-branch
 pnpm bench                        # shows each case next to its "(baseline)" row
+pnpm bench:report functions/sum   # or the report, with a "vs baseline" column
 ```
 
 The timings depend on the machine, so `.bench/` is not committed and the benchmarks do not run in CI. Create the baseline and the new run on the same machine, with the same load.
@@ -76,7 +97,7 @@ The timings depend on the machine, so `.bench/` is not committed and the benchma
 
 | Column | Meaning |
 |---|---|
-| `hz` | runs per second: higher is faster |
+| `hz` | runs per second (ops/s in the report): higher is faster |
 | `mean`, `p75`, `p99` | time of one run, in ms |
 | `rme` | relative margin of error |
 | `samples` | how many runs were measured |
@@ -85,26 +106,28 @@ A difference smaller than the `rme` of the two rows is noise.
 
 ### Add a benchmark
 
-Create `test/bench/functions/<name>.bench.ts` or `test/bench/chains/<scenario>.bench.ts`:
+Create `test/bench/functions/<name>.bench.ts`. `scenarios()` registers the standard groups of [ADR 0021](docs/decisions/0021-benchmark-standards.md) and [ADR 0022](docs/decisions/0022-benchmark-scenarios-in-practice.md): `<name>/direct` on `numbers`, `<name>/small` on `small`, `<name>/map` and `<name>/filter` after `map(double)` and `filter(isEven)`. `group()` adds one more group on `numbers`: an early exit (`start`, `middle`) or an optional callback.
 
 ```ts
-import { test } from 'vitest';
 import * as Helpers from '../helpers';
 
 import * as IterableLinq from 'iterable-linq-utility';
 
 // Read the exports once: an imported binding goes through a module runner getter on every read.
-const { from } = IterableLinq;
-const { cases, numbers, sum } = Helpers;
-
-test('map: number', async ({ bench }) => {
-	await cases(bench, 'map/number')      // the baseline folder: <function>/<variant>
-		.add('native', () => sum(numbers.map(v => v * 2)))
-		.add('chain', () => sum(from(numbers).map(v => v * 2)))
-		.run();
+const { Functions } = IterableLinq;
+const { double, scenarios, sum } = Helpers;
+
+scenarios('map', {
+	native: values => sum(values.map(double)),       // an array
+	chain: chain => sum(chain.map(double)),          // a chain
+	Functions: values => sum(Functions.map(values, double))   // an iterable
 });
 ```
 
+- `native` is the array method a user would write. Add `loop`, a hand-written `for…of`, when the array method is a different algorithm (`reduce` for `sum`); when there is no array method, `native` is the loop.
+- `pnpm check:structure` fails when the bench of an operation has no `direct` or `small` group. `test/bench/functions/sum.bench.ts` is the example.
+- The benches of `test/bench/chains/<scenario>.bench.ts`, and the groups that need other data, use `cases(bench, '<function>/<group>')` directly: the id is also the baseline folder.
+
 - Every table needs at least two cases: add a native reference.
 - Import the library and the helpers as namespaces and copy the exports into local constants, as above. Vitest prints a `Benchmark Warning` when a benchmark reads an imported binding too many times.
-- The shared data is in `test/bench/helpers.ts`: `numbers` (100,000 integers), `records` (100,000 objects) and `small` (1,000 integers).
+- The shared data is in `test/bench/helpers.ts`: `numbers` (100,000 integers) for every scenario, `small` (1,000 integers) for `<name>/small`, `records` (100,000 objects) only for a key or a selector on objects. The callbacks and values of the scenarios are there too: `double`, `isEven`, `first`, `middle`, `missing`.

package/dist/index.d.cts

@@ -6,6 +6,22 @@
  */
 export declare type Action<T> = (value: T, index: number) => Unit;
 
+/**
+ * Lazily yields the values of `iterable`, then `value`.
+ * `value` is yielded only when the source ends, so it is never reached on an infinite source.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param value - the value yielded after the last value of the source
+ * @returns a lazy, re-runnable `Iterable` of the values of the source followed by `value`
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.append([1, 2, 3], 4)); // [1, 2, 3, 4]
+ * ```
+ * @since 0.8.0
+ */
+declare function append<T>(iterable: Iterable<T>, value: T): Iterable<T>;
+
 /**
  * Callback of `forEachAsync`: an async side effect run on each value.
  * @param value - the current value
@@ -103,6 +119,23 @@ declare type ComparerFunction<T> = (a: T, b: T) => number;
 
 declare type ComparingProps<T> = keyof T | Array<keyof T>;
 
+/**
+ * Lazily yields the values of `iterable`, then the values of each iterable in `others`, in order.
+ * Each iterable is opened only when the previous one ends, so the iterables after an infinite one are never read.
+ * Stopping early closes only the iterable being read.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param others - the iterables read after the source
+ * @returns a lazy, re-runnable `Iterable` of the values of the source followed by the values of `others`
+ * @throws Error if `iterable` or a value of `others` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.concat([1, 2], [3], new Set([4, 5]))); // [1, 2, 3, 4, 5]
+ * ```
+ * @since 0.8.0
+ */
+declare function concat<T>(iterable: Iterable<T>, ...others: Iterable<T>[]): Iterable<T>;
+
 /**
  * Counts the values of `iterable`; reads the whole source.
  * @operation `Action`
@@ -451,9 +484,11 @@ export declare function fromRange(start: number, end: number, options?: IRangeOp
 
 declare namespace Functions {
     export {
+        append,
         at,
         average,
         collectToArray,
+        concat,
         count,
         distinct,
         empty_2 as empty,
@@ -476,16 +511,21 @@ declare namespace Functions {
         memoize,
         getMemoizeDefaultOptions,
         min,
+        prepend,
         range,
         reduce,
         repeat_2 as repeat,
+        reverse,
         sequenceEqual,
         single,
         skip,
+        skipLast,
         skipWhile,
+        slice,
         some,
         sum,
         take,
+        takeLast,
         takeWhile,
         tap,
         tapChain
@@ -528,6 +568,19 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.1
      */
     [Symbol.iterator](): Iterator<T, any, undefined>;
+    /**
+     * Yields the values of the chain, then `value`.
+     * `value` is yielded only when the source ends, so it is never reached on an infinite chain.
+     * @operation `Transformation`
+     * @param value - the value yielded after the last value of the chain
+     * @returns a new chain with the values of this chain followed by `value`
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).append(4).collectToArray(); // [1, 2, 3, 4]
+     * ```
+     * @since 0.8.0
+     */
+    append(value: T): IIterableLinq<T>;
     /**
      * Returns the value at `index`, like `Array.prototype.at`; a negative index counts from the end.
      * A non-negative index runs the chain up to the value, then closes the source; a negative index runs the whole chain,
@@ -581,6 +634,21 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.1
      */
     collectToArray(): T[];
+    /**
+     * Yields the values of the chain, then the values of each iterable in `others`, in order.
+     * Each iterable is opened only when the previous one ends, so the iterables after an infinite chain are never read.
+     * Stopping early closes only the iterable being read.
+     * @operation `Transformation`
+     * @param others - the iterables read after the chain; other chains are iterables too
+     * @returns a new chain with the values of this chain followed by the values of `others`
+     * @throws Error if a value of `others` is missing or does not implement `[Symbol.iterator]`
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2]).concat([3], new Set([4, 5])).collectToArray(); // [1, 2, 3, 4, 5]
+     * ```
+     * @since 0.8.0
+     */
+    concat(...others: Iterable<T>[]): IIterableLinq<T>;
     /**
      * Counts the values of the chain; runs the whole chain.
      * @operation `Action`
@@ -925,6 +993,19 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.8
      */
     min(comparer?: Comparer<T>): T | undefined;
+    /**
+     * Yields `value`, then the values of the chain.
+     * `value` is yielded before the source is read.
+     * @operation `Transformation`
+     * @param value - the value yielded before the first value of the chain
+     * @returns a new chain with `value` followed by the values of this chain
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).prepend(0).collectToArray(); // [0, 1, 2, 3]
+     * ```
+     * @since 0.8.0
+     */
+    prepend(value: T): IIterableLinq<T>;
     /**
      * Runs the chain and accumulates its values into a single result, starting from the first value.
      * @operation `Action`
@@ -952,6 +1033,19 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.0.10
      */
     reduce<R>(neutralElement: R, reducer: Reducer<T, R>): R;
+    /**
+     * Lazily yields the values in reverse order. Unlike `Array.prototype.reverse`, the source is not changed.
+     * The whole chain runs before the first value is yielded, so `reverse` does not end on an infinite chain.
+     * Every run of the chain reads the source again.
+     * @operation `Transformation`
+     * @returns a lazy, re-runnable chain of the values from the last to the first
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3]).reverse().collectToArray(); // [3, 2, 1]
+     * ```
+     * @since 0.9.0
+     */
+    reverse(): IIterableLinq<T>;
     /**
      * Tells whether the chain and `other` have the same values in the same order.
      * It reads the two sources side by side, and stops and closes both at the first difference or when one ends before the other.
@@ -1025,6 +1119,20 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.3.0
      */
     skip(count: number): IIterableLinq<T>;
+    /**
+     * Lazily yields every value except the last `count`.
+     * A value is yielded once `count` more values have been read, keeping only those `count` values, so `skipLast` works with infinite chains.
+     * @operation `Transformation`
+     * @param count - how many values to leave out at the end; must be a non-negative integer
+     * @returns a lazy, re-runnable chain of the values before the last `count`
+     * @throws Error if `count` is negative, not an integer, `NaN` or `Infinity`
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 4, 5]).skipLast(2).collectToArray(); // [1, 2, 3]
+     * ```
+     * @since 0.9.0
+     */
+    skipLast(count: number): IIterableLinq<T>;
     /**
      * Skips the values while `predicate` returns `true`, then yields the first rejected value and all the rest.
      * After the first rejected value, `predicate` is not called again.
@@ -1040,6 +1148,24 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.5.0
      */
     skipWhile(predicate: Predicate<T>): IIterableLinq<T>;
+    /**
+     * Yields the values from `start` to `end` (excluded), like `Array.prototype.slice`; a negative index counts from the end.
+     * With non-negative indexes the values are yielded as they are read, and the source is closed at `end`, so `slice` also ends an infinite chain.
+     * A negative `end` yields each value once `-end` more values have been read, keeping only those `-end` values.
+     * A negative `start` runs the whole chain before yielding, keeping only the last `-start` values.
+     * @operation `Transformation`
+     * @param start - an integer, `0` by default; `-1` is the last value
+     * @param end - an integer; the values are yielded up to the end of the chain by default
+     * @returns a new chain with the values from `start` to `end`
+     * @throws Error if `start` or `end` is given and is not an integer (fractions, `NaN` and `Infinity` included)
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 4, 5]).slice(1, 3).collectToArray(); // [2, 3]
+     * IterableLinq.from([1, 2, 3, 4, 5]).slice(-2).collectToArray(); // [4, 5]
+     * ```
+     * @since 0.8.0
+     */
+    slice(start?: number, end?: number): IIterableLinq<T>;
     /**
      * Runs the chain until its first value, then stops and closes the source.
      * @operation `Action`
@@ -1104,6 +1230,20 @@ export declare interface IIterableLinqBase<T> {
      * @since 0.3.0
      */
     take(count: number): IIterableLinq<T>;
+    /**
+     * Lazily yields the last `count` values.
+     * The whole chain runs before the first value is yielded, keeping only the last `count` values, so `takeLast` does not end on an infinite chain.
+     * @operation `Transformation`
+     * @param count - how many values to yield; must be a non-negative integer
+     * @returns a lazy, re-runnable chain of at most `count` values
+     * @throws Error if `count` is negative, not an integer, `NaN` or `Infinity`
+     * @example
+     * ```ts
+     * IterableLinq.from([1, 2, 3, 4, 5]).takeLast(2).collectToArray(); // [4, 5]
+     * ```
+     * @since 0.9.0
+     */
+    takeLast(count: number): IIterableLinq<T>;
     /**
      * Yields the values while a type guard accepts them, narrowing their type, then closes the source.
      * The source is never read past the first rejected value, which is not yielded.
@@ -1408,6 +1548,22 @@ export declare function override<K extends Extract<keyof IIterableLinq<unknown>,
  */
 export declare type Predicate<T> = (value: T, index: number) => boolean;
 
+/**
+ * Lazily yields `value`, then the values of `iterable`.
+ * `value` is yielded before the source is read.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param value - the value yielded before the first value of the source
+ * @returns a lazy, re-runnable `Iterable` of `value` followed by the values of the source
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.prepend([1, 2, 3], 0)); // [0, 1, 2, 3]
+ * ```
+ * @since 0.8.0
+ */
+declare function prepend<T>(iterable: Iterable<T>, value: T): Iterable<T>;
+
 /**
  * Returns the numbers from 0 up to, but not including, `end`, computed as `index * step`.
  * The direction follows the sign of `end`; `reverse` yields the same numbers backwards; a `NaN` bound gives an empty `Iterable`.
@@ -1513,6 +1669,22 @@ export declare function repeat<T>(value: T, count: number): IIterableLinq<T>;
  */
 declare function repeat_2<T>(value: T, count: number): Iterable<T>;
 
+/**
+ * Lazily yields the values in reverse order. Unlike `Array.prototype.reverse`, the source is not changed.
+ * The whole source is read before the first value is yielded, so `reverse` does not end on an infinite source.
+ * Every iteration reads the source again.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @returns a lazy, re-runnable `Iterable` of the values from the last to the first
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`
+ * @example
+ * ```ts
+ * Array.from(Functions.reverse([1, 2, 3])); // [3, 2, 1]
+ * ```
+ * @since 0.9.0
+ */
+declare function reverse<T>(iterable: Iterable<T>): Iterable<T>;
+
 /**
  * Tells whether `iterable` and `other` have the same values in the same order.
  * It reads the two sources side by side, and stops and closes both at the first difference or when one ends before the other.
@@ -1599,6 +1771,22 @@ declare function single<T>(iterable: Iterable<T>, predicate: Predicate<T> | unde
  */
 declare function skip<T>(iterable: Iterable<T>, count: number): Iterable<T>;
 
+/**
+ * Lazily yields every value except the last `count`.
+ * A value is yielded once `count` more values have been read, keeping only those `count` values, so `skipLast` works with infinite sources.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param count - how many values to leave out at the end; must be a non-negative integer
+ * @returns a lazy, re-runnable `Iterable` of the values before the last `count`
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `count` is negative, not an integer, `NaN` or `Infinity`
+ * @example
+ * ```ts
+ * Array.from(Functions.skipLast([1, 2, 3, 4, 5], 2)); // [1, 2, 3]
+ * ```
+ * @since 0.9.0
+ */
+declare function skipLast<T>(iterable: Iterable<T>, count: number): Iterable<T>;
+
 /**
  * Lazily skips the values while `predicate` returns `true`, then yields the first rejected value and all the rest.
  * After the first rejected value, `predicate` is not called again.
@@ -1616,6 +1804,26 @@ declare function skip<T>(iterable: Iterable<T>, count: number): Iterable<T>;
  */
 declare function skipWhile<T>(iterable: Iterable<T>, predicate: Predicate<T>): Iterable<T>;
 
+/**
+ * Lazily yields the values from `start` to `end` (excluded), like `Array.prototype.slice`; a negative index counts from the end.
+ * With non-negative indexes the values are yielded as they are read, and the source is closed at `end`, so `slice` also ends an infinite source.
+ * A negative `end` yields each value once `-end` more values have been read, keeping only those `-end` values.
+ * A negative `start` reads the whole source before yielding, keeping only the last `-start` values.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param start - an integer, `0` by default; `-1` is the last value
+ * @param end - an integer; the values are yielded up to the end of the source by default
+ * @returns a lazy, re-runnable `Iterable` of the values from `start` to `end`
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `start` or `end` is given and is not an integer (fractions, `NaN` and `Infinity` included)
+ * @example
+ * ```ts
+ * Array.from(Functions.slice([1, 2, 3, 4, 5], 1, 3)); // [2, 3]
+ * Array.from(Functions.slice([1, 2, 3, 4, 5], -2)); // [4, 5]
+ * ```
+ * @since 0.8.0
+ */
+declare function slice<T>(iterable: Iterable<T>, start?: number, end?: number): Iterable<T>;
+
 /**
  * Tells whether `iterable` contains a value; reads one value, then closes the source.
  * @operation `Action`
@@ -1692,6 +1900,22 @@ declare function sum<T>(iterable: Iterable<T>, selector: Mapper<T, number> | und
  */
 declare function take<T>(iterable: Iterable<T>, count: number): Iterable<T>;
 
+/**
+ * Lazily yields the last `count` values.
+ * The whole source is read before the first value is yielded, keeping only the last `count` values, so `takeLast` does not end on an infinite source.
+ * @operation `Transformation`
+ * @param iterable - the source `Iterable`
+ * @param count - how many values to yield; must be a non-negative integer
+ * @returns a lazy, re-runnable `Iterable` of at most `count` values
+ * @throws Error if `iterable` is missing or does not implement `[Symbol.iterator]`, or if `count` is negative, not an integer, `NaN` or `Infinity`
+ * @example
+ * ```ts
+ * Array.from(Functions.takeLast([1, 2, 3, 4, 5], 2)); // [4, 5]
+ * ```
+ * @since 0.9.0
+ */
+declare function takeLast<T>(iterable: Iterable<T>, count: number): Iterable<T>;
+
 /**
  * Lazily yields the values while a type guard accepts them, narrowing their type, then closes the source.
  * The source is never read past the first rejected value, which is not yielded.