@pithos/core 2.2.2 → 2.4.0

package/dist/eidos/memento/memento.js

@@ -0,0 +1,114 @@
+/**
+ * Functional Memento Pattern.
+ *
+ * In OOP, the Memento pattern requires an Originator class that creates
+ * snapshots, a Memento class that stores state, and a Caretaker that manages
+ * the history.
+ *
+ * In functional TypeScript with immutable data, state is already a snapshot.
+ * The pattern simplifies to a history manager that tracks state changes
+ * and enables undo/redo.
+ *
+ * ## Memento vs Command for undo/redo
+ *
+ * - **Memento** (`createHistory`): stores *state snapshots*.
+ *   Undo restores the previous state. Use when state is cheap to copy.
+ *
+ * - **Command** (`createCommandStack`): stores *actions* with their inverses.
+ *   Undo calls the command's undo function. Use when you have reversible operations.
+ *
+ * @module eidos/memento
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { createHistory } from "@pithos/core/eidos/memento/memento";
+ *
+ * type EditorState = { content: string; cursor: number };
+ *
+ * const history = createHistory<EditorState>({ content: "", cursor: 0 });
+ *
+ * history.push({ content: "Hello", cursor: 5 });
+ * history.push({ content: "Hello World", cursor: 11 });
+ *
+ * history.current(); // { content: "Hello World", cursor: 11 }
+ * history.undo();    // Some({ content: "Hello", cursor: 5 })
+ * history.redo();    // Some({ content: "Hello World", cursor: 11 })
+ * ```
+ */
+import { some, none } from "../../zygos/option.js";
+/**
+ * Creates a history manager for undo/redo functionality.
+ *
+ * Tracks state changes as snapshots. Pushing a new state clears any
+ * redo history (standard undo/redo behavior).
+ *
+ * @template T - The state type
+ * @param initial - The initial state
+ * @returns A history manager
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const history = createHistory({ count: 0 });
+ *
+ * history.push({ count: 1 });
+ * history.push({ count: 2 });
+ * history.push({ count: 3 });
+ *
+ * history.undo(); // Some({ count: 2 })
+ * history.undo(); // Some({ count: 1 })
+ * history.redo(); // Some({ count: 2 })
+ *
+ * // New push clears redo stack
+ * history.push({ count: 10 });
+ * history.canRedo(); // false
+ * ```
+ */
+export function createHistory(initial) {
+    const undoStack = [{ state: initial, timestamp: Date.now() }];
+    const redoStack = [];
+    return {
+        current() {
+            return undoStack[undoStack.length - 1].state;
+        },
+        push(state) {
+            undoStack.push({ state, timestamp: Date.now() });
+            redoStack.length = 0;
+        },
+        undo() {
+            if (undoStack.length <= 1)
+                return none;
+            const lastIndex = undoStack.length - 1;
+            const snapshot = undoStack[lastIndex];
+            undoStack.length = lastIndex;
+            redoStack.push(snapshot);
+            return some(undoStack[undoStack.length - 1].state);
+        },
+        redo() {
+            if (redoStack.length === 0)
+                return none;
+            const lastIndex = redoStack.length - 1;
+            const snapshot = redoStack[lastIndex];
+            redoStack.length = lastIndex;
+            undoStack.push(snapshot);
+            return some(undoStack[undoStack.length - 1].state);
+        },
+        canUndo() {
+            return undoStack.length > 1;
+        },
+        canRedo() {
+            return redoStack.length > 0;
+        },
+        history() {
+            return undoStack;
+        },
+        clear() {
+            const current = undoStack[undoStack.length - 1];
+            undoStack.length = 0;
+            undoStack.push(current);
+            redoStack.length = 0;
+        },
+    };
+}
+//# sourceMappingURL=memento.js.map

