@pithos/core 2.3.0 → 2.4.0

package/dist/eidos/chain/chain.js

@@ -0,0 +1,111 @@
+/**
+ * Functional Chain of Responsibility Pattern.
+ *
+ * In OOP, Chain of Responsibility requires a Handler interface, a BaseHandler
+ * class with a `next` reference, and concrete handler subclasses linked together.
+ * In functional TypeScript, a handler is a function that either returns a result
+ * or delegates to the next handler. The chain is built by composing handlers.
+ *
+ * @module eidos/chain
+ * @since 2.4.0
+ *
+ * @see {@link https://pithos.dev/api/eidos/chain/ | Explanations, examples and live demo}
+ *
+ * @example
+ * ```ts
+ * import { createChain, type Handler } from "@pithos/core/eidos/chain/chain";
+ *
+ * const auth: Handler<Request, Response> = (req, next) =>
+ *   req.token ? next(req) : { status: 401 };
+ *
+ * const validate: Handler<Request, Response> = (req, next) =>
+ *   req.body ? next(req) : { status: 400 };
+ *
+ * const handle: Handler<Request, Response> = (req) =>
+ *   { status: 200, data: process(req) };
+ *
+ * const pipeline = createChain(auth, validate, handle);
+ * pipeline({ token: "abc", body: "data" }); // { status: 200, ... }
+ * ```
+ */
+import { ok, err } from "../../zygos/result/result.js";
+/**
+ * Creates a chain from an ordered list of handlers.
+ * Each handler can inspect the input and either:
+ * - return a result (short-circuit)
+ * - call `next(input)` to pass to the next handler
+ *
+ * The last handler's `next` throws if called, since there is
+ * nothing after it. The last handler should always produce a result.
+ *
+ * @template In - The request/input type
+ * @template Out - The response/output type
+ * @param handlers - Ordered list of handlers (first = outermost)
+ * @returns A function that runs the chain
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const log: Handler<number, string> = (n, next) => {
+ *   console.log(`processing ${n}`);
+ *   return next(n);
+ * };
+ *
+ * const double: Handler<number, string> = (n) => String(n * 2);
+ *
+ * const chain = createChain(log, double);
+ * chain(21); // logs "processing 21", returns "42"
+ * ```
+ */
+export function createChain(...handlers) {
+    if (handlers.length === 0) {
+        throw new Error("createChain requires at least one handler");
+    }
+    return (input) => {
+        let index = 0;
+        const next = (inp) => {
+            if (index >= handlers.length) {
+                throw new Error("End of chain reached: last handler must not call next()");
+            }
+            const handler = handlers[index++];
+            return handler(inp, next);
+        };
+        return next(input);
+    };
+}
+/**
+ * Creates a safe chain that catches errors and returns a zygos `Result`.
+ * Behaves like `createChain`, but wraps the execution in a try/catch.
+ *
+ * @deprecated Use `Result.fromThrowable` from `@zygos/result/result` instead.
+ *
+ * ```ts
+ * import { Result } from "../../zygos/result/result.js";
+ *
+ * const chain = createChain(auth, validate, handle);
+ * const safeRun = Result.fromThrowable(
+ *   (input: Request) => chain(input),
+ *   (e) => e instanceof Error ? e : new Error(String(e)),
+ * );
+ * const result = safeRun(request);
+ * ```
+ *
+ * @see {@link https://pithos.dev/api/eidos/chain/ | Full explanation, examples and live demo}
+ * @template In - The request/input type
+ * @template Out - The response/output type
+ * @param handlers - Ordered list of handlers
+ * @returns A function returning `Result<Out, Error>`
+ * @since 2.4.0
+ */
+export function safeChain(...handlers) {
+    const chain = createChain(...handlers);
+    return (input) => {
+        try {
+            return ok(chain(input));
+        }
+        catch (error) {
+            return err(error instanceof Error ? error : new Error(String(error)));
+        }
+    };
+}
+//# sourceMappingURL=chain.js.map

