@nlozgachev/pipekit 0.3.0 → 0.4.1

package/esm/src/Core/Lens.js

@@ -0,0 +1,98 @@
+export var Lens;
+(function (Lens) {
+    /**
+     * Constructs a Lens from a getter and a setter.
+     *
+     * @example
+     * ```ts
+     * const nameLens = Lens.make(
+     *   (user: User) => user.name,
+     *   (name) => (user) => ({ ...user, name }),
+     * );
+     * ```
+     */
+    Lens.make = (get, set) => ({ get, set });
+    /**
+     * Creates a Lens that focuses on a property of an object.
+     * Call with the structure type first, then the key.
+     *
+     * @example
+     * ```ts
+     * const nameLens = Lens.prop<User>()("name");
+     * ```
+     */
+    Lens.prop = () => (key) => Lens.make((s) => s[key], (a) => (s) => ({ ...s, [key]: a }));
+    /**
+     * Reads the focused value from a structure.
+     *
+     * @example
+     * ```ts
+     * pipe(user, Lens.get(nameLens)); // "Alice"
+     * ```
+     */
+    Lens.get = (lens) => (s) => lens.get(s);
+    /**
+     * Replaces the focused value within a structure, returning a new structure.
+     *
+     * @example
+     * ```ts
+     * pipe(user, Lens.set(nameLens)("Bob")); // new User with name "Bob"
+     * ```
+     */
+    Lens.set = (lens) => (a) => (s) => lens.set(a)(s);
+    /**
+     * Applies a function to the focused value, returning a new structure.
+     *
+     * @example
+     * ```ts
+     * pipe(user, Lens.modify(nameLens)(n => n.toUpperCase())); // "ALICE"
+     * ```
+     */
+    Lens.modify = (lens) => (f) => (s) => lens.set(f(lens.get(s)))(s);
+    /**
+     * Composes two Lenses: focuses through the outer, then through the inner.
+     * Use in a pipe chain to build up a deep focus step by step.
+     *
+     * @example
+     * ```ts
+     * const userCityLens = pipe(
+     *   Lens.prop<User>()("address"),
+     *   Lens.andThen(Lens.prop<Address>()("city")),
+     * );
+     * ```
+     */
+    Lens.andThen = (inner) => (outer) => Lens.make((s) => inner.get(outer.get(s)), (b) => (s) => outer.set(inner.set(b)(outer.get(s)))(s));
+    /**
+     * Composes a Lens with an Optional, producing an Optional.
+     * Use when the next step in the focus is optional (may be absent).
+     *
+     * @example
+     * ```ts
+     * const userBioOpt = pipe(
+     *   Lens.prop<User>()("profile"),
+     *   Lens.andThenOptional(Optional.prop<Profile>()("bio")),
+     * );
+     * ```
+     */
+    Lens.andThenOptional = (inner) => (outer) => ({
+        get: (s) => inner.get(outer.get(s)),
+        set: (b) => (s) => outer.set(inner.set(b)(outer.get(s)))(s),
+    });
+    /**
+     * Converts a Lens to an Optional. Every Lens is a valid Optional
+     * whose get always returns Some.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Lens.prop<User>()("address"),
+     *   Lens.toOptional,
+     *   Optional.andThen(Optional.prop<Address>()("landmark")),
+     * );
+     * ```
+     */
+    Lens.toOptional = (lens) => ({
+        get: (s) => ({ kind: "Some", value: lens.get(s) }),
+        set: lens.set,
+    });
+})(Lens || (Lens = {}));

package/esm/src/Core/Optional.js

