iterable-linq-utility 0.0.15 → 0.1.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) [2022] [Federico Maria Ceruti]
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) [2022] [Federico Maria Ceruti]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1 +1,107 @@
-Work in Progress
+[![](https://data.jsdelivr.com/v1/package/npm/iterable-linq-utility/badge)](https://www.jsdelivr.com/package/npm/iterable-linq-utility)
+[![](https://img.shields.io/npm/v/iterable-linq-utility.svg)](https://npmjs.org/package/iterable-linq-utility)
+[![](https://img.shields.io/npm/dm/iterable-linq-utility.svg)](https://npmjs.org/package/iterable-linq-utility)
+
+A [.NET Linq to Objects](https://learn.microsoft.com/it-it/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) porting with javacript naming conventions (e.g.: `Select` as been ranamed to `map`) and some new features (e.g.: [memoize](https://amebus.github.io/iterable-linq-utility/api-reference/transformations.md#memoize) and [materialize](https://amebus.github.io/iterable-linq-utility/api-reference/actions.md#materialize)).
+
+[Official documentation available here](https://amebus.github.io/iterable-linq-utility)
+
+## Main Idea
+
+As the previous description says, the idea is to create a kind-of-porting of [.NET Linq to Objects](https://learn.microsoft.com/it-it/dotnet/csharp/programming-guide/concepts/linq/linq-to-objects) with a naming convetions that is more javascript and functional programming oriented and not sql oriented [^1].  
+In other words the idea is:
+
+- to keep the [LINQ Deferred Exceution](https://learn.microsoft.com/en-us/dotnet/standard/linq/deferred-execution-lazy-evaluation#deferred-execution) and apply it to the [JavaScript Iterator Protocol](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols) with a more standard way of naming well known high order functions like `map`, `flatMap`, `reduce` used by javascript and some functional programming libraries (e.g.: [Ramdajs](https://github.com/functionalland/ramda), [SanctuaryJs](https://github.com/orgs/sanctuary-js/repositories?type=all), [FantasyLand](https://github.com/fantasyland) and [lodash](https://github.com/lodash/lodash)).
+- to keep the **Linq repeatable execution** which allows to traverse the same chain multiple times without having to recreate it from scratch every time, in this way is possible to store the chain in a variable and then trigger it to get the max and min without recreating it:
+
+  ```ts
+  const myChain = IterableLinq.from([1,2,3,4]).filter().map(); // chain creation
+  const max = myChain.max();
+  const min = myChain.min(); // using the same chain twice
+  ```
+
+Since in javascript you cannot rely on [extensions methods](https://learn.microsoft.com/en-us/dotnet/csharp/programming-guide/classes-and-structs/extension-methods) as in c# there is the need to create a wrapper over `Iterable` to achive the same [Deferred Exceution](https://learn.microsoft.com/en-us/dotnet/standard/linq/deferred-execution-lazy-evaluation#deferred-execution) concept.  
+
+```typescript
+IterableLinq
+    .fromRange(start, end)
+    .filter(myFilterFunction)
+    .map(myMapFunction)
+    .collectToArray()
+```
+
+as **Operations Chain** or **O~s~C**.  
+The **O~s~C** supports two types of operations:
+
+- [Actions](https://amebus.github.io/iterable-linq-utility/api-reference/actions.md)
+- [Transformations](https://amebus.github.io/iterable-linq-utility/api-reference/transformations.md)
+
+## Benchmarks
+
+The benchmarks use [Vitest benchmarking](https://vitest.dev/guide/benchmarking) and live in `test/bench`:
+
+- `functions/`: one file for each function, with several variants (for example `min` with no comparer, a compare function, a key and a list of keys);
+- `chains/`: whole chains, from `map(filter(range))` to multi-stage pipelines, early exits and chains read by more than one action.
+
+Every table compares the library with a native reference (an array method or a hand-written loop) and, where it exists, with the raw function in `Functions`.
+
+The benchmarks measure the built bundle (`dist/iterable-linq-utility.js`), the same code that users run. The `bench` scripts build it first.
+
+### Run
+
+```sh
+pnpm bench                        # every benchmark, about 3 minutes
+pnpm bench functions/min          # only the files whose path contains "functions/min"
+pnpm bench chains                 # only the chains
+BENCH_TIME=1000 pnpm bench        # more time for each case (default 500 ms): more samples, less noise
+```
+
+### Find regressions
+
+A baseline is a saved run. Each table shows it as extra rows, marked `(baseline)`, next to the new run.
+
+```sh
+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
+```
+
+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.
+
+### Read the tables
+
+| Column | Meaning |
+|---|---|
+| `hz` | runs per second: higher is faster |
+| `mean`, `p75`, `p99` | time of one run, in ms |
+| `rme` | relative margin of error |
+| `samples` | how many runs were measured |
+
+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`:
+
+```ts
+import * as IterableLinq from 'iterable-linq-utility';
+import { test } from 'vitest';
+
+import * as Helpers from '../helpers';
+
+// 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();
+});
+```
+
+- 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).