@nlozgachev/pipelined 0.9.0 → 0.11.0

package/README.md

@@ -17,8 +17,6 @@ state flag soup, you get types that name every possible state and make invalid o
 Each type comes with a consistent set of operations — `map`, `chain`, `match`, `getOrElse` — that
 compose with `pipe` and `flow`.
 
-No FP jargon required. You won't find `Monad`, `Functor`, or `Applicative` in the API.
-
 ## What's included?
 
 ### pipelined/core
@@ -39,8 +37,16 @@ No FP jargon required. You won't find `Monad`, `Functor`, or `Applicative` in th
 - **`Optional<S, A>`** — like `Lens`, but the target may be absent (nullable fields, array indices).
 - **`Reader<R, A>`** — a computation that depends on an environment `R`, supplied once at the
   boundary.
+
+
+### pipelined/utils
+
+Everyday utilities for built-in JS types.
+
 - **`Arr`** — array utilities, data-last, returning `Option` instead of `undefined`.
-- **`Rec`** — record utilities, data-last, with `Option`-returning key lookup.
+- **`Rec`** — record/object utilities, data-last, with `Option`-returning key lookup.
+- **`Num`** — number utilities: `range`, `clamp`, `between`, safe `parse`, and curried arithmetic.
+- **`Str`** — string utilities: `split`, `trim`, `words`, `lines`, and safe `parse.int` / `parse.float`.
 
 ### pipelined/types
 

package/esm/src/Core/Option.js

@@ -1,4 +1,5 @@
 import { Result } from "./Result.js";
