@nlozgachev/pipelined 0.10.0 → 0.12.0

package/esm/src/Utils/Dict.js

@@ -0,0 +1,421 @@
+import { Option } from "../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" }
+ * ```
+ */
+export 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.some(m.get(key)) : 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 || (Dict = {}));

package/esm/src/Utils/Num.js

@@ -0,0 +1,124 @@
+import { Option } from "../Core/Option.js";
+/**
+ * Number utilities for common operations. All transformation functions are data-last
+ * and curried so they compose naturally with `pipe` and `Arr.map`.
+ *
+ * @example
+ * ```ts
+ * import { Num } from "@nlozgachev/pipelined/utils";
+ * import { pipe } from "@nlozgachev/pipelined/composition";
+ *
+ * pipe(
+ *   Num.range(1, 6),
+ *   Arr.map(Num.multiply(2)),
+ *   Arr.filter(Num.between(4, 8))
+ * ); // [4, 6, 8]
+ * ```
+ */
+export var Num;
+(function (Num) {
+    /**
+     * Generates an array of numbers from `from` to `to` (both inclusive),
+     * stepping by `step` (default `1`). If `step` is negative or zero, or `from > to`,
+     * returns an empty array. When `step` does not land exactly on `to`, the last value
+     * is the largest reachable value that does not exceed `to`.
+     *
+     * @example
+     * ```ts
+     * Num.range(0, 5);       // [0, 1, 2, 3, 4, 5]
+     * Num.range(0, 10, 2);   // [0, 2, 4, 6, 8, 10]
+     * Num.range(0, 9, 2);    // [0, 2, 4, 6, 8]
+     * Num.range(5, 0);       // []
+     * Num.range(3, 3);       // [3]
+     * ```
+     */
+    Num.range = (from, to, step = 1) => {
+        if (step <= 0 || from > to)
+            return [];
+        const count = Math.floor((to - from) / step) + 1;
+        const result = new Array(count);
+        for (let i = 0; i < count; i++) {
+            result[i] = from + i * step;
+        }
+        return result;
+    };
+    /**
+     * Clamps a number between `min` and `max` (both inclusive).
+     *
+     * @example
+     * ```ts
+     * pipe(150, Num.clamp(0, 100)); // 100
+     * pipe(-5, Num.clamp(0, 100));  // 0
+     * pipe(42, Num.clamp(0, 100));  // 42
+     * ```
+     */
+    Num.clamp = (min, max) => (n) => Math.min(Math.max(n, min), max);
+    /**
+     * Returns `true` when the number is between `min` and `max` (both inclusive).
+     *
+     * @example
+     * ```ts
+     * pipe(5, Num.between(1, 10));  // true
+     * pipe(0, Num.between(1, 10));  // false
+     * pipe(10, Num.between(1, 10)); // true
+     * ```
+     */
+    Num.between = (min, max) => (n) => n >= min && n <= max;
+    /**
+     * Parses a string as a number. Returns `None` when the result is `NaN`.
+     *
+     * @example
+     * ```ts
+     * Num.parse("42");   // Some(42)
+     * Num.parse("3.14"); // Some(3.14)
+     * Num.parse("abc");  // None
+     * Num.parse("");     // None
+     * ```
+     */
+    Num.parse = (s) => {
+        if (s.trim() === "")
+            return Option.none();
+        const n = Number(s);
+        return isNaN(n) ? Option.none() : Option.some(n);
+    };
+    /**
+     * Adds `b` to a number. Data-last: use in `pipe` or `Arr.map`.
+     *
+     * @example
+     * ```ts
+     * pipe(5, Num.add(3));                   // 8
+     * pipe([1, 2, 3], Arr.map(Num.add(10))); // [11, 12, 13]
+     * ```
+     */
+    Num.add = (b) => (a) => a + b;
+    /**
+     * Subtracts `b` from a number. Data-last: `subtract(b)(a)` = `a - b`.
+     *
+     * @example
+     * ```ts
+     * pipe(10, Num.subtract(3));                  // 7
+     * pipe([5, 10, 15], Arr.map(Num.subtract(2))); // [3, 8, 13]
+     * ```
+     */
+    Num.subtract = (b) => (a) => a - b;
+    /**
+     * Multiplies a number by `b`. Data-last: use in `pipe` or `Arr.map`.
+     *
+     * @example
+     * ```ts
+     * pipe(6, Num.multiply(7));                    // 42
+     * pipe([1, 2, 3], Arr.map(Num.multiply(100))); // [100, 200, 300]
+     * ```
+     */
+    Num.multiply = (b) => (a) => a * b;
+    /**
+     * Divides a number by `b`. Data-last: `divide(b)(a)` = `a / b`.
+     *
+     * @example
+     * ```ts
+     * pipe(20, Num.divide(4));                      // 5
+     * pipe([10, 20, 30], Arr.map(Num.divide(10)));  // [1, 2, 3]
+     * ```
+     */
+    Num.divide = (b) => (a) => a / b;
+})(Num || (Num = {}));

package/esm/src/{Core → Utils}/Rec.js

@@ -1,4 +1,4 @@
-import { Option } from "./Option.js";
+import { Option } from "../Core/Option.js";
 /**
  * Functional record/object utilities that compose well with pipe.
  * All functions are data-last and curried where applicable.
@@ -23,9 +23,11 @@ export var Rec;
      * ```
      */
     Rec.map = (f) => (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
         const result = {};
-        for (const key of Object.keys(data)) {
-            result[key] = f(data[key]);
+        for (let i = 0; i < keys.length; i++) {
+            result[keys[i]] = f(vals[i]);
         }
         return result;
     };
@@ -39,9 +41,11 @@ export var Rec;
      * ```
      */
     Rec.mapWithKey = (f) => (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
         const result = {};
-        for (const key of Object.keys(data)) {
-            result[key] = f(key, data[key]);
+        for (let i = 0; i < keys.length; i++) {
+            result[keys[i]] = f(keys[i], vals[i]);
         }
         return result;
     };
@@ -54,10 +58,12 @@ export var Rec;
      * ```
      */
     Rec.filter = (predicate) => (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
         const result = {};
-        for (const key of Object.keys(data)) {
-            if (predicate(data[key]))
-                result[key] = data[key];
+        for (let i = 0; i < keys.length; i++) {
+            if (predicate(vals[i]))
+                result[keys[i]] = vals[i];
         }
         return result;
     };
@@ -71,10 +77,12 @@ export var Rec;
      * ```
      */
     Rec.filterWithKey = (predicate) => (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
         const result = {};
-        for (const key of Object.keys(data)) {
-            if (predicate(key, data[key]))
-                result[key] = data[key];
+        for (let i = 0; i < keys.length; i++) {
+            if (predicate(keys[i], vals[i]))
+                result[keys[i]] = vals[i];
         }
         return result;
     };
@@ -109,6 +117,32 @@ export var Rec;
      * ```
      */
     Rec.fromEntries = (data) => Object.fromEntries(data);
+    /**
+     * Groups elements of an array into a record keyed by the result of `keyFn`. Each key maps to
+     * the array of elements that produced it, in insertion order.
+     *
+     * Unlike `Dict.groupBy`, keys are always strings. Use `Dict.groupBy` when you need non-string
+     * keys or want to avoid the plain-object prototype chain.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   ["apple", "avocado", "banana", "blueberry"],
+     *   Rec.groupBy(s => s[0]),
+     * ); // { a: ["apple", "avocado"], b: ["banana", "blueberry"] }
+     * ```
+     */
+    Rec.groupBy = (keyFn) => (items) => {
+        const result = {};
+        for (const item of items) {
+            const key = keyFn(item);
+            if (key in result)
+                result[key].push(item);
+            else
+                result[key] = [item];
+        }
+        return result;
+    };
     /**
      * Picks specific keys from a record.
      *
@@ -164,4 +198,44 @@ export var Rec;
      * Returns the number of keys in a record.
      */
     Rec.size = (data) => Object.keys(data).length;
+    /**
+     * Transforms each key while preserving values.
+     * If two keys map to the same new key, the last one wins.
+     *
+     * @example
+     * ```ts
+     * pipe({ firstName: "Alice", lastName: "Smith" }, Rec.mapKeys(k => k.toUpperCase()));
+     * // { FIRSTNAME: "Alice", LASTNAME: "Smith" }
+     * ```
+     */
+    Rec.mapKeys = (f) => (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
+        const result = {};
+        for (let i = 0; i < keys.length; i++) {
+            result[f(keys[i])] = vals[i];
+        }
+        return result;
+    };
+    /**
+     * Removes all `None` values from a `Record<string, Option<A>>`, returning a plain `Record<string, A>`.
+     * Useful when building records from fallible lookups.
+     *
+     * @example
+     * ```ts
+     * Rec.compact({ a: Option.some(1), b: Option.none(), c: Option.some(3) });
+     * // { a: 1, c: 3 }
+     * ```
+     */
+    Rec.compact = (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
+        const result = {};
+        for (let i = 0; i < keys.length; i++) {
+            const v = vals[i];
+            if (v.kind === "Some")
+                result[keys[i]] = v.value;
+        }
+        return result;
+    };
 })(Rec || (Rec = {}));