@pithos/core 2.3.0 → 2.4.0

package/dist/eidos/singleton/singleton.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Functional Singleton Pattern.
+ *
+ * In OOP, the Singleton pattern requires a class with a private constructor
+ * and a static `getInstance()` method to ensure only one instance exists.
+ *
+ * In functional TypeScript, this is absorbed by the ES module system:
+ * - A module is evaluated exactly once
+ * - `export const instance = create()` is a singleton by default
+ * - No pattern needed — it's native module behavior
+ *
+ * For lazy initialization, Arkhe provides `once` which caches the first call.
+ *
+ * ## Why Singleton is considered an anti-pattern
+ *
+ * The Singleton appears in the GoF book (1994), but the community has since
+ * largely recognized it as an anti-pattern:
+ *
+ * - **Global state in disguise** — A singleton is just a global variable with
+ *   extra steps. It creates implicit coupling throughout your codebase.
+ *
+ * - **Testability nightmare** — You can't easily mock a singleton. Every test
+ *   shares the same instance and its state, leading to flaky tests.
+ *
+ * - **Hidden dependencies** — Code using `getInstance()` has invisible deps.
+ *   You can't tell what a function needs just by looking at its signature.
+ *
+ * - **Concurrency issues** — Lazy initialization is a race condition waiting
+ *   to happen (less relevant in single-threaded JS, but still a code smell).
+ *
+ * ## The modern alternative: Dependency Injection
+ *
+ * Instead of reaching for a global singleton, pass dependencies explicitly:
+ *
+ * ```ts
+ * // ❌ Singleton — hidden dependency
+ * const fetchUsers = () => {
+ *   const db = Database.getInstance();
+ *   return db.query("SELECT * FROM users");
+ * };
+ *
+ * // ✅ Dependency injection — explicit, testable
+ * const fetchUsers = (db: Database) => {
+ *   return db.query("SELECT * FROM users");
+ * };
+ * ```
+ *
+ * This module re-exports `once` from Arkhe for discoverability.
+ *
+ * @module eidos/singleton
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { once } from "@pithos/core/eidos/singleton/singleton";
+ * // or directly from Arkhe:
+ * import { once } from "../../arkhe/function/once.js";
+ *
+ * // Lazy singleton initialization
+ * const getDb = once(() => connectToDatabase());
+ *
+ * getDb(); // connects
+ * getDb(); // returns cached connection
+ *
+ * // But consider: could this be passed as a parameter instead?
+ * ```
+ */
+export { once } from "../../arkhe/function/once.js";
+/**
+ * Alias for `once` — creates a lazy singleton from a factory function.
+ * Re-exported for discoverability when searching for "singleton".
+ *
+ * @see once
+ */
+export { once as singleton } from "../../arkhe/function/once.js";
+//# sourceMappingURL=singleton.d.ts.map

package/dist/eidos/singleton/singleton.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton.d.ts","sourceRoot":"","sources":["../../../src/eidos/singleton/singleton.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAE5C;;;;;GAKG;AACH,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/eidos/singleton/singleton.js

@@ -0,0 +1,77 @@
+/**
+ * Functional Singleton Pattern.
+ *
+ * In OOP, the Singleton pattern requires a class with a private constructor
+ * and a static `getInstance()` method to ensure only one instance exists.
+ *
+ * In functional TypeScript, this is absorbed by the ES module system:
+ * - A module is evaluated exactly once
+ * - `export const instance = create()` is a singleton by default
+ * - No pattern needed — it's native module behavior
+ *
+ * For lazy initialization, Arkhe provides `once` which caches the first call.
+ *
+ * ## Why Singleton is considered an anti-pattern
+ *
+ * The Singleton appears in the GoF book (1994), but the community has since
+ * largely recognized it as an anti-pattern:
+ *
+ * - **Global state in disguise** — A singleton is just a global variable with
+ *   extra steps. It creates implicit coupling throughout your codebase.
+ *
+ * - **Testability nightmare** — You can't easily mock a singleton. Every test
+ *   shares the same instance and its state, leading to flaky tests.
+ *
+ * - **Hidden dependencies** — Code using `getInstance()` has invisible deps.
+ *   You can't tell what a function needs just by looking at its signature.
+ *
+ * - **Concurrency issues** — Lazy initialization is a race condition waiting
+ *   to happen (less relevant in single-threaded JS, but still a code smell).
+ *
+ * ## The modern alternative: Dependency Injection
+ *
+ * Instead of reaching for a global singleton, pass dependencies explicitly:
+ *
+ * ```ts
+ * // ❌ Singleton — hidden dependency
+ * const fetchUsers = () => {
+ *   const db = Database.getInstance();
+ *   return db.query("SELECT * FROM users");
+ * };
+ *
+ * // ✅ Dependency injection — explicit, testable
+ * const fetchUsers = (db: Database) => {
+ *   return db.query("SELECT * FROM users");
+ * };
+ * ```
+ *
+ * This module re-exports `once` from Arkhe for discoverability.
+ *
+ * @module eidos/singleton
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { once } from "@pithos/core/eidos/singleton/singleton";
+ * // or directly from Arkhe:
+ * import { once } from "../../arkhe/function/once.js";
+ *
+ * // Lazy singleton initialization
+ * const getDb = once(() => connectToDatabase());
+ *
+ * getDb(); // connects
+ * getDb(); // returns cached connection
+ *
+ * // But consider: could this be passed as a parameter instead?
+ * ```
+ */
+// Re-export from Arkhe for discoverability
+export { once } from "../../arkhe/function/once.js";
+/**
+ * Alias for `once` — creates a lazy singleton from a factory function.
+ * Re-exported for discoverability when searching for "singleton".
+ *
+ * @see once
+ */
+export { once as singleton } from "../../arkhe/function/once.js";
+//# sourceMappingURL=singleton.js.map

