@nlozgachev/pipelined 0.42.0 → 0.43.0

package/dist/utils.d.mts

@@ -1,7 +1,160 @@
-import { M as Maybe, R as Result, E as Equality, b as Ordering, T as Task } from './Task-BprUabHP.mjs';
-import { NonEmptyList } from './types.mjs';
-import './Duration-BTeT9D-q.mjs';
+import { N as NonEmptyArr } from './InternalTypes-DsCqxWZm.mjs';
+import { M as Maybe, R as Result, E as Equality, b as Ordering, T as Task } from './Validation-Do6uWLLZ.mjs';
+import './types.mjs';
 
+declare namespace ArrMaybe {
+    /**
+     * Maps each element to a Maybe and collects the results.
+     * Returns None if any mapping returns None.
+     *
+     * @example
+     * ```ts
+     * const parseNum = (s: string): Maybe<number> => {
+     *   const n = Number(s);
+     *   return isNaN(n) ? Maybe.none() : Maybe.some(n);
+     * };
+     *
+     * pipe(["1", "2", "3"], Arr.Maybe.traverse(parseNum)); // Some([1, 2, 3])
+     * pipe(["1", "x", "3"], Arr.Maybe.traverse(parseNum)); // None
+     * ```
+     */
+    const traverse: <A, B>(f: (a: A) => Maybe<B>) => (data: readonly A[]) => Maybe<readonly B[]>;
+    /**
+     * Collects an array of Maybe instances into a Maybe of array.
+     * Returns None if any element is None.
+     *
+     * @example
+     * ```ts
+     * Arr.Maybe.sequence([Maybe.some(1), Maybe.some(2)]); // Some([1, 2])
+     * Arr.Maybe.sequence([Maybe.some(1), Maybe.none()]); // None
+     * ```
+     */
+    const sequence: <A>(data: readonly Maybe<A>[]) => Maybe<readonly A[]>;
+}
+declare namespace ArrResult {
+    /**
+     * Maps each element to a Result and collects the results.
+     * Returns the first Err if any mapping fails.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   [1, 2, 3],
+     *   Arr.Result.traverse(n => n > 0 ? Result.ok(n) : Result.err("negative"))
+     * ); // Ok([1, 2, 3])
+     * ```
+     */
+    const traverse: <E, A, B>(f: (a: A) => Result<E, B>) => (data: readonly A[]) => Result<E, readonly B[]>;
+    /**
+     * Collects an array of Results into a Result of array.
+     * Returns the first Err if any element is Err.
+     */
+    const sequence: <E, A>(data: readonly Result<E, A>[]) => Result<E, readonly A[]>;
+}
+declare namespace ArrTaskResult {
+    /**
+     * Maps each element to a TaskResult and runs them sequentially.
+     * Returns the first Err encountered, or Ok of all results if all succeed.
+     *
+     * @example
+     * ```ts
+     * const validate = (n: number): Task.Result<string, number> =>
+     *   n > 0 ? Task.Result.ok(n) : Task.Result.err("non-positive");
+     *
+     * pipe(
+     *   [1, 2, 3],
+     *   Arr.Task.Result.traverse(validate)
+     * )(); // Deferred<Ok([1, 2, 3])>
+     *
+     * pipe(
+     *   [1, -1, 3],
+     *   Arr.Task.Result.traverse(validate)
+     * )(); // Deferred<Err("non-positive")>
+     * ```
+     */
+    const traverse: <E, A, B>(f: (a: A) => Task<Result<E, B>>) => (data: readonly A[]) => Task<Result<E, readonly B[]>>;
+    /**
+     * Collects an array of TaskResults into a TaskResult of array.
+     * Returns the first Err if any element is Err, runs sequentially.
+     */
+    const sequence: <E, A>(data: readonly Task<Result<E, A>>[]) => Task<Result<E, readonly A[]>>;
+}
+declare namespace ArrTask {
+    /**
+     * Maps each element to a Task and runs all in parallel.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   [1, 2, 3],
+     *   Arr.Task.traverse(n => Task.resolve(n * 2))
+     * )(); // Promise<[2, 4, 6]>
+     * ```
+     */
+    const traverse: <A, B>(f: (a: A) => Task<B>) => (data: readonly A[]) => Task<readonly B[]>;
+    /**
+     * Collects an array of Tasks into a Task of array. Runs in parallel.
+     */
+    const sequence: <A>(data: readonly Task<A>[]) => Task<readonly A[]>;
+    const Result: typeof ArrTaskResult;
+}
+declare namespace ArrNonEmpty {
+    /**
+     * Creates a single-element list.
+     *
+     * @example
+     * ```ts
+     * Arr.NonEmpty.singleton(42); // [42]
+     * ```
+     */
+    const singleton: <A>(value: A) => NonEmptyArr<A>;
+    /**
+     * Returns Some if the array is non-empty, None otherwise.
+     *
+     * @example
+     * ```ts
+     * Arr.NonEmpty.fromArray([1, 2]); // Some([1, 2])
+     * Arr.NonEmpty.fromArray([]); // None
+     * ```
+     */
+    const fromArray: <A>(data: readonly A[]) => Maybe<NonEmptyArr<A>>;
+    /**
+     * Returns the first element of a NonEmptyArr.
+     *
+     * @example
+     * ```ts
+     * Arr.NonEmpty.head([1, 2, 3]); // 1
+     * ```
+     */
+    const head: <A>(data: NonEmptyArr<A>) => A;
+    /**
+     * Returns the last element of a NonEmptyArr.
+     *
+     * @example
+     * ```ts
+     * Arr.NonEmpty.last([1, 2, 3]); // 3
+     * ```
+     */
+    const last: <A>(data: NonEmptyArr<A>) => A;
+    /**
+     * Returns all elements except the first.
+     *
+     * @example
+     * ```ts
+     * Arr.NonEmpty.tail([1, 2, 3]); // [2, 3]
+     * ```
+     */
+    const tail: <A>(data: NonEmptyArr<A>) => readonly A[];
+    /**
+     * Reduces a NonEmptyArr from the left without an initial value.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3, 4] as NonEmptyArr<number>, Arr.NonEmpty.reduce((a, b) => a + b)); // 10
+     * ```
+     */
+    const reduce: <A>(f: (acc: A, a: A) => A) => (data: NonEmptyArr<A>) => A;
+}
 /**
  * Functional array utilities that compose well with pipe.
  * All functions are data-last and curried where applicable.
@@ -18,6 +171,16 @@ import './Duration-BTeT9D-q.mjs';
  * ```
  */
 declare namespace Arr {
+    /**
+     * A type alias representing an array that is guaranteed to contain at least one element.
+     * Under the hood, this is a read-only tuple structure: `readonly [A, ...A[]]`.
+     *
+     * @example
+     * ```ts
+     * const list: Arr.NonEmpty<number> = [1, 2, 3];
+     * ```
+     */
+    type NonEmpty<A> = NonEmptyArr<A>;
     /**
      * Returns the first element of an array, or None if the array is empty.
      *
@@ -93,7 +256,10 @@ declare namespace Arr {
      * pipe([1, 2, 3], Arr.map(n => n * 2)); // [2, 4, 6]
      * ```
      */
-    const map: <A, B>(f: (a: A) => B) => (data: readonly A[]) => readonly B[];
+    const map: <A, B>(f: (a: A) => B) => {
+        (data: NonEmpty<A>): NonEmpty<B>;
+        (data: readonly A[]): readonly B[];
+    };
     /**
      * Transforms each element using both its value and its zero-based index.
      *
@@ -105,7 +271,10 @@ declare namespace Arr {
      * ); // [{ position: 1, value: "a" }, { position: 2, value: "b" }, { position: 3, value: "c" }]
      * ```
      */
-    const mapWithIndex: <A, B>(f: (i: number, a: A) => B) => (data: readonly A[]) => readonly B[];
+    const mapWithIndex: <A, B>(f: (i: number, a: A) => B) => {
+        (data: NonEmpty<A>): NonEmpty<B>;
+        (data: readonly A[]): readonly B[];
+    };
     /**
      * Filters elements that satisfy the predicate.
      *
@@ -184,7 +353,7 @@ declare namespace Arr {
      * ); // { a: ["apple", "avocado"], b: ["banana"] }
      * ```
      */
-    const groupBy: <A>(f: (a: A) => string) => (data: readonly A[]) => Record<string, NonEmptyList<A>>;
+    const groupBy: <A>(f: (a: A) => string) => (data: readonly A[]) => Record<string, NonEmptyArr<A>>;
     /**
      * Removes duplicate elements using strict equality.
      *
@@ -272,7 +441,23 @@ declare namespace Arr {
      * pipe([1, 2, 3], Arr.intersperse(0)); // [1, 0, 2, 0, 3]
      * ```
      */
-    const intersperse: <A>(sep: A) => (data: readonly A[]) => readonly A[];
+    const intersperse: <A>(sep: A) => {
+        (data: NonEmpty<A>): NonEmpty<A>;
+        (data: readonly A[]): readonly A[];
+    };
+    /**
+     * Concatenates a standard array or NonEmptyArr with another array.
+     * If the first array is a NonEmptyArr, the result is guaranteed to be a NonEmptyArr.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2], Arr.concat([3, 4])); // [1, 2, 3, 4]
+     * ```
+     */
+    const concat: <A>(other: readonly A[]) => {
+        (data: NonEmpty<A>): NonEmpty<A>;
+        (data: readonly A[]): readonly A[];
+    };
     /**
      * Splits an array into chunks of the given size.
      *
@@ -309,97 +494,31 @@ declare namespace Arr {
      * ```
      */
     const reduce: <A, B>(initial: B, f: (acc: B, a: A) => B) => (data: readonly A[]) => B;
+    const Maybe: typeof ArrMaybe;
+    const Result: typeof ArrResult;
+    const Task: typeof ArrTask;
     /**
-     * Maps each element to a Maybe and collects the results.
-     * Returns None if any mapping returns None.
-     *
-     * @example
-     * ```ts
-     * const parseNum = (s: string): Maybe<number> => {
-     *   const n = Number(s);
-     *   return isNaN(n) ? Maybe.none() : Maybe.some(n);
-     * };
-     *
-     * pipe(["1", "2", "3"], Arr.traverse(parseNum)); // Some([1, 2, 3])
-     * pipe(["1", "x", "3"], Arr.traverse(parseNum)); // None
-     * ```
-     */
-    const traverse: <A, B>(f: (a: A) => Maybe<B>) => (data: readonly A[]) => Maybe<readonly B[]>;
-    /**
-     * Maps each element to a Result and collects the results.
-     * Returns the first Err if any mapping fails.
-     *
-     * @example
-     * ```ts
-     * pipe(
-     *   [1, 2, 3],
-     *   Arr.traverseResult(n => n > 0 ? Result.ok(n) : Result.err("negative"))
-     * ); // Ok([1, 2, 3])
-     * ```
+     * Returns true if the array is non-empty (type guard).
      */
-    const traverseResult: <E, A, B>(f: (a: A) => Result<E, B>) => (data: readonly A[]) => Result<E, readonly B[]>;
+    const isNonEmpty: <A>(data: readonly A[]) => data is NonEmpty<A>;
     /**
-     * Maps each element to a Task and runs all in parallel.
+     * Prepends a value to the beginning of an array, returning a NonEmptyArr.
      *
      * @example
      * ```ts
-     * pipe(
-     *   [1, 2, 3],
-     *   Arr.traverseTask(n => Task.resolve(n * 2))
-     * )(); // Promise<[2, 4, 6]>
+     * pipe([1, 2], Arr.prepend(0)); // [0, 1, 2]
      * ```
      */
-    const traverseTask: <A, B>(f: (a: A) => Task<B>) => (data: readonly A[]) => Task<readonly B[]>;
+    const prepend: <A>(value: A) => (data: readonly A[]) => NonEmpty<A>;
     /**
-     * Collects an array of Maybe instances into a Maybe of array.
-     * Returns None if any element is None.
+     * Appends a value to the end of an array, returning a NonEmptyArr.
      *
      * @example
      * ```ts
-     * Arr.sequence([Maybe.some(1), Maybe.some(2)]); // Some([1, 2])
-     * Arr.sequence([Maybe.some(1), Maybe.none()]); // None
+     * pipe([1, 2], Arr.append(3)); // [1, 2, 3]
      * ```
      */
-    const sequence: <A>(data: readonly Maybe<A>[]) => Maybe<readonly A[]>;
-    /**
-     * Collects an array of Results into a Result of array.
-     * Returns the first Err if any element is Err.
-     */
-    const sequenceResult: <E, A>(data: readonly Result<E, A>[]) => Result<E, readonly A[]>;
-    /**
-     * Collects an array of Tasks into a Task of array. Runs in parallel.
-     */
-    const sequenceTask: <A>(data: readonly Task<A>[]) => Task<readonly A[]>;
-    /**
-     * Maps each element to a TaskResult and runs them sequentially.
-     * Returns the first Err encountered, or Ok of all results if all succeed.
-     *
-     * @example
-     * ```ts
-     * const validate = (n: number): TaskResult<string, number> =>
-     *   n > 0 ? TaskResult.ok(n) : TaskResult.err("non-positive");
-     *
-     * pipe(
-     *   [1, 2, 3],
-     *   Arr.traverseTaskResult(validate)
-     * )(); // Deferred<Ok([1, 2, 3])>
-     *
-     * pipe(
-     *   [1, -1, 3],
-     *   Arr.traverseTaskResult(validate)
-     * )(); // Deferred<Err("non-positive")>
-     * ```
-     */
-    const traverseTaskResult: <E, A, B>(f: (a: A) => Task<Result<E, B>>) => (data: readonly A[]) => Task<Result<E, readonly B[]>>;
-    /**
-     * Collects an array of TaskResults into a TaskResult of array.
-     * Returns the first Err if any element is Err, runs sequentially.
-     */
-    const sequenceTaskResult: <E, A>(data: readonly Task<Result<E, A>>[]) => Task<Result<E, readonly A[]>>;
-    /**
-     * Returns true if the array is non-empty (type guard).
-     */
-    const isNonEmpty: <A>(data: readonly A[]) => data is NonEmptyList<A>;
+    const append: <A>(value: A) => (data: readonly A[]) => NonEmpty<A>;
     /**
      * Returns the length of an array.
      */
@@ -430,7 +549,10 @@ declare namespace Arr {
      * Arr.reverse([1, 2, 3]); // [3, 2, 1]
      * ```
      */
-    const reverse: <A>(data: readonly A[]) => readonly A[];
+    const reverse: {
+        <A>(data: NonEmpty<A>): NonEmpty<A>;
+        <A>(data: readonly A[]): readonly A[];
+    };
     /**
      * Returns a new array with `item` inserted before the element at `index`.
      * Negative indices are clamped to 0; indices beyond the array length append to the end.
@@ -513,6 +635,7 @@ declare namespace Arr {
      * ```
      */
     const splitAt: (index: number) => <A>(data: readonly A[]) => readonly [readonly A[], readonly A[]];
+    const NonEmpty: typeof ArrNonEmpty;
 }
 
 /**
@@ -1062,6 +1185,122 @@ declare namespace Num {
     const max: (ns: readonly number[]) => Maybe<number>;
 }
 
+declare const _nonEmptyRecord: unique symbol;
+/**
+ * A branded type representing a record with at least one key-value pair.
+ */
+type NonEmptyRecord<A> = Readonly<Record<string, A>> & {
+    readonly [_nonEmptyRecord]: true;
+};
+declare namespace RecMaybe {
+    /**
+     * Map a function that returns a `Maybe` over each value of a record,
+     * and combine the results into a single `Maybe` containing the updated record.
+     * If any value results in `None`, the entire operation returns `None` (short-circuits).
+     *
+     * @example
+     * ```ts
+     * const parseNum = (s: string) => s === "NaN" ? Maybe.none() : Maybe.some(Number(s));
+     * pipe({ a: "1", b: "2" }, Rec.Maybe.traverse(parseNum)); // Some({ a: 1, b: 2 })
+     * pipe({ a: "1", b: "NaN" }, Rec.Maybe.traverse(parseNum)); // None
+     * ```
+     */
+    const traverse: <A, B>(f: (a: A) => Maybe<B>) => (data: Readonly<Record<string, A>>) => Maybe<Readonly<Record<string, B>>>;
+    /**
+     * Sequence a record of `Maybe` values into a `Maybe` of a record.
+     * If any key contains `None`, the entire operation returns `None`.
+     *
+     * @example
+     * ```ts
+     * Rec.Maybe.sequence({ a: Maybe.some(1), b: Maybe.some(2) }); // Some({ a: 1, b: 2 })
+     * Rec.Maybe.sequence({ a: Maybe.some(1), b: Maybe.none() }); // None
+     * ```
+     */
+    const sequence: <A>(data: Readonly<Record<string, Maybe<A>>>) => Maybe<Readonly<Record<string, A>>>;
+}
+declare namespace RecResult {
+    /**
+     * Map a function that returns a `Result` over each value of a record,
+     * and combine the results into a single `Result` containing the updated record.
+     * If any value results in an `Err`, the entire operation returns that `Err` (short-circuits).
+     *
+     * @example
+     * ```ts
+     * const checkPositive = (n: number) => n < 0 ? Result.err("negative") : Result.ok(n);
+     * pipe({ a: 1, b: 2 }, Rec.Result.traverse(checkPositive)); // Ok({ a: 1, b: 2 })
+     * pipe({ a: 1, b: -2 }, Rec.Result.traverse(checkPositive)); // Err("negative")
+     * ```
+     */
+    const traverse: <E, A, B>(f: (a: A) => Result<E, B>) => (data: Readonly<Record<string, A>>) => Result<E, Readonly<Record<string, B>>>;
+    /**
+     * Sequence a record of `Result` values into a `Result` of a record.
+     * If any key contains an `Err`, the entire operation returns that `Err`.
+     *
+     * @example
+     * ```ts
+     * Rec.Result.sequence({ a: Result.ok(1), b: Result.ok(2) }); // Ok({ a: 1, b: 2 })
+     * Rec.Result.sequence({ a: Result.ok(1), b: Result.err("oops") }); // Err("oops")
+     * ```
+     */
+    const sequence: <E, A>(data: Readonly<Record<string, Result<E, A>>>) => Result<E, Readonly<Record<string, A>>>;
+}
+declare namespace RecNonEmpty {
+    /**
+     * Creates a NonEmpty record from a single key-value pair.
+     *
+     * @example
+     * ```ts
+     * Rec.NonEmpty.singleton("a", 1); // { a: 1 }
+     * ```
+     */
+    const singleton: <A>(key: string, value: A) => NonEmptyRecord<A>;
+    /**
+     * Creates a NonEmpty record from a standard record if it is not empty.
+     *
+     * @example
+     * ```ts
+     * Rec.NonEmpty.fromRecord({ a: 1 }); // Some({ a: 1 })
+     * Rec.NonEmpty.fromRecord({});      // None
+     * ```
+     */
+    const fromRecord: <A>(data: Readonly<Record<string, A>>) => Maybe<NonEmptyRecord<A>>;
+    /**
+     * Returns a non-empty array of keys for a NonEmpty record.
+     *
+     * @example
+     * ```ts
+     * Rec.NonEmpty.keys(Rec.NonEmpty.singleton("a", 1)); // ["a"]
+     * ```
+     */
+    const keys: <A>(data: NonEmptyRecord<A>) => NonEmptyArr<string>;
+    /**
+     * Returns a non-empty array of values for a NonEmpty record.
+     *
+     * @example
+     * ```ts
+     * Rec.NonEmpty.values(Rec.NonEmpty.singleton("a", 1)); // [1]
+     * ```
+     */
+    const values: <A>(data: NonEmptyRecord<A>) => NonEmptyArr<A>;
+    /**
+     * Returns a non-empty array of entry tuples for a NonEmpty record.
+     *
+     * @example
+     * ```ts
+     * Rec.NonEmpty.entries(Rec.NonEmpty.singleton("a", 1)); // [["a", 1]]
+     * ```
+     */
+    const entries: <A>(data: NonEmptyRecord<A>) => NonEmptyArr<readonly [string, A]>;
+    /**
+     * Reduces a NonEmpty record's values from the left without an initial value.
+     *
+     * @example
+     * ```ts
+     * pipe(Rec.NonEmpty.singleton("a", 1), Rec.NonEmpty.reduce((a, b) => a + b)); // 1
+     * ```
+     */
+    const reduce: <A>(f: (acc: A, a: A) => A) => (data: NonEmptyRecord<A>) => A;
+}
 /**
  * Functional record/object utilities that compose well with pipe.
  * All functions are data-last and curried where applicable.
@@ -1076,6 +1315,14 @@ declare namespace Num {
  * ```
  */
 declare namespace Rec {
+    /**
+     * A branded type representing a record with at least one key-value pair.
+     */
+    type NonEmpty<A> = NonEmptyRecord<A>;
+    /**
+     * Type guard to check if a record is non-empty.
+     */
+    const isNonEmpty: <A>(data: Readonly<Record<string, A>>) => data is NonEmptyRecord<A>;
     /**
      * Transforms each value in a record.
      *
@@ -1084,7 +1331,10 @@ declare namespace Rec {
      * pipe({ a: 1, b: 2 }, Rec.map(n => n * 2)); // { a: 2, b: 4 }
      * ```
      */
-    const map: <A, B>(f: (a: A) => B) => (data: Readonly<Record<string, A>>) => Readonly<Record<string, B>>;
+    const map: <A, B>(f: (a: A) => B) => {
+        (data: NonEmpty<A>): NonEmpty<B>;
+        (data: Readonly<Record<string, A>>): Readonly<Record<string, B>>;
+    };
     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.
@@ -1095,7 +1345,10 @@ declare namespace Rec {
      * // { a: "a:1", b: "b:2" }
      * ```
      */
-    const mapWithKey: <A, B>(f: (key: string, a: A) => B) => (data: Readonly<Record<string, A>>) => Readonly<Record<string, B>>;
+    const mapWithKey: <A, B>(f: (key: string, a: A) => B) => {
+        (data: NonEmpty<A>): NonEmpty<B>;
+        (data: Readonly<Record<string, A>>): Readonly<Record<string, B>>;
+    };
     /**
      * Filters values in a record by a predicate.
      *
@@ -1110,7 +1363,7 @@ declare namespace Rec {
      *
      * @example
      * ```ts
-     * pipe({ a: 1, b: 2 }, Rec.filterWithKey((k, v) => k !== "a" && v > 0));
+     * pipe({ a: 1, b: 2, c: 3 }, Rec.filterWithKey((k, v) => k !== "a" && v > 0));
      * // { b: 2 }
      * ```
      */
@@ -1219,6 +1472,9 @@ declare namespace Rec {
      * ```
      */
     const compact: <A>(data: Readonly<Record<string, Maybe<A>>>) => Readonly<Record<string, A>>;
+    const Maybe: typeof RecMaybe;
+    const Result: typeof RecResult;
+    const NonEmpty: typeof RecNonEmpty;
 }
 
 /**
@@ -1626,4 +1882,4 @@ declare namespace Uniq {
     const toArray: <A>(s: ReadonlySet<A>) => readonly A[];
 }
 
-export { Arr, Dict, Num, Rec, Str, Uniq };
+export { Arr, Dict, type NonEmptyRecord, Num, Rec, Str, Uniq };