@nlozgachev/pipelined 0.39.0 → 0.41.0

package/README.md

@@ -33,7 +33,7 @@ not anything is there:
 ```ts
 import { pipe } from "@nlozgachev/pipelined/composition";
 import { Maybe } from "@nlozgachev/pipelined/core";
-import { Num, Str } from "@nlozgachev/pipelined/utils";
+import { Num, Str } from "@nlozgachev/pipelined/data";
 
 const parseDiscount = (raw: string): string =>
   pipe(
@@ -120,7 +120,7 @@ steps to compose naturally with the core types:
 ```ts
 import { pipe } from "@nlozgachev/pipelined/composition";
 import { Maybe } from "@nlozgachev/pipelined/core";
-import { Arr, Num, Rec, Str } from "@nlozgachev/pipelined/utils";
+import { Arr, Num, Rec, Str } from "@nlozgachev/pipelined/data";
 
 type RawItem = { name: string; price: string; category: string };
 type Item = { name: string; price: number; category: string };

package/dist/Duration-BTeT9D-q.d.mts

@@ -0,0 +1,127 @@
+declare const _brand: unique symbol;
+/**
+ * Brand<K, T> creates a nominal type by tagging T with a phantom brand K.
+ * Prevents accidentally mixing up values that share the same underlying type.
+ *
+ * @example
+ * ```ts
+ * type UserId = Brand<"UserId", string>;
+ * type ProductId = Brand<"ProductId", string>;
+ *
+ * const toUserId = Brand.wrap<"UserId", string>();
+ * const toProductId = Brand.wrap<"ProductId", string>();
+ *
+ * const userId: UserId = toUserId("user-123");
+ * const productId: ProductId = toProductId("prod-456");
+ *
+ * // Type error: ProductId is not assignable to UserId
+ * // const wrong: UserId = productId;
+ * ```
+ */
+type Brand<K extends string, T> = T & {
+    readonly [_brand]: K;
+};
+declare namespace Brand {
+    /**
+     * Returns a constructor that wraps a value of type T in brand K.
+     * The resulting function performs an unchecked cast — only use when the raw
+     * value is known to satisfy the brand's invariants.
+     *
+     * @example
+     * ```ts
+     * type PositiveNumber = Brand<"PositiveNumber", number>;
+     * const toPositiveNumber = Brand.wrap<"PositiveNumber", number>();
+     *
+     * const n: PositiveNumber = toPositiveNumber(42);
+     * ```
+     */
+    const wrap: <K extends string, T>() => (value: T) => Brand<K, T>;
+    /**
+     * Strips the brand and returns the underlying value.
+     * Since Brand<K, T> extends T this is rarely needed, but can improve readability.
+     *
+     * @example
+     * ```ts
+     * const userId: UserId = toUserId("user-123");
+     * const raw: string = Brand.unwrap(userId); // "user-123"
+     * ```
+     */
+    const unwrap: <K extends string, T>(branded: Brand<K, T>) => T;
+}
+
+/**
+ * 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 as B, Duration as D };

package/dist/Duration-BTeT9D-q.d.ts

@@ -0,0 +1,127 @@
+declare const _brand: unique symbol;
+/**
+ * Brand<K, T> creates a nominal type by tagging T with a phantom brand K.
+ * Prevents accidentally mixing up values that share the same underlying type.
+ *
+ * @example
+ * ```ts
+ * type UserId = Brand<"UserId", string>;
+ * type ProductId = Brand<"ProductId", string>;
+ *
+ * const toUserId = Brand.wrap<"UserId", string>();
+ * const toProductId = Brand.wrap<"ProductId", string>();
+ *
+ * const userId: UserId = toUserId("user-123");
+ * const productId: ProductId = toProductId("prod-456");
+ *
+ * // Type error: ProductId is not assignable to UserId
+ * // const wrong: UserId = productId;
+ * ```
+ */
+type Brand<K extends string, T> = T & {
+    readonly [_brand]: K;
+};
+declare namespace Brand {
+    /**
+     * Returns a constructor that wraps a value of type T in brand K.
+     * The resulting function performs an unchecked cast — only use when the raw
+     * value is known to satisfy the brand's invariants.
+     *
+     * @example
+     * ```ts
+     * type PositiveNumber = Brand<"PositiveNumber", number>;
+     * const toPositiveNumber = Brand.wrap<"PositiveNumber", number>();
+     *
+     * const n: PositiveNumber = toPositiveNumber(42);
+     * ```
+     */
+    const wrap: <K extends string, T>() => (value: T) => Brand<K, T>;
+    /**
+     * Strips the brand and returns the underlying value.
+     * Since Brand<K, T> extends T this is rarely needed, but can improve readability.
+     *
+     * @example
+     * ```ts
+     * const userId: UserId = toUserId("user-123");
+     * const raw: string = Brand.unwrap(userId); // "user-123"
+     * ```
+     */
+    const unwrap: <K extends string, T>(branded: Brand<K, T>) => T;
+}
+
+/**
+ * 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 as B, Duration as D };

package/dist/{Task-uupX7xd9.d.ts → Task-BprUabHP.d.mts}

@@ -1,4 +1,5 @@
-import { NonEmptyList, Duration } from './types.js';
+import { D as Duration } from './Duration-BTeT9D-q.mjs';
+import { NonEmptyList } from './types.mjs';
 
 declare const _deferred: unique symbol;
 /**
@@ -1093,7 +1094,7 @@ declare namespace Task {
      * );
      * ```
      */