+const _none = { kind: "None" };
 export var Option;
 (function (Option) {
     /**
@@ -12,7 +13,7 @@ export var Option;
     /**
      * Creates a None (empty Option).
      */
-    Option.none = () => ({ kind: "None" });
+    Option.none = () => _none;
     /**
      * Type guard that checks if a Option is None.
      */

package/esm/src/Core/Optional.js

@@ -84,12 +84,12 @@ export var Optional;
      *
      * @example
      * ```ts
-     * pipe(profile, Optional.getOrElse(bioOpt)("no bio"));
+     * pipe(profile, Optional.getOrElse(bioOpt)(() => "no bio"));
      * ```
      */
     Optional.getOrElse = (opt) => (defaultValue) => (s) => {
         const val = opt.get(s);
-        return val.kind === "Some" ? val.value : defaultValue;
+        return val.kind === "Some" ? val.value : defaultValue();
     };
     /**
      * Extracts a value from an Optional focus using handlers for the present

package/esm/src/Core/RemoteData.js

@@ -1,15 +1,17 @@
 import { Option } from "./Option.js";
 import { Result } from "./Result.js";
+const _notAsked = { kind: "NotAsked" };
+const _loading = { kind: "Loading" };
 export var RemoteData;
 (function (RemoteData) {
     /**
      * Creates a NotAsked RemoteData.
      */
-    RemoteData.notAsked = () => ({ kind: "NotAsked" });
+    RemoteData.notAsked = () => _notAsked;
     /**
      * Creates a Loading RemoteData.
      */
-    RemoteData.loading = () => ({ kind: "Loading" });
+    RemoteData.loading = () => _loading;
     /**
      * Creates a Failure RemoteData with the given error.
      */
@@ -159,9 +161,9 @@ export var RemoteData;
      *
      * @example
      * ```ts
-     * pipe(RemoteData.success(5), RemoteData.getOrElse(0)); // 5
-     * pipe(RemoteData.loading(), RemoteData.getOrElse(0)); // 0
-     * pipe(RemoteData.loading<string, number>(), RemoteData.getOrElse(null)); // null — typed as number | null
+     * pipe(RemoteData.success(5), RemoteData.getOrElse(() => 0)); // 5
+     * pipe(RemoteData.loading(), RemoteData.getOrElse(() => 0)); // 0
+     * pipe(RemoteData.loading<string, number>(), RemoteData.getOrElse(() => null)); // null — typed as number | null
      * ```
      */
     RemoteData.getOrElse = (defaultValue) => (data) => RemoteData.isSuccess(data) ? data.value : defaultValue();
@@ -205,7 +207,5 @@ export var RemoteData;
      * ); // Ok(42)
      * ```
      */
-    RemoteData.toResult = (onNotReady) => (data) => RemoteData.isSuccess(data)
-        ? Result.ok(data.value)
-        : Result.err(RemoteData.isFailure(data) ? data.error : onNotReady());
+    RemoteData.toResult = (onNotReady) => (data) => RemoteData.isSuccess(data) ? Result.ok(data.value) : Result.err(RemoteData.isFailure(data) ? data.error : onNotReady());
 })(RemoteData || (RemoteData = {}));

package/esm/src/Core/TaskValidation.js

@@ -39,15 +39,6 @@ export var TaskValidation;
      * Transforms the success value inside a TaskValidation.
      */
     TaskValidation.map = (f) => (data) => Task.map(Validation.map(f))(data);
-    /**
-     * Chains TaskValidation computations. If the first is Valid, passes the value
-     * to f. If the first is Invalid, propagates the errors.
-     *
-     * Note: chain short-circuits on first error. Use ap to accumulate errors.
-     */
-    TaskValidation.chain = (f) => (data) => Task.chain((validation) => Validation.isValid(validation)
-        ? f(validation.value)
-        : Task.resolve(Validation.invalidAll(validation.errors)))(data);
     /**
      * Applies a function wrapped in a TaskValidation to a value wrapped in a
      * TaskValidation. Both Tasks run in parallel and errors from both sides
@@ -97,9 +88,41 @@ export var TaskValidation;
     TaskValidation.tap = (f) => (data) => Task.map(Validation.tap(f))(data);
     /**
      * Recovers from an Invalid state by providing a fallback TaskValidation.
+     * The fallback receives the accumulated error list so callers can inspect which errors occurred.
      * The fallback can produce a different success type, widening the result to `TaskValidation<E, A | B>`.
      */
-    TaskValidation.recover = (fallback) => (data) => Task.chain((validation) => Validation.isValid(validation)
-        ? Task.resolve(validation)
-        : fallback())(data);
+    TaskValidation.recover = (fallback) => (data) => Task.chain((validation) => Validation.isValid(validation) ? Task.resolve(validation) : fallback(validation.errors))(data);
+    /**
+     * Runs two TaskValidations concurrently and combines their results into a tuple.
+     * If both are Valid, returns Valid with both values. If either fails, accumulates
+     * errors from both sides.
+     *
+     * @example
+     * ```ts
+     * await TaskValidation.product(
+     *   validateName(form.name),
+     *   validateAge(form.age),
+     * )(); // Valid(["Alice", 30]) or Invalid([...errors])
+     * ```
+     */
+    TaskValidation.product = (first, second) => Task.from(() => Promise.all([
+        Deferred.toPromise(first()),
+        Deferred.toPromise(second()),
+    ]).then(([va, vb]) => Validation.product(va, vb)));
+    /**
+     * Runs all TaskValidations concurrently and collects results.
+     * If all are Valid, returns Valid with all values as an array.
+     * If any fail, returns Invalid with all accumulated errors.
+     *
+     * @example
+     * ```ts
+     * await TaskValidation.productAll([
+     *   validateName(form.name),
+     *   validateEmail(form.email),
+     *   validateAge(form.age),
+     * ])(); // Valid([name, email, age]) or Invalid([...all errors])
+     * ```
+     */
+    TaskValidation.productAll = (data) => Task.from(() => Promise.all(data.map((t) => Deferred.toPromise(t())))
+        .then((results) => Validation.productAll(results)));
 })(TaskValidation || (TaskValidation = {}));

package/esm/src/Core/Validation.js

@@ -119,9 +119,9 @@ export var Validation;
      *
      * @example
      * ```ts
-     * pipe(Validation.valid(5), Validation.getOrElse(0)); // 5
-     * pipe(Validation.invalid("oops"), Validation.getOrElse(0)); // 0
-     * pipe(Validation.invalid("oops"), Validation.getOrElse(null)); // null — typed as number | null
+     * pipe(Validation.valid(5), Validation.getOrElse(() => 0)); // 5
+     * pipe(Validation.invalid("oops"), Validation.getOrElse(() => 0)); // 0
+     * pipe(Validation.invalid("oops"), Validation.getOrElse(() => null)); // null — typed as number | null
      * ```
      */
     Validation.getOrElse = (defaultValue) => (data) => Validation.isValid(data) ? data.value : defaultValue();

package/esm/src/Core/index.js

@@ -1,11 +1,9 @@
-export * from "./Arr.js";
 export * from "./Logged.js";
 export * from "./Deferred.js";
 export * from "./Lens.js";
 export * from "./Option.js";
 export * from "./Reader.js";
 export * from "./Optional.js";
-export * from "./Rec.js";
 export * from "./Predicate.js";
 export * from "./Refinement.js";
 export * from "./RemoteData.js";

package/esm/src/{Core → Utils}/Arr.js

@@ -1,7 +1,7 @@
-import { Deferred } from "./Deferred.js";
-import { Option } from "./Option.js";
-import { Result } from "./Result.js";
-import { Task } from "./Task.js";
+import { Deferred } from "../Core/Deferred.js";
+import { Option } from "../Core/Option.js";
+import { Result } from "../Core/Result.js";
+import { Task } from "../Core/Task.js";
 import { isNonEmptyList } from "../Types/NonEmptyList.js";
 /**
  * Functional array utilities that compose well with pipe.
@@ -110,7 +110,13 @@ export var Arr;
      * pipe([1, 2, 3], Arr.map(n => n * 2)); // [2, 4, 6]
      * ```
      */
-    Arr.map = (f) => (data) => data.map(f);
+    Arr.map = (f) => (data) => {
+        const n = data.length;
+        const result = new Array(n);
+        for (let i = 0; i < n; i++)
+            result[i] = f(data[i]);
+        return result;
+    };
     /**
      * Filters elements that satisfy the predicate.
      *
@@ -119,7 +125,15 @@ export var Arr;
      * pipe([1, 2, 3, 4], Arr.filter(n => n % 2 === 0)); // [2, 4]
      * ```
      */
-    Arr.filter = (predicate) => (data) => data.filter(predicate);
+    Arr.filter = (predicate) => (data) => {
+        const n = data.length;
+        const result = [];
+        for (let i = 0; i < n; i++) {
+            if (predicate(data[i]))
+                result.push(data[i]);
+        }
+        return result;
+    };
     /**
      * Splits an array into two groups based on a predicate.
      * First group contains elements that satisfy the predicate,
@@ -213,9 +227,9 @@ export var Arr;
      */
     Arr.zip = (other) => (data) => {
         const len = Math.min(data.length, other.length);
-        const result = [];
+        const result = new Array(len);
         for (let i = 0; i < len; i++) {
-            result.push([data[i], other[i]]);
+            result[i] = [data[i], other[i]];
         }
         return result;
     };
@@ -229,9 +243,9 @@ export var Arr;
      */
     Arr.zipWith = (f) => (other) => (data) => {
         const len = Math.min(data.length, other.length);
-        const result = [];
+        const result = new Array(len);
         for (let i = 0; i < len; i++) {
-            result.push(f(data[i], other[i]));
+            result[i] = f(data[i], other[i]);
         }
         return result;
     };
@@ -286,7 +300,17 @@ export var Arr;
      * pipe([1, 2, 3], Arr.flatMap(n => [n, n * 10])); // [1, 10, 2, 20, 3, 30]
      * ```
      */
-    Arr.flatMap = (f) => (data) => [].concat(...data.map(f));
+    Arr.flatMap = (f) => (data) => {
+        const n = data.length;
+        const result = [];
+        for (let i = 0; i < n; i++) {
+            const chunk = f(data[i]);
+            const m = chunk.length;
+            for (let j = 0; j < m; j++)
+                result.push(chunk[j]);
+        }
+        return result;
+    };
     /**
      * Reduces an array from the left.
      *
@@ -313,12 +337,13 @@ export var Arr;
      * ```
      */
     Arr.traverse = (f) => (data) => {
-        const result = [];
-        for (const a of data) {
-            const mapped = f(a);
-            if (Option.isNone(mapped))
+        const n = data.length;
+        const result = new Array(n);
+        for (let i = 0; i < n; i++) {
+            const mapped = f(data[i]);
+            if (mapped.kind === "None")
                 return Option.none();
-            result.push(mapped.value);
+            result[i] = mapped.value;
         }
         return Option.some(result);
     };
@@ -335,12 +360,13 @@ export var Arr;
      * ```
      */
     Arr.traverseResult = (f) => (data) => {
-        const result = [];
-        for (const a of data) {
-            const mapped = f(a);
-            if (Result.isErr(mapped))
+        const n = data.length;
+        const result = new Array(n);
+        for (let i = 0; i < n; i++) {
+            const mapped = f(data[i]);
+            if (mapped.kind === "Error")
                 return mapped;
-            result.push(mapped.value);
+            result[i] = mapped.value;
         }
         return Result.ok(result);
     };
@@ -427,7 +453,13 @@ export var Arr;
      * pipe([1, 2, 3], Arr.some(n => n > 2)); // true
      * ```
      */
-    Arr.some = (predicate) => (data) => data.some(predicate);
+    Arr.some = (predicate) => (data) => {
+        const n = data.length;
+        for (let i = 0; i < n; i++)
+            if (predicate(data[i]))
+                return true;
+        return false;
+    };
     /**
      * Returns true if all elements satisfy the predicate.
      *
@@ -436,7 +468,13 @@ export var Arr;
      * pipe([1, 2, 3], Arr.every(n => n > 0)); // true
      * ```
      */
-    Arr.every = (predicate) => (data) => data.every(predicate);
+    Arr.every = (predicate) => (data) => {
+        const n = data.length;
+        for (let i = 0; i < n; i++)
+            if (!predicate(data[i]))
+                return false;
+        return true;
+    };
     /**
      * Reverses an array. Returns a new array.
      *
@@ -495,4 +533,38 @@ export var Arr;
             i++;
         return data.slice(i);
     };
+    /**
+     * Like `reduce`, but returns every intermediate accumulator as an array.
+     * The initial value is not included — the output has the same length as the input.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3], Arr.scan(0, (acc, n) => acc + n)); // [1, 3, 6]
+     * ```
+     */
+    Arr.scan = (initial, f) => (data) => {
+        const n = data.length;
+        const result = new Array(n);
+        let acc = initial;
+        for (let i = 0; i < n; i++) {
+            acc = f(acc, data[i]);
+            result[i] = acc;
+        }
+        return result;
+    };
+    /**
+     * Splits an array at an index into a `[before, after]` tuple.
+     * Negative indices clamp to 0; indices beyond the array length clamp to the end.
+     *
+     * @example
+     * ```ts
+     * pipe([1, 2, 3, 4], Arr.splitAt(2)); // [[1, 2], [3, 4]]
+     * pipe([1, 2, 3], Arr.splitAt(0));    // [[], [1, 2, 3]]
+     * pipe([1, 2, 3], Arr.splitAt(10));   // [[1, 2, 3], []]
+     * ```
+     */
+    Arr.splitAt = (index) => (data) => {
+        const i = Math.max(0, index);
+        return [data.slice(0, i), data.slice(i)];
+    };
 })(Arr || (Arr = {}));

