iterable-linq-utility 0.8.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

@@ -515,14 +515,17 @@ declare namespace Functions {
         range,
         reduce,
         repeat_2 as repeat,
+        reverse,
         sequenceEqual,
         single,
         skip,
+        skipLast,
         skipWhile,
         slice,
         some,
         sum,
         take,
+        takeLast,
         takeWhile,
         tap,
         tapChain
@@ -1030,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.
@@ -1103,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.
@@ -1200,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.
@@ -1625,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.
@@ -1711,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.
@@ -1824,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.

package/dist/index.d.ts

@@ -515,14 +515,17 @@ declare namespace Functions {
         range,
         reduce,
         repeat_2 as repeat,
+        reverse,
         sequenceEqual,
         single,
         skip,
+        skipLast,
         skipWhile,
         slice,
         some,
         sum,
         take,
+        takeLast,
         takeWhile,
         tap,
         tapChain
@@ -1030,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.
@@ -1103,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.
@@ -1200,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.
@@ -1625,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.
@@ -1711,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.
@@ -1824,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.