@nlozgachev/pipelined 0.6.4

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,QAAQ,CAAC,SAAS,MAAM,CAAC,EAAE,KAAK,CAAC,KAAG,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAInE,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,GAAI,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,CAIlF,CAAC;IAEJ;;;;;;;;;;;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/Option.d.ts

@@ -0,0 +1,205 @@
+import { WithKind, WithValue } from "./InternalTypes.js";
+import { Result } from "./Result.js";
+/**
+ * Option represents an optional value: every Option is either Some (contains a value) or None (empty).
+ * Use Option instead of null/undefined to make optionality explicit and composable.
+ *
+ * @example
+ * ```ts
+ * const findUser = (id: string): Option<User> =>
+ *   users.has(id) ? Option.some(users.get(id)!) : Option.none();
+ *
+ * pipe(
+ *   findUser("123"),
+ *   Option.map(user => user.name),
+ *   Option.getOrElse("Unknown")
+ * );
+ * ```
+ */
+export type Option<T> = Some<T> | None;
+export type Some<A> = WithKind<"Some"> & WithValue<A>;
+export type None = WithKind<"None">;
+export declare namespace Option {
+    /**
+     * Creates a Some containing the given value.
+     */
+    const some: <A>(value: A) => Some<A>;
+    /**
+     * Type guard that checks if a Option is Some.
+     */
+    const isSome: <A>(data: Option<A>) => data is Some<A>;
+    /**
+     * Creates a None (empty Option).
+     */
+    const none: () => None;
+    /**
+     * Type guard that checks if a Option is None.
+     */
+    const isNone: <A>(data: Option<A>) => data is 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)
+     * ```
+     */
+    const fromNullable: <A>(value: A | null | undefined) => Option<A>;
+    /**
+     * Extracts the value from a Option, returning null if None.
+     */
+    const toNullable: <A>(data: Option<A>) => A | null;
+    /**
+     * Extracts the value from a Option, returning undefined if None.
+     */
+    const toUndefined: <A>(data: Option<A>) => A | undefined;
+    /**
+     * Creates a Option from a possibly undefined value.
+     * Returns None if undefined, Some otherwise.
+     */
+    const fromUndefined: <A>(value: A | undefined) => Option<A>;
+    /**
+     * 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")
+     * ```
+     */
+    const toResult: <E>(onNone: () => E) => <A>(data: Option<A>) => Result<E, A>;
+    /**
+     * 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
+     * ```
+     */
+    const fromResult: <E, A>(data: Result<E, A>) => Option<A>;
+    /**
+     * 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
+     * ```
+     */
+    const map: <A, B>(f: (a: A) => B) => (data: Option<A>) => Option<B>;
+    /**
+     * 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
+     * ```
+     */
+    const chain: <A, B>(f: (a: A) => Option<B>) => (data: Option<A>) => Option<B>;
+    /**
+     * 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"
+     * ```
+     */
+    const fold: <A, B>(onNone: () => B, onSome: (a: A) => B) => (data: Option<A>) => B;
+    /**
+     * 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"
+     *   })
+     * );
+     * ```
+     */
+    const match: <A, B>(cases: {
+        none: () => B;
+        some: (a: A) => B;
+    }) => (data: Option<A>) => B;
+    /**
+     * 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
+     * ```
+     */
+    const getOrElse: <A>(defaultValue: A) => (data: Option<A>) => A;
+    /**
+     * 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)
+     * );
+     * ```
+     */
+    const tap: <A>(f: (a: A) => void) => (data: Option<A>) => Option<A>;
+    /**
+     * 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
+     * ```
+     */
+    const filter: <A>(predicate: (a: A) => boolean) => (data: Option<A>) => Option<A>;
+    /**
+     * Recovers from a None by providing a fallback Option.
+     */
+    const recover: <A>(fallback: () => Option<A>) => (data: Option<A>) => Option<A>;
+    /**
+     * 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)
+     * ```
+     */
+    const ap: <A>(arg: Option<A>) => <B>(data: Option<(a: A) => B>) => Option<B>;
+}
+//# sourceMappingURL=Option.d.ts.map

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

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

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/Reader.d.ts

