@nlozgachev/pipelined 0.31.0 → 0.33.0

package/dist/index.mjs

@@ -28,10 +28,14 @@ import {
   uncurry4
 } from "./chunk-NRF2FVPZ.mjs";
 import {
+  Combinable,
+  Equality,
+  Lazy,
   Lens,
   Logged,
   Op,
   Optional,
+  Ordering,
   Predicate,
   Reader,
   Refinement,
@@ -44,7 +48,7 @@ import {
   These,
   Tuple,
   Validation
-} from "./chunk-VIC54JR4.mjs";
+} from "./chunk-FZX4MTRI.mjs";
 import {
   Arr,
   Dict,
@@ -52,30 +56,37 @@ import {
   Rec,
   Str,
   Uniq
-} from "./chunk-FWYOEWJ2.mjs";
+} from "./chunk-W53ZYTLX.mjs";
 import {
   Deferred,
   Maybe,
   Result,
   Task
-} from "./chunk-SDGDJ7CU.mjs";
-import {
-  Brand
-} from "./chunk-BYWKZLHM.mjs";
+} from "./chunk-GSTKY7MF.mjs";
+import "./chunk-IPP4XFYH.mjs";
 import {
   isNonEmptyList
 } from "./chunk-DBIC62UV.mjs";
+import {
+  Brand,
+  Duration
+} from "./chunk-VWVPHDZO.mjs";
 export {
   Arr,
   Brand,
+  Combinable,
   Deferred,
   Dict,
+  Duration,
+  Equality,
+  Lazy,
   Lens,
   Logged,
   Maybe,
   Num,
   Op,
   Optional,
+  Ordering,
   Predicate,
   Reader,
   Rec,

package/dist/types.d.mts

@@ -1,4 +1,31 @@
-export { N as NonEmptyList, i as isNonEmptyList } from './NonEmptyList-BlGFjor5.mjs';
+/**
+ * A list that is guaranteed to have at least one element.
+ * Useful for ensuring functions receive non-empty input and for
+ * accumulating errors in Validation.
+ *
+ * @example
+ * ```ts
+ * const errors: NonEmptyList<string> = ["First error", "Second error"];
+ *
+ * // TypeScript ensures at least one element:
+ * const invalid: NonEmptyList<string> = []; // Error!
+ * ```
+ */
+type NonEmptyList<A> = readonly [A, ...A[]];
+/**
+ * Type guard that checks if an array is non-empty.
+ *
+ * @example
+ * ```ts
+ * const items: string[] = getItems();
+ *
+ * if (isNonEmptyList(items)) {
+ *   // TypeScript knows items has at least one element
+ *   const first = items[0]; // string, not string | undefined
+ * }
+ * ```
+ */
+declare const isNonEmptyList: <A>(list: readonly A[]) => list is NonEmptyList<A>;
 
 declare const _brand: unique symbol;
 /**
@@ -51,4 +78,79 @@ declare namespace Brand {
     const unwrap: <K extends string, T>(branded: Brand<K, T>) => T;
 }
 
-export { Brand };
+/**
+ * A branded nominal type representing a duration of time in milliseconds.
+ * Use Duration to ensure safe time-based operators and clear unit conversions.
+ *
+ * @example
+ * ```ts
+ * const halfSecond = Duration.milliseconds(500);
+ * const twoSeconds = Duration.seconds(2);
+ * const total = pipe(halfSecond, Duration.add(twoSeconds));
+ *
+ * Duration.toSeconds(total); // 2.5
+ * ```
+ */
+type Duration = Brand<"Duration", number>;
+declare namespace Duration {
+    /**
+     * Creates a Duration from milliseconds.
+     */
+    const milliseconds: (ms: number) => Duration;
+    /**
+     * Creates a Duration from seconds.
+     */
+    const seconds: (s: number) => Duration;
+    /**
+     * Creates a Duration from minutes.
+     */
+    const minutes: (m: number) => Duration;
+    /**
+     * Creates a Duration from hours.
+     */
+    const hours: (h: number) => Duration;
+    /**
+     * Creates a Duration from days.
+     */
+    const days: (d: number) => Duration;
+    /**
+     * Converts a Duration back to raw milliseconds.
+     */
+    const toMilliseconds: (d: Duration) => number;
+    /**
+     * Converts a Duration to seconds.
+     */
+    const toSeconds: (d: Duration) => number;
+    /**
+     * Converts a Duration to minutes.
+     */
+    const toMinutes: (d: Duration) => number;
+    /**
+     * Converts a Duration to hours.
+     */
+    const toHours: (d: Duration) => number;
+    /**
+     * Converts a Duration to days.
+     */
+    const toDays: (d: Duration) => number;
+    /**
+     * Adds two Durations together.
+     *
+     * @example
+     * ```ts
+     * pipe(Duration.seconds(1), Duration.add(Duration.milliseconds(500))); // 1500ms
+     * ```
+     */
+    const add: (other: Duration) => (self: Duration) => Duration;
+    /**
+     * Subtracts the other Duration from this one.
+     *
+     * @example
+     * ```ts
+     * pipe(Duration.seconds(1), Duration.subtract(Duration.milliseconds(500))); // 500ms
+     * ```
+     */
+    const subtract: (other: Duration) => (self: Duration) => Duration;
+}
+
+export { Brand, Duration, type NonEmptyList, isNonEmptyList };

package/dist/types.d.ts

@@ -1,4 +1,31 @@
-export { N as NonEmptyList, i as isNonEmptyList } from './NonEmptyList-BlGFjor5.js';
+/**
+ * A list that is guaranteed to have at least one element.
+ * Useful for ensuring functions receive non-empty input and for
+ * accumulating errors in Validation.
+ *
+ * @example
+ * ```ts
+ * const errors: NonEmptyList<string> = ["First error", "Second error"];
+ *
+ * // TypeScript ensures at least one element:
+ * const invalid: NonEmptyList<string> = []; // Error!
+ * ```
+ */
+type NonEmptyList<A> = readonly [A, ...A[]];
+/**
+ * Type guard that checks if an array is non-empty.
+ *
+ * @example
+ * ```ts
+ * const items: string[] = getItems();
+ *
+ * if (isNonEmptyList(items)) {
+ *   // TypeScript knows items has at least one element
+ *   const first = items[0]; // string, not string | undefined
+ * }
+ * ```
+ */
+declare const isNonEmptyList: <A>(list: readonly A[]) => list is NonEmptyList<A>;
 
 declare const _brand: unique symbol;
 /**
@@ -51,4 +78,79 @@ declare namespace Brand {
     const unwrap: <K extends string, T>(branded: Brand<K, T>) => T;
 }
 
-export { Brand };
+/**
+ * A branded nominal type representing a duration of time in milliseconds.
+ * Use Duration to ensure safe time-based operators and clear unit conversions.
+ *
+ * @example
+ * ```ts
+ * const halfSecond = Duration.milliseconds(500);
+ * const twoSeconds = Duration.seconds(2);
+ * const total = pipe(halfSecond, Duration.add(twoSeconds));
+ *
+ * Duration.toSeconds(total); // 2.5
+ * ```
+ */
+type Duration = Brand<"Duration", number>;
+declare namespace Duration {
+    /**
+     * Creates a Duration from milliseconds.
+     */
+    const milliseconds: (ms: number) => Duration;
+    /**
+     * Creates a Duration from seconds.
+     */
+    const seconds: (s: number) => Duration;
+    /**
+     * Creates a Duration from minutes.
+     */
+    const minutes: (m: number) => Duration;
+    /**
+     * Creates a Duration from hours.
+     */
+    const hours: (h: number) => Duration;
+    /**
+     * Creates a Duration from days.
+     */
+    const days: (d: number) => Duration;
+    /**
+     * Converts a Duration back to raw milliseconds.
+     */
+    const toMilliseconds: (d: Duration) => number;
+    /**
+     * Converts a Duration to seconds.
+     */
+    const toSeconds: (d: Duration) => number;
+    /**
+     * Converts a Duration to minutes.
+     */
+    const toMinutes: (d: Duration) => number;
+    /**
+     * Converts a Duration to hours.
+     */
+    const toHours: (d: Duration) => number;
+    /**
+     * Converts a Duration to days.
+     */
+    const toDays: (d: Duration) => number;
+    /**
+     * Adds two Durations together.
+     *
+     * @example
+     * ```ts
+     * pipe(Duration.seconds(1), Duration.add(Duration.milliseconds(500))); // 1500ms
+     * ```
+     */
+    const add: (other: Duration) => (self: Duration) => Duration;
+    /**
+     * Subtracts the other Duration from this one.
+     *
+     * @example
+     * ```ts
+     * pipe(Duration.seconds(1), Duration.subtract(Duration.milliseconds(500))); // 500ms
+     * ```
+     */
+    const subtract: (other: Duration) => (self: Duration) => Duration;
+}
+
+export { Brand, Duration, type NonEmptyList, isNonEmptyList };

package/dist/types.js

@@ -21,6 +21,7 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 var Types_exports = {};
 __export(Types_exports, {
   Brand: () => Brand,
+  Duration: () => Duration,
   isNonEmptyList: () => isNonEmptyList
 });
 module.exports = __toCommonJS(Types_exports);
@@ -32,10 +33,29 @@ var Brand;
   Brand2.unwrap = (branded) => branded;
 })(Brand || (Brand = {}));
 