@@ -0,0 +1,164 @@
+import { Option } from "./Option.js";
+export var Optional;
+(function (Optional) {
+    /**
+     * Constructs an Optional from a getter (returning Option<A>) and a setter.
+     *
+     * @example
+     * ```ts
+     * const firstChar = Optional.make(
+     *   (s: string) => s.length > 0 ? Option.some(s[0]) : Option.none(),
+     *   (c) => (s) => s.length > 0 ? c + s.slice(1) : s,
+     * );
+     * ```
+     */
+    Optional.make = (get, set) => ({ get, set });
+    /**
+     * Creates an Optional that focuses on an optional property of an object.
+     * Only keys whose type includes undefined (i.e. `field?: T`) are accepted.
+     * Call with the structure type first, then the key.
+     *
+     * @example
+     * ```ts
+     * type Profile = { username: string; bio?: string };
+     * const bioOpt = Optional.prop<Profile>()("bio");
+     * ```
+     */
+    Optional.prop = () => (key) => Optional.make((s) => {
+        const val = s[key];
+        return val != null
+            ? Option.some(val)
+            : Option.none();
+    }, (a) => (s) => ({ ...s, [key]: a }));
+    /**
+     * Creates an Optional that focuses on an element at a given index in an array.
+     * Returns None when the index is out of bounds; set is a no-op when out of bounds.
+     *
+     * @example
+     * ```ts
+     * const firstItem = Optional.index<string>(0);
+     *
+     * pipe(["a", "b"], Optional.get(firstItem)); // Some("a")
+     * pipe([], Optional.get(firstItem));         // None
+     * ```
+     */
+    Optional.index = (i) => Optional.make((arr) => i >= 0 && i < arr.length ? Option.some(arr[i]) : Option.none(), (a) => (arr) => {
+        if (i < 0 || i >= arr.length)
+            return arr;
+        const copy = [...arr];
+        copy[i] = a;
+        return copy;
+    });
+    /**
+     * Reads the focused value from a structure, returning Option<A>.
+     *
+     * @example
+     * ```ts
+     * pipe(profile, Optional.get(bioOpt)); // Some("...") or None
+     * ```
+     */
+    Optional.get = (opt) => (s) => opt.get(s);
+    /**
+     * Replaces the focused value within a structure.
+     * For indexed focuses, this is a no-op when the index is out of bounds.
+     *
+     * @example
+     * ```ts
+     * pipe(profile, Optional.set(bioOpt)("hello"));
+     * ```
+     */
+    Optional.set = (opt) => (a) => (s) => opt.set(a)(s);
+    /**
+     * Applies a function to the focused value if it is present; returns the
+     * structure unchanged if the focus is absent.
+     *
+     * @example
+     * ```ts
+     * pipe(profile, Optional.modify(bioOpt)(s => s.toUpperCase()));
+     * ```
+     */
+    Optional.modify = (opt) => (f) => (s) => {
+        const val = opt.get(s);
+        return val.kind === "None" ? s : opt.set(f(val.value))(s);
+    };
+    /**
+     * Returns the focused value or a default when the focus is absent.
+     *
+     * @example
+     * ```ts
+     * pipe(profile, Optional.getOrElse(bioOpt)("no bio"));
+     * ```
+     */
+    Optional.getOrElse = (opt) => (defaultValue) => (s) => {
+        const val = opt.get(s);
+        return val.kind === "Some" ? val.value : defaultValue;
+    };
+    /**
+     * Extracts a value from an Optional focus using handlers for the present
+     * and absent cases.
+     *
+     * @example
+     * ```ts
+     * pipe(profile, Optional.fold(bioOpt)(() => "no bio", (bio) => bio.toUpperCase()));
+     * ```
+     */
+    Optional.fold = (opt) => (onNone, onSome) => (s) => {
+        const val = opt.get(s);
+        return val.kind === "Some" ? onSome(val.value) : onNone();
+    };
+    /**
+     * Pattern matches on an Optional focus using a named-case object.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   profile,
+     *   Optional.match(bioOpt)({ none: () => "no bio", some: (bio) => bio }),
+     * );
+     * ```
+     */
+    Optional.match = (opt) => (cases) => (s) => {
+        const val = opt.get(s);
+        return val.kind === "Some" ? cases.some(val.value) : cases.none();
+    };
+    /**
+     * Composes two Optionals: focuses through the outer, then through the inner.
+     * Returns None if either focus is absent.
+     *
+     * @example
+     * ```ts
+     * const deepOpt = pipe(
+     *   Optional.prop<User>()("address"),
+     *   Optional.andThen(Optional.prop<Address>()("landmark")),
+     * );
+     * ```
+     */
+    Optional.andThen = (inner) => (outer) => Optional.make((s) => {
+        const mid = outer.get(s);
+        return mid.kind === "None" ? Option.none() : inner.get(mid.value);
+    }, (b) => (s) => {
+        const mid = outer.get(s);
+        return mid.kind === "None" ? s : outer.set(inner.set(b)(mid.value))(s);
+    });
+    /**
+     * Composes an Optional with a Lens, producing an Optional.
+     * The Lens focuses within the value found by the Optional.
+     *
+     * @example
+     * ```ts
+     * const cityOpt = pipe(
+     *   Optional.prop<User>()("address"),
+     *   Optional.andThenLens(Lens.prop<Address>()("city")),
+     * );
+     * ```
+     */
+    Optional.andThenLens = (inner) => (outer) => Optional.make((s) => {
+        const mid = outer.get(s);
+        return mid.kind === "None"
+            ? Option.none()
+            : Option.some(inner.get(mid.value));
+    }, (b) => (s) => {
+        const mid = outer.get(s);
+        return mid.kind === "None" ? s : outer.set(inner.set(b)(mid.value))(s);
+    });
+})(Optional || (Optional = {}));

