@voidhash/mimic-react 0.0.1-alpha.2

package/dist/index.d.cts

@@ -0,0 +1 @@
+export { };

package/dist/index.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/index.mjs

@@ -0,0 +1 @@
+export {  };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@voidhash/mimic-react",
+  "version": "0.0.1-alpha.2",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voidhashcom/mimic",
+    "directory": "packages/mimic-react"
+  },
+  "main": "./src/index.ts",
+  "exports": {
+    "./zustand": "./src/zustand/index.ts"
+  },
+  "dependencies": {
+    "zustand": "^5.0.9"
+  },
+  "devDependencies": {
+    "@effect/vitest": "^0.26.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.2"
+  },
+  "peerDependencies": {
+    "@voidhash/mimic": "0.0.1-alpha.2"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "biome check .",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run -c vitest.mts"
+  }
+}

package/src/zustand/index.ts

@@ -0,0 +1,24 @@
+/**
+ * @voidhash/mimic-react/zustand
+ *
+ * Zustand middleware for integrating mimic ClientDocument with reactive state.
+ *
+ * @since 0.0.1
+ */
+
+// =============================================================================
+// Middleware
+// =============================================================================
+
+export { mimic } from "./middleware.js";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type {
+  MimicObject,
+  MimicSlice,
+  MimicMiddlewareOptions,
+  MimicStateCreator,
+} from "./types.js";

package/src/zustand/middleware.ts

@@ -0,0 +1,171 @@
+import type { StateCreator, StoreMutatorIdentifier } from "zustand";
+import type { ClientDocument } from "@voidhash/mimic/client";
+import type { Primitive, Presence } from "@voidhash/mimic";
+import type {
+  MimicSlice,
+  MimicObject,
+  MimicMiddlewareOptions,
+} from "./types.js";
+
+// =============================================================================
+// Middleware Implementation
+// =============================================================================
+
+type MimicMiddleware = <
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined = undefined,
+  T extends object = object,
+  Mps extends [StoreMutatorIdentifier, unknown][] = [],
+  Mcs extends [StoreMutatorIdentifier, unknown][] = [],
+>(
+  document: ClientDocument.ClientDocument<TSchema, TPresence>,
+  config: StateCreator<T & MimicSlice<TSchema, TPresence>, Mps, Mcs, T>,
+  options?: MimicMiddlewareOptions
+) => StateCreator<T & MimicSlice<TSchema, TPresence>, Mps, Mcs, T & MimicSlice<TSchema, TPresence>>;
+
+type MimicMiddlewareImpl = <
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined = undefined,
+  T extends object = object,
+>(
+  document: ClientDocument.ClientDocument<TSchema, TPresence>,
+  config: StateCreator<T & MimicSlice<TSchema, TPresence>, [], [], T>,
+  options?: MimicMiddlewareOptions
+) => StateCreator<T & MimicSlice<TSchema, TPresence>, [], [], T & MimicSlice<TSchema, TPresence>>;
+
+/**
+ * Creates a MimicObject from the current document state.
+ */
+const createMimicObject = <
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined = undefined
+>(
+  document: ClientDocument.ClientDocument<TSchema, TPresence>
+): MimicObject<TSchema, TPresence> => {
+  const presence = document.presence
+    ? {
+        selfId: document.presence.selfId(),
+        self: document.presence.self(),
+        // Important: clone Maps to ensure zustand selectors re-render
+        // when presence changes (the underlying ClientDocument mutates Maps in-place).
+        others: new Map(document.presence.others()),
+        all: new Map(document.presence.all()),
+      }
+    : undefined;
+
+  return {
+    document,
+    snapshot: document.root.toSnapshot() as Primitive.InferSnapshot<TSchema>,
+    presence: presence as MimicObject<TSchema, TPresence>["presence"],
+    isConnected: document.isConnected(),
+    isReady: document.isReady(),
+    pendingCount: document.getPendingCount(),
+    hasPendingChanges: document.hasPendingChanges(),
+  };
+};
+
+/**
+ * Implementation of the mimic middleware.
+ */
+const mimicImpl: MimicMiddlewareImpl = <
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined = undefined,
+  T extends object = object
+>(
+  document: ClientDocument.ClientDocument<TSchema, TPresence>,
+  config: any,
+  options: MimicMiddlewareOptions = {}
+) => {
+  const { autoSubscribe = true, autoConnect = true } = options;
+
+  return (set: any, get: any, api: any) => {
+    // Create initial mimic slice
+    const initialMimic = createMimicObject(document);
+
+    // Helper to update mimic state
+    const updateMimicState = () => {
+      const newMimic = createMimicObject(document);
+      set(
+        (state: any) => ({
+          ...state,
+          mimic: newMimic,
+        }),
+        false
+      );
+    };
+
+    // Subscribe to document changes
+    if (autoSubscribe) {
+      document.subscribe({
+        onStateChange: () => {
+          updateMimicState();
+        },
+        onConnectionChange: () => {
+          updateMimicState();
+        },
+        onReady: () => {
+          updateMimicState();
+        },
+      });
+
+      // Subscribe to presence changes (if presence schema is enabled)
+      document.presence?.subscribe({
+        onPresenceChange: () => {
+          updateMimicState();
+        },
+      });
+    }
+
+    if (autoConnect) {
+      document.connect();
+    }
+
+    // Get user's state - pass through set/get/api directly
+    // The user's set calls won't affect mimic state since we update it separately
+    const userState = config(set, get, api);
+
+    // Combine user state with mimic slice
+    return {
+      ...userState,
+      mimic: initialMimic,
+    };
+  };
+};
+
+/**
+ * Zustand middleware that integrates a ClientDocument.
+ * 
+ * Adds a `mimic` object to the store containing:
+ * - `document`: The ClientDocument instance for performing transactions
+ * - `snapshot`: Read-only snapshot of the document state (reactive)
+ * - `presence`: Reactive presence snapshot (self + others). Undefined if presence is not enabled on the ClientDocument.
+ * - `isConnected`: Connection status
+ * - `isReady`: Ready status
+ * - `pendingCount`: Number of pending transactions
+ * - `hasPendingChanges`: Whether there are pending changes
+ * 
+ * @example
+ * ```ts
+ * import { create } from 'zustand'
+ * import { mimic } from '@voidhash/mimic-react/zustand'
+ * 
+ * const useStore = create(
+ *   mimic(clientDocument, (set, get) => ({
+ *     // Your additional store state
+ *   }))
+ * )
+ * 
+ * // Read snapshot (reactive)
+ * const snapshot = useStore(state => state.mimic.snapshot)
+ * 
+ * // Read presence (reactive, if enabled)
+ * const myPresence = useStore(state => state.mimic.presence?.self)
+ * const othersPresence = useStore(state => state.mimic.presence?.others)
+ * 
+ * // Write via document
+ * store.getState().mimic.document.transaction(root => {
+ *   root.name.set("New Name")
+ * })
+ * ```
+ */
+export const mimic = mimicImpl as unknown as MimicMiddleware;

