@nlozgachev/pipelined 0.10.0 → 0.12.0

package/script/src/{Core → Utils}/Arr.js

@@ -1,10 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Arr = void 0;
-const Deferred_js_1 = require("./Deferred.js");
-const Option_js_1 = require("./Option.js");
-const Result_js_1 = require("./Result.js");
-const Task_js_1 = require("./Task.js");
+const Deferred_js_1 = require("../Core/Deferred.js");
+const Option_js_1 = require("../Core/Option.js");
+const Result_js_1 = require("../Core/Result.js");
+const Task_js_1 = require("../Core/Task.js");
 const NonEmptyList_js_1 = require("../Types/NonEmptyList.js");
 /**
  * Functional array utilities that compose well with pipe.
@@ -113,7 +113,13 @@ var Arr;
      * pipe([1, 2, 3], Arr.map(n => n * 2)); // [2, 4, 6]
      * ```
      */
-    Arr.map = (f) => (data) => data.map(f);
+    Arr.map = (f) => (data) => {
+        const n = data.length;
+        const result = new Array(n);
+        for (let i = 0; i < n; i++)
+            result[i] = f(data[i]);
+        return result;
+    };
     /**
      * Filters elements that satisfy the predicate.
      *
@@ -122,7 +128,15 @@ var Arr;
      * pipe([1, 2, 3, 4], Arr.filter(n => n % 2 === 0)); // [2, 4]
      * ```
      */
-    Arr.filter = (predicate) => (data) => data.filter(predicate);
+    Arr.filter = (predicate) => (data) => {
+        const n = data.length;
+        const result = [];
+        for (let i = 0; i < n; i++) {
+            if (predicate(data[i]))
+                result.push(data[i]);
+        }
+        return result;
+    };
     /**
      * Splits an array into two groups based on a predicate.
      * First group contains elements that satisfy the predicate,
@@ -216,9 +230,9 @@ var Arr;
      */
     Arr.zip = (other) => (data) => {
         const len = Math.min(data.length, other.length);
-        const result = [];
+        const result = new Array(len);
         for (let i = 0; i < len; i++) {
-            result.push([data[i], other[i]]);
+            result[i] = [data[i], other[i]];
         }
         return result;
     };
@@ -232,9 +246,9 @@ var Arr;
      */
     Arr.zipWith = (f) => (other) => (data) => {
         const len = Math.min(data.length, other.length);
-        const result = [];
+        const result = new Array(len);
         for (let i = 0; i < len; i++) {
-            result.push(f(data[i], other[i]));
+            result[i] = f(data[i], other[i]);
         }
         return result;
     };