+// src/Types/Duration.ts
+var Duration;
+((Duration2) => {
+  const wrap = Brand.wrap();
+  Duration2.milliseconds = (ms) => wrap(ms);
+  Duration2.seconds = (s) => wrap(s * 1e3);
+  Duration2.minutes = (m) => wrap(m * 60 * 1e3);
+  Duration2.hours = (h) => wrap(h * 60 * 60 * 1e3);
+  Duration2.days = (d) => wrap(d * 24 * 60 * 60 * 1e3);
+  Duration2.toMilliseconds = (d) => Brand.unwrap(d);
+  Duration2.toSeconds = (d) => Brand.unwrap(d) / 1e3;
+  Duration2.toMinutes = (d) => Brand.unwrap(d) / (60 * 1e3);
+  Duration2.toHours = (d) => Brand.unwrap(d) / (60 * 60 * 1e3);
+  Duration2.toDays = (d) => Brand.unwrap(d) / (24 * 60 * 60 * 1e3);
+  Duration2.add = (other) => (self) => wrap(Brand.unwrap(self) + Brand.unwrap(other));
+  Duration2.subtract = (other) => (self) => wrap(Brand.unwrap(self) - Brand.unwrap(other));
+})(Duration || (Duration = {}));
+
 // src/Types/NonEmptyList.ts
 var isNonEmptyList = (list) => list.length > 0;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   Brand,