package/src/zustand/types.ts

@@ -0,0 +1,117 @@
+import type { StateCreator, StoreMutatorIdentifier } from "zustand";
+import type { ClientDocument } from "@voidhash/mimic/client";
+import type { Primitive, Presence } from "@voidhash/mimic";
+
+// =============================================================================
+// Mimic State Types
+// =============================================================================
+
+/**
+ * Presence data exposed on the zustand store (reactive snapshot).
+ */
+export interface MimicPresence<TPresence extends Presence.AnyPresence> {
+  /**
+   * This client's connection ID (set after receiving presence snapshot).
+   * Undefined before the snapshot is received.
+   */
+  readonly selfId: string | undefined;
+
+  /**
+   * This client's current presence data.
+   * Undefined if not set.
+   */
+  readonly self: Presence.Infer<TPresence> | undefined;
+
+  /**
+   * Other clients' presence entries (connectionId -> entry).
+   */
+  readonly others: ReadonlyMap<
+    string,
+    Presence.PresenceEntry<Presence.Infer<TPresence>>
+  >;
+
+  /**
+   * All presence entries including self (connectionId -> entry).
+   */
+  readonly all: ReadonlyMap<
+    string,
+    Presence.PresenceEntry<Presence.Infer<TPresence>>
+  >;
+}
+
+/**
+ * The mimic object containing the document and client state.
+ * This is added to the zustand store by the middleware.
+ */
+export interface MimicObject<
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined = undefined
+> {
+  /** The ClientDocument instance for performing transactions */
+  readonly document: ClientDocument.ClientDocument<TSchema, TPresence>;
+  /** Read-only snapshot of the document state */
+  readonly snapshot: Primitive.InferSnapshot<TSchema>;
+  /**
+   * Reactive presence snapshot (self + others).
+   * Undefined when the ClientDocument was created without a presence schema.
+   */
+  readonly presence: TPresence extends Presence.AnyPresence
+    ? MimicPresence<TPresence>
+    : undefined;
+  /** Whether the client is connected to the server */
+  readonly isConnected: boolean;
+  /** Whether the client is fully initialized and ready */
+  readonly isReady: boolean;
+  /** Number of pending transactions */
+  readonly pendingCount: number;
+  /** Whether there are pending changes */
+  readonly hasPendingChanges: boolean;
+}
+
+/**
+ * The state slice added by the mimic middleware.
+ */
+export interface MimicSlice<
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined = undefined
+> {
+  /** The mimic object containing document and state */
+  readonly mimic: MimicObject<TSchema, TPresence>;
+}
+
+// =============================================================================
+// Middleware Types
+// =============================================================================
+
+/**
+ * Type for the mimic middleware mutator.
+ */
+export type MimicMutator<
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined = undefined
+> = [
+  "mimic",
+  TSchema,
+  TPresence
+];
+
+/**
+ * Type for state creator with mimic slice merged.
+ */
+export type MimicStateCreator<
+  TSchema extends Primitive.AnyPrimitive,
+  TPresence extends Presence.AnyPresence | undefined,
+  T,
+  Mps extends [StoreMutatorIdentifier, unknown][] = [],
+  Mcs extends [StoreMutatorIdentifier, unknown][] = [],
+> = StateCreator<T & MimicSlice<TSchema, TPresence>, Mps, Mcs, T>;
+
+/**
+ * Options for the mimic middleware.
+ */
+export interface MimicMiddlewareOptions {
+  /** If true, automatically subscribe when store is created (default: true) */
+  readonly autoSubscribe?: boolean;
+  /** If true, automatically attempt to connect the document to the remote server */
+  readonly autoConnect?: boolean;
+}