@nlozgachev/pipelined 0.6.4 → 0.7.0

package/esm/src/Core/TaskValidation.js

@@ -87,6 +87,7 @@ export var TaskValidation;
     TaskValidation.match = (cases) => (data) => Task.map(Validation.match(cases))(data);
     /**
      * Returns the success value or a default value if the TaskValidation is invalid.
+     * The default can be a different type, widening the result to `Task<A | B>`.
      */
     TaskValidation.getOrElse = (defaultValue) => (data) => Task.map(Validation.getOrElse(defaultValue))(data);
     /**
@@ -96,6 +97,9 @@ 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 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())(data);
 })(TaskValidation || (TaskValidation = {}));

package/esm/src/Core/These.js

@@ -184,23 +184,27 @@ export var These;
     };
     /**
      * Returns the first value, or a default if the These has no first value.
+     * The default can be a different type, widening the result to `A | C`.
      *
      * @example
      * ```ts
      * pipe(These.first(5), These.getFirstOrElse(0));            // 5
      * pipe(These.both(5, "warn"), These.getFirstOrElse(0));     // 5
      * pipe(These.second("warn"), These.getFirstOrElse(0));      // 0
+     * pipe(These.second("warn"), These.getFirstOrElse(null));   // null — typed as number | null
      * ```
      */
     These.getFirstOrElse = (defaultValue) => (data) => These.hasFirst(data) ? data.first : defaultValue;
     /**
      * Returns the second value, or a default if the These has no second value.
+     * The default can be a different type, widening the result to `B | D`.
      *
      * @example
      * ```ts
      * pipe(These.second("warn"), These.getSecondOrElse("none")); // "warn"
      * pipe(These.both(5, "warn"), These.getSecondOrElse("none")); // "warn"
      * pipe(These.first(5), These.getSecondOrElse("none"));       // "none"
+     * pipe(These.first(5), These.getSecondOrElse(null));         // null — typed as string | null
      * ```
      */
     These.getSecondOrElse = (defaultValue) => (data) => These.hasSecond(data) ? data.second : defaultValue;

package/esm/src/Core/Validation.js

@@ -132,11 +132,13 @@ export var Validation;
     Validation.match = (cases) => (data) => Validation.isValid(data) ? cases.valid(data.value) : cases.invalid(data.errors);
     /**
      * Returns the success value or a default value if the Validation is invalid.
+     * The default can be a different type, widening the result to `A | B`.
      *
      * @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
      * ```
      */
     Validation.getOrElse = (defaultValue) => (data) => Validation.isValid(data) ? data.value : defaultValue;
