@rimbu/common 2.0.0 → 2.0.2

package/README.md

@@ -8,62 +8,64 @@
 
 # @rimbu/common
 
-This package exports common types and objects used in many other Rimbu packages.
+Welcome to `@rimbu/common`! This package exports essential types and utilities that are widely used across various Rimbu packages. It provides a robust foundation for building efficient and reliable applications.
 
-Here is a brief overview:
+### Overview of most important Exported Types:
 
-| Name            | Description                                                                                              |
-| --------------- | -------------------------------------------------------------------------------------------------------- |
-| `CollectFun`    | types and values used in various `collect` methods in the collection.                                    |
-| `Comp`          | an interface and default implementations of comparison functions to order/sort values.                   |
-| `Eq`            | an interface and default implementations of equality functions to check value equality                   |
-| `Err`           | functions to easily create error throwing behavior as fallback values                                    |
-| `FastIterable`  | an `Iterable` implementation that can be more performant than usual iterables                            |
-| `IndexRange`    | utilities to select index ranges in indexed collections                                                  |
-| `OptLazy`       | a utility to provide values that can optionally be lazy                                                  |
-| `Range`         | utility types to specify ranges for comparable types                                                     |
-| `Reducer`       | an API to create reusable pieces of logic that process streams of data that can be processed in parallel |
-| `TraverseState` | a utility for loops to maintain the traversal state                                                      |
-| `Update`        | a standard way to update a value                                                                         |
+| Name            | Description                                                                                           |
+| --------------- | ----------------------------------------------------------------------------------------------------- |
+| `CollectFun`    | Types and values used in various `collect` methods within collections.                                |
+| `Comp`          | Interface and default implementations of comparison functions for ordering/sorting values.            |
+| `Eq`            | Interface and default implementations of equality functions for checking value equality.              |
+| `Err`           | Functions to easily create error-throwing behavior as fallback values.                                |
+| `FastIterable`  | An `Iterable` implementation that offers better performance than standard iterables.                  |
+| `IndexRange`    | Utilities for selecting index ranges in indexed collections.                                          |
+| `OptLazy`       | A utility to provide values that can optionally be lazy.                                              |
+| `Range`         | Utility types to specify ranges for comparable types.                                                 |
+| `Reducer`       | An API to create reusable logic pieces that process data streams, which can be processed in parallel. |
+| `TraverseState` | A utility for loops to maintain traversal state.                                                      |
+| `Update`        | A standard way to update a value.                                                                     |
 
-Other than these values, there are a number of utility types that are exported that are also used throughout the collection.
+### Documentation
 