package/dist/eidos/chain/chain.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.js","sourceRoot":"","sources":["../../../src/eidos/chain/chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,OAAO,EAAE,EAAE,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAiB/C;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,UAAU,WAAW,CACzB,GAAG,QAA4B;IAE/B,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC;IAC/D,CAAC;IAED,OAAO,CAAC,KAAS,EAAO,EAAE;QACxB,IAAI,KAAK,GAAG,CAAC,CAAC;QAEd,MAAM,IAAI,GAAG,CAAC,GAAO,EAAO,EAAE;YAC5B,IAAI,KAAK,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CAAC,yDAAyD,CAAC,CAAC;YAC7E,CAAC;YACD,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;YAClC,OAAO,OAAO,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC5B,CAAC,CAAC;QAEF,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,SAAS,CACvB,GAAG,QAA4B;IAE/B,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,QAAQ,CAAC,CAAC;IACvC,OAAO,CAAC,KAAS,EAAE,EAAE;QACnB,IAAI,CAAC;YACH,OAAO,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,GAAG,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QACxE,CAAC;IACH,CAAC,CAAC;AACJ,CAAC"}

package/dist/eidos/command/command.d.ts

@@ -0,0 +1,267 @@
+/**
+ * Functional Command Pattern.
+ *
+ * In OOP, the Command pattern requires a Command interface, concrete command
+ * classes, a Receiver, and an Invoker - all to encapsulate an action as an object.
+ * In functional TypeScript, a command is a thunk (zero-arg function).
+ * The real value is in undo/redo, which becomes a pair of closures.
+ *
+ * ## Two flavors
+ *
+ * - `createCommandStack`: imperative. Commands are thunks that mutate external state.
+ *   Works naturally with Vue, Angular, Svelte, or any mutable-reactive system.
+ *
+ * - `createReactiveCommandStack`: declarative. Commands are pure `(state) => state`
+ *   transforms. The stack manages state and notifies via `onChange`.
+ *   Works naturally with React or any immutable-state system.
+ *
+ * ## Command vs Memento for undo/redo
+ *
+ * - **Command** (`createCommandStack` / `createReactiveCommandStack`):
+ *   stores *actions* with their inverses.
+ *   Undo calls the command's undo function. Use when you have reversible operations.
+ *
+ * - **Memento** (`createHistory`): stores *state snapshots*.
+ *   Undo restores the previous state. Use when state is cheap to copy.
+ *
+ * @module eidos/command
+ * @since 2.4.0
+ *
+ * @see {@link https://pithos.dev/api/eidos/command/ | Explanations, examples and live demo}
+ *
+ * @example Imperative (side effects, external state)
+ * ```ts
+ * import { undoable, createCommandStack } from "@pithos/core/eidos/command/command";
+ *
+ * let counter = 0;
+ * const increment = undoable(() => counter++, () => counter--);
+ *
+ * const stack = createCommandStack();
+ * stack.execute(increment); // counter = 1
+ * stack.execute(increment); // counter = 2
+ * stack.undo();             // counter = 1
+ * stack.redo();             // counter = 2
+ * ```
+ *
+ * @example Reactive (pure transforms, framework-friendly)
+ * ```ts
+ * import { undoableState, createReactiveCommandStack } from "@pithos/core/eidos/command/command";
+ *
+ * interface Counter { value: number }
+ *
+ * const increment = undoableState<Counter>(
+ *   (s) => ({ ...s, value: s.value + 1 }),
+ *   (s) => ({ ...s, value: s.value - 1 }),
+ * );
+ *
+ * const stack = createReactiveCommandStack({
+ *   initial: { value: 0 },
+ *   onChange: (state) => console.log(state), // or setBoard, or ref.value = state
+ * });
+ *
+ * stack.execute(increment); // onChange({ value: 1 })
+ * stack.execute(increment); // onChange({ value: 2 })
+ * stack.undo();             // onChange({ value: 1 })
+ * stack.redo();             // onChange({ value: 2 })
+ * ```
+ */
+import type { Result as ResultType } from "../../zygos/result/result.js";
+/**
+ * A Command is a thunk - a deferred action with no arguments.
+ * In FP, this IS the pattern: a function is already a reifiable value.
+ *
+ * @since 2.4.0
+ */
+export type Command = () => void;
+/**
+ * An UndoableCommand pairs an execute action with its inverse.
+ * Replaces the GoF Command interface + ConcreteCommand classes.
+ *
+ * @since 2.4.0
+ */
+export interface UndoableCommand {
+    readonly execute: Command;
+    readonly undo: Command;
+}
+/**
+ * Creates an undoable command from an execute/undo pair.
+ *
+ * @param execute - The action to perform
+ * @param undo - The action that reverses execute
+ * @returns An UndoableCommand
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const items: string[] = [];
+ *
+ * const addItem = (item: string) => undoable(
+ *   () => items.push(item),
+ *   () => items.pop(),
+ * );
+ *
+ * const cmd = addItem("hello");
+ * cmd.execute(); // items = ["hello"]
+ * cmd.undo();    // items = []
+ * ```
+ */
+export declare function undoable(execute: Command, undo: Command): UndoableCommand;
+/**
+ * Creates a command stack with undo/redo support.
+ *
+ * This stores *actions* (execute/undo pairs). When you undo, it calls the
+ * command's undo function. Use this when you have reversible operations.
+ *
+ * For storing *states* (snapshots) instead of actions, see the Memento pattern's
+ * `createHistory` which stores state snapshots and restores them on undo.
+ *
+ * @returns Stack with `execute`, `undo`, `redo`, `canUndo`, `canRedo`, `clear`
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * let value = 0;
+ * const stack = createCommandStack();
+ *
+ * stack.execute(undoable(() => value += 10, () => value -= 10));
+ * stack.execute(undoable(() => value *= 2,  () => value /= 2));
+ * // value = 20
+ *
+ * stack.undo(); // value = 10
+ * stack.undo(); // value = 0
+ * stack.redo(); // value = 10
+ * ```
+ */
+export declare function createCommandStack(): {
+    /** Execute a command and push it to the undo stack. Clears redo stack. */
+    execute: (cmd: UndoableCommand) => void;
+    /**
+     * Undo the last command. Returns false if nothing to undo.
+     * Check `canUndo` first if the result matters to your logic.
+     */
+    undo: () => boolean;
+    /**
+     * Redo the last undone command. Returns false if nothing to redo.
+     * Check `canRedo` first if the result matters to your logic.
+     */
+    redo: () => boolean;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    /** Clear all history. */
+    clear: () => void;
+};
+/**
+ * Executes a command safely, catching any error and returning
+ * a zygos `Result` instead of throwing.
+ *
+ * @deprecated Use `Result.fromThrowable` from `@zygos/result/result` instead.
+ *
+ * ```ts
+ * import { Result } from "../../zygos/result/result.js";
+ *
+ * const safeCmd = Result.fromThrowable(riskyCommand, (e) =>
+ *   e instanceof Error ? e : new Error(String(e)),
+ * );
+ * const result = safeCmd();
+ * ```
+ *
+ * @see {@link https://pithos.dev/api/eidos/command/ | Full explanation, examples and live demo}
+ * @param cmd - The command to execute
+ * @returns `Ok(void)` on success, `Err(Error)` on failure
+ * @since 2.4.0
+ */
+export declare function safeExecute(cmd: Command): ResultType<void, Error>;
+/**
+ * A state command is a pure function: takes current state, returns next state.
+ * No mutation, no side effects. The stack manages the state for you.
+ *
+ * @since 2.5.0
+ */
+export type StateCommand<S> = (state: S) => S;
+/**
+ * An undoable state command pairs a forward transform with its inverse.
+ * Both are pure functions from state to state.
+ *
+ * @since 2.5.0
+ */
+export interface UndoableStateCommand<S> {
+    readonly execute: StateCommand<S>;
+    readonly undo: StateCommand<S>;
+}
+/**
+ * Creates an undoable state command from an execute/undo pair.
+ * Unlike `undoable` (imperative thunks), these are pure state transforms.
+ *
+ * @param execute - Pure function that produces the next state
+ * @param undo - Pure function that reverses execute
+ * @returns An UndoableStateCommand
+ * @since 2.5.0
+ *
+ * @example
+ * ```ts
+ * interface Counter { value: number }
+ *
+ * const increment = undoableState<Counter>(
+ *   (s) => ({ ...s, value: s.value + 1 }),
+ *   (s) => ({ ...s, value: s.value - 1 }),
+ * );
+ * ```
+ */
+export declare function undoableState<S>(execute: StateCommand<S>, undo: StateCommand<S>): UndoableStateCommand<S>;
+/**
+ * Options for `createReactiveCommandStack`.
+ *
+ * @since 2.5.0
+ */
+export interface ReactiveCommandStackOptions<S> {
+    /** The initial state. */
+    readonly initial: S;
+    /** Called after every state change (execute, undo, redo, clear). */
+    readonly onChange: (state: S) => void;
+}
+/**
+ * Creates a reactive command stack with undo/redo support.
+ *
+ * Unlike `createCommandStack` (imperative, mutation-based), this variant
+ * manages state internally and notifies via `onChange` on every transition.
+ * Commands are pure functions from state to state, making it naturally
+ * compatible with React, Vue, Angular, or any reactive framework.
+ *
+ * @param options - Initial state and onChange callback
+ * @returns Stack with `execute`, `undo`, `redo`, `canUndo`, `canRedo`, `clear`, `state`
+ * @since 2.5.0
+ *
+ * @example
+ * ```ts
+ * // React
+ * const [board, setBoard] = useState(INITIAL);
+ * const stack = useRef(createReactiveCommandStack({
+ *   initial: INITIAL,
+ *   onChange: setBoard,
+ * }));
+ *
+ * stack.current.execute(undoableState(
+ *   (b) => moveTask(b, "todo", "done", task),
+ *   (b) => moveTask(b, "done", "todo", task),
+ * ));
+ * // setBoard is called automatically with the new state
+ *
+ * stack.current.undo();  // setBoard called with previous state
+ * stack.current.redo();  // setBoard called with next state
+ * ```
+ */
+export declare function createReactiveCommandStack<S>(options: ReactiveCommandStackOptions<S>): {
+    /** Execute a state command. Clears redo stack. */
+    execute: (cmd: UndoableStateCommand<S>) => void;
+    /** Undo the last command. Returns false if nothing to undo. */
+    undo: () => boolean;
+    /** Redo the last undone command. Returns false if nothing to redo. */
+    redo: () => boolean;
+    /** Current state. */
+    readonly state: S;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    /** Reset to initial state and clear all history. */
+    clear: () => void;
+};
+//# sourceMappingURL=command.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"command.d.ts","sourceRoot":"","sources":["../../../src/eidos/command/command.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkEG;AAGH,OAAO,KAAK,EAAE,MAAM,IAAI,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC;AAEjC;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,eAAe,CAEzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,kBAAkB;IAK9B,0EAA0E;mBAC3D,eAAe,KAAG,IAAI;IAMrC;;;OAGG;gBACO,OAAO;IAQjB;;;OAGG;gBACO,OAAO;sBAQF,OAAO;sBAIP,OAAO;IAItB,yBAAyB;iBACd,IAAI;EAKlB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,OAAO,GAAG,UAAU,CAAC,IAAI,EAAE,KAAK,CAAC,CAKjE;AAID;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC;IACrC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EACxB,IAAI,EAAE,YAAY,CAAC,CAAC,CAAC,GACpB,oBAAoB,CAAC,CAAC,CAAC,CAEzB;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA2B,CAAC,CAAC;IAC5C,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;CACvC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,EAC1C,OAAO,EAAE,2BAA2B,CAAC,CAAC,CAAC;IAWrC,kDAAkD;mBACnC,oBAAoB,CAAC,CAAC,CAAC,KAAG,IAAI;IAO7C,+DAA+D;gBACrD,OAAO;IASjB,sEAAsE;gBAC5D,OAAO;IASjB,qBAAqB;oBACR,CAAC;sBAIC,OAAO;sBAIP,OAAO;IAItB,oDAAoD;iBACzC,IAAI;EAOlB"}

