@voidhash/mimic-react 0.0.1-alpha.5 → 0.0.1-alpha.6

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @voidhash/mimic-react@0.0.1-alpha.5 build /home/runner/work/mimic/mimic/packages/mimic-react
+> @voidhash/mimic-react@0.0.1-alpha.6 build /home/runner/work/mimic/mimic/packages/mimic-react
 > tsdown
 
 ℹ tsdown v0.18.2 powered by rolldown v1.0.0-beta.55
@@ -13,7 +13,7 @@
 ℹ [ESM] dist/index.mjs    0.01 kB │ gzip: 0.03 kB
 ℹ [ESM] dist/index.d.mts  0.01 kB │ gzip: 0.03 kB
 ℹ [ESM] 2 files, total: 0.02 kB
+✔ Build complete in 3369ms
 ℹ [CJS] dist/index.d.cts  0.01 kB │ gzip: 0.03 kB
 ℹ [CJS] 1 files, total: 0.01 kB
-✔ Build complete in 2911ms
-✔ Build complete in 2911ms
+✔ Build complete in 3371ms

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voidhash/mimic-react",
-  "version": "0.0.1-alpha.5",
+  "version": "0.0.1-alpha.6",
   "type": "module",
   "repository": {
     "type": "git",
@@ -9,21 +9,27 @@
   },
   "main": "./src/index.ts",
   "exports": {
-    "./zustand": "./src/zustand/index.ts"
+    "./zustand": "./src/zustand/index.ts",
+    "./zustand-commander": "./src/zustand-commander/index.ts"
   },
   "dependencies": {
     "zustand": "^5.0.9"
   },
   "devDependencies": {
     "@effect/vitest": "^0.26.0",
+    "@types/react": "^19.0.0",
+    "effect": "^3.16.0",
+    "react": "^19.0.0",
     "tsdown": "^0.18.2",
     "typescript": "5.8.3",
     "vite-tsconfig-paths": "^5.1.4",
     "vitest": "^3.2.4",
-    "@voidhash/tsconfig": "0.0.1-alpha.5"
+    "@voidhash/tsconfig": "0.0.1-alpha.6"
   },
   "peerDependencies": {
-    "@voidhash/mimic": "0.0.1-alpha.5"
+    "effect": "^3.16.0",
+    "react": "^18.0.0 || ^19.0.0",
+    "@voidhash/mimic": "0.0.1-alpha.6"
   },
   "scripts": {
     "build": "tsdown",

package/src/zustand/middleware.ts

@@ -70,7 +70,7 @@ const createMimicObject = <
 const mimicImpl: MimicMiddlewareImpl = <
   TSchema extends Primitive.AnyPrimitive,
   TPresence extends Presence.AnyPresence | undefined = undefined,
-  T extends object = object
+  _T extends object = object
 >(
   document: ClientDocument.ClientDocument<TSchema, TPresence>,
   config: any,

package/src/zustand-commander/commander.ts

@@ -0,0 +1,395 @@
+/**
+ * @voidhash/mimic-react/zustand-commander
+ *
+ * Commander creation and command definition.
+ *
+ * @since 0.0.1
+ */
+
+import type { StoreApi } from "zustand";
+import {
+  COMMAND_SYMBOL,
+  UNDOABLE_COMMAND_SYMBOL,
+  isUndoableCommand,
+  type AnyEffectSchema,
+  type Command,
+  type Commander,
+  type CommanderOptions,
+  type CommanderSlice,
+  type CommandContext,
+  type CommandDispatch,
+  type CommandFn,
+  type InferSchemaType,
+  type RevertFn,
+  type UndoableCommand,
+  type UndoEntry,
+} from "./types.js";
+
+// =============================================================================
+// Default Options
+// =============================================================================
+
+const DEFAULT_OPTIONS: Required<CommanderOptions> = {
+  maxUndoStackSize: 100,
+};
+
+// =============================================================================
+// Commander Implementation
+// =============================================================================
+
+/**
+ * Creates a commander instance bound to a specific store type.
+ *
+ * @example
+ * ```ts
+ * // Create commander for your store type
+ * const commander = createCommander<StoreState>();
+ *
+ * // Define commands
+ * const addItem = commander.action(
+ *   Schema.Struct({ name: Schema.String }),
+ *   (ctx, params) => {
+ *     const { mimic } = ctx.getState();
+ *     mimic.document.transaction(root => {
+ *       // add item
+ *     });
+ *   }
+ * );
+ *
+ * // Create store with middleware
+ * const useStore = create(
+ *   commander.middleware(
+ *     mimic(document, (set, get) => ({
+ *       // your state
+ *     }))
+ *   )
+ * );
+ * ```
+ */
+export function createCommander<TStore extends object>(
+  options: CommanderOptions = {}
+): Commander<TStore & CommanderSlice> {
+  const { maxUndoStackSize } = { ...DEFAULT_OPTIONS, ...options };
+
+  // Track the store API once middleware is applied
+  let _storeApi: StoreApi<TStore & CommanderSlice> | null = null;
+
+  /**
+   * Creates the dispatch function for use within command handlers.
+   */
+  const createDispatch = (): CommandDispatch<TStore & CommanderSlice> => {
+    return <TParams, TReturn>(
+      command: Command<TStore & CommanderSlice, TParams, TReturn>
+    ) => {
+      return (params: TParams): TReturn => {
+        if (!_storeApi) {
+          throw new Error(
+            "Commander: Store not initialized. Make sure to use the commander middleware."
+          );
+        }
+
+        // Create context for the command
+        const ctx: CommandContext<TStore & CommanderSlice> = {
+          getState: () => _storeApi!.getState(),
+          setState: (partial) => _storeApi!.setState(partial as any),
+          dispatch: createDispatch(),
+        };
+
+        // Execute the command
+        const result = command.fn(ctx, params);
+
+        // If it's an undoable command, add to undo stack
+        if (isUndoableCommand(command)) {
+          const entry: UndoEntry<TParams, TReturn> = {
+            command,
+            params,
+            result,
+            timestamp: Date.now(),
+          };
+
+          _storeApi.setState((state: TStore & CommanderSlice) => {
+            const { undoStack, redoStack } = state._commander;
+
+            // Add to undo stack, respecting max size
+            const newUndoStack = [...undoStack, entry].slice(-maxUndoStackSize);
+
+            // Clear redo stack when a new command is executed
+            return {
+              ...state,
+              _commander: {
+                undoStack: newUndoStack,
+                redoStack: [],
+              },
+            };
+          });
+        }
+
+        return result;
+      };
+    };
+  };
+
+  /**
+   * Create a regular command (no undo support).
+   */
+  function action<TParamsSchema extends AnyEffectSchema, TReturn = void>(
+    paramsSchema: TParamsSchema,
+    fn: CommandFn<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>
+  ): Command<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>;
+  function action<TReturn = void>(
+    fn: CommandFn<TStore & CommanderSlice, void, TReturn>
+  ): Command<TStore & CommanderSlice, void, TReturn>;
+  function action<TParamsSchema extends AnyEffectSchema, TReturn = void>(
+    paramsSchemaOrFn:
+      | TParamsSchema
+      | CommandFn<TStore & CommanderSlice, void, TReturn>,
+    maybeFn?: CommandFn<
+      TStore & CommanderSlice,
+      InferSchemaType<TParamsSchema>,
+      TReturn
+    >
+  ): Command<TStore & CommanderSlice, any, TReturn> {
+    // Check if we have two arguments (schema + fn) or just one (fn only)
+    if (maybeFn !== undefined) {
+      // First arg is schema, second is fn
+      return {
+        [COMMAND_SYMBOL]: true,
+        fn: maybeFn,
+        paramsSchema: paramsSchemaOrFn as TParamsSchema,
+      };
+    }
+
+    // Single argument - must be the action function (no params schema)
+    if (typeof paramsSchemaOrFn !== "function") {
+      throw new Error("Commander: action requires a function");
+    }
+
+    return {
+      [COMMAND_SYMBOL]: true,
+      fn: paramsSchemaOrFn as CommandFn<TStore & CommanderSlice, void, TReturn>,
+      paramsSchema: null,
+    };
+  }
+
+  /**
+   * Create an undoable command with undo/redo support.
+   */
+  function undoableAction<TParamsSchema extends AnyEffectSchema, TReturn>(
+    paramsSchema: TParamsSchema,
+    fn: CommandFn<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>,
+    revert: RevertFn<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>
+  ): UndoableCommand<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>;
+  function undoableAction<TReturn>(
+    fn: CommandFn<TStore & CommanderSlice, void, TReturn>,
+    revert: RevertFn<TStore & CommanderSlice, void, TReturn>
+  ): UndoableCommand<TStore & CommanderSlice, void, TReturn>;
+  function undoableAction<TParamsSchema extends AnyEffectSchema, TReturn>(
+    paramsSchemaOrFn:
+      | TParamsSchema
+      | CommandFn<TStore & CommanderSlice, void, TReturn>,
+    fnOrRevert:
+      | CommandFn<TStore & CommanderSlice, InferSchemaType<TParamsSchema>, TReturn>
+      | RevertFn<TStore & CommanderSlice, void, TReturn>,
+    maybeRevert?: RevertFn<
+      TStore & CommanderSlice,
+      InferSchemaType<TParamsSchema>,
+      TReturn
+    >
+  ): UndoableCommand<TStore & CommanderSlice, any, TReturn> {
+    // Check if we have three arguments (schema + fn + revert) or two (fn + revert)
+    if (maybeRevert !== undefined) {
+      // First arg is schema, second is fn, third is revert
+      return {
+        [COMMAND_SYMBOL]: true,
+        [UNDOABLE_COMMAND_SYMBOL]: true,
+        fn: fnOrRevert as CommandFn<
+          TStore & CommanderSlice,
+          InferSchemaType<TParamsSchema>,
+          TReturn
+        >,
+        paramsSchema: paramsSchemaOrFn as TParamsSchema,
+        revert: maybeRevert,
+      };
+    }
+
+    // Two arguments - fn + revert (no params schema)
+    if (typeof paramsSchemaOrFn !== "function") {
+      throw new Error("Commander: undoableAction requires a function");
+    }
+
+    return {
+      [COMMAND_SYMBOL]: true,
+      [UNDOABLE_COMMAND_SYMBOL]: true,
+      fn: paramsSchemaOrFn as CommandFn<TStore & CommanderSlice, void, TReturn>,
+      paramsSchema: null,
+      revert: fnOrRevert as RevertFn<TStore & CommanderSlice, void, TReturn>,
+    };
+  }
+
+  /**
+   * Zustand middleware that adds commander functionality.
+   */
+  const middleware = <T extends object>(
+    config: (
+      set: StoreApi<T & CommanderSlice>["setState"],
+      get: StoreApi<T & CommanderSlice>["getState"],
+      api: StoreApi<T & CommanderSlice>
+    ) => T
+  ) => {
+    return (
+      set: StoreApi<T & CommanderSlice>["setState"],
+      get: StoreApi<T & CommanderSlice>["getState"],
+      api: StoreApi<T & CommanderSlice>
+    ): T & CommanderSlice => {
+      // Store the API reference for dispatch
+      _storeApi = api as unknown as StoreApi<TStore & CommanderSlice>;
+
+      // Get user's state
+      const userState = config(set, get, api);
+
+      // Add commander slice
+      return {
+        ...userState,
+        _commander: {
+          undoStack: [],
+          redoStack: [],
+        },
+      };
+    };
+  };
+
+  return {
+    action,
+    undoableAction,
+    middleware: middleware as Commander<TStore & CommanderSlice>["middleware"],
+  };
+}
+
+// =============================================================================
+// Undo/Redo Functions
+// =============================================================================
+
+/**
+ * Perform an undo operation on the store.
+ * Returns true if an undo was performed, false if undo stack was empty.
+ */
+export function performUndo<TStore extends CommanderSlice>(
+  storeApi: StoreApi<TStore>
+): boolean {
+  const state = storeApi.getState();
+  const { undoStack, redoStack } = state._commander;
+
+  // Pop the last entry from undo stack
+  const entry = undoStack[undoStack.length - 1];
+  if (!entry) {
+    return false;
+  }
+
+  const newUndoStack = undoStack.slice(0, -1);
+
+  // Create context for the revert function
+  const ctx: CommandContext<TStore> = {
+    getState: () => storeApi.getState(),
+    setState: (partial) => storeApi.setState(partial as any),
+    dispatch: createDispatchForUndo(storeApi),
+  };
+
+  // Execute the revert function
+  entry.command.revert(ctx, entry.params, entry.result);
+
+  // Move entry to redo stack
+  storeApi.setState((state: TStore) => ({
+    ...state,
+    _commander: {
+      undoStack: newUndoStack,
+      redoStack: [...redoStack, entry],
+    },
+  }));
+
+  return true;
+}
+
+/**
+ * Perform a redo operation on the store.
+ * Returns true if a redo was performed, false if redo stack was empty.
+ */
+export function performRedo<TStore extends CommanderSlice>(
+  storeApi: StoreApi<TStore>
+): boolean {
+  const state = storeApi.getState();
+  const { undoStack, redoStack } = state._commander;
+
+  // Pop the last entry from redo stack
+  const entry = redoStack[redoStack.length - 1];
+  if (!entry) {
+    return false;
+  }
+
+  const newRedoStack = redoStack.slice(0, -1);
+
+  // Create context for re-executing the command
+  const ctx: CommandContext<TStore> = {
+    getState: () => storeApi.getState(),
+    setState: (partial) => storeApi.setState(partial as any),
+    dispatch: createDispatchForUndo(storeApi),
+  };
+
+  // Re-execute the command
+  const result = entry.command.fn(ctx, entry.params);
+
+  // Create new entry with potentially new result
+  const newEntry: UndoEntry = {
+    command: entry.command,
+    params: entry.params,
+    result,
+    timestamp: Date.now(),
+  };
+
+  // Move entry back to undo stack
+  storeApi.setState((state: TStore) => ({
+    ...state,
+    _commander: {
+      undoStack: [...undoStack, newEntry],
+      redoStack: newRedoStack,
+    },
+  }));
+
+  return true;
+}
+
+/**
+ * Creates a dispatch function for use during undo/redo operations.
+ * This dispatch does NOT add to undo stack (to avoid infinite loops).
+ */
+function createDispatchForUndo<TStore>(
+  storeApi: StoreApi<TStore>
+): CommandDispatch<TStore> {
+  return <TParams, TReturn>(command: Command<TStore, TParams, TReturn>) => {
+    return (params: TParams): TReturn => {
+      const ctx: CommandContext<TStore> = {
+        getState: () => storeApi.getState(),
+        setState: (partial) => storeApi.setState(partial as any),
+        dispatch: createDispatchForUndo(storeApi),
+      };
+
+      // Execute without adding to undo stack
+      return command.fn(ctx, params);
+    };
+  };
+}
+
+/**
+ * Clear the undo and redo stacks.
+ */
+export function clearUndoHistory<TStore extends CommanderSlice>(
+  storeApi: StoreApi<TStore>
+): void {
+  storeApi.setState((state: TStore) => ({
+    ...state,
+    _commander: {
+      undoStack: [],
+      redoStack: [],
+    },
+  }));
+}
+