@pithos/core 2.2.2 → 2.4.0

package/dist/eidos/composite/composite.d.ts

@@ -0,0 +1,168 @@
+/**
+ * Functional Composite Pattern.
+ *
+ * In OOP, the Composite pattern requires a Component interface, Leaf classes,
+ * and Composite classes that hold children and delegate operations recursively.
+ * In functional TypeScript, a composite is a discriminated union (leaf | branch)
+ * with a fold function that traverses the tree.
+ *
+ * The key insight: treat leaves and branches uniformly via pattern matching,
+ * not inheritance. The fold function replaces the recursive `operation()` method.
+ *
+ * @module eidos/composite
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { leaf, branch, fold, map } from "@pithos/core/eidos/composite/composite";
+ *
+ * // File system tree
+ * type FSNode = Composite<{ name: string; size: number }>;
+ *
+ * const tree: FSNode = branch({ name: "root", size: 0 }, [
+ *   leaf({ name: "file1.txt", size: 100 }),
+ *   branch({ name: "docs", size: 0 }, [
+ *     leaf({ name: "readme.md", size: 50 }),
+ *   ]),
+ * ]);
+ *
+ * // Calculate total size
+ * const totalSize = fold(tree, {
+ *   leaf: (data) => data.size,
+ *   branch: (data, childResults) => childResults.reduce((a, b) => a + b, 0),
+ * });
+ * ```
+ */
+import type { Option } from "../../zygos/option.js";
+/**
+ * A Leaf node contains data but no children.
+ *
+ * @template T - The data type stored in nodes
+ * @since 2.4.0
+ */
+export type Leaf<T> = {
+    readonly type: "leaf";
+    readonly data: T;
+};
+/**
+ * A Branch node contains data and children.
+ *
+ * @template T - The data type stored in nodes
+ * @since 2.4.0
+ */
+export type Branch<T> = {
+    readonly type: "branch";
+    readonly data: T;
+    readonly children: ReadonlyArray<Composite<T>>;
+};
+/**
+ * A Composite is either a Leaf or a Branch.
+ * This discriminated union replaces the OOP Component/Leaf/Composite hierarchy.
+ *
+ * @template T - The data type stored in nodes
+ * @since 2.4.0
+ */
+export type Composite<T> = Leaf<T> | Branch<T>;
+/**
+ * Creates a leaf node.
+ *
+ * @template T - The data type
+ * @param data - The leaf's data
+ * @returns A Leaf node
+ * @since 2.4.0
+ */
+export declare function leaf<T>(data: T): Leaf<T>;
+/**
+ * Creates a branch node with children.
+ *
+ * @template T - The data type
+ * @param data - The branch's data
+ * @param children - Child nodes
+ * @returns A Branch node
+ * @since 2.4.0
+ */
+export declare function branch<T>(data: T, children: Composite<T>[]): Branch<T>;
+/**
+ * Handlers for folding over a composite tree.
+ *
+ * @template T - The data type in nodes
+ * @template R - The result type
+ * @since 2.4.0
+ */
+export type FoldHandlers<T, R> = {
+    /** Handle a leaf node. Receives the leaf's data. */
+    leaf: (data: T) => R;
+    /** Handle a branch node. Receives the branch's data and results from children. */
+    branch: (data: T, childResults: R[]) => R;
+};
+/**
+ * Folds over a composite tree, reducing it to a single value.
+ * This replaces the recursive `operation()` method from OOP Composite.
+ *
+ * @template T - The data type in nodes
+ * @template R - The result type
+ * @param node - The root node to fold
+ * @param handlers - Functions to handle leaf and branch nodes
+ * @returns The folded result
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * // Count all nodes
+ * const count = fold(tree, {
+ *   leaf: () => 1,
+ *   branch: (_, children) => 1 + children.reduce((a, b) => a + b, 0),
+ * });
+ *
+ * // Render to string
+ * const render = fold(tree, {
+ *   leaf: (data) => data.name,
+ *   branch: (data, children) => `${data.name}(${children.join(", ")})`,
+ * });
+ * ```
+ */
+export declare function fold<T, R>(node: Composite<T>, handlers: FoldHandlers<T, R>): R;
+/**
+ * Maps over a composite tree, transforming each node's data.
+ *
+ * @template T - The source data type
+ * @template U - The target data type
+ * @param node - The root node to map
+ * @param fn - Function to transform node data
+ * @returns A new tree with transformed data
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const doubled = map(tree, (data) => ({ ...data, size: data.size * 2 }));
+ * ```
+ */
+export declare function map<T, U>(node: Composite<T>, fn: (data: T) => U): Composite<U>;
+/**
+ * Flattens a composite tree into an array of all node data.
+ * Traverses depth-first, pre-order (parent before children).
+ *
+ * @template T - The data type
+ * @param node - The root node to flatten
+ * @returns Array of all node data
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const allFiles = flatten(tree);
+ * // [{ name: "root", ... }, { name: "file1.txt", ... }, ...]
+ * ```
+ */
+export declare function flatten<T>(node: Composite<T>): T[];
+/**
+ * Finds the first node matching a predicate (depth-first).
+ * Short-circuits on first match.
+ *
+ * @template T - The data type
+ * @param node - The root node to search
+ * @param predicate - Function to test each node
+ * @returns Option containing the matching node data
+ * @since 2.4.0
+ */
+export declare function find<T>(node: Composite<T>, predicate: (data: T) => boolean): Option<T>;
+//# sourceMappingURL=composite.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"composite.d.ts","sourceRoot":"","sources":["../../../src/eidos/composite/composite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,MAAM,IAAI,CAAC,CAAC,IAAI;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;CAClB,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,MAAM,CAAC,CAAC,IAAI;IACtB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;CAChD,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;AAE/C;;;;;;;GAOG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAExC;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,MAAM,CAAC,CAAC,CAAC,CAEtE;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,EAAE,CAAC,IAAI;IAC/B,oDAAoD;IACpD,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC;IACrB,kFAAkF;IAClF,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;CAC3C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,IAAI,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,CAM9E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,GAAG,SAAS,CAAC,CAAC,CAAC,CAQ9E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAKlD;AAED;;;;;;;;;GASG;AACH,wBAAgB,IAAI,CAAC,CAAC,EACpB,IAAI,EAAE,SAAS,CAAC,CAAC,CAAC,EAClB,SAAS,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,GAC9B,MAAM,CAAC,CAAC,CAAC,CASX"}

