@nlozgachev/pipekit 0.1.7 → 0.2.0

package/esm/src/Core/Task.js

@@ -1,3 +1,4 @@
+import { Result } from "./Result.js";
 export var Task;
 (function (Task) {
     /**
@@ -10,10 +11,6 @@ export var Task;
      * ```
      */
     Task.of = (value) => () => Promise.resolve(value);
-    /**
-     * Creates a Task that will reject with the given error.
-     */
-    Task.fail = (error) => () => Promise.reject(error);
     /**
      * Creates a Task from a function that returns a Promise.
      * Alias for directly creating a Task.
@@ -37,7 +34,7 @@ export var Task;
      */
     Task.map = (f) => (data) => () => data().then(f);
     /**
-     * Chains Task computations. If the first succeeds, passes the value to f.
+     * Chains Task computations. Passes the resolved value of the first Task to f.
      *
      * @example
      * ```ts
@@ -95,6 +92,7 @@ export var Task;
     Task.all = (tasks) => () => Promise.all(tasks.map((t) => t()));
     /**
      * Delays the execution of a Task by the specified milliseconds.
+     * Useful for debouncing or rate limiting.
      *
      * @example
      * ```ts
@@ -105,4 +103,74 @@ export var Task;
      * ```
      */
     Task.delay = (ms) => (data) => () => new Promise((resolve, reject) => setTimeout(() => data().then(resolve, reject), ms));
+    /**
+     * Runs a Task a fixed number of times sequentially, collecting all results into an array.
+     * An optional delay (ms) can be inserted between runs.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   pollSensor,
+     *   Task.repeat({ times: 5, delay: 1000 })
+     * )(); // Task<Reading[]> — 5 readings, one per second
+     * ```
+     */
+    Task.repeat = (options) => (task) => () => {
+        const { times, delay: ms } = options;
+        if (times <= 0)
+            return Promise.resolve([]);
+        const results = [];
+        const wait = () => ms !== undefined && ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve();
+        const run = (left) => task().then((a) => {
+            results.push(a);
+            if (left <= 1)
+                return results;
+            return wait().then(() => run(left - 1));
+        });
+        return run(times);
+    };
+    /**
+     * Runs a Task repeatedly until the result satisfies a predicate, returning that result.
+     * An optional delay (ms) can be inserted between runs.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   checkStatus,
+     *   Task.repeatUntil({ when: (s) => s === "ready", delay: 500 })
+     * )(); // polls every 500ms until status is "ready"
+     * ```
+     */
+    Task.repeatUntil = (options) => (task) => () => {
+        const { when: predicate, delay: ms } = options;
+        const wait = () => ms !== undefined && ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve();
+        const run = () => task().then((a) => {
+            if (predicate(a))
+                return a;
+            return wait().then(run);
+        });
+        return run();
+    };
+    /**
+     * Converts a `Task<A>` into a `Task<Result<E, A>>`, resolving to `Err` if the
+     * Task does not complete within the given time.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   fetchUser,
+     *   Task.timeout(5000, () => new TimeoutError("fetch user timed out")),
+     *   TaskResult.chain(processUser)
+     * );
+     * ```
+     */
+    Task.timeout = (ms, onTimeout) => (task) => () => {
+        let timerId;
+        return Promise.race([
+            task().then((a) => { clearTimeout(timerId); return Result.ok(a); }),
+            new Promise((resolve) => {
+                timerId = setTimeout(() => resolve(Result.err(onTimeout())), ms);
+            }),
+        ]);
+    };
 })(Task || (Task = {}));

package/esm/src/Core/TaskOption.js

@@ -9,7 +9,7 @@ export var TaskOption;
     /**
      * Creates a TaskOption that resolves to None.
      */
-    TaskOption.none = () => Task.of(Option.toNone());
+    TaskOption.none = () => Task.of(Option.none());
     /**
      * Lifts an Option into a TaskOption.
      */
@@ -29,7 +29,7 @@ export var TaskOption;
      * );
      * ```
      */
-    TaskOption.tryCatch = (f) => () => f().then(Option.of).catch(() => Option.toNone());
+    TaskOption.tryCatch = (f) => () => f().then(Option.of).catch(() => Option.none());
     /**
      * Transforms the value inside a TaskOption.
      */
@@ -46,7 +46,7 @@ export var TaskOption;
      * )();
      * ```
      */
