@nlozgachev/pipelined 0.12.0 → 0.14.0

package/esm/src/Utils/Dict.js

@@ -1,421 +0,0 @@
-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

@@ -1,124 +0,0 @@
-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 = {}));