@nlozgachev/pipelined 0.6.4

package/esm/src/Core/Option.js

@@ -0,0 +1,186 @@
+import { Result } from "./Result.js";
+export var Option;
+(function (Option) {
+    /**
+     * Creates a Some containing the given value.
+     */
+    Option.some = (value) => ({ kind: "Some", value });
+    /**
+     * Type guard that checks if a Option is Some.
+     */
+    Option.isSome = (data) => data.kind === "Some";
+    /**
+     * Creates a None (empty Option).
+     */
+    Option.none = () => ({ kind: "None" });
+    /**
+     * Type guard that checks if a Option is None.
+     */
+    Option.isNone = (data) => data.kind === "None";
+    /**
+     * Creates a Option from a nullable value.
+     * Returns None if the value is null or undefined, Some otherwise.
+     *
+     * @example
+     * ```ts
+     * Option.fromNullable(null); // None
+     * Option.fromNullable(42); // Some(42)
+     * ```
+     */
+    Option.fromNullable = (value) => value === null || value === undefined ? Option.none() : Option.some(value);
+    /**
+     * Extracts the value from a Option, returning null if None.
+     */
+    Option.toNullable = (data) => Option.isSome(data) ? data.value : null;
+    /**
+     * Extracts the value from a Option, returning undefined if None.
+     */
+    Option.toUndefined = (data) => Option.isSome(data) ? data.value : undefined;
+    /**
+     * Creates a Option from a possibly undefined value.
+     * Returns None if undefined, Some otherwise.
+     */
+    Option.fromUndefined = (value) => value === undefined ? Option.none() : Option.some(value);
+    /**
+     * Converts an Option to a Result.
+     * Some becomes Ok, None becomes Err with the provided error.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Option.some(42),
+     *   Option.toResult(() => "Value was missing")
+     * ); // Ok(42)
+     *
+     * pipe(
+     *   Option.none(),
+     *   Option.toResult(() => "Value was missing")
+     * ); // Err("Value was missing")
+     * ```
+     */
+    Option.toResult = (onNone) => (data) => Option.isSome(data) ? Result.ok(data.value) : Result.err(onNone());
+    /**
+     * Creates an Option from a Result.
+     * Ok becomes Some, Err becomes None (the error is discarded).
+     *
+     * @example
+     * ```ts
+     * Option.fromResult(Result.ok(42)); // Some(42)
+     * Option.fromResult(Result.err("oops")); // None
+     * ```
+     */
+    Option.fromResult = (data) => Result.isOk(data) ? Option.some(data.value) : Option.none();
+    /**
+     * Transforms the value inside a Option if it exists.
+     *
+     * @example
+     * ```ts
+     * pipe(Option.some(5), Option.map(n => n * 2)); // Some(10)
+     * pipe(Option.none(), Option.map(n => n * 2)); // None
+     * ```
+     */
+    Option.map = (f) => (data) => Option.isSome(data) ? Option.some(f(data.value)) : data;
+    /**
+     * Chains Option computations. If the first is Some, passes the value to f.
+     * If the first is None, propagates None.
+     *
+     * @example
+     * ```ts
+     * const parseNumber = (s: string): Option<number> => {
+     *   const n = parseInt(s, 10);
+     *   return isNaN(n) ? Option.none() : Option.some(n);
+     * };
+     *
+     * pipe(Option.some("42"), Option.chain(parseNumber)); // Some(42)
+     * pipe(Option.some("abc"), Option.chain(parseNumber)); // None
+     * ```
+     */
+    Option.chain = (f) => (data) => Option.isSome(data) ? f(data.value) : data;
+    /**
+     * Extracts the value from a Option by providing handlers for both cases.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Option.some(5),
+     *   Option.fold(
+     *     () => "No value",
+     *     n => `Value: ${n}`
+     *   )
+     * ); // "Value: 5"
+     * ```
+     */
+    Option.fold = (onNone, onSome) => (data) => Option.isSome(data) ? onSome(data.value) : onNone();
+    /**
+     * Pattern matches on a Option, returning the result of the matching case.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   optionUser,
+     *   Option.match({
+     *     some: user => `Hello, ${user.name}`,
+     *     none: () => "Hello, stranger"
+     *   })
+     * );
+     * ```
+     */
+    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.
+     *
+     * @example
+     * ```ts
+     * pipe(Option.some(5), Option.getOrElse(0)); // 5
+     * pipe(Option.none(), Option.getOrElse(0)); // 0
+     * ```
+     */
+    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.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Option.some(5),
+     *   Option.tap(n => console.log("Value:", n)),
+     *   Option.map(n => n * 2)
+     * );
+     * ```
+     */
+    Option.tap = (f) => (data) => {
+        if (Option.isSome(data))
+            f(data.value);
+        return data;
+    };
+    /**
+     * Filters a Option based on a predicate.
+     * Returns None if the predicate returns false or if the Option is already None.
+     *
+     * @example
+     * ```ts
+     * pipe(Option.some(5), Option.filter(n => n > 3)); // Some(5)
+     * pipe(Option.some(2), Option.filter(n => n > 3)); // None
+     * ```
+     */
+    Option.filter = (predicate) => (data) => Option.isSome(data) && predicate(data.value) ? data : Option.none();
+    /**
+     * Recovers from a None by providing a fallback Option.
+     */
+    Option.recover = (fallback) => (data) => Option.isSome(data) ? data : fallback();
+    /**
+     * Applies a function wrapped in a Option to a value wrapped in a Option.
+     *
+     * @example
+     * ```ts
+     * const add = (a: number) => (b: number) => a + b;
+     * pipe(
+     *   Option.some(add),
+     *   Option.ap(Option.some(5)),
+     *   Option.ap(Option.some(3))
+     * ); // Some(8)
+     * ```
+     */
+    Option.ap = (arg) => (data) => Option.isSome(data) && Option.isSome(arg) ? Option.some(data.value(arg.value)) : Option.none();
+})(Option || (Option = {}));

package/esm/src/Core/Optional.js

@@ -0,0 +1,160 @@
+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/Reader.js

@@ -0,0 +1,134 @@
+export var Reader;
+(function (Reader) {
+    /**
+     * Lifts a pure value into a Reader. The environment is ignored.
+     *
+     * @example
+     * ```ts
+     * const always42: Reader<Config, number> = Reader.resolve(42);
+     * always42(anyConfig); // 42
+     * ```
+     */
+    Reader.resolve = (value) => (_env) => value;
+    /**
+     * Returns the full environment as the result.
+     * The fundamental way to access the environment in a pipeline.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Reader.ask<Config>(),
+     *   Reader.map(config => config.baseUrl)
+     * )(appConfig); // "https://api.example.com"
+     * ```
+     */
+    Reader.ask = () => (env) => env;
+    /**
+     * Projects a value from the environment using a selector function.
+     * Equivalent to `pipe(Reader.ask(), Reader.map(f))` but more direct.
+     *
+     * @example
+     * ```ts
+     * const getBaseUrl: Reader<Config, string> = Reader.asks(c => c.baseUrl);
+     * getBaseUrl(appConfig); // "https://api.example.com"
+     * ```
+     */
+    Reader.asks = (f) => (env) => f(env);
+    /**
+     * Transforms the value produced by a Reader.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   Reader.asks((c: Config) => c.baseUrl),
+     *   Reader.map(url => url.toUpperCase())
+     * )(appConfig); // "HTTPS://API.EXAMPLE.COM"
+     * ```
+     */
+    Reader.map = (f) => (data) => (env) => f(data(env));
+    /**
+     * Sequences two Readers. Both see the same environment.
+     * The output of the first is passed to `f`, which returns the next Reader.
+     *
+     * @example
+     * ```ts
+     * const buildUrl = (path: string): Reader<Config, string> =>
+     *   Reader.asks(c => `${c.baseUrl}${path}`);
+     *
+     * const addAuth = (url: string): Reader<Config, string> =>
+     *   Reader.asks(c => `${url}?key=${c.apiKey}`);
+     *
+     * pipe(
+     *   buildUrl("/items"),
+     *   Reader.chain(addAuth)
+     * )(appConfig); // "https://api.example.com/items?key=secret"
+     * ```
+     */
+    Reader.chain = (f) => (data) => (env) => f(data(env))(env);
+    /**
+     * Applies a function wrapped in a Reader to a value wrapped in a Reader.
+     * Both Readers see the same environment.
+     *
+     * @example
+     * ```ts
+     * const add = (a: number) => (b: number) => a + b;
+     * pipe(
+     *   Reader.resolve<Config, typeof add>(add),
+     *   Reader.ap(Reader.asks(c => c.timeout)),
+     *   Reader.ap(Reader.resolve(5))
+     * )(appConfig);
+     * ```
+     */
+    Reader.ap = (arg) => (data) => (env) => data(env)(arg(env));
+    /**
+     * Executes a side effect on the produced value without changing the Reader.
+     * Useful for logging or debugging inside a pipeline.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   buildUrl("/users"),
+     *   Reader.tap(url => console.log("Requesting:", url)),
+     *   Reader.chain(addAuth)
+     * )(appConfig);
+     * ```
+     */
+    Reader.tap = (f) => (data) => (env) => {
+        const a = data(env);
+        f(a);
+        return a;
+    };
+    /**
+     * Adapts a Reader to work with a different (typically wider) environment
+     * by transforming the environment before passing it to the Reader.
+     * This lets you compose Readers that expect different environments.
+     *
+     * @example
+     * ```ts
+     * type AppEnv = { db: DbPool; config: Config; logger: Logger };
+     *
+     * // buildUrl only needs Config
+     * const buildUrl: Reader<Config, string> = Reader.asks(c => c.baseUrl);
+     *
+     * // Zoom in from AppEnv to Config
+     * const buildUrlFromApp: Reader<AppEnv, string> =
+     *   pipe(buildUrl, Reader.local((env: AppEnv) => env.config));
+     *
+     * buildUrlFromApp(appEnv); // works with the full AppEnv
+     * ```
+     */
+    Reader.local = (f) => (data) => (env) => data(f(env));
+    /**
+     * Runs a Reader by supplying the environment. Use this at the edge of your
+     * program where the environment is available.
+     *
+     * @example
+     * ```ts
+     * pipe(
+     *   buildEndpoint("/users"),
+     *   Reader.run(appConfig)
+     * ); // "https://api.example.com/users?key=secret"
+     * ```
+     */
+    Reader.run = (env) => (data) => data(env);
+})(Reader || (Reader = {}));