package/dist/eidos/memento/memento.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memento.js","sourceRoot":"","sources":["../../../src/eidos/memento/memento.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAuC3C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,aAAa,CAAI,OAAU;IACzC,MAAM,SAAS,GAAkB,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;IAC7E,MAAM,SAAS,GAAkB,EAAE,CAAC;IAEpC,OAAO;QACL,OAAO;YACL,OAAO,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC;QAC/C,CAAC;QAED,IAAI,CAAC,KAAQ;YACX,SAAS,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC;YACjD,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;QACvB,CAAC;QAED,IAAI;YACF,IAAI,SAAS,CAAC,MAAM,IAAI,CAAC;gBAAE,OAAO,IAAI,CAAC;YACvC,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;YACvC,MAAM,QAAQ,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;YACtC,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC;YAC7B,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzB,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACrD,CAAC;QAED,IAAI;YACF,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YACxC,MAAM,SAAS,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;YACvC,MAAM,QAAQ,GAAG,SAAS,CAAC,SAAS,CAAC,CAAC;YACtC,SAAS,CAAC,MAAM,GAAG,SAAS,CAAC;YAC7B,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;YACzB,OAAO,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;QACrD,CAAC;QAED,OAAO;YACL,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;QAC9B,CAAC;QAED,OAAO;YACL,OAAO,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;QAC9B,CAAC;QAED,OAAO;YACL,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,KAAK;YACH,MAAM,OAAO,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;YAChD,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;YACrB,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YACxB,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC;QACvB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/eidos/observer/observer.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Functional Observer Pattern.
+ *
+ * In OOP, the Observer pattern requires Subject/Observer interfaces,
+ * concrete classes, and manual attach/detach management.
+ * In functional TypeScript, it's a Set of callbacks behind a closure.
+ *
+ * @module eidos/observer
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { createObservable } from "@pithos/core/eidos/observer/observer";
+ *
+ * const onClick = createObservable<{ x: number; y: number }>();
+ *
+ * const unsub = onClick.subscribe(({ x, y }) => console.log(x, y));
+ * onClick.notify({ x: 10, y: 20 }); // logs: 10 20
+ * unsub();
+ * onClick.notify({ x: 30, y: 40 }); // nothing - unsubscribed
+ * ```
+ */
+import type { Result } from "../../zygos/result/result.js";
+/**
+ * A listener is a callback that reacts to emitted values.
+ * Replaces the GoF Observer interface.
+ *
+ * @template T - The value type
+ * @since 2.4.0
+ */
+export type Listener<T> = (value: T) => void;
+/**
+ * A function that removes a listener when called.
+ * Replaces the GoF `detach(observer)` method.
+ *
+ * @since 2.4.0
+ */
+export type Unsubscribe = () => void;
+/**
+ * Creates an observable (pub/sub emitter).
+ * Replaces the GoF Subject class - no interface, no attach/detach ceremony,
+ * just subscribe and get back an unsubscribe function.
+ *
+ * @template T - The type of values emitted to listeners
+ * @returns Observable with `subscribe`, `notify`, `once`, `safeNotify`, `size`, `clear`
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const onUserLogin = createObservable<{ id: string; name: string }>();
+ *
+ * // Subscribe - returns an unsubscribe function
+ * const unsub = onUserLogin.subscribe((user) => {
+ *   console.log(`${user.name} logged in`);
+ * });
+ *
+ * // One-time listener
+ * onUserLogin.once((user) => {
+ *   sendWelcomeEmail(user);
+ * });
+ *
+ * onUserLogin.notify({ id: "1", name: "Alice" });
+ * unsub();
+ * ```
+ */
+export declare function createObservable<T>(): {
+    /** Add a listener. Returns an unsubscribe function. */
+    subscribe: (listener: Listener<T>) => Unsubscribe;
+    /**
+     * Emit a value to all listeners. Fail-fast: if a listener throws,
+     * the error propagates and subsequent listeners are not called.
+     * Use `safeNotify` for resilient notification.
+     */
+    notify: (value: T) => void;
+    /**
+     * Subscribe for a single notification, then auto-unsubscribe.
+     * The listener is wrapped internally - always use the returned
+     * `Unsubscribe` function to cancel before it fires.
+     */
+    once: (listener: Listener<T>) => Unsubscribe;
+    /**
+     * Emit a value to all listeners with error safety.
+     * Unlike `notify`, this catches listener errors and continues
+     * notifying remaining listeners. Returns a zygos `Result`:
+     * - `Ok(void)` if all listeners succeeded
+     * - `Err(Error[])` with collected errors from failing listeners
+     *
+     * @since 2.4.0
+     */
+    safeNotify: (value: T) => Result<void, Error[]>;
+    /** Current number of listeners. */
+    readonly size: number;
+    /** Remove all listeners. */
+    clear: () => void;
+};
+//# sourceMappingURL=observer.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../../src/eidos/observer/observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEnD;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,gBAAgB,CAAC,CAAC;IAI9B,uDAAuD;0BACjC,QAAQ,CAAC,CAAC,CAAC,KAAG,WAAW;IAO/C;;;;OAIG;oBACa,CAAC,KAAG,IAAI;IAMxB;;;;OAIG;qBACc,QAAQ,CAAC,CAAC,CAAC,KAAG,WAAW;IAW1C;;;;;;;;OAQG;wBACiB,CAAC,KAAG,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC;IAc7C,mCAAmC;mBACvB,MAAM;IAIlB,4BAA4B;iBACjB,IAAI;EAIlB"}