+  Duration,
   isNonEmptyList
 });

package/dist/types.mjs

@@ -1,10 +1,13 @@
-import {
-  Brand
-} from "./chunk-BYWKZLHM.mjs";
+import "./chunk-IPP4XFYH.mjs";
 import {
   isNonEmptyList
 } from "./chunk-DBIC62UV.mjs";
+import {
+  Brand,
+  Duration
+} from "./chunk-VWVPHDZO.mjs";
 export {
   Brand,
+  Duration,
   isNonEmptyList
 };

package/dist/utils.d.mts

@@ -1,5 +1,5 @@
-import { M as Maybe, R as Result, T as Task } from './Task-BDcKwFAj.mjs';
-import { N as NonEmptyList } from './NonEmptyList-BlGFjor5.mjs';
+import { M as Maybe, R as Result, E as Equality, b as Ordering, T as Task } from './Task-5na0QzS4.mjs';
+import { NonEmptyList } from './types.mjs';
 
 /**
  * Functional array utilities that compose well with pipe.
@@ -140,6 +140,38 @@ declare namespace Arr {
      * ```
      */
     const partition: <A>(predicate: (a: A) => boolean) => (data: readonly A[]) => readonly [readonly A[], readonly A[]];
+    /**
+     * Narrows a list of Maybe values down to a list of their underlying values,
+     * discarding all None instances.
+     *
+     * @example
+     * ```ts
+     * Arr.compact([Maybe.some(1), Maybe.none(), Maybe.some(3)]); // [1, 3]
+     * ```
+     */
+    const compact: <A>(data: readonly Maybe<A>[]) => readonly A[];
+    /**
+     * Separates an array of Result values into two separate lists of errors and successes.
+     * Returns a tuple containing `[errors, successes]`.
+     *
+     * @example
+     * ```ts
+     * Arr.separate([Result.ok(1), Result.error("bad"), Result.ok(3)]); // [["bad"], [1, 3]]
+     * ```
+     */
+    const separate: <E, A>(data: readonly Result<E, A>[]) => readonly [readonly E[], readonly A[]];
+    /**
+     * Maps each element to a Result, and separates the results into a tuple of failures and successes.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   [1, 2, 3, 4],
+     *   Arr.partitionMap(n => n % 2 === 0 ? Result.ok(n) : Result.error(`odd: ${n}`))
+     * ); // [["odd: 1", "odd: 3"], [2, 4]]
+     * ```
+     */
+    const partitionMap: <A, E, B>(f: (a: A) => Result<E, B>) => (data: readonly A[]) => readonly [readonly E[], readonly B[]];
     /**
      * Groups elements by a key function.
      *
@@ -173,8 +205,26 @@ declare namespace Arr {
      * ```
      */
     const uniqBy: <A, B>(f: (a: A) => B) => (data: readonly A[]) => readonly A[];