-    const run: (signal?: AbortSignal) => <A>(task: Task<A>) => Promise<A>;
+    const run: (signal?: AbortSignal) => <A>(task: Task<A>) => Deferred<A>;
     /**
      * Converts a Task value into an object containing a single property.
      * Initiates the pipeline accumulator record.

package/dist/{Task-DcXhCZYg.d.mts → Task-Dt3ZMen6.d.ts}

@@ -1,4 +1,5 @@
-import { NonEmptyList, Duration } from './types.mjs';
+import { D as Duration } from './Duration-BTeT9D-q.js';
+import { NonEmptyList } from './types.js';
 
 declare const _deferred: unique symbol;
 /**
@@ -1093,7 +1094,7 @@ declare namespace Task {
      * );
      * ```
      */
-    const run: (signal?: AbortSignal) => <A>(task: Task<A>) => Promise<A>;
+    const run: (signal?: AbortSignal) => <A>(task: Task<A>) => Deferred<A>;
     /**
      * Converts a Task value into an object containing a single property.
      * Initiates the pipeline accumulator record.

package/dist/{chunk-4R4XUP4M.mjs → chunk-COGQKPIP.mjs}

@@ -1,6 +1,6 @@
 import {
   Duration
-} from "./chunk-5AFEEFE4.mjs";
+} from "./chunk-GBB6LVLI.mjs";
 
 // src/Core/Combinable.ts
 var Combinable;
@@ -1800,7 +1800,7 @@ var Task;
     };
     return { task, abort };
   };
-  Task2.run = (signal) => (task) => Deferred.toPromise(task(signal));
+  Task2.run = (signal) => (task) => task(signal);
   Task2.bindTo = (key) => (data) => (0, Task2.map)((a) => ({ [key]: a }))(data);
   Task2.bind = (key, f) => (data) => (0, Task2.chain)(
     (a) => (0, Task2.map)((b) => ({ ...a, [key]: b }))(f(a))
@@ -1864,7 +1864,7 @@ var TaskResult3;
       ([of_, oa]) => Result.ap(oa)(of_)
     )
   );
-  TaskResult4.run = (signal) => (task) => Deferred.toPromise(task(signal));
+  TaskResult4.run = (signal) => (task) => task(signal);
   TaskResult4.bindTo = (key) => (data) => (0, TaskResult4.map)((a) => ({ [key]: a }))(data);
   TaskResult4.bind = (key, f) => (data) => (0, TaskResult4.chain)(
     (a) => (0, TaskResult4.map)((b) => ({ ...a, [key]: b }))(f(a))

package/dist/{chunk-5AFEEFE4.mjs → chunk-GBB6LVLI.mjs}

@@ -28,6 +28,6 @@ var isNonEmptyList = (list) => list.length > 0;
 
 export {
   Brand,
-  Duration,
-  isNonEmptyList
+  isNonEmptyList,
+  Duration
 };

package/dist/{chunk-3Q5UBRYB.mjs → chunk-TCE2UETM.mjs}

@@ -1,3 +1,7 @@
+import {
+  Duration
+} from "./chunk-GBB6LVLI.mjs";
+
 // src/Composition/compose.ts
 function compose(f0, f1, f2, f3, f4, f5, f6, f7, f8, f9) {
   const len = arguments.length;
@@ -316,10 +320,90 @@ pipe.try = (f, onError) => (a) => {
 };
 
 // src/Composition/tap.ts
-var tap = (f) => (a) => {
-  f(a);
-  return a;
-};
+import { inspect as nodeInspect } from "util";
+function tap(f) {
+  return (a) => {
+    f(a);
+    return a;
+  };
+}
+((tap2) => {
+  tap2.log = (options) => (a) => {
+    const logger = options?.logger ?? console.log;
+    const formatter = options?.formatter ?? ((val) => {
+      try {
+        return typeof val === "object" && val !== null ? JSON.stringify(val) : String(val);
+      } catch {
+        return String(val);
+      }
+    });
+    const formatted = formatter(a);
+    if (options?.label !== void 0) {
+      logger(`[${options.label}]: ${formatted}`);
+    } else {
+      logger(formatted);
+    }
+    return a;
+  };
+  tap2.inspect = (options) => (a) => {
+    const label = options?.label;
+    const depth = options?.depth ?? null;
+    const colors = options?.colors ?? true;
+    let formatted;
+    if (typeof nodeInspect === "function") {
+      formatted = nodeInspect(a, { depth, colors });
+    } else {
+      try {
+        formatted = JSON.stringify(a, null, 2);
+      } catch {
+        formatted = String(a);
+      }
+    }
+    if (label !== void 0) {
+      console.log(`[${label}]: ${formatted}`);
+    } else {
+      console.log(formatted);
+    }
+    return a;
+  };
+  tap2.async = (fn, options) => (a) => {
+    const onError = options?.onError ?? console.error;
+    fn(a).catch((err) => {
+      onError(err);
+    });
+    return a;
+  };
+  tap2.time = (fn, config) => (a) => {
+    const start = performance.now();
+    const triggerFinish = (duration) => {
+      if (config.label !== void 0) {
+        console.log(`[${config.label}]: ${Duration.toMilliseconds(duration)}ms`);
+      } else if (config.onFinish) {
+        config.onFinish(duration);
+      }
+    };
+    try {
+      const res = fn(a);
+      if (res instanceof Promise) {
+        res.then(() => {
+          const duration = Duration.milliseconds(performance.now() - start);
+          triggerFinish(duration);
+        }, () => {
+          const duration = Duration.milliseconds(performance.now() - start);
+          triggerFinish(duration);
+        });
+      } else {
+        const duration = Duration.milliseconds(performance.now() - start);
+        triggerFinish(duration);
+      }
+    } catch (err) {
+      const duration = Duration.milliseconds(performance.now() - start);
+      triggerFinish(duration);
+      throw err;
+    }
+    return a;
+  };
+})(tap || (tap = {}));
 
 // src/Composition/uncurry.ts
 function uncurry(f) {

package/dist/{chunk-GTJ2YCYY.mjs → chunk-V37OUM35.mjs}

@@ -3,12 +3,12 @@ import {
   Maybe,
   Result,
   Task
-} from "./chunk-4R4XUP4M.mjs";
+} from "./chunk-COGQKPIP.mjs";
 import {
   isNonEmptyList
-} from "./chunk-5AFEEFE4.mjs";
+} from "./chunk-GBB6LVLI.mjs";
 
-// src/Utils/Arr.ts
+// src/Data/Arr.ts
 var Arr;
 ((Arr2) => {
   Arr2.head = (data) => data.length > 0 ? Maybe.some(data[0]) : Maybe.none();
@@ -340,7 +340,7 @@ var Arr;
   };
 })(Arr || (Arr = {}));
 
-// src/Utils/Dict.ts
+// src/Data/Dict.ts
 var Dict;
 ((Dict2) => {
   Dict2.empty = () => new globalThis.Map();
@@ -478,7 +478,7 @@ var Dict;
   Dict2.toRecord = (m) => Object.fromEntries(m);
 })(Dict || (Dict = {}));
 
-// src/Utils/Num.ts
+// src/Data/Num.ts
 var Num;
 ((Num2) => {
   Num2.range = (from, to, step = 1) => {
@@ -494,6 +494,7 @@ var Num;
   };
   Num2.clamp = (min2, max2) => (n) => Math.min(Math.max(n, min2), max2);
   Num2.between = (min2, max2) => (n) => n >= min2 && n <= max2;
+  Num2.inRange = (start, end) => (n) => n >= start && n < end;
   Num2.parse = (s) => {
     if (s.trim() === "") {
       return Maybe.none();
@@ -545,7 +546,7 @@ var Num;
   };
 })(Num || (Num = {}));
 
-// src/Utils/Rec.ts
+// src/Data/Rec.ts
 var Rec;
 ((Rec2) => {
   Rec2.map = (f) => (data) => {
@@ -673,7 +674,7 @@ var Rec;
   };
 })(Rec || (Rec = {}));
 
-// src/Utils/Str.ts
+// src/Data/Str.ts
 var Str;
 ((Str2) => {
   Str2.split = (separator) => (s) => s.split(separator);
@@ -733,7 +734,7 @@ var Str;
   };
 })(Str || (Str = {}));
 
-// src/Utils/Uniq.ts
+// src/Data/Uniq.ts
 var Uniq;
 ((Uniq2) => {
   Uniq2.empty = () => new globalThis.Set();

package/dist/composition.d.mts

@@ -1,3 +1,5 @@
+import { D as Duration } from './Duration-BTeT9D-q.mjs';
+
 /**
  * Composes functions from right to left, returning a new function.
  * This is the traditional mathematical function composition: (f . g)(x) = f(g(x))
@@ -617,7 +619,132 @@ interface pipe {
  *
  * @see {@link Maybe.tap} for Maybe-specific tap that only runs on Some
  */
