@pithos/core 2.3.0 → 2.5.0

package/dist/eidos/proxy/proxy.js

@@ -0,0 +1,121 @@
+/**
+ * Functional Proxy Pattern.
+ *
+ * In OOP, the Proxy pattern requires a Subject interface, a RealSubject class,
+ * and a Proxy class that wraps it to control access (lazy init, caching,
+ * access control, logging...).
+ * In functional TypeScript, Proxy provides ready-made higher-order functions
+ * for the most common proxy use cases.
+ *
+ * Compared to Decorator (generic hooks via before/after/around), Proxy
+ * offers opinionated, named wrappers for specific access-control scenarios.
+ *
+ * Several proxy use cases are already covered by arkhe utilities,
+ * re-exported here for discoverability:
+ * - `memoize` - caching proxy with custom key resolvers, cache injection (LRU, TTL)
+ * - `once` - single-use proxy, executes once then caches the result
+ * - `throttle` - rate-limiting proxy, at most one call per time window
+ * - `debounce` - debounce proxy, defers execution until inactivity
+ *
+ * @module eidos/proxy
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { lazy, memoize, once, throttle, guarded } from "@pithos/core/eidos/proxy/proxy";
+ *
+ * // Lazy initialization proxy
+ * const query = lazy(() => {
+ *   const conn = createConnection();
+ *   return (sql: string) => conn.execute(sql);
+ * });
+ *
+ * // Caching proxy
+ * const fetchUser = memoize((id: string) => db.query(id));
+ *
+ * // Single-use proxy
+ * const init = once(() => bootstrap());
+ *
+ * // Rate-limiting proxy
+ * const onScroll = throttle(() => recalcLayout(), 200);
+ *
+ * // Access control proxy
+ * const deleteUser = guarded(
+ *   (id: string) => db.delete(id),
+ *   (id) => id !== "admin" ? true : "Cannot delete admin",
+ * );
+ * ```
+ */
+import { ok, err } from "../../zygos/result/result.js";
+/** Caching proxy - re-exported from arkhe for discoverability. */
+export { memoize } from "../../arkhe/function/memoize.js";
+/** Single-use proxy - re-exported from arkhe for discoverability. */
+export { once } from "../../arkhe/function/once.js";
+/** Rate-limiting proxy - re-exported from arkhe for discoverability. */
+export { throttle } from "../../arkhe/function/throttle.js";
+/** Debounce proxy - re-exported from arkhe for discoverability. */
+export { debounce } from "../../arkhe/function/debounce.js";
+/**
+ * Lazy proxy - defers function creation until first call.
+ * The factory is called once on the first invocation, then
+ * the created function is used directly for all subsequent calls.
+ *
+ * @template In - The input type
+ * @template Out - The output type
+ * @param factory - A function that creates the real function on demand
+ * @returns A proxy that initializes lazily
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * // Expensive connection is only created when first needed
+ * const query = lazy(() => {
+ *   const conn = createConnection(); // heavy init
+ *   return (sql: string) => conn.execute(sql);
+ * });
+ *
+ * // Nothing happens yet...
+ * query("SELECT 1"); // NOW the connection is created, then query runs
+ * query("SELECT 2"); // reuses the same connection
+ * ```
+ */
+export function lazy(factory) {
+    let fn = null;
+    return (input) => {
+        if (!fn)
+            fn = factory();
+        return fn(input);
+    };
+}
+/**
+ * Guarded proxy - checks access before calling the function.
+ * The check returns `true` to allow, or a rejection reason string to deny.
+ * Returns a zygos `Result`: `Ok(output)` if allowed, `Err(reason)` if denied.
+ *
+ * @template In - The input type
+ * @template Out - The output type
+ * @param fn - The function to guard
+ * @param check - Access check. Return `true` to allow, or a string reason to deny.
+ * @returns A proxy returning `Result<Out, string>`
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const deleteUser = guarded(
+ *   (id: string) => db.delete(id),
+ *   (id) => id !== "admin" ? true : "Cannot delete admin user",
+ * );
+ *
+ * deleteUser("user-1"); // Ok(void)
+ * deleteUser("admin");  // Err("Cannot delete admin user")
+ * ```
+ */
+export function guarded(fn, check) {
+    return (input) => {
+        const result = check(input);
+        if (result !== true)
+            return err(result);
+        return ok(fn(input));
+    };
+}
+//# sourceMappingURL=proxy.js.map

