@voidhash/mimic 0.0.1-alpha.1

package/src/client/index.ts

@@ -0,0 +1,61 @@
+/**
+ * @voidhash/mimic-client
+ * 
+ * Optimistic client library for the Mimic sync engine.
+ * Provides optimistic updates with server synchronization.
+ * 
+ * @since 0.0.1
+ */
+
+// =============================================================================
+// Presence (re-exported from core for convenience)
+// =============================================================================
+
+export * as Presence from "../Presence.js";
+
+// =============================================================================
+// Main Client Document
+// =============================================================================
+
+export * as ClientDocument from "./ClientDocument.js";
+
+// =============================================================================
+// Transport Interface
+// =============================================================================
+
+export * as Transport from "./Transport.js";
+
+// =============================================================================
+// WebSocket Transport
+// =============================================================================
+
+export * as WebSocketTransport from "./WebSocketTransport.js";
+
+// =============================================================================
+// Rebase Logic
+// =============================================================================
+
+export * as Rebase from "./Rebase.js";
+
+// =============================================================================
+// State Monitoring
+// =============================================================================
+
+export * as StateMonitor from "./StateMonitor.js";
+
+// =============================================================================
+// Errors
+// =============================================================================
+
+export {
+  MimicClientError,
+  TransactionRejectedError,
+  NotConnectedError,
+  ConnectionError,
+  StateDriftError,
+  TransactionTimeoutError,
+  RebaseError,
+  InvalidStateError,
+  WebSocketError,
+  AuthenticationError,
+} from "./errors.js";

package/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * @since 0.0.1
+ */
+
+export * as Primitive from "./Primitive.js";
+export * as Document from "./Document.js";
+export * as Transaction from "./Transaction.js";
+export * as Operation from "./Operation.js";
+export * as OperationPath from "./OperationPath.js";
+export * as ProxyEnvironment from "./ProxyEnvironment.js";
+export * as Transform from "./Transform.js";
+export * as Presence from "./Presence.js";

package/src/primitives/Array.ts