package/dist/eidos/observer/observer.js

@@ -0,0 +1,117 @@
+/**
+ * Functional Observer Pattern.
+ *
+ * In OOP, the Observer pattern requires Subject/Observer interfaces,
+ * concrete classes, and manual attach/detach management.
+ * In functional TypeScript, it's a Set of callbacks behind a closure.
+ *
+ * @module eidos/observer
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { createObservable } from "@pithos/core/eidos/observer/observer";
+ *
+ * const onClick = createObservable<{ x: number; y: number }>();
+ *
+ * const unsub = onClick.subscribe(({ x, y }) => console.log(x, y));
+ * onClick.notify({ x: 10, y: 20 }); // logs: 10 20
+ * unsub();
+ * onClick.notify({ x: 30, y: 40 }); // nothing - unsubscribed
+ * ```
+ */
+import { ok, err } from "../../zygos/result/result.js";
+/**
+ * Creates an observable (pub/sub emitter).
+ * Replaces the GoF Subject class - no interface, no attach/detach ceremony,
+ * just subscribe and get back an unsubscribe function.
+ *
+ * @template T - The type of values emitted to listeners
+ * @returns Observable with `subscribe`, `notify`, `once`, `safeNotify`, `size`, `clear`
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const onUserLogin = createObservable<{ id: string; name: string }>();
+ *
+ * // Subscribe - returns an unsubscribe function
+ * const unsub = onUserLogin.subscribe((user) => {
+ *   console.log(`${user.name} logged in`);
+ * });
+ *
+ * // One-time listener
+ * onUserLogin.once((user) => {
+ *   sendWelcomeEmail(user);
+ * });
+ *
+ * onUserLogin.notify({ id: "1", name: "Alice" });
+ * unsub();
+ * ```
+ */
+export function createObservable() {
+    const listeners = new Set();
+    return {
+        /** Add a listener. Returns an unsubscribe function. */
+        subscribe: (listener) => {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        /**
+         * Emit a value to all listeners. Fail-fast: if a listener throws,
+         * the error propagates and subsequent listeners are not called.
+         * Use `safeNotify` for resilient notification.
+         */
+        notify: (value) => {
+            for (const listener of listeners) {
+                listener(value);
+            }
+        },
+        /**
+         * Subscribe for a single notification, then auto-unsubscribe.
+         * The listener is wrapped internally - always use the returned
+         * `Unsubscribe` function to cancel before it fires.
+         */
+        once: (listener) => {
+            const wrapper = (value) => {
+                listeners.delete(wrapper);
+                listener(value);
+            };
+            listeners.add(wrapper);
+            return () => {
+                listeners.delete(wrapper);
+            };
+        },
+        /**
+         * Emit a value to all listeners with error safety.
+         * Unlike `notify`, this catches listener errors and continues
+         * notifying remaining listeners. Returns a zygos `Result`:
+         * - `Ok(void)` if all listeners succeeded
+         * - `Err(Error[])` with collected errors from failing listeners
+         *
+         * @since 2.4.0
+         */
+        safeNotify: (value) => {
+            const errors = [];
+            for (const listener of listeners) {
+                try {
+                    listener(value);
+                }
+                catch (error) {
+                    errors.push(error instanceof Error ? error : new Error(String(error)));
+                }
+            }
+            return errors.length > 0 ? err(errors) : ok(undefined);
+        },
+        /** Current number of listeners. */
+        get size() {
+            return listeners.size;
+        },
+        /** Remove all listeners. */
+        clear: () => {
+            listeners.clear();
+        },
+    };
+}
+//# sourceMappingURL=observer.js.map

package/dist/eidos/observer/observer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.js","sourceRoot":"","sources":["../../../src/eidos/observer/observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAoB/C;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,gBAAgB;IAC9B,MAAM,SAAS,GAAG,IAAI,GAAG,EAAe,CAAC;IAEzC,OAAO;QACL,uDAAuD;QACvD,SAAS,EAAE,CAAC,QAAqB,EAAe,EAAE;YAChD,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;YACxB,OAAO,GAAG,EAAE;gBACV,SAAS,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;YAC7B,CAAC,CAAC;QACJ,CAAC;QAED;;;;WAIG;QACH,MAAM,EAAE,CAAC,KAAQ,EAAQ,EAAE;YACzB,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBACjC,QAAQ,CAAC,KAAK,CAAC,CAAC;YAClB,CAAC;QACH,CAAC;QAED;;;;WAIG;QACH,IAAI,EAAE,CAAC,QAAqB,EAAe,EAAE;YAC3C,MAAM,OAAO,GAAgB,CAAC,KAAK,EAAE,EAAE;gBACrC,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;gBAC1B,QAAQ,CAAC,KAAK,CAAC,CAAC;YAClB,CAAC,CAAC;YACF,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;YACvB,OAAO,GAAG,EAAE;gBACV,SAAS,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;YAC5B,CAAC,CAAC;QACJ,CAAC;QAED;;;;;;;;WAQG;QACH,UAAU,EAAE,CAAC,KAAQ,EAAyB,EAAE;YAC9C,MAAM,MAAM,GAAY,EAAE,CAAC;YAC3B,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;gBACjC,IAAI,CAAC;oBACH,QAAQ,CAAC,KAAK,CAAC,CAAC;gBAClB,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,MAAM,CAAC,IAAI,CACT,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAC1D,CAAC;gBACJ,CAAC;YACH,CAAC;YACD,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,CAAC,CAAC;QACzD,CAAC;QAED,mCAAmC;QACnC,IAAI,IAAI;YACN,OAAO,SAAS,CAAC,IAAI,CAAC;QACxB,CAAC;QAED,4BAA4B;QAC5B,KAAK,EAAE,GAAS,EAAE;YAChB,SAAS,CAAC,KAAK,EAAE,CAAC;QACpB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/eidos/prototype/prototype.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Functional Prototype Pattern.
+ *
+ * In OOP, the Prototype pattern requires a `clone()` method on objects to
+ * create copies without coupling to concrete classes.
+ *
+ * In functional TypeScript with immutable data, this is covered by Arkhe:
+ * - `deepClone` for deep copies (handles circular refs, Date, Map, Set, etc.)
+ * - `deepCloneFull` for binary data (TypedArrays, ArrayBuffer, Blob, File)
+ * - Spread operator `{ ...obj }` for shallow copies
+ *
+ * This module re-exports Arkhe's clone functions for discoverability.
+ *
+ * @module eidos/prototype
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { deepClone } from "@pithos/core/eidos/prototype/prototype";
+ * // or directly from Arkhe:
+ * import { deepClone } from "../../arkhe/object/deep-clone.js";
+ *
+ * const original = { a: 1, b: { c: 2 }, d: new Map([["x", 1]]) };
+ * const cloned = deepClone(original);
+ *
+ * // For shallow copies, just use spread:
+ * const shallow = { ...original, a: 99 };
+ * ```
+ */
+export { deepClone } from "../../arkhe/object/deep-clone.js";
+export { deepCloneFull } from "../../arkhe/object/deep-clone-full.js";
+//# sourceMappingURL=prototype.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"prototype.d.ts","sourceRoot":"","sources":["../../../src/eidos/prototype/prototype.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/eidos/prototype/prototype.js

@@ -0,0 +1,33 @@
+/**
+ * Functional Prototype Pattern.
+ *
+ * In OOP, the Prototype pattern requires a `clone()` method on objects to
+ * create copies without coupling to concrete classes.
+ *
+ * In functional TypeScript with immutable data, this is covered by Arkhe:
+ * - `deepClone` for deep copies (handles circular refs, Date, Map, Set, etc.)
+ * - `deepCloneFull` for binary data (TypedArrays, ArrayBuffer, Blob, File)
+ * - Spread operator `{ ...obj }` for shallow copies
+ *
+ * This module re-exports Arkhe's clone functions for discoverability.
+ *
+ * @module eidos/prototype
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { deepClone } from "@pithos/core/eidos/prototype/prototype";
+ * // or directly from Arkhe:
+ * import { deepClone } from "../../arkhe/object/deep-clone.js";
+ *
+ * const original = { a: 1, b: { c: 2 }, d: new Map([["x", 1]]) };
+ * const cloned = deepClone(original);
+ *
+ * // For shallow copies, just use spread:
+ * const shallow = { ...original, a: 99 };
+ * ```
+ */
+// Re-export from Arkhe for discoverability
+export { deepClone } from "../../arkhe/object/deep-clone.js";
+export { deepCloneFull } from "../../arkhe/object/deep-clone-full.js";
+//# sourceMappingURL=prototype.js.map

package/dist/eidos/prototype/prototype.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prototype.js","sourceRoot":"","sources":["../../../src/eidos/prototype/prototype.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,2CAA2C;AAC3C,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/eidos/proxy/proxy.d.ts

@@ -0,0 +1,108 @@
+/**
+ * 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 type { Result } from "../../zygos/result/result.js";
+/** Caching proxy - re-exported from arkhe for discoverability. */
+export { memoize } from "../../arkhe/function/memoize.js";
+export type { MemoizedFunction, MemoizeOptions, MemoizeCache } 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 declare function lazy<In, Out>(factory: () => (input: In) => Out): (input: In) => Out;
+/**
+ * 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 declare function guarded<In, Out>(fn: (input: In) => Out, check: (input: In) => true | string): (input: In) => Result<Out, string>;
+//# sourceMappingURL=proxy.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../../../src/eidos/proxy/proxy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAEnD,kEAAkE;AAClE,OAAO,EAAE,OAAO,EAAE,MAAM,yBAAyB,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE9F,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,wBAAgB,IAAI,CAAC,EAAE,EAAE,GAAG,EAC1B,OAAO,EAAE,MAAM,CAAC,KAAK,EAAE,EAAE,KAAK,GAAG,GAChC,CAAC,KAAK,EAAE,EAAE,KAAK,GAAG,CAMpB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CAAC,EAAE,EAAE,GAAG,EAC7B,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,GAAG,EACtB,KAAK,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,IAAI,GAAG,MAAM,GAClC,CAAC,KAAK,EAAE,EAAE,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAMpC"}

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"}