@nlozgachev/pipelined 0.46.0 → 0.48.0

package/dist/{utils.d.mts → data.d.mts}

@@ -1,6 +1,7 @@
-import { a as NonEmptyArr, N as NonEmpty } from './InternalTypes-CLE7qlOc.mjs';
-import { M as Maybe, R as Result, E as Equality, b as Ordering, T as Task } from './Validation-v38R0qH-.mjs';
-import { Brand } from './types.mjs';
+import { a as NonEmptyArr, N as NonEmpty } from './InternalTypes-CDiDBAY4.mjs';
+import { M as Maybe, R as Result, E as Equality, b as Ordering, T as Task } from './Validation-D-aARYlP.mjs';
+import { B as Brand } from './Duration-B8joKzro.mjs';
+import './types.mjs';
 
 declare namespace ArrTaskResult {
     /**
@@ -14,12 +15,12 @@ declare namespace ArrTaskResult {
      *
      * pipe(
      *   [1, 2, 3],
-     *   Arr.Task.Result.traverse(validate)
+     *   Arr.traverse.Task.Result(validate)
      * )(); // Deferred<Ok([1, 2, 3])>
      *
      * pipe(
      *   [1, -1, 3],
-     *   Arr.Task.Result.traverse(validate)
+     *   Arr.traverse.Task.Result(validate)
      * )(); // Deferred<Err("non-positive")>
      * ```
      */
@@ -27,6 +28,14 @@ declare namespace ArrTaskResult {
     /**
      * Collects an array of Task.Results into a Task.Result of array.
      * Returns the first Err if any element is Err, runs sequentially.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   [Task.Result.ok(1), Task.Result.ok(2)],
+     *   Arr.sequence.Task.Result
+     * )(); // Deferred<Ok([1, 2])>
+     * ```
      */
     const sequence: <E, A>(data: readonly Task<Result<E, A>>[]) => Task<Result<E, readonly A[]>>;
 }
@@ -84,7 +93,7 @@ declare namespace ArrNonEmpty {
      *
      * @example
      * ```ts
-     * pipe([1, 2, 3, 4] as NonEmptyArr<number>, Arr.NonEmpty.reduce((a, b) => a + b)); // 10
+     * pipe([1, 2, 3, 4] as Arr.NonEmpty<number>, Arr.NonEmpty.reduce((a: number, b: number) => a + b)); // 10
      * ```
      */
     const reduce: <A>(f: (acc: A, a: A) => A) => (data: NonEmptyArr<A>) => A;
@@ -383,6 +392,8 @@ declare namespace Arr {
      * ```ts
      * pipe([3, 1, 2], Arr.sortWith(Ordering.number)); // [1, 2, 3]
      *
+     * type Product = { price: number };
+     * const products: Product[] = [{ price: 20 }, { price: 10 }];
      * const byPrice = pipe(Ordering.number, Ordering.by((p: Product) => p.price));
      * pipe(products, Arr.sortWith(byPrice));
      * ```
@@ -402,7 +413,7 @@ declare namespace Arr {
      *
      * @example
      * ```ts
-     * pipe([1, 2], Arr.zipWith((a, b) => a + b, ["a", "b"])); // ["1a", "2b"]
+     * pipe([1, 2], Arr.zipWith((a: number, b: string) => `${a}${b}`)(["a", "b"])); // ["1a", "2b"]
      * ```
      */
     export const zipWith: <A, B, C>(f: (a: A, b: B) => C) => (other: readonly B[]) => (data: readonly A[]) => readonly C[];
@@ -481,10 +492,22 @@ declare namespace Arr {
     export namespace is {
         /**
          * Returns true if the array is empty.
+         *
+         * @example
+         * ```ts
+         * Arr.is.empty([]);  // true
+         * Arr.is.empty([1]); // false
+         * ```
          */
         const empty: <A>(data: readonly A[]) => data is readonly [];
         /**
          * Returns true if the array is non-empty (type guard).
+         *
+         * @example
+         * ```ts
+         * Arr.is.nonEmpty([1, 2]); // true
+         * Arr.is.nonEmpty([]);     // false
+         * ```
          */
         const nonEmpty: <A>(data: readonly A[]) => data is NonEmpty<A>;
     }
@@ -508,6 +531,11 @@ declare namespace Arr {
     export const append: <A>(value: A) => (data: readonly A[]) => NonEmpty<A>;
     /**
      * Returns the length of an array.
+     *
+     * @example
+     * ```ts
+     * Arr.size([1, 2, 3]); // 3
+     * ```
      */
     export const size: <A>(data: readonly A[]) => number;
     /**
@@ -619,10 +647,257 @@ declare namespace Arr {
      * ```
      */
     export const splitAt: (index: number) => <A>(data: readonly A[]) => readonly [readonly A[], readonly A[]];
+    /**
+     * Partitions an array by applying a function returning `Maybe<B>`.
+     * Elements returning `None` are gathered into `failures` (original `A` values);
+     * elements returning `Some(b)` are gathered into `successes` (`B` values).
+     *
+     * @example
+     * ```ts
+     * const parseNumber = (s: string) => isNaN(Number(s)) ? Maybe.make.none() : Maybe.make.some(Number(s));
+     * pipe(["1", "abc", "3"], Arr.partitionMaybe(parseNumber)); // [["abc"], [1, 3]]
+     * ```
+     */
+    export const partitionMaybe: <A, B>(f: (a: A) => Maybe<B>) => (data: readonly A[]) => readonly [failures: readonly A[], successes: readonly B[]];
+    /**
+     * Safely looks up an element by index. Supports negative indices counting back from the end.
+     * Returns `None` if the index is out of bounds.
+     *
+     * @example
+     * ```ts
+     * pipe([10, 20, 30], Arr.at(1));  // Some(20)
+     * pipe([10, 20, 30], Arr.at(-1)); // Some(30)
+     * pipe([10, 20, 30], Arr.at(5));  // None
+     * ```
+     */
+    export const at: (index: number) => <A>(data: readonly A[]) => Maybe<A>;
+    /**
+     * Finds the first element in an array for which `f` returns `Some(b)`.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   ["1", "a", "2"],
+     *   Arr.findMap((s) => isNaN(Number(s)) ? Maybe.make.none() : Maybe.make.some(Number(s)))
+     * ); // Some(1)
+     * ```
+     */
+    export const findMap: <A, B>(f: (a: A) => Maybe<B>) => (data: readonly A[]) => Maybe<B>;
+    /**
+     * Indexes elements of an array into a `ReadonlyMap<K, A>` using a key extraction function.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   [{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }],
+     *   Arr.indexBy((u) => u.id)
+     * ); // ReadonlyMap { 1 => { id: 1, name: "Alice" }, 2 => { id: 2, name: "Bob" } }
+     * ```
+     */
+    export const indexBy: <A, K>(keyFn: (a: A) => K) => (data: readonly A[]) => ReadonlyMap<K, A>;
+    /**
+     * Counts occurrences of each element in an array, returning a `ReadonlyMap<A, number>`.
+     *
+     * @example
+     * ```ts
+     * Arr.frequencies(["a", "b", "a", "c", "b", "a"]);
+     * // ReadonlyMap { "a" => 3, "b" => 2, "c" => 1 }
+     * ```
+     */
+    export const frequencies: <A>(data: readonly A[]) => ReadonlyMap<A, number>;
+    /**
+     * Groups consecutive elements that share the same key returned by `keyFn`.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   [1, 1, 2, 3, 3, 1],
+     *   Arr.chunkBy((n) => n)
+     * ); // [[1, 1], [2], [3, 3], [1]]
+     * ```
+     */
+    export const chunkBy: <A, K>(keyFn: (a: A) => K) => (data: readonly A[]) => readonly (readonly A[])[];
+    /**
+     * Removes consecutive duplicate elements.
+     * An optional `Equality<A>` can be provided (defaults to `Object.is`).
+     *
+     * @example
+     * ```ts
+     * Arr.dedupeAdjacent()([1, 1, 2, 2, 1, 3]); // [1, 2, 1, 3]
+     * ```
+     */
+    export const dedupeAdjacent: <A>(eq?: Equality<A>) => (data: readonly A[]) => readonly A[];
+    /**
+     * Produces a sliding window of `size` elements over an array, advancing by `step` (default `1`).
+     * Returns an empty array if `size <= 0` or `size > data.length`.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3, 4], Arr.windowed(2)); // [[1, 2], [2, 3], [3, 4]]
+     * pipe([1, 2, 3, 4], Arr.windowed(2, { step: 2 })); // [[1, 2], [3, 4]]
+     * ```
+     */
+    export const windowed: (size: number, options?: {
+        step?: number;
+    }) => <A>(data: readonly A[]) => readonly (readonly A[])[];
+    /**
+     * Generates an array from an initial seed state until `f` returns `None`.
+     *
+     * @example
+     * ```ts
+     * Arr.unfold(1, (n) => n > 3 ? Maybe.make.none() : Maybe.make.some([n, n + 1]));
+     * // [1, 2, 3]
+     * ```
+     */
+    export const unfold: <A, S>(initial: S, f: (state: S) => Maybe<readonly [A, S]>) => readonly A[];
     export const NonEmpty: typeof ArrNonEmpty;
     export {  };
 }
 
+/**
+ * Safe conversion and arithmetic utilities for arbitrary-precision integers (`bigint`).
+ * All functions are pure and data-last to compose cleanly with `pipe`.
+ *
+ * @example
+ * ```ts
+ * import { BigNum } from "@nlozgachev/pipelined/data";
+ * import { pipe } from "@nlozgachev/pipelined/composition";
+ *
+ * const result = pipe(
+ *   BigNum.from.string("100"),
+ *   Maybe.map(BigNum.add(50n))
+ * ); // Some(150n)
+ * ```
+ */
+declare namespace BigNum {
+    namespace from {
+        /**
+         * Safely parses a string into a `bigint`. Returns `None` if parsing fails.
+         *
+         * @example
+         * ```ts
+         * BigNum.from.string("123"); // Some(123n)
+         * BigNum.from.string("abc"); // None
+         * ```
+         */
+        const string: (s: string) => Maybe<bigint>;
+        /**
+         * Safely converts a number into a `bigint`. Returns `None` for floats, `NaN`, or non-safe integers.
+         *
+         * @example
+         * ```ts
+         * BigNum.from.number(42);   // Some(42n)
+         * BigNum.from.number(3.14); // None
+         * ```
+         */
+        const number: (n: number) => Maybe<bigint>;
+    }
+    namespace to {
+        /**
+         * Safely converts a `bigint` to a `number`. Returns `None` if the value is outside JavaScript's safe integer range.
+         *
+         * @example
+         * ```ts
+         * BigNum.to.number(42n);                    // Some(42)
+         * BigNum.to.number(9007199254740993n);      // None
+         * ```
+         */
+        const number: (b: bigint) => Maybe<number>;
+    }
+    /**
+     * Adds `b` to `a`. Data-last curried signature: `add(b)(a)` = `a + b`.
+     *
+     * @example
+     * ```ts
+     * pipe(10n, BigNum.add(5n)); // 15n
+     * ```
+     */
+    const add: (b: bigint) => (a: bigint) => bigint;
+    /**
+     * Subtracts `b` from `a`. Data-last curried signature: `sub(b)(a)` = `a - b`.
+     *
+     * @example
+     * ```ts
+     * pipe(10n, BigNum.sub(3n)); // 7n
+     * ```
+     */
+    const sub: (b: bigint) => (a: bigint) => bigint;
+    /**
+     * Multiplies `a` by `b`. Data-last curried signature: `mul(b)(a)` = `a * b`.
+     *
+     * @example
+     * ```ts
+     * pipe(6n, BigNum.mul(7n)); // 42n
+     * ```
+     */
+    const mul: (b: bigint) => (a: bigint) => bigint;
+    /**
+     * Divides `a` by `b`. Returns `None` if `b` is `0n`.
+     *
+     * @example
+     * ```ts
+     * pipe(20n, BigNum.div(4n)); // Some(5n)
+     * pipe(5n, BigNum.div(0n));  // None
+     * ```
+     */
+    const div: (b: bigint) => (a: bigint) => Maybe<bigint>;
+    /**
+     * Computes remainder of `a / b`. Returns `None` if `b` is `0n`.
+     *
+     * @example
+     * ```ts
+     * pipe(10n, BigNum.mod(3n)); // Some(1n)
+     * pipe(5n, BigNum.mod(0n));  // None
+     * ```
+     */
+    const mod: (b: bigint) => (a: bigint) => Maybe<bigint>;
+    /**
+     * Clamps `a` between `min` and `max` (inclusive).
+     *
+     * @example
+     * ```ts
+     * pipe(150n, BigNum.clamp(0n, 100n)); // 100n
+     * ```
+     */
+    const clamp: (min: bigint, max: bigint) => (a: bigint) => bigint;
+    /**
+     * Returns `true` if `a` is in the range `[start, end)` (inclusive start, exclusive end).
+     *
+     * @example
+     * ```ts
+     * pipe(5n, BigNum.inRange(1n, 10n)); // true
+     * ```
+     */
+    const inRange: (start: bigint, end: bigint) => (a: bigint) => boolean;
+    /**
+     * Returns absolute value of a `bigint`.
+     *
+     * @example
+     * ```ts
+     * BigNum.abs(-42n); // 42n
+     * ```
+     */
+    const abs: (a: bigint) => bigint;
+    /**
+     * Returns the minimum of `a` and `b`.
+     *
+     * @example
+     * ```ts
+     * pipe(10n, BigNum.min(5n)); // 5n
+     * ```
+     */
+    const min: (b: bigint) => (a: bigint) => bigint;
+    /**
+     * Returns the maximum of `a` and `b`.
+     *
+     * @example
+     * ```ts
+     * pipe(10n, BigNum.max(5n)); // 10n
+     * ```
+     */
+    const max: (b: bigint) => (a: bigint) => bigint;
+}
+
 /**
  * A branded type representing a key-value dictionary with at least one entry.
  */
@@ -743,6 +1018,12 @@ declare namespace Dict {
         const empty: <K, V>(m: ReadonlyMap<K, V>) => boolean;
         /**
          * Type guard to check if a dictionary is non-empty.
+         *
+         * @example
+         * ```ts
+         * Dict.is.nonEmpty(Dict.from.entries([["a", 1]])); // true
+         * Dict.is.nonEmpty(Dict.empty());                 // false
+         * ```
          */
         const nonEmpty: <K, V>(m: ReadonlyMap<K, V>) => m is NonEmpty<K, V>;
     }
@@ -804,8 +1085,8 @@ declare namespace Dict {
      *
      * @example
      * ```ts
-     * pipe(Dict.from.Entries([["a", 1]]), Dict.has("a")); // true
-     * pipe(Dict.from.Entries([["a", 1]]), Dict.has("b")); // false
+     * pipe(Dict.from.entries([["a", 1]]), Dict.has("a")); // true
+     * pipe(Dict.from.entries([["a", 1]]), Dict.has("b")); // false
      * ```
      */
     const has: <K>(key: K) => <V>(m: ReadonlyMap<K, V>) => boolean;
@@ -814,8 +1095,8 @@ declare namespace Dict {
      *
      * @example
      * ```ts
-     * pipe(Dict.from.Entries([["a", 1]]), Dict.lookup("a")); // Some(1)
-     * pipe(Dict.from.Entries([["a", 1]]), Dict.lookup("b")); // None
+     * pipe(Dict.from.entries([["a", 1]]), Dict.lookup("a")); // Some(1)
+     * pipe(Dict.from.entries([["a", 1]]), Dict.lookup("b")); // None
      * ```
      */
     const lookup: <K>(key: K) => <V>(m: ReadonlyMap<K, V>) => Maybe<V>;
@@ -824,7 +1105,7 @@ declare namespace Dict {
      *
      * @example
      * ```ts
-     * Dict.size(Dict.from.Entries([["a", 1], ["b", 2]])); // 2
+     * Dict.size(Dict.from.entries([["a", 1], ["b", 2]])); // 2
      * ```
      */
     const size: <K, V>(m: ReadonlyMap<K, V>) => number;
@@ -833,7 +1114,7 @@ declare namespace Dict {
      *
      * @example
      * ```ts
-     * Dict.keys(Dict.from.Entries([["a", 1], ["b", 2]])); // ["a", "b"]
+     * Dict.keys(Dict.from.entries([["a", 1], ["b", 2]])); // ["a", "b"]
      * ```
      */
     const keys: <K, V>(m: ReadonlyMap<K, V>) => readonly K[];
@@ -842,7 +1123,7 @@ declare namespace Dict {
      *
      * @example
      * ```ts
-     * Dict.values(Dict.from.Entries([["a", 1], ["b", 2]])); // [1, 2]
+     * Dict.values(Dict.from.entries([["a", 1], ["b", 2]])); // [1, 2]
      * ```
      */
     const values: <K, V>(m: ReadonlyMap<K, V>) => readonly V[];
@@ -851,7 +1132,7 @@ declare namespace Dict {
      *
      * @example
      * ```ts
-     * Dict.entries(Dict.from.Entries([["a", 1], ["b", 2]])); // [["a", 1], ["b", 2]]
+     * Dict.entries(Dict.from.entries([["a", 1], ["b", 2]])); // [["a", 1], ["b", 2]]
      * ```
      */
     const entries: <K, V>(m: ReadonlyMap<K, V>) => readonly (readonly [K, V])[];
@@ -861,7 +1142,7 @@ declare namespace Dict {
      *
      * @example
      * ```ts
-     * pipe(Dict.from.Entries([["a", 1]]), Dict.insert("b", 2));
+     * pipe(Dict.from.entries([["a", 1]]), Dict.insert("b", 2));
      * // ReadonlyMap { "a" => 1, "b" => 2 }
      * ```
      */
@@ -872,7 +1153,7 @@ declare namespace Dict {
      *
      * @example
      * ```ts
-     * pipe(Dict.from.Entries([["a", 1], ["b", 2]]), Dict.remove("a"));
+     * pipe(Dict.from.entries([["a", 1], ["b", 2]]), Dict.remove("a"));
      * // ReadonlyMap { "b" => 2 }
      * ```
      */
@@ -885,11 +1166,9 @@ declare namespace Dict {
      *
      * @example
      * ```ts
-     * import { Maybe } from "@nlozgachev/pipelined/core";
-     *
-     * const increment = (opt: Maybe<number>) => Maybe.getOrElse(() => 0)(opt) + 1;
-     * pipe(Dict.from.Entries([["views", 5]]), Dict.upsert("views", increment)); // { views: 6 }
-     * pipe(Dict.from.Entries([["views", 5]]), Dict.upsert("likes", increment)); // { views: 5, likes: 1 }
+     * const increment = (opt: Maybe<number>) => pipe(opt, Maybe.getOrElse(() => 0)) + 1;
+     * pipe(Dict.from.entries([["views", 5]]), Dict.upsert("views", increment)); // { views: 6 }
+     * pipe(Dict.from.entries([["views", 5]]), Dict.upsert("likes", increment)); // { views: 5, likes: 1 }
      * ```
      */
     const upsert: <K, V>(key: K, f: (existing: Maybe<V>) => V) => (m: ReadonlyMap<K, V>) => ReadonlyMap<K, V>;
@@ -898,7 +1177,7 @@ declare namespace Dict {
      *
      * @example
      * ```ts
-     * pipe(Dict.from.Entries([["a", 1], ["b", 2]]), Dict.map(n => n * 2));
+     * pipe(Dict.from.entries([["a", 1], ["b", 2]]), Dict.map(n => n * 2));
      * // ReadonlyMap { "a" => 2, "b" => 4 }
      * ```
      */
@@ -908,7 +1187,7 @@ declare namespace Dict {
      *
      * @example
      * ```ts
-     * pipe(Dict.from.Entries([["a", 1], ["b", 2]]), Dict.mapWithKey((k, v) => `${k}:${v}`));
+     * pipe(Dict.from.entries([["a", 1], ["b", 2]]), Dict.mapWithKey((k, v) => `${k}:${v}`));
      * // ReadonlyMap { "a" => "a:1", "b" => "b:2" }
      * ```
      */
@@ -918,7 +1197,7 @@ declare namespace Dict {
      *
      * @example
      * ```ts
-     * pipe(Dict.from.Entries([["a", 1], ["b", 3], ["c", 0]]), Dict.filter(n => n > 0));
+     * pipe(Dict.from.entries([["a", 1], ["b", 3], ["c", 0]]), Dict.filter(n => n > 0));
      * // ReadonlyMap { "a" => 1, "b" => 3 }
      * ```
      */
@@ -929,7 +1208,7 @@ declare namespace Dict {
      *
      * @example
      * ```ts
-     * pipe(Dict.from.Entries([["a", 1], ["b", 2]]), Dict.filterWithKey((k, v) => k !== "a" && v > 0));
+     * pipe(Dict.from.entries([["a", 1], ["b", 2]]), Dict.filterWithKey((k, v) => k !== "a" && v > 0));
      * // ReadonlyMap { "b" => 2 }
      * ```
      */
@@ -940,9 +1219,7 @@ declare namespace Dict {
      *
      * @example
      * ```ts
-     * import { Maybe } from "@nlozgachev/pipelined/core";
-     *
-     * Dict.compact(Dict.from.Entries([
+     * Dict.compact(Dict.from.entries<string, Maybe<number>>([
      *   ["a", Maybe.make.some(1)],
      *   ["b", Maybe.make.none()],
      *   ["c", Maybe.make.some(3)],
@@ -973,8 +1250,8 @@ declare namespace Dict {
      * @example
      * ```ts
      * pipe(
-     *   Dict.from.Entries([["a", 1], ["b", 2]]),
-     *   Dict.union(Dict.from.Entries([["b", 3], ["c", 4]])),
+     *   Dict.from.entries([["a", 1], ["b", 2]]),
+     *   Dict.union(Dict.from.entries([["b", 3], ["c", 4]])),
      * );
      * // ReadonlyMap { "a" => 1, "b" => 3, "c" => 4 }
      * ```
@@ -987,8 +1264,8 @@ declare namespace Dict {
      * @example
      * ```ts
      * pipe(
-     *   Dict.from.Entries([["a", 1], ["b", 2], ["c", 3]]),
-     *   Dict.intersection(Dict.from.Entries([["b", 99], ["c", 0]])),
+     *   Dict.from.entries([["a", 1], ["b", 2], ["c", 3]]),
+     *   Dict.intersection(Dict.from.entries([["b", 99], ["c", 0]])),
      * );
      * // ReadonlyMap { "b" => 2, "c" => 3 }
      * ```
@@ -1000,8 +1277,8 @@ declare namespace Dict {
      * @example
      * ```ts
      * pipe(
-     *   Dict.from.Entries([["a", 1], ["b", 2], ["c", 3]]),
-     *   Dict.difference(Dict.from.Entries([["b", 0]])),
+     *   Dict.from.entries([["a", 1], ["b", 2], ["c", 3]]),
+     *   Dict.difference(Dict.from.entries([["b", 0]])),
      * );
      * // ReadonlyMap { "a" => 1, "c" => 3 }
      * ```
@@ -1013,8 +1290,8 @@ declare namespace Dict {
      *
      * @example
      * ```ts
-     * Dict.reduce(0, (acc, value) => acc + value)(
-     *   Dict.from.Entries([["a", 1], ["b", 2], ["c", 3]])
+     * Dict.reduce(0, (acc, value: number) => acc + value)(
+     *   Dict.from.entries([["a", 1], ["b", 2], ["c", 3]])
      * ); // 6
      * ```
      */
@@ -1026,25 +1303,105 @@ declare namespace Dict {
      * @example
      * ```ts
      * Dict.reduceWithKey("", (acc, value, key) => acc + key + ":" + value + " ")(
-     *   Dict.from.Entries([["a", 1], ["b", 2]])
+     *   Dict.from.entries([["a", 1], ["b", 2]])
      * ); // "a:1 b:2 "
      * ```
      */
     const reduceWithKey: <K, A, B>(init: B, f: (acc: B, value: A, key: K) => B) => (m: ReadonlyMap<K, A>) => B;
+    /**
+     * Merges two maps using a custom combination function on key collisions.
+     * Supports both uncurried `Dict.mergeWith(combine)(first, second)` and curried `pipe(first, Dict.mergeWith(combine)(second))`.
+     *
+     * @example
+     * ```ts
+     * const combineStats = Dict.mergeWith((a: number, b: number) => a + b);
+     * const map1 = Dict.from.entries([["a", 1], ["b", 2]]);
+     * const map2 = Dict.from.entries([["b", 3], ["c", 4]]);
+     * combineStats(map1, map2);
+     * pipe(map1, combineStats(map2));
+     * ```
+     */
+    function mergeWith<K, V>(combine: (a: V, b: V) => V): {
+        (second: ReadonlyMap<K, V>): (first: ReadonlyMap<K, V>) => ReadonlyMap<K, V>;
+        (first: ReadonlyMap<K, V>, second: ReadonlyMap<K, V>): ReadonlyMap<K, V>;
+    };
     namespace to {
         /**
          * Converts a `ReadonlyMap<string, V>` to a plain object. Only meaningful when keys are strings.
          *
          * @example
          * ```ts
-         * Dict.to.Record(Dict.from.Entries([["a", 1], ["b", 2]])); // { a: 1, b: 2 }
+         * Dict.to.Record(Dict.from.entries([["a", 1], ["b", 2]])); // { a: 1, b: 2 }
          * ```
          */
         const Record: <V>(m: ReadonlyMap<string, V>) => Readonly<Record<string, V>>;
     }
+    /**
+     * Transforms key and value pairs simultaneously into a new ReadonlyMap.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Dict.from.entries([["a", 1], ["b", 2]]),
+     *   Dict.mapEntries((k, v) => [k.toUpperCase(), v * 10])
+     * ); // Map { "A" => 10, "B" => 20 }
+     * ```
+     */
+    const mapEntries: <K1, V1, K2, V2>(f: (key: K1, value: V1) => readonly [K2, V2]) => (data: ReadonlyMap<K1, V1>) => ReadonlyMap<K2, V2>;
+    /**
+     * Transforms keys of a ReadonlyMap while preserving values.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Dict.from.entries([["a", 1], ["b", 2]]),
+     *   Dict.mapKeys((k) => k.toUpperCase())
+     * ); // Map { "A" => 1, "B" => 2 }
+     * ```
+     */
+    const mapKeys: <K1, K2, V>(f: (key: K1) => K2) => (data: ReadonlyMap<K1, V>) => ReadonlyMap<K2, V>;
     const NonEmpty: typeof DictNonEmpty;
 }
 
+/**
+ * Pure, non-throwing JSON utilities.
+ * Wraps runtime JSON parsing and stringifying in typed `Result` containers.
+ *
+ * @example
+ * ```ts
+ * import { Json } from "@nlozgachev/pipelined/data";
+ * import { pipe } from "@nlozgachev/pipelined/composition";
+ *
+ * const result = pipe(
+ *   Json.parse('{"name":"Alice"}'),
+ *   Result.map((data: any) => data.name)
+ * ); // Ok("Alice")
+ * ```
+ */
+declare namespace Json {
+    /**
+     * Safely parses a JSON string into `unknown`.
+     * Converts thrown exceptions into a `Result<SyntaxError, unknown>`.
+     *
+     * @example
+     * ```ts
+     * Json.parse('{"a": 1}'); // Ok({ a: 1 })
+     * Json.parse('{invalid}'); // Err(SyntaxError)
+     * ```
+     */
+    const parse: (text: string) => Result<SyntaxError, unknown>;
+    /**
+     * Safely stringifies a value into a JSON string.
+     * Converts thrown exceptions (e.g. circular references) into a `Result<TypeError, string>`.
+     *
+     * @example
+     * ```ts
+     * Json.stringify({ a: 1 }); // Ok('{"a":1}')
+     * ```
+     */
+    const stringify: (value: unknown, replacer?: (this: any, key: string, value: any) => any, space?: string | number) => Result<TypeError, string>;
+}
+
 /**
  * Number utilities for common operations. All transformation functions are data-last
  * and curried so they compose naturally with `pipe` and `Arr.map`.
@@ -1062,6 +1419,102 @@ declare namespace Dict {
  * ```
  */
 declare namespace Num {
+    namespace is {
+        /**
+         * Returns `true` when the number is equal to zero.
+         *
+         * @example
+         * ```ts
+         * Num.is.zero(0); // true
+         * Num.is.zero(5); // false
+         * ```
+         */
+        const zero: (n: number) => boolean;
+        /**
+         * Returns `true` when the number is a whole integer.
+         *
+         * @example
+         * ```ts
+         * Num.is.integer(5);    // true
+         * Num.is.integer(3.14); // false
+         * ```
+         */
+        const integer: (n: number) => boolean;
+        /**
+         * Returns `true` when the number is a finite float (fractional number).
+         *
+         * @example
+         * ```ts
+         * Num.is.float(3.14); // true
+         * Num.is.float(5);    // false
+         * ```
+         */
+        const float: (n: number) => boolean;
+        /**
+         * Returns `true` when the number is finite (not `Infinity`, `-Infinity`, or `NaN`).
+         *
+         * @example
+         * ```ts
+         * Num.is.finite(42);       // true
+         * Num.is.finite(Infinity); // false
+         * ```
+         */
+        const finite: (n: number) => boolean;
+        /**
+         * Returns `true` when the value is `NaN`.
+         *
+         * @example
+         * ```ts
+         * Num.is.nan(NaN); // true
+         * Num.is.nan(42);  // false
+         * ```
+         */
+        const nan: (n: number) => boolean;
+        /**
+         * Returns `true` when the number is an even integer.
+         *
+         * @example
+         * ```ts
+         * Num.is.even(4);   // true
+         * Num.is.even(3);   // false
+         * Num.is.even(2.5); // false
+         * ```
+         */
+        const even: (n: number) => boolean;
+        /**
+         * Returns `true` when the number is an odd integer.
+         *
+         * @example
+         * ```ts
+         * Num.is.odd(3);   // true
+         * Num.is.odd(4);   // false
+         * Num.is.odd(2.5); // false
+         * ```
+         */
+        const odd: (n: number) => boolean;
+        /**
+         * Returns `true` when the number is strictly greater than zero.
+         *
+         * @example
+         * ```ts
+         * Num.is.positive(5);  // true
+         * Num.is.positive(0);  // false
+         * Num.is.positive(-5); // false
+         * ```
+         */
+        const positive: (n: number) => boolean;
+        /**
+         * Returns `true` when the number is strictly less than zero.
+         *
+         * @example
+         * ```ts
+         * Num.is.negative(-5); // true
+         * Num.is.negative(0);  // false
+         * Num.is.negative(5);  // false
+         * ```
+         */
+        const negative: (n: number) => boolean;
+    }
     /**
      * 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`,
@@ -1266,6 +1719,18 @@ declare namespace Num {
      * ```
      */
     const max: (ns: readonly number[]) => Maybe<number>;
+    /**
+     * Formats a number using `Intl.NumberFormat`. Returns `None` when `n` is `NaN` or non-finite.
+     * Data-last curried signature.
+     *
+     * @example
+     * ```ts
+     * const formatCurrency = Num.format({ style: "currency", currency: "USD" }, "en-US");
+     * pipe(1234.5, formatCurrency); // Some("$1,234.50")
+     * pipe(NaN, formatCurrency);    // None
+     * ```
+     */
+    const format: (options?: Intl.NumberFormatOptions, locales?: string | string[]) => (n: number) => Maybe<string>;
 }
 
 /**
@@ -1370,10 +1835,22 @@ declare namespace Rec {
     namespace is {
         /**
          * Returns true if the record has no keys.
+         *
+         * @example
+         * ```ts
+         * Rec.is.empty({});       // true
+         * Rec.is.empty({ a: 1 }); // false
+         * ```
          */
         const empty: <A>(data: Readonly<Record<string, A>>) => boolean;
         /**
          * Type guard to check if a record is non-empty.
+         *
+         * @example
+         * ```ts
+         * Rec.is.nonEmpty({ a: 1 }); // true
+         * Rec.is.nonEmpty({});       // false
+         * ```
          */
         const nonEmpty: <A, K extends string>(data: Readonly<Record<K, A>>) => data is NonEmptyRecord<A, K>;
     }
@@ -1386,6 +1863,17 @@ declare namespace Rec {
      * ```
      */
     const map: <A, B>(f: (a: A) => B) => <K extends string>(data: Readonly<Record<K, A>>) => Readonly<Record<K, B>>;
+    /**
+     * Maps each value in a record with a function returning a `Maybe`, keeping only `Some` values.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   { a: 1, b: 2, c: 3 },
+     *   Rec.filterMap((n) => (n % 2 === 0 ? Maybe.make.some(n * 10) : Maybe.make.none()))
+     * ); // { b: 20 }
+     * ```
+     */
     const filterMap: <A, B>(f: (a: A) => Maybe<B>) => (data: Readonly<Record<string, A>>) => Readonly<Record<string, B>>;
     /**
      * Transforms each value in a record, also receiving the key.
@@ -1428,14 +1916,29 @@ declare namespace Rec {
     const lookup: <K extends string>(key: K) => <V>(data: Record<string, V>) => Maybe<V>;
     /**
      * Returns all keys of a record.
+     *
+     * @example
+     * ```ts
+     * Rec.keys({ a: 1, b: 2 }); // ["a", "b"]
+     * ```
      */
     const keys: <T extends Record<string, unknown>>(data: T) => readonly (keyof T & string)[];
     /**
      * Returns all values of a record.
+     *
+     * @example
+     * ```ts
+     * Rec.values({ a: 1, b: 2 }); // [1, 2]
+     * ```
      */
     const values: <T extends Record<string, unknown>>(data: T) => readonly T[keyof T & string][];
     /**
      * Returns all key-value pairs of a record.
+     *
+     * @example
+     * ```ts
+     * Rec.entries({ a: 1, b: 2 }); // [["a", 1], ["b", 2]]
+     * ```
      */
     const entries: <T extends Record<string, unknown>>(data: T) => readonly (readonly [keyof T, T[keyof T]])[];
     namespace from {
@@ -1492,8 +1995,28 @@ declare namespace Rec {
      * ```
      */
     const merge: <A>(other: Readonly<Record<string, A>>) => (data: Readonly<Record<string, A>>) => Readonly<Record<string, A>>;
+    /**
+     * Merges two records using a custom combination function on key collisions.
+     * Supports both uncurried `Rec.mergeWith(combine)(first, second)` and curried `pipe(first, Rec.mergeWith(combine)(second))`.
+     *
+     * @example
+     * ```ts
+     * const combineStats = Rec.mergeWith((a: number, b: number) => a + b);
+     * combineStats({ a: 1, b: 2 }, { b: 3, c: 4 }); // { a: 1, b: 5, c: 4 }
+     * pipe({ a: 1, b: 2 }, combineStats({ b: 3, c: 4 })); // { a: 1, b: 5, c: 4 }
+     * ```
+     */
+    function mergeWith<A>(combine: (a: A, b: A) => A): {
+        (second: Readonly<Record<string, A>>): (first: Readonly<Record<string, A>>) => Readonly<Record<string, A>>;
+        (first: Readonly<Record<string, A>>, second: Readonly<Record<string, A>>): Readonly<Record<string, A>>;
+    };
     /**
      * Returns the number of keys in a record.
+     *
+     * @example
+     * ```ts
+     * Rec.size({ a: 1, b: 2 }); // 2
+     * ```
      */
     const size: <A>(data: Readonly<Record<string, A>>) => number;
     /**
@@ -1518,6 +2041,30 @@ declare namespace Rec {
      * ```
      */
     const compact: <A>(data: Readonly<Record<string, Maybe<A>>>) => Readonly<Record<string, A>>;
+    /**
+     * Transforms key and value pairs simultaneously.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   { a: 1, b: 2 },
+     *   Rec.mapEntries((k, v) => [k.toUpperCase(), v * 10])
+     * ); // { A: 10, B: 20 }
+     * ```
+     */
+    const mapEntries: <A, K2 extends string, B>(f: (key: string, value: A) => readonly [K2, B]) => (data: Readonly<Record<string, A>>) => Readonly<Record<K2, B>>;
+    /**
+     * Immutably updates a value at a deep nested path inside a record.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   { user: { profile: { age: 30 } } },
+     *   Rec.updateIn(["user", "profile", "age"], (n: number) => n + 1)
+     * ); // { user: { profile: { age: 31 } } }
+     * ```
+     */
+    const updateIn: <T>(path: readonly [string, ...string[]], f: (val: T) => T) => (data: Readonly<Record<string, unknown>>) => Readonly<Record<string, unknown>>;
     namespace traverse {
         const Maybe: <A, B>(f: (a: A) => Maybe<B>) => (data: Readonly<Record<string, A>>) => Maybe<Readonly<Record<string, B>>>;
         const Result: <E, A, B>(f: (a: A) => Result<E, B>) => (data: Readonly<Record<string, A>>) => Result<E, Readonly<Record<string, B>>>;
@@ -1781,6 +2328,31 @@ declare namespace Str {
      * ```
      */
     const parseJson: (s: string) => Result<SyntaxError, unknown>;
+    /**
+     * Converts the first character of a string to lower case.
+     *
+     * @example
+     * ```ts
+     * Str.uncapitalize("Hello"); // "hello"
+     * Str.uncapitalize("");      // ""
+     * ```
+     */
+    const uncapitalize: (s: string) => string;
+    /**
+     * Truncates a string to a maximum length, appending an optional suffix (default `"..."`).
+     * Data-last curried signature.
+     *
+     * @example
+     * ```ts
+     * pipe("Hello, world!", Str.truncate({ length: 8 })); // "Hello..."
+     * pipe("Hello", Str.truncate({ length: 10 }));        // "Hello"
+     * pipe("Hello, world!", Str.truncate({ length: 8, suffix: "…" })); // "Hello, w…"
+     * ```
+     */
+    const truncate: (options: {
+        length: number;
+        suffix?: string;
+    }) => (s: string) => string;
     const NonEmpty: typeof StrNonEmpty;
 }
 
@@ -1876,6 +2448,12 @@ declare namespace Uniq {
         const empty: <A>(s: ReadonlySet<A>) => boolean;
         /**
          * Type guard to check if a unique collection is non-empty.
+         *
+         * @example
+         * ```ts
+         * Uniq.is.nonEmpty(Uniq.from.Array([1, 2])); // true
+         * Uniq.is.nonEmpty(Uniq.empty());            // false
+         * ```
          */
         const nonEmpty: <A>(s: ReadonlySet<A>) => s is NonEmpty<A>;
     }
@@ -2016,7 +2594,7 @@ declare namespace Uniq {
      *
      * @example
      * ```ts
-     * Uniq.reduce(0, (acc, n) => acc + n)(Uniq.from.Array([1, 2, 3])); // 6
+     * Uniq.reduce(0, (acc, n: number) => acc + n)(Uniq.from.Array([1, 2, 3])); // 6
      * ```
      */
     const reduce: <A, B>(init: B, f: (acc: B, a: A) => B) => (s: ReadonlySet<A>) => B;
@@ -2034,4 +2612,4 @@ declare namespace Uniq {
     const NonEmpty: typeof UniqNonEmpty;
 }
 
-export { Arr, Dict, type NonEmptyMap, type NonEmptyRecord, type NonEmptySet, type NonEmptyString, Num, Rec, Str, Uniq };
+export { Arr, BigNum, Dict, Json, type NonEmptyMap, type NonEmptyRecord, type NonEmptySet, type NonEmptyString, Num, Rec, Str, Uniq };