@nlozgachev/pipelined 0.6.5 → 0.8.0

package/esm/src/Core/State.js

@@ -0,0 +1,181 @@
+export var State;
+(function (State) {
+    /**
+     * Lifts a pure value into a State computation. The state passes through unchanged.
+     *
+     * @example
+     * ```ts
+     * State.run(10)(State.resolve(42)); // [42, 10] — value 42, state unchanged
+     * ```
+     */
+    State.resolve = (value) => (s) => [value, s];
+    /**
+     * Produces the current state as the value, without modifying it.
+     *
+     * @example
+     * ```ts
+     * const readStack: State<string[], string[]> = State.get();
+     * State.run(["a", "b"])(readStack); // [["a", "b"], ["a", "b"]]
+     * ```
+     */
+    State.get = () => (s) => [s, s];
+    /**
+     * Reads a projection of the state without modifying it.
+     * Equivalent to `pipe(State.get(), State.map(f))` but more direct.
+     *
+     * @example
+     * ```ts
+     * type AppState = { count: number; label: string };
+     * const readCount: State<AppState, number> = State.gets(s => s.count);
+     * State.run({ count: 5, label: "x" })(readCount); // [5, { count: 5, label: "x" }]
+     * ```
+     */
+    State.gets = (f) => (s) => [f(s), s];
+    /**
+     * Replaces the current state with a new value. Produces no meaningful value.
+     *
+     * @example
+     * ```ts
+     * const reset: State<number, undefined> = State.put(0);
+     * State.run(99)(reset); // [undefined, 0]
+     * ```
+     */
+    State.put = (newState) => (_s) => [undefined, newState];
+    /**
+     * Applies a function to the current state to produce the next state.
+     * Produces no meaningful value.
+     *
+     * @example
+     * ```ts
+     * const push = (item: string): State<string[], undefined> =>
+     *   State.modify(stack => [...stack, item]);
+     *
+     * State.run(["a"])(push("b")); // [undefined, ["a", "b"]]
+     * ```
+     */
+    State.modify = (f) => (s) => [undefined, f(s)];
+    /**
+     * Transforms the value produced by a State computation.
+     * The state transformation is unchanged.
+     *
+     * @example
+     * ```ts
+     * const readLength: State<string[], number> = pipe(
+     *   State.get<string[]>(),
+     *   State.map(stack => stack.length),
+     * );
+     *
+     * State.run(["a", "b", "c"])(readLength); // [3, ["a", "b", "c"]]
+     * ```
+     */
+    State.map = (f) => (st) => (s) => {
+        const [a, s1] = st(s);
+        return [f(a), s1];
+    };
+    /**
+     * Sequences two State computations. The state output of the first is passed
+     * as the state input to the second.
+     *
+     * Data-last — the first computation is the data being piped.
+     *
+     * @example
+     * ```ts
+     * const push = (item: string): State<string[], undefined> =>
+     *   State.modify(stack => [...stack, item]);
+     *
+     * const program = pipe(
+     *   push("a"),
+     *   State.chain(() => push("b")),
+     *   State.chain(() => State.get<string[]>()),
+     * );
+     *
+     * State.evaluate([])(program); // ["a", "b"]
+     * ```
+     */
+    State.chain = (f) => (st) => (s) => {
+        const [a, s1] = st(s);
+        return f(a)(s1);
+    };
+    /**
+     * Applies a function wrapped in a State to a value wrapped in a State.
+     * The function computation runs first; its output state is the input to the
+     * argument computation.
+     *
+     * @example
+     * ```ts
+     * const addCounted = (n: number) => (m: number) => n + m;
+     * const program = pipe(
+     *   State.resolve<number, typeof addCounted>(addCounted),
+     *   State.ap(State.gets((s: number) => s * 2)),
+     *   State.ap(State.gets((s: number) => s)),
+     * );
+     *
+     * State.evaluate(3)(program); // 6 + 3 = 9
+     * ```
+     */
+    State.ap = (arg) => (fn) => (s) => {
+        const [f, s1] = fn(s);
+        const [a, s2] = arg(s1);
+        return [f(a), s2];
+    };
+    /**
+     * Runs a side effect on the produced value without changing the State computation.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   State.get<number>(),
+     *   State.tap(n => console.log("current:", n)),
+     *   State.chain(() => State.modify(n => n + 1)),
+     * );
+     * ```
+     */
+    State.tap = (f) => (st) => (s) => {
+        const [a, s1] = st(s);
+        f(a);
+        return [a, s1];
+    };
+    /**
+     * Runs a State computation with an initial state, returning both the
+     * produced value and the final state as a pair.
+     *
+     * Data-last — the computation is the data being piped.
+     *
+     * @example
+     * ```ts
+     * const program = pipe(
+     *   State.modify<number>(n => n + 1),
+     *   State.chain(() => State.get<number>()),
+     * );
+     *
+     * State.run(0)(program); // [1, 1]
+     * ```
+     */
+    State.run = (initialState) => (st) => st(initialState);
+    /**
+     * Runs a State computation with an initial state, returning only the
+     * produced value (discarding the final state).
+     *
+     * @example
+     * ```ts
+     * State.evaluate([])(pipe(
+     *   State.modify<string[]>(s => [...s, "x"]),
+     *   State.chain(() => State.get<string[]>()),
+     * )); // ["x"]
+     * ```
+     */
+    State.evaluate = (initialState) => (st) => st(initialState)[0];
+    /**
+     * Runs a State computation with an initial state, returning only the
+     * final state (discarding the produced value).
+     *
+     * @example
+     * ```ts
+     * State.execute(0)(pipe(
+     *   State.modify<number>(n => n + 10),
+     *   State.chain(() => State.modify<number>(n => n * 2)),
+     * )); // 20
+     * ```
+     */
+    State.execute = (initialState) => (st) => st(initialState)[1];
+})(State || (State = {}));