package/esm/src/Core/Rec.js

@@ -0,0 +1,167 @@
+import { Option } from "./Option.js";
+/**
+ * Functional record/object utilities that compose well with pipe.
+ * All functions are data-last and curried where applicable.
+ *
+ * @example
+ * ```ts
+ * pipe(
+ *   { a: 1, b: 2, c: 3 },
+ *   Rec.filter(n => n > 1),
+ *   Rec.map(n => n * 10)
+ * ); // { b: 20, c: 30 }
+ * ```
+ */
+export var Rec;
+(function (Rec) {
+    /**
+     * Transforms each value in a record.
+     *
+     * @example
+     * ```ts
+     * pipe({ a: 1, b: 2 }, Rec.map(n => n * 2)); // { a: 2, b: 4 }
+     * ```
+     */
+    Rec.map = (f) => (data) => {
+        const result = {};
+        for (const key of Object.keys(data)) {
+            result[key] = f(data[key]);
+        }
+        return result;
+    };
+    /**
+     * Transforms each value in a record, also receiving the key.
+     *
+     * @example
+     * ```ts
+     * pipe({ a: 1, b: 2 }, Rec.mapWithKey((k, v) => `${k}:${v}`));
+     * // { a: "a:1", b: "b:2" }
+     * ```
+     */
+    Rec.mapWithKey = (f) => (data) => {
+        const result = {};
+        for (const key of Object.keys(data)) {
+            result[key] = f(key, data[key]);
+        }
+        return result;
+    };
+    /**
+     * Filters values in a record by a predicate.
+     *
+     * @example
+     * ```ts
+     * pipe({ a: 1, b: 2, c: 3 }, Rec.filter(n => n > 1)); // { b: 2, c: 3 }
+     * ```
+     */
+    Rec.filter = (predicate) => (data) => {
+        const result = {};
+        for (const key of Object.keys(data)) {
+            if (predicate(data[key]))
+                result[key] = data[key];
+        }
+        return result;
+    };
+    /**
+     * Filters values in a record by a predicate that also receives the key.
+     *
+     * @example
+     * ```ts
+     * pipe({ a: 1, b: 2 }, Rec.filterWithKey((k, v) => k !== "a" && v > 0));
+     * // { b: 2 }
+     * ```
+     */
+    Rec.filterWithKey = (predicate) => (data) => {
+        const result = {};
+        for (const key of Object.keys(data)) {
+            if (predicate(key, data[key]))
+                result[key] = data[key];
+        }
+        return result;
+    };
+    /**
+     * Looks up a value by key, returning Option.
+     *
+     * @example
+     * ```ts
+     * pipe({ a: 1, b: 2 }, Rec.lookup("a")); // Some(1)
+     * pipe({ a: 1, b: 2 }, Rec.lookup("c")); // None
+     * ```
+     */
+    Rec.lookup = (key) => (data) => Object.prototype.hasOwnProperty.call(data, key) ? Option.some(data[key]) : Option.none();
+    /**
+     * Returns all keys of a record.
+     */
+    Rec.keys = (data) => Object.keys(data);
+    /**
+     * Returns all values of a record.
+     */
+    Rec.values = (data) => Object.values(data);
+    /**
+     * Returns all key-value pairs of a record.
+     */
+    Rec.entries = (data) => Object.entries(data);
+    /**
+     * Creates a record from key-value pairs.
+     *
+     * @example
+     * ```ts
+     * Rec.fromEntries([["a", 1], ["b", 2]]); // { a: 1, b: 2 }
+     * ```
+     */
+    Rec.fromEntries = (data) => Object.fromEntries(data);
+    /**
+     * Picks specific keys from a record.
+     *
+     * @example
+     * ```ts
+     * pipe({ a: 1, b: 2, c: 3 }, Rec.pick("a", "c")); // { a: 1, c: 3 }
+     * ```
+     */
+    Rec.pick = (...pickedKeys) => (data) => {
+        const result = {};
+        for (const key of pickedKeys) {
+            if (Object.prototype.hasOwnProperty.call(data, key)) {
+                result[key] = data[key];
+            }
+        }
+        return result;
+    };
+    /**
+     * Omits specific keys from a record.
+     *
+     * @example
+     * ```ts
+     * pipe({ a: 1, b: 2, c: 3 }, Rec.omit("b")); // { a: 1, c: 3 }
+     * ```
+     */
+    Rec.omit = (...omittedKeys) => (data) => {
+        const omitSet = new Set(omittedKeys);
+        const result = {};
+        for (const key of Object.keys(data)) {
+            if (!omitSet.has(key)) {
+                result[key] = data[key];
+            }
+        }
+        return result;
+    };
+    /**
+     * Merges two records. Values from the second record take precedence.
+     *
+     * @example
+     * ```ts
+     * pipe({ a: 1, b: 2 }, Rec.merge({ b: 3, c: 4 })); // { a: 1, b: 3, c: 4 }
+     * ```
+     */
+    Rec.merge = (other) => (data) => ({
+        ...data,
+        ...other,
+    });
+    /**
+     * Returns true if the record has no keys.
+     */
+    Rec.isEmpty = (data) => Object.keys(data).length === 0;
+    /**
+     * Returns the number of keys in a record.
+     */
+    Rec.size = (data) => Object.keys(data).length;
+})(Rec || (Rec = {}));