@@ -0,0 +1,156 @@
+/**
+ * A computation that reads from a shared environment `R` and produces a value `A`.
+ * Use Reader to thread a dependency (config, logger, DB pool) through a pipeline
+ * without passing it explicitly to every function.
+ *
+ * @example
+ * ```ts
+ * type Config = { baseUrl: string; apiKey: string };
+ *
+ * const buildUrl = (path: string): Reader<Config, string> =>
+ *   (config) => `${config.baseUrl}${path}`;
+ *
+ * const withAuth = (url: string): Reader<Config, string> =>
+ *   (config) => `${url}?key=${config.apiKey}`;
+ *
+ * const fetchEndpoint = (path: string): Reader<Config, string> =>
+ *   pipe(
+ *     buildUrl(path),
+ *     Reader.chain(withAuth)
+ *   );
+ *
+ * // Inject the config once at the edge
+ * fetchEndpoint("/users")(appConfig); // "https://api.example.com/users?key=secret"
+ * ```
+ */
+export type Reader<R, A> = (env: R) => A;
+export declare namespace 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
+     * ```
+     */
+    const resolve: <R, A>(value: A) => Reader<R, A>;
+    /**
+     * 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"
+     * ```
+     */
+    const ask: <R>() => Reader<R, R>;
+    /**
+     * 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"
+     * ```
+     */
+    const asks: <R, A>(f: (env: R) => A) => Reader<R, A>;
+    /**
+     * 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"
+     * ```
+     */
+    const map: <R, A, B>(f: (a: A) => B) => (data: Reader<R, A>) => Reader<R, B>;
+    /**
+     * 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"
+     * ```
+     */
+    const chain: <R, A, B>(f: (a: A) => Reader<R, B>) => (data: Reader<R, A>) => Reader<R, B>;
+    /**
+     * 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);
+     * ```
+     */
+    const ap: <R, A>(arg: Reader<R, A>) => <B>(data: Reader<R, (a: A) => B>) => Reader<R, B>;
+    /**
+     * 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);
+     * ```
+     */
+    const tap: <R, A>(f: (a: A) => void) => (data: Reader<R, A>) => Reader<R, 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
+     * ```
+     */
+    const local: <R2, R>(f: (env: R2) => R) => <A>(data: Reader<R, A>) => Reader<R2, A>;
+    /**
+     * 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"
+     * ```
+     */
+    const run: <R>(env: R) => <A>(data: Reader<R, A>) => A;
+}
+//# sourceMappingURL=Reader.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Reader.d.ts","sourceRoot":"","sources":["../../../src/src/Core/Reader.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;AAEzC,yBAAiB,MAAM,CAAC;IACtB;;;;;;;;OAQG;IACI,MAAM,OAAO,GAAI,CAAC,EAAE,CAAC,EAAE,OAAO,CAAC,KAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAoB,CAAC;IAEzE;;;;;;;;;;;OAWG;IACI,MAAM,GAAG,GAAI,CAAC,OAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAiB,CAAC;IAEvD;;;;;;;;;OASG;IACI,MAAM,IAAI,GAAI,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,KAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAAoB,CAAC;IAE9E;;;;;;;;;;OAUG;IACI,MAAM,GAAG,GAAI,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CACnE,CAAC;IAEf;;;;;;;;;;;;;;;;;OAiBG;IACI,MAAM,KAAK,GACf,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CACtD,CAAC;IAEtB;;;;;;;;;;;;;OAaG;IACI,MAAM,EAAE,GACZ,CAAC,EAAE,CAAC,EAAE,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,KAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CACtD,CAAC;IAExB;;;;;;;;;;;;OAYG;IACI,MAAM,GAAG,GAAI,CAAC,EAAE,CAAC,EAAE,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,IAAI,MAAM,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,CAAC,EAAE,CAAC,CAIhF,CAAC;IAEF;;;;;;;;;;;;;;;;;;OAkBG;IACI,MAAM,KAAK,GACf,EAAE,EAAE,CAAC,EAAE,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,MAAM,CAAC,EAAE,EAAE,CAAC,CAA0B,CAAC;IAEhG;;;;;;;;;;;OAWG;IACI,MAAM,GAAG,GAAI,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,KAAG,CAAc,CAAC;CAC3E"}