@nlozgachev/pipekit 0.4.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/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.4.0",
+  "version": "0.4.1",
   "description": "Simple functional programming toolkit for TypeScript",
   "keywords": [
     "functional",

package/script/src/Core/Lens.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Lens = void 0;
+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 || (exports.Lens = Lens = {}));

package/script/src/Core/Optional.js

@@ -0,0 +1,167 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Optional = void 0;
+const Option_js_1 = require("./Option.js");
+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_js_1.Option.some(val)
+            : Option_js_1.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_js_1.Option.some(arr[i]) : Option_js_1.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_js_1.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_js_1.Option.none()
+            : Option_js_1.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 || (exports.Optional = Optional = {}));

package/script/src/Core/index.js

@@ -15,7 +15,9 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./Arr.js"), exports);
+__exportStar(require("./Lens.js"), exports);
 __exportStar(require("./Option.js"), exports);
+__exportStar(require("./Optional.js"), exports);
 __exportStar(require("./Rec.js"), exports);
 __exportStar(require("./RemoteData.js"), exports);
 __exportStar(require("./Result.js"), exports);

package/types/src/Core/Lens.d.ts

@@ -0,0 +1,118 @@
+import type { Optional } from "./Optional.js";
+/**
+ * Lens<S, A> focuses on a single value A inside a structure S, providing
+ * a composable way to read and immutably update nested data.
+ *
+ * A Lens always succeeds: the focused value is guaranteed to exist.
+ * For optional or indexed focuses, use Optional<S, A>.
+ *
+ * @example
+ * ```ts
+ * type Address = { city: string; zip: string };
+ * type User = { name: string; address: Address };
+ *
+ * const addressLens = Lens.prop<User>()("address");
+ * const cityLens    = Lens.prop<Address>()("city");
+ * const userCityLens = pipe(addressLens, Lens.andThen(cityLens));
+ *
+ * pipe(user, Lens.get(userCityLens));             // "Berlin"
+ * pipe(user, Lens.set(userCityLens)("Hamburg"));  // new User with city updated
+ * pipe(user, Lens.modify(userCityLens)(c => c.toUpperCase())); // "BERLIN"
+ * ```
+ */
+export type Lens<S, A> = {
+    readonly get: (s: S) => A;
+    readonly set: (a: A) => (s: S) => S;
+};
+export declare namespace Lens {
+    /**
+     * Constructs a Lens from a getter and a setter.
+     *
+     * @example
+     * ```ts
+     * const nameLens = Lens.make(
+     *   (user: User) => user.name,
+     *   (name) => (user) => ({ ...user, name }),
+     * );
+     * ```
+     */
+    const make: <S, A>(get: (s: S) => A, set: (a: A) => (s: S) => S) => Lens<S, A>;
+    /**
+     * 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");
+     * ```
+     */
+    const prop: <S>() => <K extends keyof S>(key: K) => Lens<S, S[K]>;
+    /**
+     * Reads the focused value from a structure.
+     *
+     * @example
+     * ```ts
+     * pipe(user, Lens.get(nameLens)); // "Alice"
+     * ```
+     */
+    const get: <S, A>(lens: Lens<S, A>) => (s: S) => A;
+    /**
+     * Replaces the focused value within a structure, returning a new structure.
+     *
+     * @example
+     * ```ts
+     * pipe(user, Lens.set(nameLens)("Bob")); // new User with name "Bob"
+     * ```
+     */
+    const set: <S, A>(lens: Lens<S, A>) => (a: A) => (s: S) => S;
+    /**
+     * Applies a function to the focused value, returning a new structure.
+     *
+     * @example
+     * ```ts
+     * pipe(user, Lens.modify(nameLens)(n => n.toUpperCase())); // "ALICE"
+     * ```
+     */
+    const modify: <S, A>(lens: Lens<S, A>) => (f: (a: A) => A) => (s: 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")),
+     * );
+     * ```
+     */
+    const andThen: <A, B>(inner: Lens<A, B>) => <S>(outer: Lens<S, A>) => Lens<S, B>;
+    /**
+     * 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")),
+     * );
+     * ```
+     */
+    const andThenOptional: <A, B>(inner: Optional<A, B>) => <S>(outer: Lens<S, A>) => Optional<S, B>;
+    /**
+     * 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")),
+     * );
+     * ```
+     */
+    const toOptional: <S, A>(lens: Lens<S, A>) => Optional<S, A>;
+}
+//# sourceMappingURL=Lens.d.ts.map