package/esm/src/Utils/Num.js

@@ -0,0 +1,124 @@
+import { Option } from "../Core/Option.js";
+/**
+ * Number utilities for common operations. All transformation functions are data-last
+ * and curried so they compose naturally with `pipe` and `Arr.map`.
+ *
+ * @example
+ * ```ts
+ * import { Num } from "@nlozgachev/pipelined/utils";
+ * import { pipe } from "@nlozgachev/pipelined/composition";
+ *
+ * pipe(
+ *   Num.range(1, 6),
+ *   Arr.map(Num.multiply(2)),
+ *   Arr.filter(Num.between(4, 8))
+ * ); // [4, 6, 8]
+ * ```
+ */
+export var Num;
+(function (Num) {
+    /**
+     * 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`,
+     * returns an empty array. When `step` does not land exactly on `to`, the last value
+     * is the largest reachable value that does not exceed `to`.
+     *
+     * @example
+     * ```ts
+     * Num.range(0, 5);       // [0, 1, 2, 3, 4, 5]
+     * Num.range(0, 10, 2);   // [0, 2, 4, 6, 8, 10]
+     * Num.range(0, 9, 2);    // [0, 2, 4, 6, 8]
+     * Num.range(5, 0);       // []
+     * Num.range(3, 3);       // [3]
+     * ```
+     */
+    Num.range = (from, to, step = 1) => {
+        if (step <= 0 || from > to)
+            return [];
+        const count = Math.floor((to - from) / step) + 1;
+        const result = new Array(count);
+        for (let i = 0; i < count; i++) {
+            result[i] = from + i * step;
+        }
+        return result;
+    };
+    /**
+     * Clamps a number between `min` and `max` (both inclusive).
+     *
+     * @example
+     * ```ts
+     * pipe(150, Num.clamp(0, 100)); // 100
+     * pipe(-5, Num.clamp(0, 100));  // 0
+     * pipe(42, Num.clamp(0, 100));  // 42
+     * ```
+     */
+    Num.clamp = (min, max) => (n) => Math.min(Math.max(n, min), max);
+    /**
+     * Returns `true` when the number is between `min` and `max` (both inclusive).
+     *
+     * @example
+     * ```ts
+     * pipe(5, Num.between(1, 10));  // true
+     * pipe(0, Num.between(1, 10));  // false
+     * pipe(10, Num.between(1, 10)); // true
+     * ```
+     */
+    Num.between = (min, max) => (n) => n >= min && n <= max;
+    /**
+     * Parses a string as a number. Returns `None` when the result is `NaN`.
+     *
+     * @example
+     * ```ts
+     * Num.parse("42");   // Some(42)
+     * Num.parse("3.14"); // Some(3.14)
+     * Num.parse("abc");  // None
+     * Num.parse("");     // None
+     * ```
+     */
+    Num.parse = (s) => {
+        if (s.trim() === "")
+            return Option.none();
+        const n = Number(s);
+        return isNaN(n) ? Option.none() : Option.some(n);
+    };
+    /**
+     * Adds `b` to a number. Data-last: use in `pipe` or `Arr.map`.
+     *
+     * @example
+     * ```ts
+     * pipe(5, Num.add(3));                   // 8
+     * pipe([1, 2, 3], Arr.map(Num.add(10))); // [11, 12, 13]
+     * ```
+     */
+    Num.add = (b) => (a) => a + b;
+    /**
+     * Subtracts `b` from a number. Data-last: `subtract(b)(a)` = `a - b`.
+     *
+     * @example
+     * ```ts
+     * pipe(10, Num.subtract(3));                  // 7
+     * pipe([5, 10, 15], Arr.map(Num.subtract(2))); // [3, 8, 13]
+     * ```
+     */
+    Num.subtract = (b) => (a) => a - b;
+    /**
+     * Multiplies a number by `b`. Data-last: use in `pipe` or `Arr.map`.
+     *
+     * @example
+     * ```ts
+     * pipe(6, Num.multiply(7));                    // 42
+     * pipe([1, 2, 3], Arr.map(Num.multiply(100))); // [100, 200, 300]
+     * ```
+     */
+    Num.multiply = (b) => (a) => a * b;
+    /**
+     * Divides a number by `b`. Data-last: `divide(b)(a)` = `a / b`.
+     *
+     * @example
+     * ```ts
+     * pipe(20, Num.divide(4));                      // 5
+     * pipe([10, 20, 30], Arr.map(Num.divide(10)));  // [1, 2, 3]
+     * ```
+     */
+    Num.divide = (b) => (a) => a / b;
+})(Num || (Num = {}));