@@ -0,0 +1,457 @@
+import { Effect, Schema } from "effect";
+import * as OperationDefinition from "../OperationDefinition";
+import * as Operation from "../Operation";
+import * as OperationPath from "../OperationPath";
+import * as ProxyEnvironment from "../ProxyEnvironment";
+import * as Transform from "../Transform";
+import * as FractionalIndex from "../FractionalIndex";
+import type { Primitive, PrimitiveInternal, MaybeUndefined, AnyPrimitive, Validator, InferState, InferProxy, InferSnapshot } from "../Primitive";
+import { ValidationError } from "../Primitive";
+import { runValidators } from "./shared";
+
+
+/**
+ * Entry in an ordered array with ID and fractional position
+ */
+export interface ArrayEntry<T> {
+  readonly id: string;    // Unique element identifier (UUID)
+  readonly pos: string;   // Fractional index for ordering
+  readonly value: T;      // The element value
+}
+
+/**
+ * Sort array entries by their fractional position
+ */
+const sortByPos = <T,>(entries: readonly ArrayEntry<T>[]): ArrayEntry<T>[] =>
+  [...entries].sort((a, b) => a.pos < b.pos ? -1 : a.pos > b.pos ? 1 : 0);
+
+/**
+ * Generate a fractional position between two positions
+ */
+const generatePosBetween = (left: string | null, right: string | null): string => {
+  const charSet = FractionalIndex.base62CharSet();
+  return Effect.runSync(FractionalIndex.generateKeyBetween(left, right, charSet));
+};
+
+/**
+ * Entry in an array snapshot with ID and value snapshot
+ */
+export interface ArrayEntrySnapshot<TElement extends AnyPrimitive> {
+  readonly id: string;
+  readonly value: InferSnapshot<TElement>;
+}
+
+/**
+ * Snapshot type for arrays - always an array (never undefined)
+ */
+export type ArraySnapshot<TElement extends AnyPrimitive> = readonly ArrayEntrySnapshot<TElement>[];
+
+export interface ArrayProxy<TElement extends AnyPrimitive> {
+  /** Gets the current array entries (sorted by position) */
+  get(): ArrayState<TElement>;
+  /** Replaces the entire array with new values (generates new IDs and positions) */
+  set(values: readonly InferState<TElement>[]): void;
+  /** Appends a value to the end of the array */
+  push(value: InferState<TElement>): void;
+  /** Inserts a value at the specified visual index */
+  insertAt(index: number, value: InferState<TElement>): void;
+  /** Removes the element with the specified ID */
+  remove(id: string): void;
+  /** Moves an element to a new visual index */
+  move(id: string, toIndex: number): void;
+  /** Returns a proxy for the element with the specified ID */
+  at(id: string): InferProxy<TElement>;
+  /** Finds an element by predicate and returns its proxy */
+  find(predicate: (value: InferState<TElement>, id: string) => boolean): InferProxy<TElement> | undefined;
+  /** Returns a readonly snapshot of the array for rendering (always returns an array, never undefined) */
+  toSnapshot(): ArraySnapshot<TElement>;
+}
+
+/** The state type for arrays - an array of entries */
+export type ArrayState<TElement extends AnyPrimitive> = readonly ArrayEntry<InferState<TElement>>[];
+
+interface ArrayPrimitiveSchema<TElement extends AnyPrimitive> {
+  readonly required: boolean;
+  readonly defaultValue: ArrayState<TElement> | undefined;
+  readonly element: TElement;
+  readonly validators: readonly Validator<ArrayState<TElement>>[];
+}
+
+export class ArrayPrimitive<TElement extends AnyPrimitive>
+  implements Primitive<ArrayState<TElement>, ArrayProxy<TElement>>
+{
+  readonly _tag = "ArrayPrimitive" as const;
+  readonly _State!: ArrayState<TElement>;
+  readonly _Proxy!: ArrayProxy<TElement>;
+
+  private readonly _schema: ArrayPrimitiveSchema<TElement>;
+
+  private readonly _opDefinitions = {
+    set: OperationDefinition.make({
+      kind: "array.set" as const,
+      payload: Schema.Unknown,
+      target: Schema.Unknown,
+      apply: (payload) => payload,
+    }),
+    insert: OperationDefinition.make({
+      kind: "array.insert" as const,
+      payload: Schema.Unknown,
+      target: Schema.Unknown,
+      apply: (payload) => payload,
+    }),
+    remove: OperationDefinition.make({
+      kind: "array.remove" as const,
+      payload: Schema.Unknown,
+      target: Schema.Unknown,
+      apply: (payload) => payload,
+    }),
+    move: OperationDefinition.make({
+      kind: "array.move" as const,
+      payload: Schema.Unknown,
+      target: Schema.Unknown,
+      apply: (payload) => payload,
+    }),
+  };
+
+  constructor(schema: ArrayPrimitiveSchema<TElement>) {
+    this._schema = schema;
+  }
+
+  /** Mark this array as required */
+  required(): ArrayPrimitive<TElement> {
+    return new ArrayPrimitive({
+      ...this._schema,
+      required: true,
+    });
+  }
+
+  /** Set a default value for this array */
+  default(defaultValue: ArrayState<TElement>): ArrayPrimitive<TElement> {
+    return new ArrayPrimitive({
+      ...this._schema,
+      defaultValue,
+    });
+  }
+
+  /** Get the element primitive */
+  get element(): TElement {
+    return this._schema.element;
+  }
+
+  /** Add a custom validation rule */
+  refine(fn: (value: ArrayState<TElement>) => boolean, message: string): ArrayPrimitive<TElement> {
+    return new ArrayPrimitive({
+      ...this._schema,
+      validators: [...this._schema.validators, { validate: fn, message }],
+    });
+  }
+
+  /** Minimum array length */
+  minLength(length: number): ArrayPrimitive<TElement> {
+    return this.refine(
+      (v) => v.length >= length,
+      `Array must have at least ${length} elements`
+    );
+  }
+
+  /** Maximum array length */
+  maxLength(length: number): ArrayPrimitive<TElement> {
+    return this.refine(
+      (v) => v.length <= length,
+      `Array must have at most ${length} elements`
+    );
+  }
+
+  readonly _internal: PrimitiveInternal<ArrayState<TElement>, ArrayProxy<TElement>> = {
+    createProxy: (env: ProxyEnvironment.ProxyEnvironment, operationPath: OperationPath.OperationPath): ArrayProxy<TElement> => {
+      const elementPrimitive = this._schema.element;
+
+      // Helper to get current state (sorted)
+      const getCurrentState = (): ArrayEntry<InferState<TElement>>[] => {
+        const state = env.getState(operationPath) as ArrayState<TElement> | undefined;
+        if (!state || !globalThis.Array.isArray(state)) return [];
+        return sortByPos(state);
+      };
+
+      return {
+        get: (): ArrayState<TElement> => {
+          return getCurrentState();
+        },
+
+        set: (values: readonly InferState<TElement>[]) => {
+          // Generate entries with new IDs and sequential positions
+          const entries: ArrayEntry<InferState<TElement>>[] = [];
+          let prevPos: string | null = null;
+          
+          for (const value of values) {
+            const id = env.generateId();
+            const pos = generatePosBetween(prevPos, null);
+            entries.push({ id, pos, value });
+            prevPos = pos;
+          }
+          
+          env.addOperation(
+            Operation.fromDefinition(operationPath, this._opDefinitions.set, entries)
+          );
+        },
+
+        push: (value: InferState<TElement>) => {
+          const sorted = getCurrentState();
+          const lastPos = sorted.length > 0 ? sorted[sorted.length - 1]!.pos : null;
+          const id = env.generateId();
+          const pos = generatePosBetween(lastPos, null);
+          
+          env.addOperation(
+            Operation.fromDefinition(operationPath, this._opDefinitions.insert, { id, pos, value })
+          );
+        },
+
+        insertAt: (index: number, value: InferState<TElement>) => {
+          const sorted = getCurrentState();
+          const leftPos = index > 0 && sorted[index - 1] ? sorted[index - 1]!.pos : null;
+          const rightPos = index < sorted.length && sorted[index] ? sorted[index]!.pos : null;
+          
+          const id = env.generateId();
+          const pos = generatePosBetween(leftPos, rightPos);
+          
+          env.addOperation(
+            Operation.fromDefinition(operationPath, this._opDefinitions.insert, { id, pos, value })
+          );
+        },
+
+        remove: (id: string) => {
+          env.addOperation(
+            Operation.fromDefinition(operationPath, this._opDefinitions.remove, { id })
+          );
+        },
+
+        move: (id: string, toIndex: number) => {
+          const sorted = getCurrentState();
+          // Filter out the element being moved
+          const without = sorted.filter(e => e.id !== id);
+          
+          const clampedIndex = Math.max(0, Math.min(toIndex, without.length));
+          const leftPos = clampedIndex > 0 && without[clampedIndex - 1] ? without[clampedIndex - 1]!.pos : null;
+          const rightPos = clampedIndex < without.length && without[clampedIndex] ? without[clampedIndex]!.pos : null;
+          
+          const pos = generatePosBetween(leftPos, rightPos);
+          
+          env.addOperation(
+            Operation.fromDefinition(operationPath, this._opDefinitions.move, { id, pos })
+          );
+        },
+
+        at: (id: string): InferProxy<TElement> => {
+          // Use ID in path for element access
+          const elementPath = operationPath.append(id);
+          return elementPrimitive._internal.createProxy(env, elementPath) as InferProxy<TElement>;
+        },
+
+        find: (predicate: (value: InferState<TElement>, id: string) => boolean): InferProxy<TElement> | undefined => {
+          const sorted = getCurrentState();
+          const found = sorted.find(entry => predicate(entry.value, entry.id));
+          if (!found) return undefined;
+          
+          const elementPath = operationPath.append(found.id);
+          return elementPrimitive._internal.createProxy(env, elementPath) as InferProxy<TElement>;
+        },
+
+        toSnapshot: (): ArraySnapshot<TElement> => {
+          const sorted = getCurrentState();
+          return sorted.map(entry => {
+            const elementPath = operationPath.append(entry.id);
+            const elementProxy = elementPrimitive._internal.createProxy(env, elementPath);
+            return {
+              id: entry.id,
+              value: (elementProxy as { toSnapshot(): InferSnapshot<TElement> }).toSnapshot(),
+            };
+          });
+        },
+      };
+    },
+
+    applyOperation: (
+      state: ArrayState<TElement> | undefined,
+      operation: Operation.Operation<any, any, any>
+    ): ArrayState<TElement> => {
+      const path = operation.path;
+      const tokens = path.toTokens().filter((t: string) => t !== "");
+      const currentState = state ?? [];
+
+      let newState: ArrayState<TElement>;
+
+      // If path is empty, this is an array-level operation
+      if (tokens.length === 0) {
+        switch (operation.kind) {
+          case "array.set": {
+            const payload = operation.payload;
+            if (!globalThis.Array.isArray(payload)) {
+              throw new ValidationError(`ArrayPrimitive.set requires an array payload`);
+            }
+            newState = payload as ArrayState<TElement>;
+            break;
+          }
+          case "array.insert": {
+            const { id, pos, value } = operation.payload as { id: string; pos: string; value: InferState<TElement> };
+            newState = [...currentState, { id, pos, value }];
+            break;
+          }
+          case "array.remove": {
+            const { id } = operation.payload as { id: string };
+            newState = currentState.filter(entry => entry.id !== id);
+            break;
+          }
+          case "array.move": {
+            const { id, pos } = operation.payload as { id: string; pos: string };
+            newState = currentState.map(entry => 
+              entry.id === id ? { ...entry, pos } : entry
+            );
+            break;
+          }
+          default:
+            throw new ValidationError(`ArrayPrimitive cannot apply operation of kind: ${operation.kind}`);
+        }
+      } else {
+        // Otherwise, delegate to the element with the specified ID
+        const elementId = tokens[0]!;
+        const entryIndex = currentState.findIndex(entry => entry.id === elementId);
+        
+        if (entryIndex === -1) {
+          throw new ValidationError(`Array element not found with ID: ${elementId}`);
+        }
+
+        const elementPrimitive = this._schema.element;
+        const remainingPath = path.shift();
+        const elementOperation = {
+          ...operation,
+          path: remainingPath,
+        };
+
+        const currentEntry = currentState[entryIndex]!;
+        const newValue = elementPrimitive._internal.applyOperation(currentEntry.value, elementOperation);
+
+        const mutableState = [...currentState];
+        mutableState[entryIndex] = { ...currentEntry, value: newValue };
+        newState = mutableState;
+      }
+
+      // Run validators on the new state
+      runValidators(newState, this._schema.validators);
+
+      return newState;
+    },
+
+    getInitialState: (): ArrayState<TElement> | undefined => {
+      return this._schema.defaultValue;
+    },
+
+    transformOperation: (
+      clientOp: Operation.Operation<any, any, any>,
+      serverOp: Operation.Operation<any, any, any>
+    ): Transform.TransformResult => {
+      const clientPath = clientOp.path;
+      const serverPath = serverOp.path;
+
+      // If paths don't overlap at all, no transformation needed
+      if (!OperationPath.pathsOverlap(clientPath, serverPath)) {
+        return { type: "transformed", operation: clientOp };
+      }
+
+      // Handle array.remove from server - check if client is operating on removed element
+      if (serverOp.kind === "array.remove") {
+        const removedId = (serverOp.payload as { id: string }).id;
+        const clientTokens = clientPath.toTokens().filter((t: string) => t !== "");
+        const serverTokens = serverPath.toTokens().filter((t: string) => t !== "");
+
+        // Check if client is operating on the removed element or its children
+        if (clientTokens.length > serverTokens.length) {
+          const elementId = clientTokens[serverTokens.length];
+          if (elementId === removedId) {
+            // Client operation targets a removed element - becomes noop
+            return { type: "noop" };
+          }
+        }
+      }
+
+      // Both inserting into same array - no conflict (fractional indexing handles ordering)
+      if (serverOp.kind === "array.insert" && clientOp.kind === "array.insert") {
+        return { type: "transformed", operation: clientOp };
+      }
+
+      // Both moving elements in same array
+      if (serverOp.kind === "array.move" && clientOp.kind === "array.move") {
+        const serverMoveId = (serverOp.payload as { id: string }).id;
+        const clientMoveId = (clientOp.payload as { id: string }).id;
+
+        if (serverMoveId === clientMoveId) {
+          // Client's move supersedes server's move (last-write-wins for position)
+          return { type: "transformed", operation: clientOp };
+        }
+        // Different elements - no conflict
+        return { type: "transformed", operation: clientOp };
+      }
+
+      // For operations on same exact path: client wins (last-write-wins)
+      if (OperationPath.pathsEqual(clientPath, serverPath)) {
+        return { type: "transformed", operation: clientOp };
+      }
+
+      // If server set entire array and client is operating on an element
+      if (serverOp.kind === "array.set" && OperationPath.isPrefix(serverPath, clientPath)) {
+        // Client's element operation may be invalid after array replacement
+        // However, for optimistic updates, we let the client op proceed
+        // and the server will validate/reject if needed
+        return { type: "transformed", operation: clientOp };
+      }
+
+      // Delegate to element primitive for nested operations
+      const clientTokens = clientPath.toTokens().filter((t: string) => t !== "");
+      const serverTokens = serverPath.toTokens().filter((t: string) => t !== "");
+
+      // Both operations target children of this array
+      if (clientTokens.length > 0 && serverTokens.length > 0) {
+        const clientElementId = clientTokens[0];
+        const serverElementId = serverTokens[0];
+
+        // If operating on different elements, no conflict
+        if (clientElementId !== serverElementId) {
+          return { type: "transformed", operation: clientOp };
+        }
+
+        // Same element - delegate to element primitive
+        const elementPrimitive = this._schema.element;
+        const clientOpForElement = {
+          ...clientOp,
+          path: clientOp.path.shift(),
+        };
+        const serverOpForElement = {
+          ...serverOp,
+          path: serverOp.path.shift(),
+        };
+
+        const result = elementPrimitive._internal.transformOperation(clientOpForElement, serverOpForElement);
+
+        if (result.type === "transformed") {
+          // Restore the original path prefix
+          return {
+            type: "transformed",
+            operation: {
+              ...result.operation,
+              path: clientOp.path,
+            },
+          };
+        }
+
+        return result;
+      }
+
+      // Default: no transformation needed
+      return { type: "transformed", operation: clientOp };
+    },
+  };
+}
+
+/** Creates a new ArrayPrimitive with the given element type */
+export const Array = <TElement extends AnyPrimitive>(element: TElement): ArrayPrimitive<TElement> =>
+  new ArrayPrimitive({ required: false, defaultValue: undefined, element, validators: [] });
+