package/esm/src/Core/These.js

@@ -1,131 +1,142 @@
-import { Result } from "./Result.js";
 export var These;
 (function (These) {
     /**
-     * Creates a These holding only a success value (no error).
+     * Creates a These holding only a first value.
      *
      * @example
      * ```ts
-     * These.ok(42);
+     * These.first(42); // { kind: "First", first: 42 }
      * ```
      */
-    These.ok = (value) => Result.ok(value);
+    These.first = (value) => ({ kind: "First", first: value });
     /**
-     * Creates a These holding only an error/warning (no success value).
+     * Creates a These holding only a second value.
      *
      * @example
      * ```ts
-     * These.err("Something went wrong");
+     * These.second("warning"); // { kind: "Second", second: "warning" }
      * ```
      */
-    These.err = (error) => Result.err(error);
+    These.second = (value) => ({ kind: "Second", second: value });
     /**
-     * Creates a These holding both an error/warning and a success value.
+     * Creates a These holding both a first and a second value simultaneously.
      *
      * @example
      * ```ts
-     * These.both("Deprecated API used", result);
+     * These.both(42, "Deprecated API used"); // { kind: "Both", first: 42, second: "Deprecated API used" }
      * ```
      */
-    These.both = (error, value) => ({
+    These.both = (first, second) => ({
         kind: "Both",
-        error,
-        value,
+        first,
+        second,
     });
     /**
-     * Type guard — checks if a These holds only an error/warning.
+     * Type guard — checks if a These holds only a first value.
      */
-    These.isErr = (data) => data.kind === "Error";
+    These.isFirst = (data) => data.kind === "First";
     /**
-     * Type guard — checks if a These holds only a success value.
+     * Type guard — checks if a These holds only a second value.
      */
-    These.isOk = (data) => data.kind === "Ok";
+    These.isSecond = (data) => data.kind === "Second";
     /**
-     * Type guard — checks if a These holds both an error/warning and a success value.
+     * Type guard — checks if a These holds both values simultaneously.
      */
     These.isBoth = (data) => data.kind === "Both";
     /**
-     * Returns true if the These contains a success value (Ok or Both).
+     * Returns true if the These contains a first value (First or Both).
      */
-    These.hasValue = (data) => data.kind === "Ok" || data.kind === "Both";
+    These.hasFirst = (data) => data.kind === "First" || data.kind === "Both";
     /**
-     * Returns true if the These contains an error/warning (Err or Both).
+     * Returns true if the These contains a second value (Second or Both).
      */
-    These.hasError = (data) => data.kind === "Error" || data.kind === "Both";
+    These.hasSecond = (data) => data.kind === "Second" || data.kind === "Both";
     /**
-     * Transforms the success value, leaving the error unchanged.
+     * Transforms the first value, leaving the second unchanged.
      *
      * @example
      * ```ts
-     * 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")
+     * pipe(These.first(5), These.mapFirst(n => n * 2));           // First(10)
+     * pipe(These.both(5, "warn"), These.mapFirst(n => n * 2));    // Both(10, "warn")
+     * pipe(These.second("warn"), These.mapFirst(n => n * 2));     // Second("warn")
      * ```
      */
-    These.map = (f) => (data) => {
-        if (These.isErr(data))
+    These.mapFirst = (f) => (data) => {
+        if (These.isSecond(data))
             return data;
-        if (These.isOk(data))
-            return These.ok(f(data.value));
-        return These.both(data.error, f(data.value));
+        if (These.isFirst(data))
+            return These.first(f(data.first));
+        return These.both(f(data.first), data.second);
     };
     /**
-     * Transforms the error/warning value, leaving the success value unchanged.
+     * Transforms the second value, leaving the first unchanged.
      *
      * @example
      * ```ts
-     * pipe(These.err("err"), These.mapErr(e => e.toUpperCase()));         // Err("ERR")
-     * pipe(These.both("warn", 5), These.mapErr(e => e.toUpperCase()));    // Both("WARN", 5)
+     * pipe(These.second("warn"), These.mapSecond(e => e.toUpperCase()));     // Second("WARN")
+     * pipe(These.both(5, "warn"), These.mapSecond(e => e.toUpperCase()));    // Both(5, "WARN")
      * ```
      */
-    These.mapErr = (f) => (data) => {
-        if (These.isOk(data))
+    These.mapSecond = (f) => (data) => {
+        if (These.isFirst(data))
             return data;
-        if (These.isErr(data))
-            return These.err(f(data.error));
-        return These.both(f(data.error), data.value);
+        if (These.isSecond(data))
+            return These.second(f(data.second));
+        return These.both(data.first, f(data.second));
     };
     /**
-     * Transforms both the error and success values independently.
+     * Transforms both the first and second values independently.
      *
      * @example
      * ```ts
      * pipe(
-     *   These.both("warn", 5),
-     *   These.bimap(e => e.toUpperCase(), n => n * 2)
-     * ); // Both("WARN", 10)
+     *   These.both(5, "warn"),
+     *   These.mapBoth(n => n * 2, e => e.toUpperCase())
+     * ); // Both(10, "WARN")
      * ```
      */
-    These.bimap = (onErr, onOk) => (data) => {
-        if (These.isErr(data))
-            return These.err(onErr(data.error));
-        if (These.isOk(data))
-            return These.ok(onOk(data.value));
-        return These.both(onErr(data.error), onOk(data.value));
+    These.mapBoth = (onFirst, onSecond) => (data) => {
+        if (These.isSecond(data))
+            return These.second(onSecond(data.second));
+        if (These.isFirst(data))
+            return These.first(onFirst(data.first));
+        return These.both(onFirst(data.first), onSecond(data.second));
     };
     /**
-     * Chains These computations by passing the success value to f.
-     * - Err propagates unchanged.
-     * - Ok(a) applies f(a) directly.
-     * - Both(e, a): applies f(a); if the result is Ok(b), returns Both(e, b)
-     *   to preserve the warning. Otherwise returns f(a) as-is.
+     * Chains These computations by passing the first value to f.
+     * Second propagates unchanged; First and Both apply f to the first value.
      *
      * @example
      * ```ts
-     * const double = (n: number): These<string, number> => These.ok(n * 2);
+     * const double = (n: number): These<number, string> => These.first(n * 2);
      *
-     * 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")
+     * pipe(These.first(5), These.chainFirst(double));            // First(10)
+     * pipe(These.both(5, "warn"), These.chainFirst(double));     // First(10)
+     * pipe(These.second("warn"), These.chainFirst(double));      // Second("warn")
      * ```
      */
-    These.chain = (f) => (data) => {
-        if (These.isErr(data))
+    These.chainFirst = (f) => (data) => {
+        if (These.isSecond(data))
             return data;
-        if (These.isOk(data))
-            return f(data.value);
-        const result = f(data.value);
-        return These.isOk(result) ? These.both(data.error, result.value) : result;
+        return f(data.first);
+    };
+    /**
+     * Chains These computations by passing the second value to f.
+     * First propagates unchanged; Second and Both apply f to the second value.
+     *
+     * @example
+     * ```ts
+     * const shout = (s: string): These<number, string> => These.second(s.toUpperCase());
+     *
+     * pipe(These.second("warn"), These.chainSecond(shout));      // Second("WARN")
+     * pipe(These.both(5, "warn"), These.chainSecond(shout));     // Second("WARN")
+     * pipe(These.first(5), These.chainSecond(shout));            // First(5)
+     * ```
+     */
+    These.chainSecond = (f) => (data) => {
+        if (These.isFirst(data))
+            return data;
+        return f(data.second);
     };
     /**
      * Extracts a value from a These by providing handlers for all three cases.
@@ -135,19 +146,19 @@ export var These;
      * pipe(
      *   these,
      *   These.fold(
-     *     e => `Error: ${e}`,
-     *     a => `Value: ${a}`,
-     *     (e, a) => `Both: ${e} / ${a}`
+     *     a => `First: ${a}`,
+     *     b => `Second: ${b}`,
+     *     (a, b) => `Both: ${a} / ${b}`
      *   )
      * );
      * ```
      */
-    These.fold = (onErr, onOk, onBoth) => (data) => {
-        if (These.isErr(data))
-            return onErr(data.error);
-        if (These.isOk(data))
-            return onOk(data.value);
-        return onBoth(data.error, data.value);
+    These.fold = (onFirst, onSecond, onBoth) => (data) => {
+        if (These.isSecond(data))
+            return onSecond(data.second);
+        if (These.isFirst(data))
+            return onFirst(data.first);
+        return onBoth(data.first, data.second);
     };
     /**
      * Pattern matches on a These, returning the result of the matching case.
@@ -157,86 +168,74 @@ export var These;
      * pipe(
      *   these,
      *   These.match({
-     *     err: e => `Error: ${e}`,
-     *     ok: a => `Value: ${a}`,
-     *     both: (e, a) => `Both: ${e} / ${a}`
+     *     first: a => `First: ${a}`,
+     *     second: b => `Second: ${b}`,
+     *     both: (a, b) => `Both: ${a} / ${b}`
      *   })
      * );
      * ```
      */
     These.match = (cases) => (data) => {
-        if (These.isErr(data))
-            return cases.err(data.error);
-        if (These.isOk(data))
-            return cases.ok(data.value);
-        return cases.both(data.error, data.value);
+        if (These.isSecond(data))
+            return cases.second(data.second);
+        if (These.isFirst(data))
+            return cases.first(data.first);
+        return cases.both(data.first, data.second);
     };
     /**
-     * Returns the success value, or a default if the These has no success value.
+     * Returns the first value, or a default if the These has no first value.
      *
      * @example
      * ```ts
-     * 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
+     * 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
      * ```
      */
-    These.getOrElse = (defaultValue) => (data) => These.hasValue(data) ? data.value : defaultValue;
+    These.getFirstOrElse = (defaultValue) => (data) => These.hasFirst(data) ? data.first : defaultValue;
     /**
-     * Executes a side effect on the success value without changing the These.
-     * Useful for logging or debugging.
-     */
-    These.tap = (f) => (data) => {
-        if (These.hasValue(data))
-            f(data.value);
-        return data;
-    };
-    /**
-     * Swaps the roles of error and success values.
-     * - Err(e)      → Ok(e)
-     * - Ok(a)       → Err(a)
-     * - Both(e, a)  → Both(a, e)
+     * Returns the second value, or a default if the These has no second value.
      *
      * @example
      * ```ts
-     * These.swap(These.err("err"));        // Ok("err")
-     * These.swap(These.ok(5));             // Err(5)
-     * These.swap(These.both("warn", 5));   // Both(5, "warn")
+     * 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"
      * ```
      */
-    These.swap = (data) => {
-        if (These.isErr(data))
-            return These.ok(data.error);
-        if (These.isOk(data))
-            return These.err(data.value);
-        return These.both(data.value, data.error);
-    };
+    These.getSecondOrElse = (defaultValue) => (data) => These.hasSecond(data) ? data.second : defaultValue;
     /**
-     * Converts a These to an Option.
-     * Ok and Both produce Some; Err produces None.
+     * Executes a side effect on the first value without changing the These.
+     * Useful for logging or debugging.
      *
      * @example
      * ```ts
-     * These.toOption(These.ok(42));          // Some(42)
-     * These.toOption(These.both("warn", 42)); // Some(42)
-     * These.toOption(These.err("err"));       // None
+     * pipe(These.first(5), These.tap(console.log)); // logs 5, returns First(5)
      * ```
      */
-    These.toOption = (data) => These.hasValue(data) ? { kind: "Some", value: data.value } : { kind: "None" };
+    These.tap = (f) => (data) => {
+        if (These.hasFirst(data))
+            f(data.first);
+        return data;
+    };
     /**
-     * Converts a These to a Result, discarding any warning from Both.
-     * Ok and Both produce Ok; Err produces Err.
+     * Swaps the roles of first and second values.
+     * - First(a)    → Second(a)
+     * - Second(b)   → First(b)
+     * - Both(a, b)  → Both(b, a)
      *
      * @example
      * ```ts
-     * These.toResult(These.ok(42));           // Ok(42)
-     * These.toResult(These.both("warn", 42)); // Ok(42)
-     * These.toResult(These.err("err"));       // Err("err")
+     * These.swap(These.first(5));            // Second(5)
+     * These.swap(These.second("warn"));      // First("warn")
+     * These.swap(These.both(5, "warn"));     // Both("warn", 5)
      * ```
      */
-    These.toResult = (data) => {
-        if (These.hasValue(data))
-            return Result.ok(data.value);
-        return data;
+    These.swap = (data) => {
+        if (These.isSecond(data))
+            return These.first(data.second);
+        if (These.isFirst(data))
+            return These.second(data.first);
+        return These.both(data.second, data.first);
     };
 })(These || (These = {}));

package/esm/src/Core/index.js

@@ -1,5 +1,7 @@
 export * from "./Arr.js";
+export * from "./Lens.js";
 export * from "./Option.js";
+export * from "./Optional.js";
 export * from "./Rec.js";
 export * from "./RemoteData.js";
 export * from "./Result.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nlozgachev/pipekit",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Simple functional programming toolkit for TypeScript",
   "keywords": [
     "functional",