@@ -289,7 +303,17 @@ var Arr;
      * pipe([1, 2, 3], Arr.flatMap(n => [n, n * 10])); // [1, 10, 2, 20, 3, 30]
      * ```
      */
-    Arr.flatMap = (f) => (data) => [].concat(...data.map(f));
+    Arr.flatMap = (f) => (data) => {
+        const n = data.length;
+        const result = [];
+        for (let i = 0; i < n; i++) {
+            const chunk = f(data[i]);
+            const m = chunk.length;
+            for (let j = 0; j < m; j++)
+                result.push(chunk[j]);
+        }
+        return result;
+    };
     /**
      * Reduces an array from the left.
      *
@@ -316,12 +340,13 @@ var Arr;
      * ```
      */
     Arr.traverse = (f) => (data) => {
-        const result = [];
-        for (const a of data) {
-            const mapped = f(a);
-            if (Option_js_1.Option.isNone(mapped))
+        const n = data.length;
+        const result = new Array(n);
+        for (let i = 0; i < n; i++) {
+            const mapped = f(data[i]);
+            if (mapped.kind === "None")
                 return Option_js_1.Option.none();
-            result.push(mapped.value);
+            result[i] = mapped.value;
         }
         return Option_js_1.Option.some(result);
     };
@@ -338,12 +363,13 @@ var Arr;
      * ```
      */
     Arr.traverseResult = (f) => (data) => {
-        const result = [];
-        for (const a of data) {
-            const mapped = f(a);
-            if (Result_js_1.Result.isErr(mapped))
+        const n = data.length;
+        const result = new Array(n);
+        for (let i = 0; i < n; i++) {
+            const mapped = f(data[i]);
+            if (mapped.kind === "Error")
                 return mapped;
-            result.push(mapped.value);
+            result[i] = mapped.value;
         }
         return Result_js_1.Result.ok(result);
     };
@@ -430,7 +456,13 @@ var Arr;
      * pipe([1, 2, 3], Arr.some(n => n > 2)); // true
      * ```
      */
-    Arr.some = (predicate) => (data) => data.some(predicate);
+    Arr.some = (predicate) => (data) => {
+        const n = data.length;
+        for (let i = 0; i < n; i++)
+            if (predicate(data[i]))
+                return true;
+        return false;
+    };
     /**
      * Returns true if all elements satisfy the predicate.
      *
@@ -439,7 +471,13 @@ var Arr;
      * pipe([1, 2, 3], Arr.every(n => n > 0)); // true
      * ```
      */
-    Arr.every = (predicate) => (data) => data.every(predicate);
+    Arr.every = (predicate) => (data) => {
+        const n = data.length;
+        for (let i = 0; i < n; i++)
+            if (!predicate(data[i]))
+                return false;
+        return true;
+    };
     /**
      * Reverses an array. Returns a new array.
      *
@@ -498,4 +536,38 @@ var Arr;
             i++;
         return data.slice(i);
     };
+    /**
+     * Like `reduce`, but returns every intermediate accumulator as an array.
+     * The initial value is not included — the output has the same length as the input.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3], Arr.scan(0, (acc, n) => acc + n)); // [1, 3, 6]
+     * ```
+     */
+    Arr.scan = (initial, f) => (data) => {
+        const n = data.length;
+        const result = new Array(n);
+        let acc = initial;
+        for (let i = 0; i < n; i++) {
+            acc = f(acc, data[i]);
+            result[i] = acc;
+        }
+        return result;
+    };
+    /**
+     * Splits an array at an index into a `[before, after]` tuple.
+     * Negative indices clamp to 0; indices beyond the array length clamp to the end.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3, 4], Arr.splitAt(2)); // [[1, 2], [3, 4]]
+     * pipe([1, 2, 3], Arr.splitAt(0));    // [[], [1, 2, 3]]
+     * pipe([1, 2, 3], Arr.splitAt(10));   // [[1, 2, 3], []]
+     * ```
+     */
+    Arr.splitAt = (index) => (data) => {
+        const i = Math.max(0, index);
+        return [data.slice(0, i), data.slice(i)];
+    };
 })(Arr || (exports.Arr = Arr = {}));

package/script/src/Utils/Dict.js