package/dist/eidos/singleton/singleton.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleton.js","sourceRoot":"","sources":["../../../src/eidos/singleton/singleton.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAEH,2CAA2C;AAC3C,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAE5C;;;;;GAKG;AACH,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/eidos/state/state.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Functional State Pattern.
+ *
+ * In OOP, the State pattern requires a Context class, a State interface,
+ * and concrete State subclasses that the Context delegates to.
+ * In functional TypeScript, a state machine is a record of transitions
+ * keyed by state, where each transition maps an event to the next state
+ * (and optionally updates context).
+ *
+ * @module eidos/state
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { createMachine } from "@pithos/core/eidos/state/state";
+ *
+ * const light = createMachine({
+ *   green:  { timer: { to: "yellow" } },
+ *   yellow: { timer: { to: "red" } },
+ *   red:    { timer: { to: "green" } },
+ * }, "green");
+ *
+ * light.current();      // "green"
+ * light.send("timer");  // "yellow"
+ * light.send("timer");  // "red"
+ * ```
+ */
+import type { Option } from "../../zygos/option.js";
+/**
+ * A simple transition to a target state.
+ *
+ * @template S - Union of state names
+ * @since 2.4.0
+ */
+export interface SimpleTransition<S extends string> {
+    readonly to: S;
+}
+/**
+ * A transition that updates context.
+ *
+ * @template S - Union of state names
+ * @template C - Context type
+ * @since 2.4.0
+ */
+export interface ContextTransition<S extends string, C> {
+    readonly to: S;
+    readonly update: (ctx: C) => C;
+}
+/**
+ * A transition is either simple (just target) or with context update.
+ *
+ * @template S - Union of state names
+ * @template C - Context type
+ * @since 2.4.0
+ */
+export type Transition<S extends string, C> = SimpleTransition<S> | ContextTransition<S, C>;
+/**
+ * A transition map for a single state.
+ *
+ * @template S - Union of state names
+ * @template E - Union of event names
+ * @template C - Context type
+ * @since 2.4.0
+ */
+export type Transitions<S extends string, E extends string, C> = {
+    readonly [K in E]?: Transition<S, C>;
+};
+/**
+ * Full state machine definition.
+ *
+ * @template S - Union of state names
+ * @template E - Union of event names
+ * @template C - Context type
+ * @since 2.4.0
+ */
+export type MachineDefinition<S extends string, E extends string, C> = {
+    readonly [K in S]: Transitions<S, E, C>;
+};
+/**
+ * A transition listener receives the previous state, the event, and the new state.
+ *
+ * @template S - Union of state names
+ * @template E - Union of event names
+ * @since 2.4.0
+ */
+export type TransitionListener<S extends string, E extends string> = (from: S, event: E, to: S) => void;
+/**
+ * Creates a finite state machine.
+ *
+ * @template S - Union of state names
+ * @template E - Union of event names
+ * @param definition - The state/transition map
+ * @param initial - The initial state
+ * @returns A machine with `current`, `send`, `matches`, `trySend`, `onTransition`, `reset`
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const door = createMachine({
+ *   locked: { unlock: { to: "closed" } },
+ *   closed: { open: { to: "opened" }, lock: { to: "locked" } },
+ *   opened: { close: { to: "closed" } },
+ * }, "locked");
+ *
+ * door.send("unlock"); // "closed"
+ * door.send("open");   // "opened"
+ * door.matches("opened"); // true
+ * ```
+ */
+export declare function createMachine<S extends string, E extends string>(definition: MachineDefinition<S, E, undefined>, initial: S): {
+    current: () => S;
+    send: (event: E) => S;
+    matches: (state: S) => boolean;
+    trySend: (event: E) => Option<S>;
+    onTransition: (listener: TransitionListener<S, E>) => () => void;
+    reset: () => void;
+};
+/**
+ * Creates a finite state machine with context.
+ *
+ * @template S - Union of state names
+ * @template E - Union of event names
+ * @template C - Context type
+ * @param definition - The state/transition map
+ * @param initial - The initial state
+ * @param initialContext - The initial context value
+ * @returns A machine with `current`, `context`, `send`, `matches`, `trySend`, `onTransition`, `reset`
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const counter = createMachine({
+ *   active: {
+ *     increment: { to: "active", update: (ctx: number) => ctx + 1 },
+ *     reset: { to: "active", update: () => 0 },
+ *   },
+ * }, "active", 0);
+ *
+ * counter.send("increment"); // "active"
+ * counter.context();         // 1
+ * ```
+ */
+export declare function createMachine<S extends string, E extends string, C>(definition: MachineDefinition<S, E, C>, initial: S, initialContext: C): {
+    current: () => S;
+    context: () => C;
+    send: (event: E) => S;
+    matches: (state: S) => boolean;
+    trySend: (event: E) => Option<S>;
+    onTransition: (listener: TransitionListener<S, E>) => () => void;
+    reset: () => void;
+};
+//# sourceMappingURL=state.d.ts.map