package/dist/eidos/command/command.js

@@ -0,0 +1,298 @@
+/**
+ * Functional Command Pattern.
+ *
+ * In OOP, the Command pattern requires a Command interface, concrete command
+ * classes, a Receiver, and an Invoker - all to encapsulate an action as an object.
+ * In functional TypeScript, a command is a thunk (zero-arg function).
+ * The real value is in undo/redo, which becomes a pair of closures.
+ *
+ * ## Two flavors
+ *
+ * - `createCommandStack`: imperative. Commands are thunks that mutate external state.
+ *   Works naturally with Vue, Angular, Svelte, or any mutable-reactive system.
+ *
+ * - `createReactiveCommandStack`: declarative. Commands are pure `(state) => state`
+ *   transforms. The stack manages state and notifies via `onChange`.
+ *   Works naturally with React or any immutable-state system.
+ *
+ * ## Command vs Memento for undo/redo
+ *
+ * - **Command** (`createCommandStack` / `createReactiveCommandStack`):
+ *   stores *actions* with their inverses.
+ *   Undo calls the command's undo function. Use when you have reversible operations.
+ *
+ * - **Memento** (`createHistory`): stores *state snapshots*.
+ *   Undo restores the previous state. Use when state is cheap to copy.
+ *
+ * @module eidos/command
+ * @since 2.4.0
+ *
+ * @see {@link https://pithos.dev/api/eidos/command/ | Explanations, examples and live demo}
+ *
+ * @example Imperative (side effects, external state)
+ * ```ts
+ * import { undoable, createCommandStack } from "@pithos/core/eidos/command/command";
+ *
+ * let counter = 0;
+ * const increment = undoable(() => counter++, () => counter--);
+ *
+ * const stack = createCommandStack();
+ * stack.execute(increment); // counter = 1
+ * stack.execute(increment); // counter = 2
+ * stack.undo();             // counter = 1
+ * stack.redo();             // counter = 2
+ * ```
+ *
+ * @example Reactive (pure transforms, framework-friendly)
+ * ```ts
+ * import { undoableState, createReactiveCommandStack } from "@pithos/core/eidos/command/command";
+ *
+ * interface Counter { value: number }
+ *
+ * const increment = undoableState<Counter>(
+ *   (s) => ({ ...s, value: s.value + 1 }),
+ *   (s) => ({ ...s, value: s.value - 1 }),
+ * );
+ *
+ * const stack = createReactiveCommandStack({
+ *   initial: { value: 0 },
+ *   onChange: (state) => console.log(state), // or setBoard, or ref.value = state
+ * });
+ *
+ * stack.execute(increment); // onChange({ value: 1 })
+ * stack.execute(increment); // onChange({ value: 2 })
+ * stack.undo();             // onChange({ value: 1 })
+ * stack.redo();             // onChange({ value: 2 })
+ * ```
+ */
+import { Result } from "../../zygos/result/result.js";
+/**
+ * Creates an undoable command from an execute/undo pair.
+ *
+ * @param execute - The action to perform
+ * @param undo - The action that reverses execute
+ * @returns An UndoableCommand
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * const items: string[] = [];
+ *
+ * const addItem = (item: string) => undoable(
+ *   () => items.push(item),
+ *   () => items.pop(),
+ * );
+ *
+ * const cmd = addItem("hello");
+ * cmd.execute(); // items = ["hello"]
+ * cmd.undo();    // items = []
+ * ```
+ */
+export function undoable(execute, undo) {
+    return { execute, undo };
+}
+/**
+ * Creates a command stack with undo/redo support.
+ *
+ * This stores *actions* (execute/undo pairs). When you undo, it calls the
+ * command's undo function. Use this when you have reversible operations.
+ *
+ * For storing *states* (snapshots) instead of actions, see the Memento pattern's
+ * `createHistory` which stores state snapshots and restores them on undo.
+ *
+ * @returns Stack with `execute`, `undo`, `redo`, `canUndo`, `canRedo`, `clear`
+ * @since 2.4.0
+ *
+ * @example
+ * ```ts
+ * let value = 0;
+ * const stack = createCommandStack();
+ *
+ * stack.execute(undoable(() => value += 10, () => value -= 10));
+ * stack.execute(undoable(() => value *= 2,  () => value /= 2));
+ * // value = 20
+ *
+ * stack.undo(); // value = 10
+ * stack.undo(); // value = 0
+ * stack.redo(); // value = 10
+ * ```
+ */
+export function createCommandStack() {
+    const past = [];
+    const future = [];
+    return {
+        /** Execute a command and push it to the undo stack. Clears redo stack. */
+        execute: (cmd) => {
+            cmd.execute();
+            past.push(cmd);
+            future.length = 0;
+        },
+        /**
+         * Undo the last command. Returns false if nothing to undo.
+         * Check `canUndo` first if the result matters to your logic.
+         */
+        undo: () => {
+            const cmd = past.pop();
+            if (!cmd)
+                return false;
+            cmd.undo();
+            future.push(cmd);
+            return true;
+        },
+        /**
+         * Redo the last undone command. Returns false if nothing to redo.
+         * Check `canRedo` first if the result matters to your logic.
+         */
+        redo: () => {
+            const cmd = future.pop();
+            if (!cmd)
+                return false;
+            cmd.execute();
+            past.push(cmd);
+            return true;
+        },
+        get canUndo() {
+            return past.length > 0;
+        },
+        get canRedo() {
+            return future.length > 0;
+        },
+        /** Clear all history. */
+        clear: () => {
+            past.length = 0;
+            future.length = 0;
+        },
+    };
+}
+/**
+ * Executes a command safely, catching any error and returning
+ * a zygos `Result` instead of throwing.
+ *
+ * @deprecated Use `Result.fromThrowable` from `@zygos/result/result` instead.
+ *
+ * ```ts
+ * import { Result } from "../../zygos/result/result.js";
+ *
+ * const safeCmd = Result.fromThrowable(riskyCommand, (e) =>
+ *   e instanceof Error ? e : new Error(String(e)),
+ * );
+ * const result = safeCmd();
+ * ```
+ *
+ * @see {@link https://pithos.dev/api/eidos/command/ | Full explanation, examples and live demo}
+ * @param cmd - The command to execute
+ * @returns `Ok(void)` on success, `Err(Error)` on failure
+ * @since 2.4.0
+ */
+export function safeExecute(cmd) {
+    const safe = Result.fromThrowable(cmd, (e) => e instanceof Error ? e : new Error(String(e)));
+    return safe();
+}
+/**
+ * Creates an undoable state command from an execute/undo pair.
+ * Unlike `undoable` (imperative thunks), these are pure state transforms.
+ *
+ * @param execute - Pure function that produces the next state
+ * @param undo - Pure function that reverses execute
+ * @returns An UndoableStateCommand
+ * @since 2.5.0
+ *
+ * @example
+ * ```ts
+ * interface Counter { value: number }
+ *
+ * const increment = undoableState<Counter>(
+ *   (s) => ({ ...s, value: s.value + 1 }),
+ *   (s) => ({ ...s, value: s.value - 1 }),
+ * );
+ * ```
+ */
+export function undoableState(execute, undo) {
+    return { execute, undo };
+}
+/**
+ * Creates a reactive command stack with undo/redo support.
+ *
+ * Unlike `createCommandStack` (imperative, mutation-based), this variant
+ * manages state internally and notifies via `onChange` on every transition.
+ * Commands are pure functions from state to state, making it naturally
+ * compatible with React, Vue, Angular, or any reactive framework.
+ *
+ * @param options - Initial state and onChange callback
+ * @returns Stack with `execute`, `undo`, `redo`, `canUndo`, `canRedo`, `clear`, `state`
+ * @since 2.5.0
+ *
+ * @example
+ * ```ts
+ * // React
+ * const [board, setBoard] = useState(INITIAL);
+ * const stack = useRef(createReactiveCommandStack({
+ *   initial: INITIAL,
+ *   onChange: setBoard,
+ * }));
+ *
+ * stack.current.execute(undoableState(
+ *   (b) => moveTask(b, "todo", "done", task),
+ *   (b) => moveTask(b, "done", "todo", task),
+ * ));
+ * // setBoard is called automatically with the new state
+ *
+ * stack.current.undo();  // setBoard called with previous state
+ * stack.current.redo();  // setBoard called with next state
+ * ```
+ */
+export function createReactiveCommandStack(options) {
+    let current = options.initial;
+    const past = [];
+    const future = [];
+    function notify() {
+        options.onChange(current);
+    }
+    return {
+        /** Execute a state command. Clears redo stack. */
+        execute: (cmd) => {
+            current = cmd.execute(current);
+            past.push(cmd);
+            future.length = 0;
+            notify();
+        },
+        /** Undo the last command. Returns false if nothing to undo. */
+        undo: () => {
+            const cmd = past.pop();
+            if (!cmd)
+                return false;
+            current = cmd.undo(current);
+            future.push(cmd);
+            notify();
+            return true;
+        },
+        /** Redo the last undone command. Returns false if nothing to redo. */
+        redo: () => {
+            const cmd = future.pop();
+            if (!cmd)
+                return false;
+            current = cmd.execute(current);
+            past.push(cmd);
+            notify();
+            return true;
+        },
+        /** Current state. */
+        get state() {
+            return current;
+        },
+        get canUndo() {
+            return past.length > 0;
+        },
+        get canRedo() {
+            return future.length > 0;
+        },
+        /** Reset to initial state and clear all history. */
+        clear: () => {
+            current = options.initial;
+            past.length = 0;
+            future.length = 0;
+            notify();
+        },
+    };
+}
+//# sourceMappingURL=command.js.map

package/dist/eidos/command/command.js.map

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