-For complete documentation please visit the _[Rimbu Docs](https://rimbu.org)_, or directly see the _[Rimbu Common API Docs](https://rimbu.org/api/rimbu/common)_.
+For complete documentation, please visit the [Rimbu Docs](https://rimbu.org), or directly explore the [Rimbu Common API Docs](https://rimbu.org/api/rimbu/common).
 
-Or [Try Out Rimbu](https://codesandbox.io/s/github/vitoke/rimbu-sandbox/tree/main?previewwindow=console&view=split&editorsize=65&moduleview=1&module=/src/index.ts) in CodeSandBox.
+### Try It Out
+
+Experience `@rimbu/common` in action! [Try Out Rimbu](https://codesandbox.io/s/github/vitoke/rimbu-sandbox/tree/main?previewwindow=console&view=split&editorsize=65&moduleview=1&module=/src/index.ts) on CodeSandBox.
 
 ## Installation
 
 ### Compabitity
 
-- [`Node >= 16` ![NodeJS](https://img.shields.io/badge/node.js-6DA55F?logo=node.js&logoColor=white)](https://nodejs.org)
+- [`Node` ![NodeJS](https://img.shields.io/badge/node.js-6DA55F?logo=node.js&logoColor=white)](https://nodejs.org)
 - [`Deno` ![Deno JS](https://img.shields.io/badge/deno%20js-000000?logo=deno&logoColor=white)](https://deno.com/runtime)
-- [`Bun >= 0.6.0` ![Bun](https://img.shields.io/badge/Bun-%23000000.svg?logoColor=white)](https://bun.sh/)
+- [`Bun` ![Bun](https://img.shields.io/badge/Bun-%23000000.svg?logoColor=white)](https://bun.sh/)
 - `Web` ![HTML5](https://img.shields.io/badge/html5-%23E34F26.svg?logoColor=white)
 
-### Yarn / NPM / Bun
-
-For convenience, all main types are also exported through [`@rimbu/core`](../core).
-
-To install this package only:
-
-For `yarn`:
+### Package Managers
 
-> `yarn add @rimbu/common`
+**Yarn:**
 
-For `npm`:
+```sh
+yarn add @rimbu/common
+```
 
-> `npm i @rimbu/common`
+**npm:**
 
-For `bun`:
+```sh
+npm install @rimbu/common
+```
 
-> `bun add @rimbu/common`
+**Bun:**
 
-### Deno
+```sh
+bun add @rimbu/common
+```
 
-For Deno, the following approach is recommended:
+### Deno Setup
 
-In the root folder of your project, create or edit a file called `import_map.json` with the following contents (where you should replace `x.y.z` with the desired version of Rimbu):
+Create or edit `import_map.json` in your project root:
 
 ```json
 {
@@ -73,7 +75,7 @@ In the root folder of your project, create or edit a file called `import_map.jso
 }
 ```
 
-**Note: The trailing slashes are important!**
+_Replace `x.y.z` with the desired version._
 
 In this way you can use relative imports from Rimbu in your code, like so:
 
@@ -103,20 +105,18 @@ console.log(Eq.stringCaseInsentitive()('abc', 'AbC'));
 
 ## Author
 
-[Arvid Nicolaas](https://github.com/vitoke)
+Created and maintained by [Arvid Nicolaas](https://github.com/vitoke).
 
 ## Contributing
 
-Feel very welcome to contribute to further improve Rimbu. Please read our [Contributing guide](https://github.com/rimbu-org/rimbu/blob/main/CONTRIBUTING.md).
+We welcome contributions! Please read our [Contributing guide](https://github.com/rimbu-org/rimbu/blob/main/CONTRIBUTING.md).
 
 ## Contributors
 
 <img src = "https://contrib.rocks/image?repo=rimbu-org/rimbu"/>
 
-Made with [contributors-img](https://contrib.rocks).
+_Made with [contributors-img](https://contrib.rocks)._
 
 ## License
 
-Licensed under the MIT License, Copyright © 2020-present Arvid Nicolaas.
-
-See [LICENSE](./LICENSE) for more information.
+This project is licensed under the MIT License. See the [LICENSE](./LICENSE) for details.

package/dist/bun/err.mts

@@ -18,7 +18,7 @@ export namespace ErrBase {
   export abstract class CustomError {
     constructor(readonly message: string) {}
 
-    get name() {
+    get name(): string {
       return this.constructor.name;
     }
   }

package/dist/cjs/async-optlazy.cjs

@@ -1,44 +1,62 @@
 "use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/async-optlazy.mts
-var async_optlazy_exports = {};
-__export(async_optlazy_exports, {
-  AsyncOptLazy: () => AsyncOptLazy
-});
-module.exports = __toCommonJS(async_optlazy_exports);
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AsyncOptLazy = void 0;
+var tslib_1 = require("tslib");
 var AsyncOptLazy;
-((AsyncOptLazy2) => {
-  function toMaybePromise(optLazy, ...args) {
-    if (optLazy instanceof Function)
-      return optLazy(...args);
-    return optLazy;
-  }
-  AsyncOptLazy2.toMaybePromise = toMaybePromise;
-  async function toPromise(optLazy, ...args) {
-    if (optLazy instanceof Function)
-      return optLazy(...args);
-    return optLazy;
-  }
-  AsyncOptLazy2.toPromise = toPromise;
-})(AsyncOptLazy || (AsyncOptLazy = {}));
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  AsyncOptLazy
-});
+(function (AsyncOptLazy) {
+    /**
+     * Returns the value or promised value contained in an `AsyncOptLazy` instance of type T.
+     * @param optLazy - the `AsyncOptLazy` value of type T
+     * @param args - when needed, the extra arguments to pass to the lazy invocation
+     * @typeparam T - the value type
+     * @typeparam A - (default: []) types of the argument array that can be passed in the lazy case
+     * @example
+     * ```ts
+     * AsyncOptLazy.toMaybePromise(1)              // => 1
+     * AsyncOptLazy.toMaybePromise(() => 1)        // => 1
+     * AsyncOptLazy.toMaybePromise(() => () => 1)  // => () => 1
+     * AsyncOptLazy.toMaybePromise(async () => 1)  // => Promise(1)
+     * AsyncOptLazy.toMaybePromise(Promise.resolve(1))  // => Promise(1)
+     * ```
+     */
+    function toMaybePromise(optLazy) {
+        var args = [];
+        for (var _i = 1; _i < arguments.length; _i++) {
+            args[_i - 1] = arguments[_i];
+        }
+        if (optLazy instanceof Function)
+            return optLazy.apply(void 0, tslib_1.__spreadArray([], tslib_1.__read(args), false));
+        return optLazy;
+    }
+    AsyncOptLazy.toMaybePromise = toMaybePromise;
+    /**
+     * Returns the value contained in an `AsyncOptLazy` instance of type T as a promise.
+     * @param optLazy - the `AsyncOptLazy` value of type T
+     * @param args - when needed, the extra arguments to pass to the lazy invocation
+     * @typeparam T - the value type
+     * @typeparam A - (default: []) types of the argument array that can be passed in the lazy case
+     * @example
+     * ```ts
+     * AsyncOptLazy.toPromise(1)              // => Promise(1)
+     * AsyncOptLazy.toPromise(() => 1)        // => Promise(1)
+     * AsyncOptLazy.toPromise(() => () => 1)  // => Promise(() => 1)
+     * AsyncOptLazy.toPromise(async () => 1)  // => Promise(1)
+     * AsyncOptLazy.toPromise(Promise.resolve(1))  // => Promise(1)
+     * ```
+     */
+    function toPromise(optLazy) {
+        var args = [];
+        for (var _i = 1; _i < arguments.length; _i++) {
+            args[_i - 1] = arguments[_i];
+        }
+        return tslib_1.__awaiter(this, void 0, void 0, function () {
+            return tslib_1.__generator(this, function (_a) {
+                if (optLazy instanceof Function)
+                    return [2 /*return*/, optLazy.apply(void 0, tslib_1.__spreadArray([], tslib_1.__read(args), false))];
+                return [2 /*return*/, optLazy];
+            });
+        });
+    }
+    AsyncOptLazy.toPromise = toPromise;
+})(AsyncOptLazy || (exports.AsyncOptLazy = AsyncOptLazy = {}));
+//# sourceMappingURL=async-optlazy.cjs.map

package/dist/cjs/async-optlazy.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-optlazy.cjs","sourceRoot":"","sources":["../../_cjs_prepare/async-optlazy.cts"],"names":[],"mappings":";;;;AAeA,IAAiB,YAAY,CA8C5B;AA9CD,WAAiB,YAAY;IAC3B;;;;;;;;;;;;;;OAcG;IACH,SAAgB,cAAc,CAC5B,OAA2B;QAC3B,cAAU;aAAV,UAAU,EAAV,qBAAU,EAAV,IAAU;YAAV,6BAAU;;QAEV,IAAI,OAAO,YAAY,QAAQ;YAAE,OAAO,OAAO,wDAAI,IAAI,WAAE;QACzD,OAAO,OAAO,CAAC;IACjB,CAAC;IANe,2BAAc,iBAM7B,CAAA;IAED;;;;;;;;;;;;;;OAcG;IACH,SAAsB,SAAS,CAC7B,OAA2B;QAC3B,cAAU;aAAV,UAAU,EAAV,qBAAU,EAAV,IAAU;YAAV,6BAAU;;;;gBAEV,IAAI,OAAO,YAAY,QAAQ;oBAAE,sBAAO,OAAO,wDAAI,IAAI,YAAE;gBACzD,sBAAO,OAAO,EAAC;;;KAChB;IANqB,sBAAS,YAM9B,CAAA;AACH,CAAC,EA9CgB,YAAY,4BAAZ,YAAY,QA8C5B"}

package/dist/cjs/async-optlazy.d.cts

@@ -0,0 +1,46 @@
+import type { OptLazy } from './internal.cjs';
+/**
+ * A type that is either a value T or a promise yielding a value of type T.
+ * @typeparam T - the value type
+ */
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * A potentially lazy and/or asynchronous value of type T.
+ * @typeparam T - the value type
+ * @typeparam A - (default: []) types of the argument array that can be passed in the lazy case
+ */
+export type AsyncOptLazy<T, A extends any[] = []> = OptLazy<MaybePromise<T>, A>;
+export declare namespace AsyncOptLazy {
+    /**
+     * Returns the value or promised value contained in an `AsyncOptLazy` instance of type T.
+     * @param optLazy - the `AsyncOptLazy` value of type T
+     * @param args - when needed, the extra arguments to pass to the lazy invocation
+     * @typeparam T - the value type
+     * @typeparam A - (default: []) types of the argument array that can be passed in the lazy case
+     * @example
+     * ```ts
+     * AsyncOptLazy.toMaybePromise(1)              // => 1
+     * AsyncOptLazy.toMaybePromise(() => 1)        // => 1
+     * AsyncOptLazy.toMaybePromise(() => () => 1)  // => () => 1
+     * AsyncOptLazy.toMaybePromise(async () => 1)  // => Promise(1)
+     * AsyncOptLazy.toMaybePromise(Promise.resolve(1))  // => Promise(1)
+     * ```
+     */
+    function toMaybePromise<T, A extends any[] = []>(optLazy: AsyncOptLazy<T, A>, ...args: A): MaybePromise<T>;
+    /**
+     * Returns the value contained in an `AsyncOptLazy` instance of type T as a promise.
+     * @param optLazy - the `AsyncOptLazy` value of type T
+     * @param args - when needed, the extra arguments to pass to the lazy invocation
+     * @typeparam T - the value type
+     * @typeparam A - (default: []) types of the argument array that can be passed in the lazy case
+     * @example
+     * ```ts
+     * AsyncOptLazy.toPromise(1)              // => Promise(1)
+     * AsyncOptLazy.toPromise(() => 1)        // => Promise(1)
+     * AsyncOptLazy.toPromise(() => () => 1)  // => Promise(() => 1)
+     * AsyncOptLazy.toPromise(async () => 1)  // => Promise(1)
+     * AsyncOptLazy.toPromise(Promise.resolve(1))  // => Promise(1)
+     * ```
+     */
+    function toPromise<T, A extends any[] = []>(optLazy: AsyncOptLazy<T, A>, ...args: A): Promise<T>;
+}

package/dist/cjs/collect.cjs

@@ -1,33 +1,11 @@
 "use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-
-// src/collect.mts
-var collect_exports = {};
-__export(collect_exports, {
-  CollectFun: () => CollectFun
-});
-module.exports = __toCommonJS(collect_exports);
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CollectFun = void 0;
 var CollectFun;
-((CollectFun2) => {
-  CollectFun2.Skip = Symbol("Skip");
-})(CollectFun || (CollectFun = {}));
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  CollectFun
-});
+(function (CollectFun) {
+    /**
+     * Indicates, when returned from a collect function, to skip the value.
+     */
+    CollectFun.Skip = Symbol('Skip');
+})(CollectFun || (exports.CollectFun = CollectFun = {}));
+//# sourceMappingURL=collect.cjs.map

package/dist/cjs/collect.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect.cjs","sourceRoot":"","sources":["../../_cjs_prepare/collect.cts"],"names":[],"mappings":";;;AAiBA,IAAiB,UAAU,CAU1B;AAVD,WAAiB,UAAU;IACzB;;OAEG;IACU,eAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;AAMrC,CAAC,EAVgB,UAAU,0BAAV,UAAU,QAU1B"}

package/dist/cjs/collect.d.cts

@@ -0,0 +1,29 @@
+import type { MaybePromise } from './internal.cjs';
+/**
+ * A function used in `collect` methods to collect values from a collection. This is basically a single-pass map and filter.
+ * @param value - the input value
+ * @param index - the index of the input value
+ * @param skip - a token that can be returned to skip the value
+ * @param halt - a function that, when called, ensures no more values are passed
+ * @returns either a new value to collect, or the `skip` token indicating to skip the value
+ */
+export type CollectFun<T, R> = (value: T, index: number, skip: CollectFun.Skip, halt: () => void) => R | CollectFun.Skip;
+export declare namespace CollectFun {
+    /**
+     * Indicates, when returned from a collect function, to skip the value.
+     */
+    const Skip: unique symbol;
+    /**
+     * Indicates, when returned from a collect function, to skip the value.
+     */
+    type Skip = typeof Skip;
+}
+/**
+ * A potentially asynchronous function used in `collect` methods to collect values from a collection. This is basically a single-pass map and filter.
+ * @param value - the input value
+ * @param index - the index of the input value
+ * @param skip - a token that can be returned to skip the value
+ * @param halt - a function that, when called, ensures no more values are passed
+ * @returns either a new value to collect, or the `skip` token indicating to skip the value
+ */
+export type AsyncCollectFun<T, R> = (value: T, index: number, skip: CollectFun.Skip, halt: () => void) => MaybePromise<R | CollectFun.Skip>;