package/esm/src/Core/Task.js

@@ -159,6 +159,42 @@ export var Task;
         });
         return run();
     });
+    /**
+     * Resolves with the value of the first Task to complete. All Tasks start
+     * immediately; the rest are abandoned once one resolves.
+     *
+     * @example
+     * ```ts
+     * const fast = Task.from(() => new Promise<string>(r => setTimeout(() => r("fast"), 10)));
+     * const slow = Task.from(() => new Promise<string>(r => setTimeout(() => r("slow"), 200)));
+     *
+     * await Task.race([fast, slow])(); // "fast"
+     * ```
+     */
+    Task.race = (tasks) => Task.from(() => Promise.race(tasks.map(toPromise)));
+    /**
+     * Runs an array of Tasks one at a time in order, collecting all results.
+     * Each Task starts only after the previous one resolves.
+     *
+     * @example
+     * ```ts
+     * let log: number[] = [];
+     * const makeTask = (n: number) => Task.from(() => {
+     *   log.push(n);
+     *   return Promise.resolve(n);
+     * });
+     *
+     * await Task.sequential([makeTask(1), makeTask(2), makeTask(3)])();
+     * // log = [1, 2, 3] — tasks ran in order
+     * ```
+     */
+    Task.sequential = (tasks) => Task.from(async () => {
+        const results = [];
+        for (const task of tasks) {
+            results.push(await toPromise(task));
+        }
+        return results;
+    });
     /**
      * Converts a `Task<A>` into a `Task<Result<E, A>>`, resolving to `Err` if the
      * Task does not complete within the given time.

package/esm/src/Core/Validation.js

@@ -141,7 +141,7 @@ export var Validation;
      * pipe(Validation.invalid("oops"), Validation.getOrElse(null)); // null — typed as number | null
      * ```
      */
-    Validation.getOrElse = (defaultValue) => (data) => Validation.isValid(data) ? data.value : defaultValue;
+    Validation.getOrElse = (defaultValue) => (data) => Validation.isValid(data) ? data.value : defaultValue();
     /**
      * Executes a side effect on the success value without changing the Validation.
      *

package/esm/src/Core/index.js

@@ -1,11 +1,15 @@
 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";
+export * from "./State.js";
 export * from "./Result.js";
 export * from "./Task.js";
 export * from "./TaskOption.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nlozgachev/pipelined",
-  "version": "0.6.5",
+  "version": "0.8.0",
   "description": "Simple functional programming toolkit for TypeScript",
   "keywords": [
     "functional",

package/script/src/Core/Arr.js

@@ -230,7 +230,7 @@ var Arr;
      * pipe([1, 2], Arr.zipWith((a, b) => a + b, ["a", "b"])); // ["1a", "2b"]
      * ```
      */