@@ -159,10 +161,12 @@ export var Validation;
     };
     /**
      * Recovers from an Invalid state by providing a fallback Validation.
+     * The fallback can produce a different success type, widening the result to `Validation<E, A | B>`.
      */
     Validation.recover = (fallback) => (data) => Validation.isValid(data) ? data : fallback();
     /**
      * Recovers from an Invalid state unless the errors contain any of the blocked errors.
+     * The fallback can produce a different success type, widening the result to `Validation<E, A | B>`.
      */
     Validation.recoverUnless = (blockedErrors, fallback) => (data) => Validation.isInvalid(data) &&
         !data.errors.some((err) => blockedErrors.includes(err))

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.4",
+  "version": "0.7.0",
   "description": "Simple functional programming toolkit for TypeScript",
   "keywords": [
     "functional",

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.of<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.of<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.of<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.of<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

@@ -130,12 +130,14 @@ var Option;
      */
     Option.match = (cases) => (data) => Option.isSome(data) ? cases.some(data.value) : cases.none();
     /**
-     * Returns the value inside a Option, or a default value if None.
+     * Returns the value inside an Option, or a default value if 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
      * ```
      */
     Option.getOrElse = (defaultValue) => (data) => Option.isSome(data) ? data.value : defaultValue;
@@ -170,6 +172,7 @@ var Option;
     Option.filter = (predicate) => (data) => Option.isSome(data) && predicate(data.value) ? data : Option.none();
     /**
      * Recovers from a None by providing a fallback Option.
+     * The fallback can produce a different type, widening the result to `Option<A | B>`.
      */
     Option.recover = (fallback) => (data) => Option.isSome(data) ? data : fallback();
     /**

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 = {}));

package/script/src/Core/Refinement.js

@@ -0,0 +1,118 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Refinement = void 0;
+const Option_js_1 = require("./Option.js");
+const Result_js_1 = require("./Result.js");
+var Refinement;
+(function (Refinement) {
+    /**
+     * Creates a `Refinement<A, B>` from a plain boolean predicate.
+     *
+     * This is an unsafe cast — the caller is responsible for ensuring that the
+     * predicate truly characterises values of type `B`. Use this only when
+     * bootstrapping a new refinement; prefer `compose`, `and`, or `or` to build
+     * derived refinements from existing ones.
+     *
+     * @example
+     * ```ts
+     * type PositiveNumber = number & { readonly _tag: "PositiveNumber" };
+     *
+     * const isPositive: Refinement<number, PositiveNumber> =
+     *   Refinement.make(n => n > 0);
+     * ```
+     */
+    Refinement.make = (f) => f;
+    /**
+     * Chains two refinements: if `ab` narrows `A` to `B` and `bc` narrows `B` to `C`,
+     * the result narrows `A` directly to `C`.
+     *
+     * Data-last — the first refinement `ab` is the data being piped.
+     *
+     * @example
+     * ```ts
+     * type NonEmptyString = string & { readonly _tag: "NonEmpty" };
+     * type TrimmedString  = NonEmptyString & { readonly _tag: "Trimmed" };
+     *
+     * const isNonEmpty: Refinement<string, NonEmptyString> =
+     *   Refinement.make(s => s.length > 0);
+     * const isTrimmed: Refinement<NonEmptyString, TrimmedString> =
+     *   Refinement.make(s => s === s.trim());
+     *
+     * const isNonEmptyTrimmed: Refinement<string, TrimmedString> = pipe(
+     *   isNonEmpty,
+     *   Refinement.compose(isTrimmed)
+     * );
+     * ```
+     */
+    Refinement.compose = (bc) => (ab) => (a) => ab(a) && bc(a);
+    /**
+     * Intersects two refinements: the result narrows `A` to `B & C`, passing only
+     * when both refinements hold simultaneously.
+     *
+     * Data-last — the first refinement is the data being piped.
+     *
+     * @example
+     * ```ts
+     * const isString: Refinement<unknown, string> = Refinement.make(x => typeof x === "string");
+     * const isNonEmpty: Refinement<unknown, { length: number }> =
+     *   Refinement.make(x => (x as any).length > 0);
+     *
+     * const isNonEmptyString = pipe(isString, Refinement.and(isNonEmpty));
+     * isNonEmptyString("hi");  // true
+     * isNonEmptyString("");    // false
+     * ```
+     */
+    Refinement.and = (second) => (first) => (a) => first(a) && second(a);
+    /**
+     * Unions two refinements: the result narrows `A` to `B | C`, passing when either
+     * refinement holds.
+     *
+     * Data-last — the first refinement is the data being piped.
+     *
+     * @example
+     * ```ts
+     * const isString:  Refinement<unknown, string>  = Refinement.make(x => typeof x === "string");
+     * const isNumber:  Refinement<unknown, number>  = Refinement.make(x => typeof x === "number");
+     *
+     * const isStringOrNumber = pipe(isString, Refinement.or(isNumber));
+     * isStringOrNumber("hi"); // true
+     * isStringOrNumber(42);   // true
+     * isStringOrNumber(true); // false
+     * ```
+     */
+    Refinement.or = (second) => (first) => (a) => first(a) || second(a);
+    /**
+     * Converts a `Refinement<A, B>` into a function `(a: A) => Option<B>`.
+     *
+     * Returns `Some(a)` when the refinement holds, `None` otherwise. Useful for
+     * integrating runtime validation into an `Option`-based pipeline.
+     *
+     * @example
+     * ```ts
+     * type PositiveNumber = number & { readonly _tag: "Positive" };
+     * const isPositive: Refinement<number, PositiveNumber> =
+     *   Refinement.make(n => n > 0);
+     *
+     * pipe(-1, Refinement.toFilter(isPositive)); // None
+     * pipe(42, Refinement.toFilter(isPositive)); // Some(42)
+     * ```
+     */
+    Refinement.toFilter = (r) => (a) => r(a) ? Option_js_1.Option.some(a) : Option_js_1.Option.none();
+    /**
+     * Converts a `Refinement<A, B>` into a function `(a: A) => Result<E, B>`.
+     *
+     * Returns `Ok(a)` when the refinement holds, `Err(onFail(a))` otherwise. Use
+     * this to surface validation failures as typed errors inside a `Result` pipeline.
+     *
+     * @example
+     * ```ts
+     * type NonEmptyString = string & { readonly _tag: "NonEmpty" };
+     * const isNonEmpty: Refinement<string, NonEmptyString> =
+     *   Refinement.make(s => s.length > 0);
+     *
+     * pipe("", Refinement.toResult(isNonEmpty, () => "must not be empty")); // Err(...)
+     * pipe("hi", Refinement.toResult(isNonEmpty, () => "must not be empty")); // Ok("hi")
+     * ```
+     */
+    Refinement.toResult = (r, onFail) => (a) => r(a) ? Result_js_1.Result.ok(a) : Result_js_1.Result.err(onFail(a));
+})(Refinement || (exports.Refinement = Refinement = {}));