@@ -0,0 +1,424 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Dict = void 0;
+const Option_js_1 = require("../Core/Option.js");
+/**
+ * Functional utilities for key-value dictionaries (`ReadonlyMap<K, V>`). All functions are pure
+ * and data-last — they compose naturally with `pipe`.
+ *
+ * Unlike plain objects (`Rec`), dictionaries support any key type, preserve insertion order, and
+ * make membership checks explicit via `lookup` returning `Option`.
+ *
+ * @example
+ * ```ts
+ * import { Dict } from "@nlozgachev/pipelined/utils";
+ * import { pipe } from "@nlozgachev/pipelined/composition";
+ *
+ * const scores = pipe(
+ *   Dict.fromEntries([["alice", 10], ["bob", 8], ["carol", 10]] as const),
+ *   Dict.filter(n => n >= 10),
+ *   Dict.map(n => `${n} points`),
+ * );
+ * // ReadonlyMap { "alice" => "10 points", "carol" => "10 points" }
+ * ```
+ */
+var Dict;
+(function (Dict) {
+    // ---------------------------------------------------------------------------
+    // Constructors
+    // ---------------------------------------------------------------------------
+    /**
+     * Creates an empty dictionary.
+     *
+     * @example
+     * ```ts
+     * Dict.empty<string, number>(); // ReadonlyMap {}
+     * ```
+     */
+    Dict.empty = () => new globalThis.Map();
+    /**
+     * Creates a dictionary with a single entry.
+     *
+     * @example
+     * ```ts
+     * Dict.singleton("name", "Alice"); // ReadonlyMap { "name" => "Alice" }
+     * ```
+     */
+    Dict.singleton = (key, value) => new globalThis.Map([[key, value]]);
+    /**
+     * Creates a dictionary from an array of key-value pairs.
+     *
+     * @example
+     * ```ts
+     * Dict.fromEntries([["a", 1], ["b", 2]]); // ReadonlyMap { "a" => 1, "b" => 2 }
+     * ```
+     */
+    Dict.fromEntries = (entries) => new globalThis.Map(entries);
+    /**
+     * Creates a dictionary from a plain object. Keys are always strings.
+     *
+     * @example
+     * ```ts
+     * Dict.fromRecord({ a: 1, b: 2 }); // ReadonlyMap { "a" => 1, "b" => 2 }
+     * ```
+     */
+    Dict.fromRecord = (rec) => new globalThis.Map(Object.entries(rec));
+    /**
+     * Groups elements of an array into a dictionary keyed by the result of `keyFn`. Each key maps
+     * to the array of elements that produced it, in insertion order. Uses the native `Map.groupBy`
+     * when available, falling back to a manual loop in older environments.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   [{ name: "alice", role: "admin" }, { name: "bob", role: "viewer" }, { name: "carol", role: "admin" }],
+     *   Dict.groupBy(user => user.role),
+     * );
+     * // ReadonlyMap { "admin" => [alice, carol], "viewer" => [bob] }
+     * ```
+     */
+    Dict.groupBy = (keyFn) => (items) => {
+        const result = new globalThis.Map();
+        for (const item of items) {
+            const key = keyFn(item);
+            const arr = result.get(key);
+            if (arr !== undefined)
+                arr.push(item);
+            else
+                result.set(key, [item]);
+        }
+        return result;
+    };
+    // ---------------------------------------------------------------------------
+    // Query
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns `true` if the dictionary contains the given key.
+     *
+     * @example
+     * ```ts
+     * pipe(Dict.fromEntries([["a", 1]]), Dict.has("a")); // true
+     * pipe(Dict.fromEntries([["a", 1]]), Dict.has("b")); // false
+     * ```
+     */
+    Dict.has = (key) => (m) => m.has(key);
+    /**
+     * Looks up a value by key, returning `Some(value)` if found and `None` if not.
+     *
+     * @example
+     * ```ts
+     * pipe(Dict.fromEntries([["a", 1]]), Dict.lookup("a")); // Some(1)
+     * pipe(Dict.fromEntries([["a", 1]]), Dict.lookup("b")); // None
+     * ```
+     */
+    Dict.lookup = (key) => (m) => m.has(key) ? Option_js_1.Option.some(m.get(key)) : Option_js_1.Option.none();
+    /**
+     * Returns the number of entries in the dictionary.
+     *
+     * @example
+     * ```ts
+     * Dict.size(Dict.fromEntries([["a", 1], ["b", 2]])); // 2
+     * ```
+     */
+    Dict.size = (m) => m.size;
+    /**
+     * Returns `true` if the dictionary has no entries.
+     *
+     * @example
+     * ```ts
+     * Dict.isEmpty(Dict.empty()); // true
+     * ```
+     */
+    Dict.isEmpty = (m) => m.size === 0;
+    /**
+     * Returns all keys as a readonly array, in insertion order.
+     *
+     * @example
+     * ```ts
+     * Dict.keys(Dict.fromEntries([["a", 1], ["b", 2]])); // ["a", "b"]
+     * ```
+     */
+    Dict.keys = (m) => [...m.keys()];
+    /**
+     * Returns all values as a readonly array, in insertion order.
+     *
+     * @example
+     * ```ts
+     * Dict.values(Dict.fromEntries([["a", 1], ["b", 2]])); // [1, 2]
+     * ```
+     */
+    Dict.values = (m) => [...m.values()];
+    /**
+     * Returns all key-value pairs as a readonly array of tuples, in insertion order.
+     *
+     * @example
+     * ```ts
+     * Dict.entries(Dict.fromEntries([["a", 1], ["b", 2]])); // [["a", 1], ["b", 2]]
+     * ```
+     */
+    Dict.entries = (m) => [...m.entries()];
+    // ---------------------------------------------------------------------------
+    // Modification
+    // ---------------------------------------------------------------------------
+    /**
+     * Returns a new dictionary with the given key set to the given value.
+     * If the key already exists, its value is replaced.
+     *
+     * @example
+     * ```ts
+     * pipe(Dict.fromEntries([["a", 1]]), Dict.insert("b", 2));
+     * // ReadonlyMap { "a" => 1, "b" => 2 }
+     * ```
+     */
+    Dict.insert = (key, value) => (m) => {
+        const result = new globalThis.Map(m);
+        result.set(key, value);
+        return result;
+    };
+    /**
+     * Returns a new dictionary with the given key removed.
+     * If the key does not exist, the dictionary is returned unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(Dict.fromEntries([["a", 1], ["b", 2]]), Dict.remove("a"));
+     * // ReadonlyMap { "b" => 2 }
+     * ```
+     */
+    Dict.remove = (key) => (m) => {
+        if (!m.has(key))
+            return m;
+        const result = new globalThis.Map(m);
+        result.delete(key);
+        return result;
+    };
+    /**
+     * Returns a new dictionary with the value at `key` set by `f`. If the key does not exist,
+     * `f` receives `None`. If the key exists, `f` receives `Some(currentValue)`.
+     *
+     * Useful for incrementing counters, initialising defaults, or conditional updates.
+     *
+     * @example
+     * ```ts
+     * import { Option } from "@nlozgachev/pipelined/core";
+     *
+     * const increment = (opt: Option<number>) => Option.getOrElse(() => 0)(opt) + 1;
+     * pipe(Dict.fromEntries([["views", 5]]), Dict.upsert("views", increment)); // { views: 6 }
+     * pipe(Dict.fromEntries([["views", 5]]), Dict.upsert("likes", increment)); // { views: 5, likes: 1 }
+     * ```
+     */
+    Dict.upsert = (key, f) => (m) => {
+        const result = new globalThis.Map(m);
+        result.set(key, f(Dict.lookup(key)(m)));
+        return result;
+    };
+    // ---------------------------------------------------------------------------
+    // Transform
+    // ---------------------------------------------------------------------------
+    /**
+     * Transforms each value in the dictionary.
+     *
+     * @example
+     * ```ts
+     * pipe(Dict.fromEntries([["a", 1], ["b", 2]]), Dict.map(n => n * 2));
+     * // ReadonlyMap { "a" => 2, "b" => 4 }
+     * ```
+     */
+    Dict.map = (f) => (m) => {
+        const result = new globalThis.Map();
+        for (const [k, v] of m) {
+            result.set(k, f(v));
+        }
+        return result;
+    };
+    /**
+     * Transforms each value in the dictionary, also receiving the key.
+     *
+     * @example
+     * ```ts
+     * pipe(Dict.fromEntries([["a", 1], ["b", 2]]), Dict.mapWithKey((k, v) => `${k}:${v}`));
+     * // ReadonlyMap { "a" => "a:1", "b" => "b:2" }
+     * ```
+     */
+    Dict.mapWithKey = (f) => (m) => {
+        const result = new globalThis.Map();
+        for (const [k, v] of m) {
+            result.set(k, f(k, v));
+        }
+        return result;
+    };
+    /**
+     * Returns a new dictionary containing only the entries for which the predicate returns `true`.
+     *
+     * @example
+     * ```ts
+     * pipe(Dict.fromEntries([["a", 1], ["b", 3], ["c", 0]]), Dict.filter(n => n > 0));
+     * // ReadonlyMap { "a" => 1, "b" => 3 }
+     * ```
+     */
+    Dict.filter = (predicate) => (m) => {
+        const result = new globalThis.Map();
+        for (const [k, v] of m) {
+            if (predicate(v))
+                result.set(k, v);
+        }
+        return result;
+    };
+    /**
+     * Returns a new dictionary containing only the entries for which the predicate returns `true`.
+     * The predicate also receives the key.
+     *
+     * @example
+     * ```ts
+     * pipe(Dict.fromEntries([["a", 1], ["b", 2]]), Dict.filterWithKey((k, v) => k !== "a" && v > 0));
+     * // ReadonlyMap { "b" => 2 }
+     * ```
+     */
+    Dict.filterWithKey = (predicate) => (m) => {
+        const result = new globalThis.Map();
+        for (const [k, v] of m) {
+            if (predicate(k, v))
+                result.set(k, v);
+        }
+        return result;
+    };
+    /**
+     * Removes all `None` values from a `ReadonlyMap<K, Option<A>>`, returning a plain
+     * `ReadonlyMap<K, A>`. Useful when building dictionaries from fallible lookups.
+     *
+     * @example
+     * ```ts
+     * import { Option } from "@nlozgachev/pipelined/core";
+     *
+     * Dict.compact(Dict.fromEntries([
+     *   ["a", Option.some(1)],
+     *   ["b", Option.none()],
+     *   ["c", Option.some(3)],
+     * ]));
+     * // ReadonlyMap { "a" => 1, "c" => 3 }
+     * ```
+     */
+    Dict.compact = (m) => {
+        const result = new globalThis.Map();
+        for (const [k, v] of m) {
+            if (v.kind === "Some")
+                result.set(k, v.value);
+        }
+        return result;
+    };
+    // ---------------------------------------------------------------------------
+    // Combine
+    // ---------------------------------------------------------------------------
+    /**
+     * Merges two dictionaries. When both contain the same key, the value from `other` takes
+     * precedence.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Dict.fromEntries([["a", 1], ["b", 2]]),
+     *   Dict.union(Dict.fromEntries([["b", 3], ["c", 4]])),
+     * );
+     * // ReadonlyMap { "a" => 1, "b" => 3, "c" => 4 }
+     * ```
+     */
+    Dict.union = (other) => (m) => {
+        const result = new globalThis.Map(m);
+        for (const [k, v] of other) {
+            result.set(k, v);
+        }
+        return result;
+    };
+    /**
+     * Returns a new dictionary containing only the entries whose keys appear in both dictionaries.
+     * Values are taken from the left (base) dictionary.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Dict.fromEntries([["a", 1], ["b", 2], ["c", 3]]),
+     *   Dict.intersection(Dict.fromEntries([["b", 99], ["c", 0]])),
+     * );
+     * // ReadonlyMap { "b" => 2, "c" => 3 }
+     * ```
+     */
+    Dict.intersection = (other) => (m) => {
+        const result = new globalThis.Map();
+        for (const [k, v] of m) {
+            if (other.has(k))
+                result.set(k, v);
+        }
+        return result;
+    };
+    /**
+     * Returns a new dictionary containing only the entries whose keys do not appear in `other`.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Dict.fromEntries([["a", 1], ["b", 2], ["c", 3]]),
+     *   Dict.difference(Dict.fromEntries([["b", 0]])),
+     * );
+     * // ReadonlyMap { "a" => 1, "c" => 3 }
+     * ```
+     */
+    Dict.difference = (other) => (m) => {
+        const result = new globalThis.Map();
+        for (const [k, v] of m) {
+            if (!other.has(k))
+                result.set(k, v);
+        }
+        return result;
+    };
+    // ---------------------------------------------------------------------------
+    // Fold
+    // ---------------------------------------------------------------------------
+    /**
+     * Folds the dictionary into a single value by applying `f` to each value in insertion order.
+     * When you also need the key, use `reduceWithKey`.
+     *
+     * @example
+     * ```ts
+     * Dict.reduce(0, (acc, value) => acc + value)(
+     *   Dict.fromEntries([["a", 1], ["b", 2], ["c", 3]])
+     * ); // 6
+     * ```
+     */
+    Dict.reduce = (init, f) => (m) => {
+        let acc = init;
+        for (const v of m.values()) {
+            acc = f(acc, v);
+        }
+        return acc;
+    };
+    /**
+     * Folds the dictionary into a single value by applying `f` to each key-value pair in insertion
+     * order.
+     *
+     * @example
+     * ```ts
+     * Dict.reduceWithKey("", (acc, value, key) => acc + key + ":" + value + " ")(
+     *   Dict.fromEntries([["a", 1], ["b", 2]])
+     * ); // "a:1 b:2 "
+     * ```
+     */
+    Dict.reduceWithKey = (init, f) => (m) => {
+        let acc = init;
+        for (const [k, v] of m) {
+            acc = f(acc, v, k);
+        }
+        return acc;
+    };
+    // ---------------------------------------------------------------------------
+    // Convert
+    // ---------------------------------------------------------------------------
+    /**
+     * Converts a `ReadonlyMap<string, V>` to a plain object. Only meaningful when keys are strings.
+     *
+     * @example
+     * ```ts
+     * Dict.toRecord(Dict.fromEntries([["a", 1], ["b", 2]])); // { a: 1, b: 2 }
+     * ```
+     */
+    Dict.toRecord = (m) => Object.fromEntries(m);
+})(Dict || (exports.Dict = Dict = {}));