+    /**
+     * Removes duplicate elements using a custom equality check.
+     * Preserves the order of first occurrences. Complements `uniq` (reference equality)
+     * and `uniqBy` (key extraction).
+     *
+     * @example
+     * ```ts
+     * type Point = { x: number; y: number };
+     * const eqPoint: Equality<Point> = (a, b) => a.x === b.x && a.y === b.y;
+     *
+     * pipe(
+     *   [{ x: 1, y: 1 }, { x: 2, y: 2 }, { x: 1, y: 1 }],
+     *   Arr.uniqWith(eqPoint),
+     * ); // [{ x: 1, y: 1 }, { x: 2, y: 2 }]
+     * ```
+     */
+    const uniqWith: <A>(eq: Equality<A>) => (data: readonly A[]) => readonly A[];
     /**
      * Sorts an array using a comparison function. Returns a new array.
+     * To sort with a typed `Ordering<A>`, prefer `Arr.sortWith`.
      *
      * @example
      * ```ts
@@ -182,6 +232,19 @@ declare namespace Arr {
      * ```
      */
     const sortBy: <A>(compare: (a: A, b: A) => number) => (data: readonly A[]) => readonly A[];
+    /**
+     * Sorts an array using an `Ordering<A>`. Returns a new array without mutating the original.
+     * Use this over `sortBy` when you have a typed `Ordering<A>` from the `Ordering` module.
+     *
+     * @example
+     * ```ts
+     * pipe([3, 1, 2], Arr.sortWith(Ordering.number)); // [1, 2, 3]
+     *
+     * const byPrice = pipe(Ordering.number, Ordering.by((p: Product) => p.price));
+     * pipe(products, Arr.sortWith(byPrice));
+     * ```
+     */
+    const sortWith: <A>(ord: Ordering<A>) => (data: readonly A[]) => readonly A[];
     /**
      * Pairs up elements from two arrays. Stops at the shorter array.
      *
@@ -945,6 +1008,46 @@ declare namespace Num {
      * ```
      */
     const remainder: (divisor: number) => (n: number) => Maybe<number>;
+    /**
+     * Computes the sum of a list of numbers. Returns `0` if the list is empty.
+     *
+     * @example
+     * ```ts
+     * Num.sum([1, 2, 3]); // 6
+     * Num.sum([]);        // 0
+     * ```
+     */
+    const sum: (ns: readonly number[]) => number;
+    /**
+     * Computes the mean of a list of numbers. Returns `None` if the list is empty.
+     *
+     * @example
+     * ```ts
+     * Num.mean([1, 2, 3]); // Some(2)
+     * Num.mean([]);        // None
+     * ```
+     */
+    const mean: (ns: readonly number[]) => Maybe<number>;
+    /**
+     * Computes the minimum of a list of numbers. Returns `None` if the list is empty.
+     *
+     * @example
+     * ```ts
+     * Num.min([5, 1, 3]); // Some(1)
+     * Num.min([]);        // None
+     * ```
+     */
+    const min: (ns: readonly number[]) => Maybe<number>;
+    /**
+     * Computes the maximum of a list of numbers. Returns `None` if the list is empty.
+     *
+     * @example
+     * ```ts
+     * Num.max([1, 5, 3]); // Some(5)
+     * Num.max([]);        // None
+     * ```
+     */
+    const max: (ns: readonly number[]) => Maybe<number>;
 }
 
 /**
@@ -1204,6 +1307,15 @@ declare namespace Str {
      * ```
      */
     const toLowerCase: (s: string) => string;