-    TaskOption.chain = (f) => (data) => Task.chain((option) => Option.isSome(option) ? f(option.value) : Task.of(Option.toNone()))(data);
+    TaskOption.chain = (f) => (data) => Task.chain((option) => Option.isSome(option) ? f(option.value) : Task.of(Option.none()))(data);
     /**
      * Applies a function wrapped in a TaskOption to a value wrapped in a TaskOption.
      * Both Tasks run in parallel.

package/esm/src/Core/TaskResult.js

@@ -5,11 +5,11 @@ export var TaskResult;
     /**
      * Wraps a value in a successful TaskResult.
      */
-    TaskResult.of = (value) => Task.of(Result.toOk(value));
+    TaskResult.of = (value) => Task.of(Result.ok(value));
     /**
      * Creates a failed TaskResult with the given error.
      */
-    TaskResult.fail = (error) => Task.of(Result.toErr(error));
+    TaskResult.err = (error) => Task.of(Result.err(error));
     /**
      * Creates a TaskResult from a function that may throw.
      * Catches any errors and transforms them using the onError function.
@@ -24,8 +24,8 @@ export var TaskResult;
      * ```
      */
     TaskResult.tryCatch = (f, onError) => () => f()
-        .then(Result.toOk)
-        .catch((e) => Result.toErr(onError(e)));
+        .then(Result.ok)
+        .catch((e) => Result.err(onError(e)));
     /**
      * Transforms the success value inside a TaskResult.
      */
@@ -38,7 +38,7 @@ export var TaskResult;
      * Chains TaskResult computations. If the first succeeds, passes the value to f.
      * If the first fails, propagates the error.
      */
-    TaskResult.chain = (f) => (data) => Task.chain((result) => Result.isOk(result) ? f(result.value) : Task.of(Result.toErr(result.error)))(data);
+    TaskResult.chain = (f) => (data) => Task.chain((result) => Result.isOk(result) ? f(result.value) : Task.of(Result.err(result.error)))(data);
     /**
      * Extracts the value from a TaskResult by providing handlers for both cases.
      */
@@ -60,4 +60,61 @@ export var TaskResult;
      * Useful for logging or debugging.
      */
     TaskResult.tap = (f) => (data) => Task.map(Result.tap(f))(data);
+    /**
+     * Re-runs a TaskResult on `Err` with configurable attempts, backoff, and retry condition.
+     *
+     * @param options.attempts - Total number of attempts (1 = no retry, 3 = up to 3 tries)
+     * @param options.backoff - Fixed delay in ms, or a function `(attempt) => ms` for computed delay
+     * @param options.when - Only retry when this returns true; defaults to always retry on Err
+     *
+     * @example
+     * ```ts
+     * // Retry up to 3 times with exponential backoff
+     * pipe(
+     *   fetchUser,
+     *   TaskResult.retry({ attempts: 3, backoff: n => n * 1000 })
+     * );
+     *
+     * // Only retry on network errors, not auth errors
+     * pipe(
+     *   fetchUser,
+     *   TaskResult.retry({ attempts: 3, when: e => e instanceof NetworkError })
+     * );
+     * ```
+     */
+    TaskResult.retry = (options) => (data) => () => {
+        const { attempts, backoff, when: shouldRetry } = options;
+        const getDelay = (n) => backoff === undefined ? 0 : typeof backoff === "function" ? backoff(n) : backoff;
+        const run = (left) => data().then((result) => {
+            if (Result.isOk(result))
+                return result;
+            if (left <= 1)
+                return result;
+            if (shouldRetry !== undefined && !shouldRetry(result.error))
+                return result;
+            const ms = getDelay(attempts - left + 1);
+            return (ms > 0 ? new Promise((r) => setTimeout(r, ms)) : Promise.resolve()).then(() => run(left - 1));
+        });
+        return run(attempts);
+    };
+    /**
+     * Fails a TaskResult with a typed error if it does not resolve within the given time.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   fetchUser,
+     *   TaskResult.timeout(5000, () => new TimeoutError("fetch user timed out"))
+     * );
+     * ```
+     */
+    TaskResult.timeout = (ms, onTimeout) => (data) => () => {
+        let timerId;
+        return Promise.race([
+            data().then((result) => { clearTimeout(timerId); return result; }),
+            new Promise((resolve) => {
+                timerId = setTimeout(() => resolve(Result.err(onTimeout())), ms);
+            }),
+        ]);
+    };
 })(TaskResult || (TaskResult = {}));

package/esm/src/Core/These.js

@@ -6,28 +6,28 @@ export var These;
      *
      * @example
      * ```ts
-     * These.toErr("Something went wrong");
+     * These.err("Something went wrong");
      * ```
      */