package/dist/eidos/proxy/proxy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.js","sourceRoot":"","sources":["../../../src/eidos/proxy/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAEH,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAG/C,kEAAkE;AAClE,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAGlD,qEAAqE;AACrE,OAAO,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAE5C,wEAAwE;AACxE,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD,mEAAmE;AACnE,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,IAAI,CAClB,OAAiC;IAEjC,IAAI,EAAE,GAAgC,IAAI,CAAC;IAC3C,OAAO,CAAC,KAAS,EAAO,EAAE;QACxB,IAAI,CAAC,EAAE;YAAE,EAAE,GAAG,OAAO,EAAE,CAAC;QACxB,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,OAAO,CACrB,EAAsB,EACtB,KAAmC;IAEnC,OAAO,CAAC,KAAS,EAAE,EAAE;QACnB,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,GAAG,CAAC,MAAM,CAAC,CAAC;QACxC,OAAO,EAAE,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC"}

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-lite.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Lightweight State Machine — zero external dependencies.
+ *
+ * Same core API as {@link createMachine} (`current`, `send`, `matches`,
+ * `onTransition`, `reset`) but without `trySend` (which pulls `@zygos/option`).
+ *
+ * @module eidos/state/state-lite
+ * @since 2.5.0
+ *
+ * @example
+ * ```ts
+ * import { createLiteMachine } from "@pithos/core/eidos/state/state-lite";
+ *
+ * const light = createLiteMachine({
+ *   green:  { timer: { to: "yellow" } },
+ *   yellow: { timer: { to: "red" } },
+ *   red:    { timer: { to: "green" } },
+ * }, "green");
+ *
+ * light.current();      // "green"
+ * light.send("timer");  // "yellow"
+ * ```
+ */
+/** A simple transition to a target state. */
+export interface SimpleTransition<S extends string> {
+    readonly to: S;
+}
+/**
+ * A transition that also updates context.
+ *
+ * @since 2.5.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.
+ *
+ * @since 2.5.0
+ */
+export type Transition<S extends string, C> = SimpleTransition<S> | ContextTransition<S, C>;
+/**
+ * A transition map for a single state.
+ *
+ * @since 2.5.0
+ */
+export type Transitions<S extends string, E extends string, C> = {
+    readonly [K in E]?: Transition<S, C>;
+};
+/**
+ * Full state machine definition.
+ *
+ * @since 2.5.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.
+ *
+ * @since 2.5.0
+ */
+export type TransitionListener<S extends string, E extends string> = (from: S, event: E, to: S) => void;
+/**
+ * Creates a lightweight finite state machine (no `trySend`, no `@zygos/option` dependency).
+ *
+ * @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`, `onTransition`, `reset`
+ * @since 2.5.0
+ */
+export declare function createLiteMachine<S extends string, E extends string>(definition: MachineDefinition<S, E, undefined>, initial: S): {
+    current: () => S;
+    send: (event: E) => S;
+    matches: (state: S) => boolean;
+    onTransition: (listener: TransitionListener<S, E>) => () => void;
+    reset: () => void;
+};
+/**
+ * Creates a lightweight 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`, `onTransition`, `reset`
+ * @since 2.5.0
+ */
+export declare function createLiteMachine<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;
+    onTransition: (listener: TransitionListener<S, E>) => () => void;
+    reset: () => void;
+};
+//# sourceMappingURL=state-lite.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state-lite.d.ts","sourceRoot":"","sources":["../../../src/eidos/state/state-lite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,6CAA6C;AAC7C,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM;IAChD,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC;IACpD,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;IACf,QAAQ,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;CAChC;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,IACtC,gBAAgB,CAAC,CAAC,CAAC,GACnB,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAE5B;;;;GAIG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAAE,CAAC,IAAI;IAC/D,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC;CACrC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAAE,CAAC,IAAI;IACrE,QAAQ,EAAE,CAAC,IAAI,CAAC,GAAG,WAAW,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;CACxC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,IAAI,CACnE,IAAI,EAAE,CAAC,EACP,KAAK,EAAE,CAAC,EACR,EAAE,EAAE,CAAC,KACF,IAAI,CAAC;AAQV;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAClE,UAAU,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,SAAS,CAAC,EAC9C,OAAO,EAAE,CAAC,GACT;IACD,OAAO,EAAE,MAAM,CAAC,CAAC;IACjB,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;IACtB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAC/B,YAAY,EAAE,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC;IACjE,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,MAAM,EAAE,CAAC,EACrE,UAAU,EAAE,iBAAiB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EACtC,OAAO,EAAE,CAAC,EACV,cAAc,EAAE,CAAC,GAChB;IACD,OAAO,EAAE,MAAM,CAAC,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC,CAAC;IACjB,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;IACtB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC;IAC/B,YAAY,EAAE,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,MAAM,IAAI,CAAC;IACjE,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB,CAAC"}

package/dist/eidos/state/state-lite.js

@@ -0,0 +1,69 @@
+/**
+ * Lightweight State Machine — zero external dependencies.
+ *
+ * Same core API as {@link createMachine} (`current`, `send`, `matches`,
+ * `onTransition`, `reset`) but without `trySend` (which pulls `@zygos/option`).
+ *
+ * @module eidos/state/state-lite
+ * @since 2.5.0
+ *
+ * @example
+ * ```ts
+ * import { createLiteMachine } from "@pithos/core/eidos/state/state-lite";
+ *
+ * const light = createLiteMachine({
+ *   green:  { timer: { to: "yellow" } },
+ *   yellow: { timer: { to: "red" } },
+ *   red:    { timer: { to: "green" } },
+ * }, "green");
+ *
+ * light.current();      // "green"
+ * light.send("timer");  // "yellow"
+ * ```
+ */
+function hasUpdate(t) {
+    return "update" in t;
+}
+export function createLiteMachine(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 onTransition = (listener) => {
+        listeners.add(listener);
+        return () => { listeners.delete(listener); };
+    };
+    const base = {
+        current: () => state,
+        send,
+        matches: (s) => state === s,
+        onTransition,
+        reset: () => {
+            state = initial;
+            ctx = initialContext;
+        },
+    };
+    if (initialContext !== undefined) {
+        return {
+            ...base,
+            context: () => ctx,
+        };
+    }
+    return base;
+}
+//# sourceMappingURL=state-lite.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"state-lite.js","sourceRoot":"","sources":["../../../src/eidos/state/state-lite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAuDH,SAAS,SAAS,CAChB,CAAmB;IAEnB,OAAO,QAAQ,IAAI,CAAC,CAAC;AACvB,CAAC;AAgDD,MAAM,UAAU,iBAAiB,CAC/B,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,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,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,OAAO,EAAE,GAAG,EAAE,CAAC,GAAQ;SACxB,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,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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"}