package/dist/eidos/composite/composite.js

@@ -0,0 +1,157 @@
+/**
+ * Functional Composite Pattern.
+ *
+ * In OOP, the Composite pattern requires a Component interface, Leaf classes,
+ * and Composite classes that hold children and delegate operations recursively.
+ * In functional TypeScript, a composite is a discriminated union (leaf | branch)
+ * with a fold function that traverses the tree.
+ *
+ * The key insight: treat leaves and branches uniformly via pattern matching,
+ * not inheritance. The fold function replaces the recursive `operation()` method.
+ *
+ * @module eidos/composite
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { leaf, branch, fold, map } from "@pithos/core/eidos/composite/composite";
+ *
+ * // File system tree
+ * type FSNode = Composite<{ name: string; size: number }>;
+ *
+ * const tree: FSNode = branch({ name: "root", size: 0 }, [
+ *   leaf({ name: "file1.txt", size: 100 }),
+ *   branch({ name: "docs", size: 0 }, [
+ *     leaf({ name: "readme.md", size: 50 }),
+ *   ]),
+ * ]);
+ *
+ * // Calculate total size
+ * const totalSize = fold(tree, {
+ *   leaf: (data) => data.size,
+ *   branch: (data, childResults) => childResults.reduce((a, b) => a + b, 0),
+ * });
+ * ```
+ */
+import { some, none } from "../../zygos/option.js";
+/**
+ * Creates a leaf node.
+ *
+ * @template T - The data type
+ * @param data - The leaf's data
+ * @returns A Leaf node
+ * @since 2.4.0
+ */
+export function leaf(data) {
+    return { type: "leaf", data };
+}
+/**
+ * Creates a branch node with children.
+ *
+ * @template T - The data type
+ * @param data - The branch's data
+ * @param children - Child nodes
+ * @returns A Branch node
+ * @since 2.4.0
+ */
+export function branch(data, children) {
+    return { type: "branch", data, children };
+}
+/**
+ * Folds over a composite tree, reducing it to a single value.
+ * This replaces the recursive `operation()` method from OOP Composite.
+ *
+ * @template T - The data type in nodes
+ * @template R - The result type
+ * @param node - The root node to fold
+ * @param handlers - Functions to handle leaf and branch nodes
+ * @returns The folded result
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * // Count all nodes
+ * const count = fold(tree, {
+ *   leaf: () => 1,
+ *   branch: (_, children) => 1 + children.reduce((a, b) => a + b, 0),
+ * });
+ *
+ * // Render to string
+ * const render = fold(tree, {
+ *   leaf: (data) => data.name,
+ *   branch: (data, children) => `${data.name}(${children.join(", ")})`,
+ * });
+ * ```
+ */
+export function fold(node, handlers) {
+    if (node.type === "leaf") {
+        return handlers.leaf(node.data);
+    }
+    const childResults = node.children.map((child) => fold(child, handlers));
+    return handlers.branch(node.data, childResults);
+}
+/**
+ * Maps over a composite tree, transforming each node's data.
+ *
+ * @template T - The source data type
+ * @template U - The target data type
+ * @param node - The root node to map
+ * @param fn - Function to transform node data
+ * @returns A new tree with transformed data
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const doubled = map(tree, (data) => ({ ...data, size: data.size * 2 }));
+ * ```
+ */
+export function map(node, fn) {
+    if (node.type === "leaf") {
+        return leaf(fn(node.data));
+    }
+    return branch(fn(node.data), node.children.map((child) => map(child, fn)));
+}
+/**
+ * Flattens a composite tree into an array of all node data.
+ * Traverses depth-first, pre-order (parent before children).
+ *
+ * @template T - The data type
+ * @param node - The root node to flatten
+ * @returns Array of all node data
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const allFiles = flatten(tree);
+ * // [{ name: "root", ... }, { name: "file1.txt", ... }, ...]
+ * ```
+ */
+export function flatten(node) {
+    return fold(node, {
+        leaf: (data) => [data],
+        branch: (data, childResults) => [data, ...childResults.flat()],
+    });
+}
+/**
+ * Finds the first node matching a predicate (depth-first).
+ * Short-circuits on first match.
+ *
+ * @template T - The data type
+ * @param node - The root node to search
+ * @param predicate - Function to test each node
+ * @returns Option containing the matching node data
+ * @since 2.4.0
+ */
+export function find(node, predicate) {
+    if (predicate(node.data))
+        return some(node.data);
+    if (node.type === "branch") {
+        for (const child of node.children) {
+            const found = find(child, predicate);
+            if (found._tag === "Some")
+                return found;
+        }
+    }
+    return none;
+}
+//# sourceMappingURL=composite.js.map