package/src/primitives/Boolean.ts

@@ -0,0 +1,128 @@
+import { Schema } from "effect";
+import * as OperationDefinition from "../OperationDefinition";
+import * as Operation from "../Operation";
+import * as OperationPath from "../OperationPath";
+import * as ProxyEnvironment from "../ProxyEnvironment";
+import * as Transform from "../Transform";
+import type { Primitive, PrimitiveInternal, MaybeUndefined, Validator } from "./shared";
+import { runValidators, isCompatibleOperation, ValidationError } from "./shared";
+
+
+export interface BooleanProxy<TDefined extends boolean = false> {
+  /** Gets the current boolean value */
+  get(): MaybeUndefined<boolean, TDefined>;
+  /** Sets the boolean value, generating a boolean.set operation */
+  set(value: boolean): void;
+  /** Returns a readonly snapshot of the boolean value for rendering */
+  toSnapshot(): MaybeUndefined<boolean, TDefined>;
+}
+
+interface BooleanPrimitiveSchema {
+  readonly required: boolean;
+  readonly defaultValue: boolean | undefined;
+  readonly validators: readonly Validator<boolean>[];
+}
+
+export class BooleanPrimitive<TDefined extends boolean = false> implements Primitive<boolean, BooleanProxy<TDefined>> {
+  readonly _tag = "BooleanPrimitive" as const;
+  readonly _State!: boolean;
+  readonly _Proxy!: BooleanProxy<TDefined>;
+
+  private readonly _schema: BooleanPrimitiveSchema;
+
+  private readonly _opDefinitions = {
+    set: OperationDefinition.make({
+      kind: "boolean.set" as const,
+      payload: Schema.Boolean,
+      target: Schema.Boolean,
+      apply: (payload) => payload,
+    }),
+  };
+
+  constructor(schema: BooleanPrimitiveSchema) {
+    this._schema = schema;
+  }
+
+  /** Mark this boolean as required */
+  required(): BooleanPrimitive<true> {
+    return new BooleanPrimitive({
+      ...this._schema,
+      required: true,
+    });
+  }
+
+  /** Set a default value for this boolean */
+  default(defaultValue: boolean): BooleanPrimitive<true> {
+    return new BooleanPrimitive({
+      ...this._schema,
+      defaultValue,
+    });
+  }
+
+  /** Add a custom validation rule */
+  refine(fn: (value: boolean) => boolean, message: string): BooleanPrimitive<TDefined> {
+    return new BooleanPrimitive({
+      ...this._schema,
+      validators: [...this._schema.validators, { validate: fn, message }],
+    });
+  }
+
+  readonly _internal: PrimitiveInternal<boolean, BooleanProxy<TDefined>> = {
+    createProxy: (env: ProxyEnvironment.ProxyEnvironment, operationPath: OperationPath.OperationPath): BooleanProxy<TDefined> => {
+      const defaultValue = this._schema.defaultValue;
+      return {
+        get: (): MaybeUndefined<boolean, TDefined> => {
+          const state = env.getState(operationPath) as boolean | undefined;
+          return (state ?? defaultValue) as MaybeUndefined<boolean, TDefined>;
+        },
+        set: (value: boolean) => {
+          env.addOperation(
+            Operation.fromDefinition(operationPath, this._opDefinitions.set, value)
+          );
+        },
+        toSnapshot: (): MaybeUndefined<boolean, TDefined> => {
+          const state = env.getState(operationPath) as boolean | undefined;
+          return (state ?? defaultValue) as MaybeUndefined<boolean, TDefined>;
+        },
+      };
+    },
+
+    applyOperation: (state: boolean | undefined, operation: Operation.Operation<any, any, any>): boolean => {
+      if (operation.kind !== "boolean.set") {
+        throw new ValidationError(`BooleanPrimitive cannot apply operation of kind: ${operation.kind}`);
+      }
+
+      const payload = operation.payload;
+      if (typeof payload !== "boolean") {
+        throw new ValidationError(`BooleanPrimitive.set requires a boolean payload, got: ${typeof payload}`);
+      }
+
+      // Run validators
+      runValidators(payload, this._schema.validators);
+
+      return payload;
+    },
+
+    getInitialState: (): boolean | undefined => {
+      return this._schema.defaultValue;
+    },
+
+    transformOperation: (
+      clientOp: Operation.Operation<any, any, any>,
+      serverOp: Operation.Operation<any, any, any>
+    ): Transform.TransformResult => {
+      // If paths don't overlap, no transformation needed
+      if (!OperationPath.pathsOverlap(clientOp.path, serverOp.path)) {
+        return { type: "transformed", operation: clientOp };
+      }
+
+      // For same path, client wins (last-write-wins)
+      return { type: "transformed", operation: clientOp };
+    },
+  };
+}
+
+/** Creates a new BooleanPrimitive */
+export const Boolean = (): BooleanPrimitive<false> =>
+  new BooleanPrimitive({ required: false, defaultValue: undefined, validators: [] });
+