-    These.toErr = (error) => Result.toErr(error);
+    These.err = (error) => Result.err(error);
     /**
      * Creates a These holding only a success value (no error).
      *
      * @example
      * ```ts
-     * These.toOk(42);
+     * These.ok(42);
      * ```
      */
-    These.toOk = (value) => Result.toOk(value);
+    These.ok = (value) => Result.ok(value);
     /**
      * Creates a These holding both an error/warning and a success value.
      *
      * @example
      * ```ts
-     * These.toBoth("Deprecated API used", result);
+     * These.both("Deprecated API used", result);
      * ```
      */
-    These.toBoth = (error, value) => ({
+    These.both = (error, value) => ({
         kind: "Both",
         error,
         value,
@@ -57,33 +57,33 @@ export var These;
      *
      * @example
      * ```ts
-     * pipe(These.toOk(5), These.map(n => n * 2));          // Ok(10)
-     * pipe(These.toBoth("warn", 5), These.map(n => n * 2)); // Both("warn", 10)
-     * pipe(These.toErr("err"), These.map(n => n * 2));      // Err("err")
+     * pipe(These.ok(5), These.map(n => n * 2));          // Ok(10)
+     * pipe(These.both("warn", 5), These.map(n => n * 2)); // Both("warn", 10)
+     * pipe(These.err("err"), These.map(n => n * 2));      // Err("err")
      * ```
      */
     These.map = (f) => (data) => {
         if (These.isErr(data))
             return data;
         if (These.isOk(data))
-            return These.toOk(f(data.value));
-        return These.toBoth(data.error, f(data.value));
+            return These.ok(f(data.value));
+        return These.both(data.error, f(data.value));
     };
     /**
      * Transforms the error/warning value, leaving the success value unchanged.
      *
      * @example
      * ```ts
-     * pipe(These.toErr("err"), These.mapErr(e => e.toUpperCase()));         // Err("ERR")
-     * pipe(These.toBoth("warn", 5), These.mapErr(e => e.toUpperCase()));    // Both("WARN", 5)
+     * pipe(These.err("err"), These.mapErr(e => e.toUpperCase()));         // Err("ERR")
+     * pipe(These.both("warn", 5), These.mapErr(e => e.toUpperCase()));    // Both("WARN", 5)
      * ```
      */
     These.mapErr = (f) => (data) => {
         if (These.isOk(data))
             return data;
         if (These.isErr(data))
-            return These.toErr(f(data.error));
-        return These.toBoth(f(data.error), data.value);
+            return These.err(f(data.error));
+        return These.both(f(data.error), data.value);
     };
     /**
      * Transforms both the error and success values independently.
@@ -91,17 +91,17 @@ export var These;
      * @example
      * ```ts
      * pipe(
-     *   These.toBoth("warn", 5),
+     *   These.both("warn", 5),
      *   These.bimap(e => e.toUpperCase(), n => n * 2)
      * ); // Both("WARN", 10)
      * ```
      */
     These.bimap = (onErr, onOk) => (data) => {
         if (These.isErr(data))
-            return These.toErr(onErr(data.error));
+            return These.err(onErr(data.error));
         if (These.isOk(data))
-            return These.toOk(onOk(data.value));
-        return These.toBoth(onErr(data.error), onOk(data.value));
+            return These.ok(onOk(data.value));
+        return These.both(onErr(data.error), onOk(data.value));
     };
     /**
      * Chains These computations by passing the success value to f.
@@ -112,11 +112,11 @@ export var These;
      *
      * @example
      * ```ts
-     * const double = (n: number): These<string, number> => These.toOk(n * 2);
+     * const double = (n: number): These<string, number> => These.ok(n * 2);
      *
-     * pipe(These.toOk(5), These.chain(double));           // Ok(10)
-     * pipe(These.toBoth("warn", 5), These.chain(double)); // Both("warn", 10)
-     * pipe(These.toErr("err"), These.chain(double));      // Err("err")
+     * pipe(These.ok(5), These.chain(double));           // Ok(10)
+     * pipe(These.both("warn", 5), These.chain(double)); // Both("warn", 10)
+     * pipe(These.err("err"), These.chain(double));      // Err("err")
      * ```
      */
     These.chain = (f) => (data) => {
@@ -125,7 +125,7 @@ export var These;
         if (These.isOk(data))
             return f(data.value);
         const result = f(data.value);
-        return These.isOk(result) ? These.toBoth(data.error, result.value) : result;
+        return These.isOk(result) ? These.both(data.error, result.value) : result;
     };
     /**
      * Extracts a value from a These by providing handlers for all three cases.
@@ -176,9 +176,9 @@ export var These;
      *
      * @example
      * ```ts
-     * pipe(These.toOk(5), These.getOrElse(0));           // 5
-     * pipe(These.toBoth("warn", 5), These.getOrElse(0)); // 5
-     * pipe(These.toErr("err"), These.getOrElse(0));      // 0
+     * pipe(These.ok(5), These.getOrElse(0));           // 5
+     * pipe(These.both("warn", 5), These.getOrElse(0)); // 5
+     * pipe(These.err("err"), These.getOrElse(0));      // 0
      * ```
      */
     These.getOrElse = (defaultValue) => (data) => These.hasValue(data) ? data.value : defaultValue;
@@ -199,17 +199,17 @@ export var These;
      *
      * @example
      * ```ts
-     * These.swap(These.toErr("err"));        // Ok("err")
-     * These.swap(These.toOk(5));             // Err(5)
-     * These.swap(These.toBoth("warn", 5));   // Both(5, "warn")
+     * These.swap(These.err("err"));        // Ok("err")
+     * These.swap(These.ok(5));             // Err(5)
+     * These.swap(These.both("warn", 5));   // Both(5, "warn")
      * ```
      */
     These.swap = (data) => {
         if (These.isErr(data))
-            return These.toOk(data.error);
+            return These.ok(data.error);
         if (These.isOk(data))
-            return These.toErr(data.value);
-        return These.toBoth(data.value, data.error);
+            return These.err(data.value);
+        return These.both(data.value, data.error);
     };
     /**
      * Converts a These to an Option.
@@ -217,9 +217,9 @@ export var These;
      *
      * @example
      * ```ts
-     * These.toOption(These.toOk(42));          // Some(42)
-     * These.toOption(These.toBoth("warn", 42)); // Some(42)
-     * These.toOption(These.toErr("err"));       // None
+     * These.toOption(These.ok(42));          // Some(42)
+     * These.toOption(These.both("warn", 42)); // Some(42)
+     * These.toOption(These.err("err"));       // None
      * ```
      */
     These.toOption = (data) => These.hasValue(data) ? { kind: "Some", value: data.value } : { kind: "None" };
@@ -229,14 +229,14 @@ export var These;
      *
      * @example
      * ```ts
-     * These.toResult(These.toOk(42));           // Ok(42)
-     * These.toResult(These.toBoth("warn", 42)); // Ok(42)
-     * These.toResult(These.toErr("err"));       // Err("err")
+     * These.toResult(These.ok(42));           // Ok(42)
+     * These.toResult(These.both("warn", 42)); // Ok(42)
+     * These.toResult(These.err("err"));       // Err("err")
      * ```
      */
     These.toResult = (data) => {
         if (These.hasValue(data))
-            return Result.toOk(data.value);
+            return Result.ok(data.value);
         return data;
     };
 })(These || (These = {}));

package/esm/src/Types/Brand.js

@@ -1,19 +1,19 @@
 export var Brand;
 (function (Brand) {
     /**
-     * Creates a branding constructor for brand K over type T.
+     * 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.make<"PositiveNumber", number>();
+     * const toPositiveNumber = Brand.wrap<"PositiveNumber", number>();
      *
      * const n: PositiveNumber = toPositiveNumber(42);
      * ```
      */
-    Brand.make = () => (value) => value;
+    Brand.wrap = () => (value) => value;
     /**
      * Strips the brand and returns the underlying value.
      * Since Brand<K, T> extends T this is rarely needed, but can improve readability.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nlozgachev/pipekit",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "description": "Simple functional programming toolkit for TypeScript",
   "keywords": [
     "functional",
@@ -9,6 +9,7 @@
     "composition",
     "pipe"
   ],
+  "homepage": "https://pipekit.lozgachev.dev",
   "repository": {
     "type": "git",
     "url": "https://github.com/nlozgachev/pipekit"

package/script/src/Core/Arr.js

@@ -31,7 +31,7 @@ var Arr;
      * Arr.head([]); // None
      * ```
      */
-    Arr.head = (data) => data.length > 0 ? Option_js_1.Option.toSome(data[0]) : Option_js_1.Option.toNone();
+    Arr.head = (data) => data.length > 0 ? Option_js_1.Option.some(data[0]) : Option_js_1.Option.none();
     /**
      * Returns the last element of an array, or None if the array is empty.
      *
@@ -41,7 +41,7 @@ var Arr;
      * Arr.last([]); // None
      * ```
      */
-    Arr.last = (data) => data.length > 0 ? Option_js_1.Option.toSome(data[data.length - 1]) : Option_js_1.Option.toNone();
+    Arr.last = (data) => data.length > 0 ? Option_js_1.Option.some(data[data.length - 1]) : Option_js_1.Option.none();
     /**
      * Returns all elements except the first, or None if the array is empty.
      *
@@ -51,7 +51,7 @@ var Arr;
      * Arr.tail([]); // None
      * ```
      */
-    Arr.tail = (data) => data.length > 0 ? Option_js_1.Option.toSome(data.slice(1)) : Option_js_1.Option.toNone();
+    Arr.tail = (data) => data.length > 0 ? Option_js_1.Option.some(data.slice(1)) : Option_js_1.Option.none();
     /**
      * Returns all elements except the last, or None if the array is empty.
      *
@@ -61,7 +61,7 @@ var Arr;
      * Arr.init([]); // None
      * ```
      */
-    Arr.init = (data) => data.length > 0 ? Option_js_1.Option.toSome(data.slice(0, -1)) : Option_js_1.Option.toNone();
+    Arr.init = (data) => data.length > 0 ? Option_js_1.Option.some(data.slice(0, -1)) : Option_js_1.Option.none();
     // --- Search ---
     /**
      * Returns the first element matching the predicate, or None.
@@ -73,7 +73,7 @@ var Arr;
      */
     Arr.findFirst = (predicate) => (data) => {
         const idx = data.findIndex(predicate);
-        return idx >= 0 ? Option_js_1.Option.toSome(data[idx]) : Option_js_1.Option.toNone();
+        return idx >= 0 ? Option_js_1.Option.some(data[idx]) : Option_js_1.Option.none();
     };
     /**
      * Returns the last element matching the predicate, or None.
@@ -86,9 +86,9 @@ var Arr;
     Arr.findLast = (predicate) => (data) => {
         for (let i = data.length - 1; i >= 0; i--) {
             if (predicate(data[i]))
-                return Option_js_1.Option.toSome(data[i]);
+                return Option_js_1.Option.some(data[i]);
         }
-        return Option_js_1.Option.toNone();
+        return Option_js_1.Option.none();
     };
     /**
      * Returns the index of the first element matching the predicate, or None.
@@ -100,7 +100,7 @@ var Arr;
      */
     Arr.findIndex = (predicate) => (data) => {
         const idx = data.findIndex(predicate);
-        return idx >= 0 ? Option_js_1.Option.toSome(idx) : Option_js_1.Option.toNone();
+        return idx >= 0 ? Option_js_1.Option.some(idx) : Option_js_1.Option.none();
     };
     // --- Transform ---
     /**
@@ -306,7 +306,7 @@ var Arr;
      * ```ts
      * const parseNum = (s: string): Option<number> => {
      *   const n = Number(s);
-     *   return isNaN(n) ? Option.toNone() : Option.of(n);
+     *   return isNaN(n) ? Option.none() : Option.of(n);
      * };
      *
      * pipe(["1", "2", "3"], Arr.traverse(parseNum)); // Some([1, 2, 3])
@@ -318,10 +318,10 @@ var Arr;
         for (const a of data) {
             const mapped = f(a);
             if (Option_js_1.Option.isNone(mapped))
-                return Option_js_1.Option.toNone();
+                return Option_js_1.Option.none();
             result.push(mapped.value);
         }
-        return Option_js_1.Option.toSome(result);
+        return Option_js_1.Option.some(result);
     };
     /**
      * Maps each element to a Result and collects the results.
@@ -331,7 +331,7 @@ var Arr;
      * ```ts
      * pipe(
      *   [1, 2, 3],
-     *   Arr.traverseResult(n => n > 0 ? Result.toOk(n) : Result.toErr("negative"))
+     *   Arr.traverseResult(n => n > 0 ? Result.ok(n) : Result.err("negative"))
      * ); // Ok([1, 2, 3])
      * ```
      */
@@ -343,7 +343,7 @@ var Arr;
                 return mapped;
             result.push(mapped.value);
         }
-        return Result_js_1.Result.toOk(result);
+        return Result_js_1.Result.ok(result);
     };
     /**
      * Maps each element to a Task and runs all in parallel.
@@ -364,7 +364,7 @@ var Arr;
      * @example
      * ```ts
      * Arr.sequence([Option.of(1), Option.of(2)]); // Some([1, 2])
-     * Arr.sequence([Option.of(1), Option.toNone()]); // None
+     * Arr.sequence([Option.of(1), Option.none()]); // None
      * ```
      */
     Arr.sequence = (data) => Arr.traverse((a) => a)(data);