+    /**
+     * Converts the first character of a string to uppercase.
+     *
+     * @example
+     * ```ts
+     * pipe("hello", Str.capitalize); // "Hello"
+     * ```
+     */
+    const capitalize: (s: string) => string;
     /**
      * Splits a string into lines, normalising `\r\n` and `\r` line endings.
      *
@@ -1310,6 +1422,16 @@ declare namespace Str {
          */
         float: (s: string) => Maybe<number>;
     };
+    /**
+     * Safely parses a JSON string, returning a `Result<SyntaxError, unknown>`.
+     *
+     * @example
+     * ```ts
+     * Str.parseJson('{"a": 1}'); // Ok({ a: 1 })
+     * Str.parseJson('invalid');  // Error(SyntaxError)
+     * ```
+     */
+    const parseJson: (s: string) => Result<SyntaxError, unknown>;
 }
 
 /**

package/dist/utils.d.ts

@@ -1,5 +1,5 @@
-import { M as Maybe, R as Result, T as Task } from './Task-CnF22Q2o.js';
-import { N as NonEmptyList } from './NonEmptyList-BlGFjor5.js';
+import { M as Maybe, R as Result, E as Equality, b as Ordering, T as Task } from './Task-DeiWgoeJ.js';
+import { NonEmptyList } from './types.js';
 
 /**
  * Functional array utilities that compose well with pipe.
@@ -140,6 +140,38 @@ declare namespace Arr {
      * ```
      */
     const partition: <A>(predicate: (a: A) => boolean) => (data: readonly A[]) => readonly [readonly A[], readonly A[]];
+    /**
+     * Narrows a list of Maybe values down to a list of their underlying values,
+     * discarding all None instances.
+     *
+     * @example
+     * ```ts
+     * Arr.compact([Maybe.some(1), Maybe.none(), Maybe.some(3)]); // [1, 3]
+     * ```
+     */
+    const compact: <A>(data: readonly Maybe<A>[]) => readonly A[];
+    /**
+     * Separates an array of Result values into two separate lists of errors and successes.
+     * Returns a tuple containing `[errors, successes]`.
+     *
+     * @example
+     * ```ts
+     * Arr.separate([Result.ok(1), Result.error("bad"), Result.ok(3)]); // [["bad"], [1, 3]]
+     * ```
+     */
+    const separate: <E, A>(data: readonly Result<E, A>[]) => readonly [readonly E[], readonly A[]];
+    /**
+     * Maps each element to a Result, and separates the results into a tuple of failures and successes.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   [1, 2, 3, 4],
+     *   Arr.partitionMap(n => n % 2 === 0 ? Result.ok(n) : Result.error(`odd: ${n}`))
+     * ); // [["odd: 1", "odd: 3"], [2, 4]]
+     * ```
+     */
+    const partitionMap: <A, E, B>(f: (a: A) => Result<E, B>) => (data: readonly A[]) => readonly [readonly E[], readonly B[]];
     /**
      * Groups elements by a key function.
      *
@@ -173,8 +205,26 @@ declare namespace Arr {
      * ```
      */
     const uniqBy: <A, B>(f: (a: A) => B) => (data: readonly A[]) => readonly A[];