package/dist/eidos/state/state.d.ts.map

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

package/dist/eidos/state/state.js

@@ -0,0 +1,85 @@
+/**
+ * Functional State Pattern.
+ *
+ * In OOP, the State pattern requires a Context class, a State interface,
+ * and concrete State subclasses that the Context delegates to.
+ * In functional TypeScript, a state machine is a record of transitions
+ * keyed by state, where each transition maps an event to the next state
+ * (and optionally updates context).
+ *
+ * @module eidos/state
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { createMachine } from "@pithos/core/eidos/state/state";
+ *
+ * const light = createMachine({
+ *   green:  { timer: { to: "yellow" } },
+ *   yellow: { timer: { to: "red" } },
+ *   red:    { timer: { to: "green" } },
+ * }, "green");
+ *
+ * light.current();      // "green"
+ * light.send("timer");  // "yellow"
+ * light.send("timer");  // "red"
+ * ```
+ */
+import { some, none } from "../../zygos/option.js";
+/**
+ * Type guard for context transitions.
+ */
+function hasUpdate(t) {
+    return "update" in t;
+}
+export function createMachine(definition, initial, initialContext) {
+    let state = initial;
+    let ctx = initialContext;
+    const listeners = new Set();
+    const send = (event) => {
+        const transitions = definition[state];
+        const transition = transitions[event];
+        if (transition === undefined)
+            return state;
+        const from = state;
+        state = transition.to;
+        // Stryker disable next-line ConditionalExpression: ctx check is defensive - TypeScript prevents update on machines without context
+        if (hasUpdate(transition) && ctx !== undefined) {
+            ctx = transition.update(ctx);
+        }
+        for (const listener of listeners) {
+            listener(from, event, state);
+        }
+        return state;
+    };
+    const trySend = (event) => {
+        const transitions = definition[state];
+        if (transitions[event] === undefined)
+            return none;
+        return some(send(event));
+    };
+    const onTransition = (listener) => {
+        listeners.add(listener);
+        return () => { listeners.delete(listener); };
+    };
+    const base = {
+        current: () => state,
+        send,
+        matches: (s) => state === s,
+        trySend,
+        onTransition,
+        reset: () => {
+            state = initial;
+            ctx = initialContext;
+        },
+    };
+    if (initialContext !== undefined) {
+        return {
+            ...base,
+            // INTENTIONAL: ctx is guaranteed to be C when initialContext is provided
+            context: () => ctx,
+        };
+    }
+    return base;
+}
+//# sourceMappingURL=state.js.map