package/dist/eidos/composite/composite.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"composite.js","sourceRoot":"","sources":["../../../src/eidos/composite/composite.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,eAAe,CAAC;AAmC3C;;;;;;;GAOG;AACH,MAAM,UAAU,IAAI,CAAI,IAAO;IAC7B,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CAAI,IAAO,EAAE,QAAwB;IACzD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;AAC5C,CAAC;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,IAAI,CAAO,IAAkB,EAAE,QAA4B;IACzE,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACzB,OAAO,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IACD,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC,CAAC;IACzE,OAAO,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;AAClD,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,GAAG,CAAO,IAAkB,EAAE,EAAkB;IAC9D,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QACzB,OAAO,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7B,CAAC;IACD,OAAO,MAAM,CACX,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EACb,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAC7C,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,OAAO,CAAI,IAAkB;IAC3C,OAAO,IAAI,CAAC,IAAI,EAAE;QAChB,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC;QACtB,MAAM,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC;KAC/D,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,IAAI,CAClB,IAAkB,EAClB,SAA+B;IAE/B,IAAI,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjD,IAAI,IAAI,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC3B,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;YACrC,IAAI,KAAK,CAAC,IAAI,KAAK,MAAM;gBAAE,OAAO,KAAK,CAAC;QAC1C,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/eidos/decorator/decorator.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Functional Decorator Pattern.
+ *
+ * In OOP, the Decorator pattern requires a Component interface, an abstract
+ * Decorator class, and concrete decorator subclasses with inheritance.
+ * In functional TypeScript, a decorator is a higher-order function that
+ * wraps another function while preserving its signature.
+ *
+ * @module eidos/decorator
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { decorate, before, after } from "@pithos/core/eidos/decorator/decorator";
+ *
+ * const greet = (name: string) => `Hello, ${name}!`;
+ *
+ * const enhanced = decorate(
+ *   greet,
+ *   before((name) => console.log(`calling with: ${name}`)),
+ *   after((_name, result) => console.log(`returned: ${result}`)),
+ * );
+ *
+ * enhanced("Alice");
+ * // logs: calling with: Alice
+ * // logs: returned: Hello, Alice!
+ * // returns: "Hello, Alice!"
+ * ```
+ */
+/**
+ * A Decorator is a higher-order function that wraps a function,
+ * adding behavior while preserving its signature.
+ * Replaces the GoF abstract Decorator class + inheritance chain.
+ *
+ * @template In - The input type
+ * @template Out - The output type
+ * @since 2.4.0
+ */
+export type Decorator<In, Out> = (fn: (input: In) => Out) => (input: In) => Out;
+/**
+ * Applies one or more decorators to a function.
+ * Decorators are applied left-to-right: the first decorator is the
+ * innermost wrapper, the last is the outermost.
+ *
+ * @template In - The input type
+ * @template Out - The output type
+ * @param fn - The function to decorate
+ * @param decorators - Decorators to apply
+ * @returns The decorated function
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const add = (n: number) => n + 1;
+ *
+ * const enhanced = decorate(
+ *   add,
+ *   before((n) => console.log("input:", n)),
+ *   after((_n, result) => console.log("output:", result)),
+ * );
+ *
+ * enhanced(5); // logs: input: 5, output: 6, returns 6
+ * ```
+ */
+export declare function decorate<In, Out>(fn: (input: In) => Out, ...decorators: Decorator<In, Out>[]): (input: In) => Out;
+/**
+ * Creates a decorator that runs a hook before the function executes.
+ *
+ * @template In - The input type
+ * @template Out - The output type
+ * @param hook - Function to run before, receives the input
+ * @returns A Decorator
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const withLog = before<string, string>((name) => {
+ *   console.log(`calling greet with: ${name}`);
+ * });
+ *
+ * const greet = withLog((name) => `Hello, ${name}!`);
+ * greet("Alice"); // logs then returns "Hello, Alice!"
+ * ```
+ */
+export declare function before<In, Out>(hook: (input: In) => void): Decorator<In, Out>;
+/**
+ * Creates a decorator that runs a hook after the function executes.
+ *
+ * @template In - The input type
+ * @template Out - The output type
+ * @param hook - Function to run after, receives input and output
+ * @returns A Decorator
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const withAudit = after<number, number>((input, output) => {
+ *   auditLog.record({ input, output });
+ * });
+ *
+ * const double = withAudit((n) => n * 2);
+ * double(5); // returns 10, audit log records { input: 5, output: 10 }
+ * ```
+ */
+export declare function after<In, Out>(hook: (input: In, output: Out) => void): Decorator<In, Out>;
+/**
+ * Creates a decorator with full control over execution.
+ * The wrapper receives both the original function and the input,
+ * and decides how (or whether) to call it. This is the most
+ * powerful form - `before` and `after` are special cases of `around`.
+ *
+ * @template In - The input type
+ * @template Out - The output type
+ * @param wrapper - Function that controls execution
+ * @returns A Decorator
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * // Retry decorator
+ * const withRetry = around<string, Response>((fn, input) => {
+ *   try { return fn(input); }
+ *   catch { return fn(input); } // one retry
+ * });
+ *
+ * // Caching decorator
+ * const cache = new Map<string, Data>();
+ * const withCache = around<string, Data>((fn, key) => {
+ *   const cached = cache.get(key);
+ *   if (cached) return cached;
+ *   const result = fn(key);
+ *   cache.set(key, result);
+ *   return result;
+ * });
+ * ```
+ */
+export declare function around<In, Out>(wrapper: (fn: (input: In) => Out, input: In) => Out): Decorator<In, Out>;
+//# sourceMappingURL=decorator.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decorator.d.ts","sourceRoot":"","sources":["../../../src/eidos/decorator/decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,SAAS,CAAC,EAAE,EAAE,GAAG,IAAI,CAC/B,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,GAAG,KACnB,CAAC,KAAK,EAAE,EAAE,KAAK,GAAG,CAAC;AAExB;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,QAAQ,CAAC,EAAE,EAAE,GAAG,EAC9B,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,GAAG,EACtB,GAAG,UAAU,EAAE,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,EAAE,GAClC,CAAC,KAAK,EAAE,EAAE,KAAK,GAAG,CAEpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,GAAG,EAC5B,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,IAAI,GACxB,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,CAKpB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,GAAG,EAC3B,IAAI,EAAE,CAAC,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,GAAG,KAAK,IAAI,GACrC,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,CAMpB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,MAAM,CAAC,EAAE,EAAE,GAAG,EAC5B,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,GAAG,EAAE,KAAK,EAAE,EAAE,KAAK,GAAG,GAClD,SAAS,CAAC,EAAE,EAAE,GAAG,CAAC,CAEpB"}

package/dist/eidos/decorator/decorator.js

@@ -0,0 +1,143 @@
+/**
+ * Functional Decorator Pattern.
+ *
+ * In OOP, the Decorator pattern requires a Component interface, an abstract
+ * Decorator class, and concrete decorator subclasses with inheritance.
+ * In functional TypeScript, a decorator is a higher-order function that
+ * wraps another function while preserving its signature.
+ *
+ * @module eidos/decorator
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * import { decorate, before, after } from "@pithos/core/eidos/decorator/decorator";
+ *
+ * const greet = (name: string) => `Hello, ${name}!`;
+ *
+ * const enhanced = decorate(
+ *   greet,
+ *   before((name) => console.log(`calling with: ${name}`)),
+ *   after((_name, result) => console.log(`returned: ${result}`)),
+ * );
+ *
+ * enhanced("Alice");
+ * // logs: calling with: Alice
+ * // logs: returned: Hello, Alice!
+ * // returns: "Hello, Alice!"
+ * ```
+ */
+/**
+ * Applies one or more decorators to a function.
+ * Decorators are applied left-to-right: the first decorator is the
+ * innermost wrapper, the last is the outermost.
+ *
+ * @template In - The input type
+ * @template Out - The output type
+ * @param fn - The function to decorate
+ * @param decorators - Decorators to apply
+ * @returns The decorated function
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const add = (n: number) => n + 1;
+ *
+ * const enhanced = decorate(
+ *   add,
+ *   before((n) => console.log("input:", n)),
+ *   after((_n, result) => console.log("output:", result)),
+ * );
+ *
+ * enhanced(5); // logs: input: 5, output: 6, returns 6
+ * ```
+ */
+export function decorate(fn, ...decorators) {
+    return decorators.reduce((acc, dec) => dec(acc), fn);
+}
+/**
+ * Creates a decorator that runs a hook before the function executes.
+ *
+ * @template In - The input type
+ * @template Out - The output type
+ * @param hook - Function to run before, receives the input
+ * @returns A Decorator
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const withLog = before<string, string>((name) => {
+ *   console.log(`calling greet with: ${name}`);
+ * });
+ *
+ * const greet = withLog((name) => `Hello, ${name}!`);
+ * greet("Alice"); // logs then returns "Hello, Alice!"
+ * ```
+ */
+export function before(hook) {
+    return (fn) => (input) => {
+        hook(input);
+        return fn(input);
+    };
+}
+/**
+ * Creates a decorator that runs a hook after the function executes.
+ *
+ * @template In - The input type
+ * @template Out - The output type
+ * @param hook - Function to run after, receives input and output
+ * @returns A Decorator
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const withAudit = after<number, number>((input, output) => {
+ *   auditLog.record({ input, output });
+ * });
+ *
+ * const double = withAudit((n) => n * 2);
+ * double(5); // returns 10, audit log records { input: 5, output: 10 }
+ * ```
+ */
+export function after(hook) {
+    return (fn) => (input) => {
+        const output = fn(input);
+        hook(input, output);
+        return output;
+    };
+}
+/**
+ * Creates a decorator with full control over execution.
+ * The wrapper receives both the original function and the input,
+ * and decides how (or whether) to call it. This is the most
+ * powerful form - `before` and `after` are special cases of `around`.
+ *
+ * @template In - The input type
+ * @template Out - The output type
+ * @param wrapper - Function that controls execution
+ * @returns A Decorator
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * // Retry decorator
+ * const withRetry = around<string, Response>((fn, input) => {
+ *   try { return fn(input); }
+ *   catch { return fn(input); } // one retry
+ * });
+ *
+ * // Caching decorator
+ * const cache = new Map<string, Data>();
+ * const withCache = around<string, Data>((fn, key) => {
+ *   const cached = cache.get(key);
+ *   if (cached) return cached;
+ *   const result = fn(key);
+ *   cache.set(key, result);
+ *   return result;
+ * });
+ * ```
+ */
+export function around(wrapper) {
+    return (fn) => (input) => wrapper(fn, input);
+}
+//# sourceMappingURL=decorator.js.map

package/dist/eidos/decorator/decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"decorator.js","sourceRoot":"","sources":["../../../src/eidos/decorator/decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAeH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,QAAQ,CACtB,EAAsB,EACtB,GAAG,UAAgC;IAEnC,OAAO,UAAU,CAAC,MAAM,CAAqB,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC;AAC3E,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,MAAM,CACpB,IAAyB;IAEzB,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE;QACvB,IAAI,CAAC,KAAK,CAAC,CAAC;QACZ,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;IACnB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,KAAK,CACnB,IAAsC;IAEtC,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE;QACvB,MAAM,MAAM,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;QACzB,IAAI,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACpB,OAAO,MAAM,CAAC;IAChB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,UAAU,MAAM,CACpB,OAAmD;IAEnD,OAAO,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;AAC/C,CAAC"}

package/dist/eidos/facade/facade.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Functional Facade Pattern.
+ *
+ * In OOP, the Facade pattern requires a class that encapsulates multiple
+ * subsystems and exposes a simplified interface to clients.
+ *
+ * In functional TypeScript, this is absorbed by the language:
+ * a facade is just a function that orchestrates other functions.
+ * No wrapper needed — it's what functions naturally do.
+ *
+ * This module exists for documentation and discoverability. The function is
+ * marked `@deprecated` to guide developers toward idiomatic functional code.
+ *
+ * @module eidos/facade
+ * @since 2.4.0
+ *
+ * @see {@link https://pithos.dev/api/eidos/facade/ | Explanations, examples and live demo}
+ *
+ * @example
+ * ```ts
+ * // No import needed — just write a function:
+ *
+ * // Subsystems (could be from different modules)
+ * const validateUser = (data: UserInput) => { ... };
+ * const hashPassword = (password: string) => { ... };
+ * const saveToDb = (user: User) => { ... };
+ * const sendWelcomeEmail = (email: string) => { ... };
+ *
+ * // Facade: simplified interface hiding the complexity
+ * const registerUser = async (data: UserInput) => {
+ *   const validated = validateUser(data);
+ *   const hashedPassword = await hashPassword(validated.password);
+ *   const user = await saveToDb({ ...validated, password: hashedPassword });
+ *   await sendWelcomeEmail(user.email);
+ *   return user;
+ * };
+ *
+ * // Client only sees registerUser, not the subsystems
+ * await registerUser({ name: "Alice", email: "alice@example.com", password: "..." });
+ * ```
+ *
+ * @deprecated **Pattern absorbed by the language.**
+ *
+ * In functional TypeScript, a facade is just a function that calls other functions.
+ * This function is the identity — it exists only so you find this message.
+ *
+ * Write your facade directly:
+ * ```ts
+ * const checkout = (cart: Cart, payment: Payment) => {
+ *   const validated = validateCart(cart);
+ *   const charged = processPayment(payment, validated.total);
+ *   const order = createOrder(validated, charged);
+ *   sendConfirmation(order);
+ *   return order;
+ * };
+ * ```
+ *
+ * @see {@link https://pithos.dev/api/eidos/facade/ | Full explanation, examples and live demo}
+ */
+export declare function createFacade<Args extends unknown[], Result>(fn: (...args: Args) => Result): (...args: Args) => Result;
+//# sourceMappingURL=facade.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"facade.d.ts","sourceRoot":"","sources":["../../../src/eidos/facade/facade.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0DG;AACH,wBAAgB,YAAY,CAAC,IAAI,SAAS,OAAO,EAAE,EAAE,MAAM,EACzD,EAAE,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,GAC5B,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,MAAM,CAE3B"}