-declare const tap: <A>(f: (a: A) => void) => (a: A) => A;
+declare function tap<A>(f: (a: A) => void): (a: A) => A;
+declare namespace tap {
+    /**
+     * Configuration options for {@link tap.log}.
+     */
+    type LogOptions<A> = {
+        /**
+         * An optional label prefix for the log output (e.g., `[label]: value`).
+         */
+        readonly label?: string;
+        /**
+         * The logging destination function. Defaults to `console.log`.
+         */
+        readonly logger?: (message: string) => void;
+        /**
+         * A custom formatter function to convert the piped value to a string.
+         * Defaults to `JSON.stringify` for objects and `String(value)` for primitives.
+         */
+        readonly formatter?: (value: A) => string;
+    };
+    /**
+     * Configuration options for {@link tap.inspect}.
+     */
+    type InspectOptions = {
+        /**
+         * An optional label prefix for the inspect output (e.g., `[label]: value`).
+         */
+        readonly label?: string;
+        /**
+         * The maximum depth to recurse when formatting the object.
+         * Defaults to `null` (infinite depth).
+         */
+        readonly depth?: number;
+        /**
+         * Whether to colorize the output using ANSI color codes.
+         * Defaults to `true`.
+         */
+        readonly colors?: boolean;
+    };
+    /**
+     * Configuration options for {@link tap.async}.
+     */
+    type AsyncOptions = {
+        /**
+         * A callback to handle exceptions thrown by the async side-effect.
+         * Defaults to logging via `console.error`.
+         */
+        readonly onError?: (error: unknown) => void;
+    };
+    /**
+     * Configuration options for {@link tap.time}, enforcing mutual exclusivity
+     * between console logging and custom handlers.
+     */
+    type TimeConfig = {
+        label: string;
+        onFinish?: never;
+    } | {
+        onFinish: (duration: Duration) => void;
+        label?: never;
+    };
+    /**
+     * Logs the piped value to the console or a custom logger, returning the value unchanged.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   42,
+     *   tap.log(), // logs: 42
+     *   tap.log({ label: "Count" }) // logs: [Count]: 42
+     * );
+     * ```
+     */
+    const log: <A>(options?: LogOptions<A>) => (a: A) => A;
+    /**
+     * Performs a deep structured inspect formatting on the piped value, returning it unchanged.
+     * In Node.js environments, this utilizes Node's `node:util` `inspect` utility.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   { user: { name: "Alice", details: { age: 30 } } },
+     *   tap.inspect({ label: "User Object", depth: 2 })
+     * );
+     * ```
+     */
+    const inspect: <A>(options?: InspectOptions) => (a: A) => A;
+    /**
+     * Triggers a fire-and-forget asynchronous side effect in the background,
+     * returning the piped value immediately and synchronously.
+     * Any errors thrown by the async function are caught and forwarded to `onError`.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   user,
+     *   tap.async(async (u) => {
+     *     await saveToDatabase(u);
+     *   }, { onError: (err) => logError(err) })
+     * );
+     * ```
+     */
+    const async: <A>(fn: (a: A) => Promise<unknown>, options?: AsyncOptions) => (a: A) => A;
+    /**
+     * Runs a function and measures its execution duration, returning the value unchanged.
+     * Supports both synchronous and asynchronous functions. If the timed function returns
+     * a Promise, duration measurement resolves asynchronously upon resolution/rejection.
+     *
+     * @example
+     * ```ts
+     * // Time a synchronous computation
+     * pipe(
+     *   data,
+     *   tap.time(processData, { label: "sync-process" })
+     * );
+     *
+     * // Time an asynchronous fetch with custom metrics callback
+     * pipe(
+     *   data,
+     *   tap.time(fetchData, {
+     *     onFinish: (dur) => metrics.histogram("api.time", Duration.toMilliseconds(dur))
+     *   })
+     * );
+     * ```
+     */
+    const time: <A>(fn: (a: A) => unknown, config: TimeConfig) => (a: A) => A;
+}
 
 /**
  * Converts a curried function into a multi-argument function.