package/dist/eidos/state/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/eidos/state/state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAyE3C;;GAEG;AACH,SAAS,SAAS,CAChB,CAAmB;IAEnB,OAAO,QAAQ,IAAI,CAAC,CAAC;AACvB,CAAC;AA4ED,MAAM,UAAU,aAAa,CAC3B,UAAsC,EACtC,OAAU,EACV,cAAkB;IAElB,IAAI,KAAK,GAAM,OAAO,CAAC;IACvB,IAAI,GAAG,GAAkB,cAAc,CAAC;IACxC,MAAM,SAAS,GAAG,IAAI,GAAG,EAA4B,CAAC;IAEtD,MAAM,IAAI,GAAG,CAAC,KAAQ,EAAK,EAAE;QAC3B,MAAM,WAAW,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QACtC,MAAM,UAAU,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,UAAU,KAAK,SAAS;YAAE,OAAO,KAAK,CAAC;QAE3C,MAAM,IAAI,GAAG,KAAK,CAAC;QACnB,KAAK,GAAG,UAAU,CAAC,EAAE,CAAC;QAEtB,mIAAmI;QACnI,IAAI,SAAS,CAAC,UAAU,CAAC,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;YAC/C,GAAG,GAAG,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC/B,CAAC;QAED,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;YACjC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;QAC/B,CAAC;QAED,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,CAAC,KAAQ,EAAa,EAAE;QACtC,MAAM,WAAW,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC;QACtC,IAAI,WAAW,CAAC,KAAK,CAAC,KAAK,SAAS;YAAE,OAAO,IAAI,CAAC;QAClD,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3B,CAAC,CAAC;IAEF,MAAM,YAAY,GAAG,CAAC,QAAkC,EAAgB,EAAE;QACxE,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxB,OAAO,GAAG,EAAE,GAAG,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/C,CAAC,CAAC;IAEF,MAAM,IAAI,GAAG;QACX,OAAO,EAAE,GAAG,EAAE,CAAC,KAAK;QACpB,IAAI;QACJ,OAAO,EAAE,CAAC,CAAI,EAAE,EAAE,CAAC,KAAK,KAAK,CAAC;QAC9B,OAAO;QACP,YAAY;QACZ,KAAK,EAAE,GAAG,EAAE;YACV,KAAK,GAAG,OAAO,CAAC;YAChB,GAAG,GAAG,cAAc,CAAC;QACvB,CAAC;KACF,CAAC;IAEF,IAAI,cAAc,KAAK,SAAS,EAAE,CAAC;QACjC,OAAO;YACL,GAAG,IAAI;YACP,yEAAyE;YACzE,OAAO,EAAE,GAAG,EAAE,CAAC,GAAQ;SACxB,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/eidos/strategy/strategy.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Functional Strategy Pattern.
+ *
+ * In OOP, the Strategy pattern requires an interface, concrete classes, and a
+ * context class to swap algorithms at runtime. In functional TypeScript, a
+ * strategy is simply a function - the pattern becomes composition.
+ *
+ * @module eidos/strategy
+ * @since 2.4.0
+ *
+ * @see {@link https://pithos.dev/api/eidos/strategy/ | Explanations, examples and live demo}
+ *
+ * @example
+ * ```ts
+ * import { type Strategy, createStrategies, safeStrategy } from "@pithos/core/eidos/strategy";
+ *
+ * const sorting = createStrategies({
+ *   asc: (data: number[]) => [...data].sort((a, b) => a - b),
+ *   desc: (data: number[]) => [...data].sort((a, b) => b - a),
+ * });
+ *
+ * sorting.execute("asc", [3, 1, 2]);  // [1, 2, 3]
+ * sorting.use("desc")([3, 1, 2]);     // [3, 2, 1]
+ * ```
+ */
+import type { Result } from "../../zygos/result/result.js";
+import type { Option } from "../../zygos/option.js";
+import type { GenericSchema, Infer } from "../../kanon/types/base.js";
+/**
+ * A Strategy is a function that transforms an input into an output.
+ * This replaces the GoF Strategy interface + concrete classes.
+ *
+ * @template In - The input type
+ * @template Out - The output type
+ * @since 2.4.0
+ */
+export type Strategy<In, Out> = (input: In) => Out;
+/**
+ * Creates a strategy resolver from a record of named strategies.
+ * Replaces the GoF Context class - instead of `setStrategy()` + `execute()`,
+ * you simply pick a function by key and call it.
+ *
+ * @template K - Union of strategy keys
+ * @template In - The input type
+ * @template Out - The output type
+ * @param strategies - Record mapping keys to strategy functions
+ * @returns Resolver with `use` (get fn) and `execute` (run by key)
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const pricing = createStrategies({
+ *   regular: (price: number) => price,
+ *   vip: (price: number) => price * 0.8,
+ *   premium: (price: number) => price * 0.7,
+ * });
+ *
+ * const applyVip = pricing.use("vip");
+ * applyVip(100); // 80
+ *
+ * pricing.execute("premium", 100); // 70
+ *
+ * // Safe lookup for dynamic keys (e.g. from config)
+ * const key: string = getFromConfig();
+ * pricing.get(key); // Option<Strategy<number, number>>
+ * ```
+ */
+export declare function createStrategies<K extends string, In, Out>(strategies: Record<K, Strategy<In, Out>>): {
+    /** Get a strategy by key. Typed keys only. */
+    use: (key: K) => Strategy<In, Out>;
+    /** Execute a strategy by key with the given input. */
+    execute: (key: K, input: In) => Out;
+    /** Safe lookup for dynamic/runtime keys. Returns `Option<Strategy>`. */
+    get: (key: string) => Option<Strategy<In, Out>>;
+};
+/**
+ * Wraps a strategy to return a zygos `Result` instead of throwing.
+ * Catches any exception and wraps it in `Err<Error>`.
+ *
+ * @deprecated Use `Result.fromThrowable` from `@zygos/result/result` instead.
+ *
+ * ```ts
+ * import { Result } from "../../zygos/result/result.js";
+ *
+ * const safeParseJson = Result.fromThrowable(
+ *   (input: string) => JSON.parse(input),
+ *   (e) => e instanceof Error ? e : new Error(String(e)),
+ * );
+ * safeParseJson('{"ok":true}'); // Ok({ ok: true })
+ * safeParseJson("invalid");     // Err(SyntaxError(...))
+ * ```
+ *
+ * @see {@link https://pithos.dev/api/eidos/strategy/ | Full explanation, examples and live demo}
+ * @template In - The input type
+ * @template Out - The output type
+ * @param strategy - The strategy to make safe
+ * @returns A new strategy returning `Result<Out, Error>`
+ * @since 2.4.0
+ */
+export declare function safeStrategy<In, Out>(strategy: Strategy<In, Out>): Strategy<In, Result<Out, Error>>;
+/**
+ * Composes a primary strategy with a fallback.
+ * If the primary throws, the fallback is executed instead.
+ *
+ * @template In - The input type
+ * @template Out - The output type
+ * @param primary - The strategy to try first
+ * @param fallback - The strategy to use if primary throws
+ * @returns A new combined strategy
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const fromCache: Strategy<string, Data> = (key) => cache.get(key);
+ * const fromApi: Strategy<string, Data> = (key) => api.fetch(key);
+ *
+ * const fetchData = withFallback(fromCache, fromApi);
+ * fetchData("user:123"); // tries cache, falls back to API
+ * ```
+ */
+export declare function withFallback<In, Out>(primary: Strategy<In, Out>, fallback: Strategy<In, Out>): Strategy<In, Out>;
+/**
+ * Validates input against a kanon schema before executing the strategy.
+ * Bridges kanon validation, zygos Result, and the strategy pattern.
+ *
+ * @template S - The kanon schema type
+ * @template Out - The output type of the strategy
+ * @param schema - Kanon schema to validate input against
+ * @param strategy - Strategy to execute on validated input
+ * @returns A function accepting unknown input and returning `Result<Out, string>`
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { number } from "@pithos/core/kanon";
+ *
+ * const double = withValidation(
+ *   number().min(0),
+ *   (n) => n * 2,
+ * );
+ *
+ * double(5);       // Ok(10)
+ * double(-1);      // Err("Number must be >= 0")
+ * double("hello"); // Err("Expected number")
+ * ```
+ */
+export declare function withValidation<S extends GenericSchema, Out>(schema: S, strategy: Strategy<Infer<S>, Out>): (input: unknown) => Result<Out, string>;
+//# sourceMappingURL=strategy.d.ts.map

package/dist/eidos/strategy/strategy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"strategy.d.ts","sourceRoot":"","sources":["../../../src/eidos/strategy/strategy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAKH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACnD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE9D;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,EAAE,KAAK,GAAG,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,MAAM,EAAE,EAAE,EAAE,GAAG,EACxD,UAAU,EAAE,MAAM,CAAC,CAAC,EAAE,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;IAGtC,8CAA8C;eACnC,CAAC,KAAG,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC;IAChC,sDAAsD;mBACvC,CAAC,SAAS,EAAE,KAAG,GAAG;IACjC,wEAAwE;eAC7D,MAAM,KAAG,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;EAQhD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,GAAG,EAClC,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,GAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC,CAQlC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,YAAY,CAAC,EAAE,EAAE,GAAG,EAClC,OAAO,EAAE,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,EAC1B,QAAQ,EAAE,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,GAC1B,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAQnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,aAAa,EAAE,GAAG,EACzD,MAAM,EAAE,CAAC,EACT,QAAQ,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,GAChC,CAAC,KAAK,EAAE,OAAO,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAEzC"}