package/types/src/Core/Lens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Lens.d.ts","sourceRoot":"","sources":["../../../src/src/Core/Lens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,IAAI;IACvB,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;CACrC,CAAC;AAEF,yBAAiB,IAAI,CAAC;IACpB;;;;;;;;;;OAUG;IACI,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EACvB,KAAK,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,EAChB,KAAK,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,KACzB,IAAI,CAAC,CAAC,EAAE,CAAC,CAAmB,CAAC;IAEhC;;;;;;;;OAQG;IACI,MAAM,IAAI,GAAI,CAAC,QACrB,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,CAAC,KAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAItC,CAAC;IAEJ;;;;;;;OAOG;IACI,MAAM,GAAG,GAAI,CAAC,EAAE,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,KAAG,CAAgB,CAAC;IAExE;;;;;;;OAOG;IACI,MAAM,GAAG,GAAI,CAAC,EAAE,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,MAAM,GAAG,CAAC,KAAG,CAAmB,CAAC;IAErF;;;;;;;OAOG;IACI,MAAM,MAAM,GAAI,CAAC,EAAE,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,KAAG,CACjD,CAAC;IAE9B;;;;;;;;;;;OAWG;IACI,MAAM,OAAO,GACjB,CAAC,EAAE,CAAC,EAAE,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAI3D,CAAC;IAEN;;;;;;;;;;;OAWG;IACI,MAAM,eAAe,GACzB,CAAC,EAAE,CAAC,EAAE,OAAO,QAAQ,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,OAAO,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,CAGpE,CAAC;IAEL;;;;;;;;;;;;OAYG;IACI,MAAM,UAAU,GAAI,CAAC,EAAE,CAAC,EAAE,MAAM,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,QAAQ,CAAC,CAAC,EAAE,CAAC,CAG/D,CAAC;CACJ"}

package/types/src/Core/Optional.d.ts

@@ -0,0 +1,158 @@
+import { Option } from "./Option.js";
+import type { Lens } from "./Lens.js";
+/** Keys of T for which undefined is assignable (i.e. optional fields). */
+type OptionalKeys<T> = {
+    [K in keyof T]-?: undefined extends T[K] ? K : never;
+}[keyof T];
+/**
+ * Optional<S, A> focuses on a value A inside a structure S that may or may
+ * not be present. Like a Lens, but get returns Option<A>.
+ *
+ * Compose with other Optionals via `andThen`, or with a Lens via `andThenLens`.
+ * Convert a Lens to an Optional with `Lens.toOptional`.
+ *
+ * @example
+ * ```ts
+ * type Profile = { username: string; bio?: string };
+ *
+ * const bioOpt = Optional.prop<Profile>()("bio");
+ *
+ * pipe(profile, Optional.get(bioOpt));               // Some("hello") or None
+ * pipe(profile, Optional.set(bioOpt)("hello"));      // new Profile with bio set
+ * pipe(profile, Optional.modify(bioOpt)(s => s + "!")); // appends if present
+ * ```
+ */
+export type Optional<S, A> = {
+    readonly get: (s: S) => Option<A>;
+    readonly set: (a: A) => (s: S) => S;
+};
+export declare namespace 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,
+     * );
+     * ```
+     */
+    const make: <S, A>(get: (s: S) => Option<A>, set: (a: A) => (s: S) => S) => Optional<S, A>;
+    /**
+     * 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");
+     * ```
+     */
+    const prop: <S>() => <K extends OptionalKeys<S>>(key: K) => Optional<S, NonNullable<S[K]>>;
+    /**
+     * 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
+     * ```
+     */
+    const index: <A>(i: number) => Optional<A[], A>;
+    /**
+     * Reads the focused value from a structure, returning Option<A>.
+     *
+     * @example
+     * ```ts
+     * pipe(profile, Optional.get(bioOpt)); // Some("...") or None
+     * ```
+     */
+    const get: <S, A>(opt: Optional<S, A>) => (s: S) => Option<A>;
+    /**
+     * 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"));
+     * ```
+     */
+    const set: <S, A>(opt: Optional<S, A>) => (a: A) => (s: S) => 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()));
+     * ```
+     */
+    const modify: <S, A>(opt: Optional<S, A>) => (f: (a: A) => A) => (s: S) => S;
+    /**
+     * Returns the focused value or a default when the focus is absent.
+     *
+     * @example
+     * ```ts
+     * pipe(profile, Optional.getOrElse(bioOpt)("no bio"));
+     * ```
+     */
+    const getOrElse: <S, A>(opt: Optional<S, A>) => (defaultValue: A) => (s: S) => A;
+    /**
+     * 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()));
+     * ```
+     */
+    const fold: <S, A>(opt: Optional<S, A>) => <B>(onNone: () => B, onSome: (a: A) => B) => (s: S) => B;
+    /**
+     * Pattern matches on an Optional focus using a named-case object.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   profile,
+     *   Optional.match(bioOpt)({ none: () => "no bio", some: (bio) => bio }),
+     * );
+     * ```
+     */
+    const match: <S, A>(opt: Optional<S, A>) => <B>(cases: {
+        none: () => B;
+        some: (a: A) => B;
+    }) => (s: S) => B;
+    /**
+     * 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")),
+     * );
+     * ```
+     */
+    const andThen: <A, B>(inner: Optional<A, B>) => <S>(outer: Optional<S, A>) => Optional<S, B>;
+    /**
+     * 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")),
+     * );
+     * ```
+     */
+    const andThenLens: <A, B>(inner: Lens<A, B>) => <S>(outer: Optional<S, A>) => Optional<S, B>;
+}
+export {};
+//# sourceMappingURL=Optional.d.ts.map

package/types/src/Core/Optional.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Optional.d.ts","sourceRoot":"","sources":["../../../src/src/Core/Optional.ts"],"names":[],"mappings":"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"}

package/types/src/Core/index.d.ts

@@ -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/types/src/Core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/Core/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/src/Core/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC;AACzB,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,iBAAiB,CAAC;AAChC,cAAc,iBAAiB,CAAC;AAChC,cAAc,qBAAqB,CAAC;AACpC,cAAc,YAAY,CAAC;AAC3B,cAAc,iBAAiB,CAAC"}