package/script/src/Core/RemoteData.js

@@ -156,11 +156,13 @@ var RemoteData;
     };
     /**
      * Returns the success value or a default value if the RemoteData is not Success.
+     * The default can be a different type, widening the result to `A | B`.
      *
      * @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
      * ```
      */
     RemoteData.getOrElse = (defaultValue) => (data) => RemoteData.isSuccess(data) ? data.value : defaultValue;
@@ -183,6 +185,7 @@ var RemoteData;
     };
     /**
      * Recovers from a Failure state by providing a fallback RemoteData.
+     * The fallback can produce a different success type, widening the result to `RemoteData<E, A | B>`.
      */
     RemoteData.recover = (fallback) => (data) => RemoteData.isFailure(data) ? fallback(data.error) : data;
     /**

package/script/src/Core/Result.js

@@ -105,11 +105,13 @@ var Result;
     Result.match = (cases) => (data) => Result.isOk(data) ? cases.ok(data.value) : cases.err(data.error);
     /**
      * Returns the success value or a default value if the Result is an error.
+     * The default can be a different type, widening the result to `A | B`.
      *
      * @example
      * ```ts
      * pipe(Result.ok(5), Result.getOrElse(0)); // 5
      * pipe(Result.err("error"), Result.getOrElse(0)); // 0
+     * pipe(Result.err("error"), Result.getOrElse(null)); // null — typed as number | null
      * ```
      */
     Result.getOrElse = (defaultValue) => (data) => Result.isOk(data) ? data.value : defaultValue;
@@ -133,10 +135,12 @@ var Result;
     };
     /**
      * Recovers from an error by providing a fallback Result.
+     * The fallback can produce a different success type, widening the result to `Result<E, A | B>`.
      */
     Result.recover = (fallback) => (data) => Result.isOk(data) ? data : fallback();
     /**
      * Recovers from an error unless it matches the blocked error.
+     * The fallback can produce a different success type, widening the result to `Result<E, A | B>`.
      */
     Result.recoverUnless = (blockedErr, fallback) => (data) => Result.isErr(data) && data.error !== blockedErr ? fallback() : data;
     /**