package/esm/src/{Core → Utils}/Rec.js

@@ -1,4 +1,4 @@
-import { Option } from "./Option.js";
+import { Option } from "../Core/Option.js";
 /**
  * Functional record/object utilities that compose well with pipe.
  * All functions are data-last and curried where applicable.
@@ -23,9 +23,11 @@ export var Rec;
      * ```
      */
     Rec.map = (f) => (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
         const result = {};
-        for (const key of Object.keys(data)) {
-            result[key] = f(data[key]);
+        for (let i = 0; i < keys.length; i++) {
+            result[keys[i]] = f(vals[i]);
         }
         return result;
     };
@@ -39,9 +41,11 @@ export var Rec;
      * ```
      */
     Rec.mapWithKey = (f) => (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
         const result = {};
-        for (const key of Object.keys(data)) {
-            result[key] = f(key, data[key]);
+        for (let i = 0; i < keys.length; i++) {
+            result[keys[i]] = f(keys[i], vals[i]);
         }
         return result;
     };
@@ -54,10 +58,12 @@ export var Rec;
      * ```
      */
     Rec.filter = (predicate) => (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
         const result = {};
-        for (const key of Object.keys(data)) {
-            if (predicate(data[key]))
-                result[key] = data[key];
+        for (let i = 0; i < keys.length; i++) {
+            if (predicate(vals[i]))
+                result[keys[i]] = vals[i];
         }
         return result;
     };
@@ -71,10 +77,12 @@ export var Rec;
      * ```
      */
     Rec.filterWithKey = (predicate) => (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
         const result = {};
-        for (const key of Object.keys(data)) {
-            if (predicate(key, data[key]))
-                result[key] = data[key];
+        for (let i = 0; i < keys.length; i++) {
+            if (predicate(keys[i], vals[i]))
+                result[keys[i]] = vals[i];
         }
         return result;
     };
@@ -164,4 +172,44 @@ export var Rec;
      * Returns the number of keys in a record.
      */
     Rec.size = (data) => Object.keys(data).length;
+    /**
+     * Transforms each key while preserving values.
+     * If two keys map to the same new key, the last one wins.
+     *
+     * @example
+     * ```ts
+     * pipe({ firstName: "Alice", lastName: "Smith" }, Rec.mapKeys(k => k.toUpperCase()));
+     * // { FIRSTNAME: "Alice", LASTNAME: "Smith" }
+     * ```
+     */
+    Rec.mapKeys = (f) => (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
+        const result = {};
+        for (let i = 0; i < keys.length; i++) {
+            result[f(keys[i])] = vals[i];
+        }
+        return result;
+    };
+    /**
+     * Removes all `None` values from a `Record<string, Option<A>>`, returning a plain `Record<string, A>`.
+     * Useful when building records from fallible lookups.
+     *
+     * @example
+     * ```ts
+     * Rec.compact({ a: Option.some(1), b: Option.none(), c: Option.some(3) });
+     * // { a: 1, c: 3 }
+     * ```
+     */
+    Rec.compact = (data) => {
+        const keys = Object.keys(data);
+        const vals = Object.values(data);
+        const result = {};
+        for (let i = 0; i < keys.length; i++) {
+            const v = vals[i];
+            if (v.kind === "Some")
+                result[keys[i]] = v.value;
+        }
+        return result;
+    };
 })(Rec || (Rec = {}));