+    /**
+     * Removes duplicate elements using a custom equality check.
+     * Preserves the order of first occurrences. Complements `uniq` (reference equality)
+     * and `uniqBy` (key extraction).
+     *
+     * @example
+     * ```ts
+     * type Point = { x: number; y: number };
+     * const eqPoint: Equality<Point> = (a, b) => a.x === b.x && a.y === b.y;
+     *
+     * pipe(
+     *   [{ x: 1, y: 1 }, { x: 2, y: 2 }, { x: 1, y: 1 }],
+     *   Arr.uniqWith(eqPoint),
+     * ); // [{ x: 1, y: 1 }, { x: 2, y: 2 }]
+     * ```
+     */
+    const uniqWith: <A>(eq: Equality<A>) => (data: readonly A[]) => readonly A[];
     /**
      * Sorts an array using a comparison function. Returns a new array.
+     * To sort with a typed `Ordering<A>`, prefer `Arr.sortWith`.
      *
      * @example
      * ```ts
@@ -182,6 +232,19 @@ declare namespace Arr {
      * ```
      */
     const sortBy: <A>(compare: (a: A, b: A) => number) => (data: readonly A[]) => readonly A[];
+    /**
+     * Sorts an array using an `Ordering<A>`. Returns a new array without mutating the original.
+     * Use this over `sortBy` when you have a typed `Ordering<A>` from the `Ordering` module.
+     *
+     * @example
+     * ```ts
+     * pipe([3, 1, 2], Arr.sortWith(Ordering.number)); // [1, 2, 3]
+     *
+     * const byPrice = pipe(Ordering.number, Ordering.by((p: Product) => p.price));
+     * pipe(products, Arr.sortWith(byPrice));
+     * ```
+     */
+    const sortWith: <A>(ord: Ordering<A>) => (data: readonly A[]) => readonly A[];
     /**
      * Pairs up elements from two arrays. Stops at the shorter array.
      *
@@ -945,6 +1008,46 @@ declare namespace Num {
      * ```
      */
     const remainder: (divisor: number) => (n: number) => Maybe<number>;
+    /**
+     * Computes the sum of a list of numbers. Returns `0` if the list is empty.
+     *
+     * @example
+     * ```ts
+     * Num.sum([1, 2, 3]); // 6
+     * Num.sum([]);        // 0
+     * ```
+     */
+    const sum: (ns: readonly number[]) => number;
+    /**
+     * Computes the mean of a list of numbers. Returns `None` if the list is empty.
+     *
+     * @example
+     * ```ts
+     * Num.mean([1, 2, 3]); // Some(2)
+     * Num.mean([]);        // None
+     * ```
+     */
+    const mean: (ns: readonly number[]) => Maybe<number>;
+    /**
+     * Computes the minimum of a list of numbers. Returns `None` if the list is empty.
+     *
+     * @example
+     * ```ts
+     * Num.min([5, 1, 3]); // Some(1)
+     * Num.min([]);        // None
+     * ```
+     */
+    const min: (ns: readonly number[]) => Maybe<number>;
+    /**
+     * Computes the maximum of a list of numbers. Returns `None` if the list is empty.
+     *
+     * @example
+     * ```ts
+     * Num.max([1, 5, 3]); // Some(5)
+     * Num.max([]);        // None
+     * ```
+     */
+    const max: (ns: readonly number[]) => Maybe<number>;
 }
 
 /**
@@ -1204,6 +1307,15 @@ declare namespace Str {
      * ```
      */
     const toLowerCase: (s: string) => string;
+    /**
+     * Converts the first character of a string to uppercase.
+     *
+     * @example
+     * ```ts
+     * pipe("hello", Str.capitalize); // "Hello"
+     * ```
+     */
+    const capitalize: (s: string) => string;
     /**
      * Splits a string into lines, normalising `\r\n` and `\r` line endings.
      *
@@ -1310,6 +1422,16 @@ declare namespace Str {
          */
         float: (s: string) => Maybe<number>;
     };
+    /**
+     * Safely parses a JSON string, returning a `Result<SyntaxError, unknown>`.
+     *
+     * @example
+     * ```ts
+     * Str.parseJson('{"a": 1}'); // Ok({ a: 1 })
+     * Str.parseJson('invalid');  // Error(SyntaxError)
+     * ```
+     */
+    const parseJson: (s: string) => Result<SyntaxError, unknown>;
 }
 
 /**