-    Arr.zipWith = (f, other) => (data) => {
+    Arr.zipWith = (f) => (other) => (data) => {
         const len = Math.min(data.length, other.length);
         const result = [];
         for (let i = 0; i < len; i++) {
@@ -379,6 +379,41 @@ var Arr;
      * Collects an array of Tasks into a Task of array. Runs in parallel.
      */
     Arr.sequenceTask = (data) => Arr.traverseTask((a) => a)(data);
+    /**
+     * 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")>
+     * ```
+     */
+    Arr.traverseTaskResult = (f) => (data) => Task_js_1.Task.from(async () => {
+        const result = [];
+        for (const a of data) {
+            const r = await Deferred_js_1.Deferred.toPromise(f(a)());
+            if (Result_js_1.Result.isErr(r))
+                return r;
+            result.push(r.value);
+        }
+        return Result_js_1.Result.ok(result);
+    });
+    /**
+     * Collects an array of TaskResults into a TaskResult of array.
+     * Returns the first Err if any element is Err, runs sequentially.
+     */
+    Arr.sequenceTaskResult = (data) => Arr.traverseTaskResult((a) => a)(data);
     /**
      * Returns true if the array is non-empty (type guard).
      */

package/script/src/Core/Deferred.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Deferred = void 0;
+const _store = new WeakMap();
 var Deferred;
 (function (Deferred) {
     /**
@@ -13,9 +14,11 @@ var Deferred;
      * const value = await d; // "hello"
      * ```
      */
-    Deferred.fromPromise = (p) => ({
-        then: ((f) => p.then(f)),
-    });
+    Deferred.fromPromise = (p) => {
+        const d = ({ then: ((f) => p.then(f)) });
+        _store.set(d, p);
+        return d;
+    };
     /**
      * Converts a `Deferred` back into a `Promise`.
      *
@@ -25,5 +28,6 @@ var Deferred;
      * // p is Promise<42>
      * ```
      */
-    Deferred.toPromise = (d) => new Promise((resolve) => d.then(resolve));
+    Deferred.toPromise = (d) => _store.get(d) ??
+        new Promise((resolve) => d.then(resolve));
 })(Deferred || (exports.Deferred = Deferred = {}));

package/script/src/Core/Logged.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logged = void 0;
+var Logged;
+(function (Logged) {
+    /**
+     * Wraps a pure value into a `Logged` with an empty log.
+     *
+     * @example
+     * ```ts
+     * Logged.make<string, number>(42); // { value: 42, log: [] }
+     * ```
+     */
+    Logged.make = (value) => ({ value, log: [] });
+    /**
+     * Creates a `Logged` that records a single log entry and produces no
+     * meaningful value. Use this to append to the log inside a `chain`.
+     *
+     * @example
+     * ```ts
+     * Logged.tell("operation completed"); // { value: undefined, log: ["operation completed"] }
+     * ```
+     */
+    Logged.tell = (entry) => ({ value: undefined, log: [entry] });
+    /**
+     * Transforms the value inside a `Logged` without affecting the log.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Logged.make<string, number>(5),
+     *   Logged.map(n => n * 2),
+     * ); // { value: 10, log: [] }
+     * ```
+     */
+    Logged.map = (f) => (data) => ({
+        value: f(data.value),
+        log: data.log,
+    });
+    /**
+     * Sequences two `Logged` computations, concatenating their logs.
+     * The value from the first is passed to `f`; the resulting log entries are
+     * appended after the entries from the first.
+     *
+     * Data-last — the first computation is the data being piped.
+     *
+     * @example
+     * ```ts
+     * const result = pipe(
+     *   Logged.make<string, number>(1),
+     *   Logged.chain(n => pipe(Logged.tell("step"), Logged.map(() => n + 1))),
+     *   Logged.chain(n => pipe(Logged.tell("done"), Logged.map(() => n * 10))),
+     * );
+     *
+     * Logged.run(result); // [20, ["step", "done"]]
+     * ```
+     */
+    Logged.chain = (f) => (data) => {
+        const next = f(data.value);
+        return { value: next.value, log: [...data.log, ...next.log] };
+    };
+    /**
+     * Applies a function wrapped in a `Logged` to a value wrapped in a `Logged`,
+     * concatenating both logs.
+     *
+     * @example
+     * ```ts
+     * const fn: Logged<string, (n: number) => number> = {
+     *   value: n => n * 2,
+     *   log: ["fn-loaded"],
+     * };
+     * const arg: Logged<string, number> = { value: 5, log: ["arg-loaded"] };
+     *
+     * const result = pipe(fn, Logged.ap(arg));
+     * Logged.run(result); // [10, ["fn-loaded", "arg-loaded"]]
+     * ```
+     */
+    Logged.ap = (arg) => (data) => ({
+        value: data.value(arg.value),
+        log: [...data.log, ...arg.log],
+    });
+    /**
+     * Runs a side effect on the value without changing the `Logged`.
+     * Useful for debugging or inspecting intermediate values.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Logged.make<string, number>(42),
+     *   Logged.tap(n => console.log("value:", n)),
+     * );
+     * ```
+     */
+    Logged.tap = (f) => (data) => {
+        f(data.value);
+        return data;
+    };
+    /**
+     * Extracts the value and log as a `readonly [A, ReadonlyArray<W>]` tuple.
+     * Use this at the boundary where you need to consume both.
+     *
+     * @example
+     * ```ts
+     * const result = pipe(
+     *   Logged.make<string, number>(1),
+     *   Logged.chain(n => pipe(Logged.tell("incremented"), Logged.map(() => n + 1))),
+     * );
+     *
+     * const [value, log] = Logged.run(result);
+     * // value = 2, log = ["incremented"]
+     * ```
+     */
+    Logged.run = (data) => [data.value, data.log];
+})(Logged || (exports.Logged = Logged = {}));

package/script/src/Core/Option.js

@@ -131,16 +131,17 @@ var Option;
     Option.match = (cases) => (data) => Option.isSome(data) ? cases.some(data.value) : cases.none();
     /**
      * Returns the value inside an Option, or a default value if None.
+     * The default is a thunk `() => B` — evaluated only when the Option is None.
      * The default can be a different type, widening the result to `A | B`.
      *
      * @example
      * ```ts
-     * pipe(Option.some(5), Option.getOrElse(0)); // 5
-     * pipe(Option.none(), Option.getOrElse(0)); // 0
-     * pipe(Option.none<string>(), Option.getOrElse(null)); // null — typed as string | null
+     * pipe(Option.some(5), Option.getOrElse(() => 0)); // 5
+     * pipe(Option.none(), Option.getOrElse(() => 0)); // 0
+     * pipe(Option.none<string>(), Option.getOrElse(() => null)); // null — typed as string | null
      * ```
      */
-    Option.getOrElse = (defaultValue) => (data) => Option.isSome(data) ? data.value : defaultValue;
+    Option.getOrElse = (defaultValue) => (data) => Option.isSome(data) ? data.value : defaultValue();
     /**
      * Executes a side effect on the value without changing the Option.
      * Useful for logging or debugging.
@@ -169,7 +170,7 @@ var Option;
      * pipe(Option.some(2), Option.filter(n => n > 3)); // None
      * ```
      */
-    Option.filter = (predicate) => (data) => Option.isSome(data) && predicate(data.value) ? data : Option.none();
+    Option.filter = (predicate) => (data) => Option.isSome(data) ? (predicate(data.value) ? data : Option.none()) : data;
     /**
      * Recovers from a None by providing a fallback Option.
      * The fallback can produce a different type, widening the result to `Option<A | B>`.

package/script/src/Core/Predicate.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Predicate = void 0;
+var Predicate;
+(function (Predicate) {
+    /**
+     * Negates a predicate: the result passes exactly when the original fails.
+     *
+     * @example
+     * ```ts
+     * const isBlank: Predicate<string> = s => s.trim().length === 0;
+     * const isNotBlank = Predicate.not(isBlank);
+     *
+     * isNotBlank("hello");  // true
+     * isNotBlank("   ");    // false
+     * ```
+     */
+    Predicate.not = (p) => (a) => !p(a);
+    /**
+     * Combines two predicates with logical AND: passes only when both hold.
+     *
+     * Data-last — the first predicate is the data being piped.
+     *
+     * @example
+     * ```ts
+     * const isPositive: Predicate<number> = n => n > 0;
+     * const isEven: Predicate<number> = n => n % 2 === 0;
+     *
+     * const isPositiveEven: Predicate<number> = pipe(isPositive, Predicate.and(isEven));
+     *
+     * isPositiveEven(4);   // true
+     * isPositiveEven(3);   // false — positive but odd
+     * isPositiveEven(-2);  // false — even but not positive
+     * ```
+     */
+    Predicate.and = (second) => (first) => (a) => first(a) && second(a);
+    /**
+     * Combines two predicates with logical OR: passes when either holds.
+     *
+     * Data-last — the first predicate is the data being piped.
+     *
+     * @example
+     * ```ts
+     * const isChild: Predicate<number> = n => n < 13;
+     * const isSenior: Predicate<number> = n => n >= 65;
+     *
+     * const getsDiscount: Predicate<number> = pipe(isChild, Predicate.or(isSenior));
+     *
+     * getsDiscount(8);   // true
+     * getsDiscount(70);  // true
+     * getsDiscount(30);  // false
+     * ```
+     */
+    Predicate.or = (second) => (first) => (a) => first(a) || second(a);
+    /**
+     * Adapts a `Predicate<A>` to work on a different input type `B` by applying `f`
+     * to extract the relevant `A` from a `B` before running the check.
+     *
+     * Data-last — the predicate is the data being piped; `f` is the extractor.
+     *
+     * @example
+     * ```ts
+     * type User = { name: string; age: number };
+     *
+     * const isAdult: Predicate<number> = n => n >= 18;
+     *
+     * // Lift isAdult to work on Users by extracting the age field
+     * const isAdultUser: Predicate<User> = pipe(
+     *   isAdult,
+     *   Predicate.using((u: User) => u.age)
+     * );
+     *
+     * isAdultUser({ name: "Alice", age: 30 });  // true
+     * isAdultUser({ name: "Bob",   age: 15 });  // false
+     * ```
+     */
+    Predicate.using = (f) => (p) => (b) => p(f(b));
+    /**
+     * Combines an array of predicates with AND: passes only when every predicate holds.
+     * Returns `true` for an empty array (vacuous truth).
+     *
+     * @example
+     * ```ts
+     * const checks: Predicate<string>[] = [
+     *   s => s.length > 0,
+     *   s => s.length <= 100,
+     *   s => !s.includes("<"),
+     * ];
+     *
+     * Predicate.all(checks)("hello");  // true
+     * Predicate.all(checks)("");       // false — too short
+     * Predicate.all(checks)("<b>");    // false — contains "<"
+     * Predicate.all([])("anything");   // true
+     * ```
+     */
+    Predicate.all = (predicates) => (a) => predicates.every((p) => p(a));
+    /**
+     * Combines an array of predicates with OR: passes when at least one holds.
+     * Returns `false` for an empty array.
+     *
+     * @example
+     * ```ts
+     * const acceptedFormats: Predicate<string>[] = [
+     *   s => s.endsWith(".jpg"),
+     *   s => s.endsWith(".png"),
+     *   s => s.endsWith(".webp"),
+     * ];
+     *
+     * Predicate.any(acceptedFormats)("photo.jpg");   // true
+     * Predicate.any(acceptedFormats)("photo.gif");   // false
+     * Predicate.any([])("anything");                 // false
+     * ```
+     */
+    Predicate.any = (predicates) => (a) => predicates.some((p) => p(a));
+    /**
+     * Converts a `Refinement<A, B>` into a `Predicate<A>`, discarding the compile-time
+     * narrowing. Use this when you want to combine a type guard with plain predicates
+     * using `and`, `or`, or `all`.
+     *
+     * @example
+     * ```ts
+     * const isString: Refinement<unknown, string> =
+     *   Refinement.make(x => typeof x === "string");
+     *
+     * const isShortString: Predicate<unknown> = pipe(
+     *   Predicate.fromRefinement(isString),
+     *   Predicate.and(x => (x as string).length < 10)
+     * );
+     *
+     * isShortString("hi");            // true
+     * isShortString("a very long string that exceeds ten characters");  // false
+     * isShortString(42);              // false
+     * ```
+     */
+    Predicate.fromRefinement = (r) => r;
+})(Predicate || (exports.Predicate = Predicate = {}));