@nlozgachev/pipelined 0.11.0 → 0.12.0

package/esm/src/Core/Tuple.js

@@ -0,0 +1,112 @@
+export var Tuple;
+(function (Tuple) {
+    /**
+     * Creates a pair from two values.
+     *
+     * @example
+     * ```ts
+     * Tuple.make("Paris", 2_161_000); // ["Paris", 2161000]
+     * ```
+     */
+    Tuple.make = (first, second) => [first, second];
+    /**
+     * Returns the first value from the pair.
+     *
+     * @example
+     * ```ts
+     * Tuple.first(Tuple.make("Paris", 2_161_000)); // "Paris"
+     * ```
+     */
+    Tuple.first = (tuple) => tuple[0];
+    /**
+     * Returns the second value from the pair.
+     *
+     * @example
+     * ```ts
+     * Tuple.second(Tuple.make("Paris", 2_161_000)); // 2161000
+     * ```
+     */
+    Tuple.second = (tuple) => tuple[1];
+    /**
+     * Transforms the first value, leaving the second unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(Tuple.make("alice", 42), Tuple.mapFirst((s) => s.toUpperCase())); // ["ALICE", 42]
+     * ```
+     */
+    Tuple.mapFirst = (f) => (tuple) => [f(tuple[0]), tuple[1]];
+    /**
+     * Transforms the second value, leaving the first unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(Tuple.make("alice", 42), Tuple.mapSecond((n) => n * 2)); // ["alice", 84]
+     * ```
+     */
+    Tuple.mapSecond = (f) => (tuple) => [tuple[0], f(tuple[1])];
+    /**
+     * Transforms both values independently in a single step.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Tuple.make("alice", 42),
+     *   Tuple.mapBoth(
+     *     (name) => name.toUpperCase(),
+     *     (score) => score * 2,
+     *   ),
+     * ); // ["ALICE", 84]
+     * ```
+     */
+    Tuple.mapBoth = (onFirst, onSecond) => (tuple) => [
+        onFirst(tuple[0]),
+        onSecond(tuple[1]),
+    ];
+    /**
+     * Applies a binary function to both values, collapsing the pair into a single value.
+     * Useful as the final step when consuming a pair in a pipeline.
+     *
+     * @example
+     * ```ts
+     * pipe(Tuple.make("Alice", 100), Tuple.fold((name, score) => `${name}: ${score}`));
+     * // "Alice: 100"
+     * ```
+     */
+    Tuple.fold = (f) => (tuple) => f(tuple[0], tuple[1]);
+    /**
+     * Swaps the two values: `[A, B]` becomes `[B, A]`.
+     *
+     * @example
+     * ```ts
+     * Tuple.swap(Tuple.make("key", 1)); // [1, "key"]
+     * ```
+     */
+    Tuple.swap = (tuple) => [tuple[1], tuple[0]];
+    /**
+     * Converts the pair to a heterogeneous readonly array `readonly (A | B)[]`.
+     *
+     * @example
+     * ```ts
+     * Tuple.toArray(Tuple.make("hello", 42)); // ["hello", 42]
+     * ```
+     */
+    Tuple.toArray = (tuple) => [...tuple];
+    /**
+     * Runs a side effect with both values without changing the pair.
+     * Useful for logging or debugging in the middle of a pipeline.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Tuple.make("Paris", 2_161_000),
+     *   Tuple.tap((city, pop) => console.log(`${city}: ${pop}`)),
+     *   Tuple.mapSecond((n) => n / 1_000_000),
+     * ); // logs "Paris: 2161000", returns ["Paris", 2.161]
+     * ```
+     */
+    Tuple.tap = (f) => (tuple) => {
+        f(tuple[0], tuple[1]);
+        return tuple;
+    };
+})(Tuple || (Tuple = {}));

package/esm/src/Core/index.js

@@ -1,17 +1,18 @@
-export * from "./Logged.js";
 export * from "./Deferred.js";
 export * from "./Lens.js";
+export * from "./Logged.js";
 export * from "./Option.js";
-export * from "./Reader.js";
 export * from "./Optional.js";
 export * from "./Predicate.js";
+export * from "./Reader.js";
 export * from "./Refinement.js";
 export * from "./RemoteData.js";
-export * from "./State.js";
 export * from "./Result.js";
+export * from "./State.js";
 export * from "./Task.js";
 export * from "./TaskOption.js";
 export * from "./TaskResult.js";
 export * from "./TaskValidation.js";
 export * from "./These.js";
+export * from "./Tuple.js";
 export * from "./Validation.js";

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/Rec.js

@@ -117,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.
      *