@voidhash/mimic 0.0.4 → 0.0.5

package/src/Document.ts

@@ -80,8 +80,14 @@ export interface Document<TSchema extends Primitive.AnyPrimitive> {
 // =============================================================================
 
 export interface DocumentOptions<TSchema extends Primitive.AnyPrimitive> {
-  /** Initial state for the document */
-  readonly initial?: Primitive.InferState<TSchema>;
+  /** Initial value for the document (using set input format) */
+  readonly initial?: Primitive.InferSetInput<TSchema>;
+  /**
+   * Raw initial state for the document (already in internal state format).
+   * Use this when loading state from the server or storage.
+   * Takes precedence over `initial` if both are provided.
+   */
+  readonly initialState?: Primitive.InferState<TSchema>;
 }
 
 // =============================================================================
@@ -95,9 +101,16 @@ export const make = <TSchema extends Primitive.AnyPrimitive>(
   schema: TSchema,
   options?: DocumentOptions<TSchema>
 ): Document<TSchema> => {
-  // Internal state
-  let _state: Primitive.InferState<TSchema> | undefined = 
-    options?.initial ?? schema._internal.getInitialState();
+  // Internal state - determine initial state based on options
+  // Priority: initialState (raw) > initial (needs conversion) > schema defaults
+  let _state: Primitive.InferState<TSchema> | undefined =
+    options?.initialState !== undefined
+      ? options.initialState
+      : options?.initial !== undefined
+        ? (schema._internal.convertSetInputToState
+            ? schema._internal.convertSetInputToState(options.initial)
+            : options.initial as Primitive.InferState<TSchema>)
+        : schema._internal.getInitialState();
   
   // Pending operations buffer (local changes not yet flushed)
   let _pending: Operation.Operation<any, any, any>[] = [];

package/src/client/ClientDocument.ts

@@ -265,8 +265,8 @@ export const make = <
   let _serverTransactionHistory: Transaction.Transaction[] = [];
   const MAX_HISTORY_SIZE = 100;
 
-  // The underlying document for optimistic state
-  let _optimisticDoc = Document.make(schema, { initial: _serverState });
+  // The underlying document for optimistic state (use initialState for raw state format)
+  let _optimisticDoc = Document.make(schema, { initialState: _serverState });
 
   // Subscription cleanup
   let _unsubscribe: (() => void) | null = null;
@@ -467,8 +467,8 @@ export const make = <
       serverState: _serverState,
     });
 
-    // Create fresh document from server state
-    _optimisticDoc = Document.make(schema, { initial: _serverState });
+    // Create fresh document from server state (use initialState for raw state format)
+    _optimisticDoc = Document.make(schema, { initialState: _serverState });
 
     // Apply all pending transactions
     for (const pending of _pending) {
@@ -484,16 +484,14 @@ export const make = <
 
   /**
    * Adds a transaction to pending queue and sends to server.
+   * If disconnected, the transport will queue it for later submission.
    */
   const submitTransaction = (tx: Transaction.Transaction): void => {
-    if (!transport.isConnected()) {
-      throw new NotConnectedError();
-    }
-
     debugLog("submitTransaction", {
       txId: tx.id,
       ops: tx.ops,
       pendingCount: _pending.length + 1,
+      isConnected: transport.isConnected(),
     });
 
     const pending: PendingTransaction = {
@@ -504,15 +502,18 @@ export const make = <
 
     _pending.push(pending);
 
-    // Set timeout for this transaction
-    const timeoutHandle = setTimeout(() => {
-      handleTransactionTimeout(tx.id);
-    }, transactionTimeout);
-    _timeoutHandles.set(tx.id, timeoutHandle);
+    // Only set timeout if connected - otherwise the transport queues it
+    // and the timeout will start when the message is actually sent on reconnect
+    if (transport.isConnected()) {
+      const timeoutHandle = setTimeout(() => {
+        handleTransactionTimeout(tx.id);
+      }, transactionTimeout);
+      _timeoutHandles.set(tx.id, timeoutHandle);
+    }
 
-    // Send to server
+    // Send to server (transport queues if disconnected)
     transport.send(tx);
-    debugLog("submitTransaction: sent to server", { txId: tx.id });
+    debugLog("submitTransaction: sent to transport", { txId: tx.id, queued: !transport.isConnected() });
   };
 
   /**
@@ -585,7 +586,7 @@ export const make = <
       _pending.splice(pendingIndex, 1);
 
       // Apply to server state
-      const tempDoc = Document.make(schema, { initial: _serverState });
+      const tempDoc = Document.make(schema, { initialState: _serverState });
       tempDoc.apply(serverTx.ops);
       _serverState = tempDoc.get();
 
@@ -605,7 +606,7 @@ export const make = <
       });
 
       // Apply to server state
-      const tempDoc = Document.make(schema, { initial: _serverState });
+      const tempDoc = Document.make(schema, { initialState: _serverState });
       tempDoc.apply(serverTx.ops);
       _serverState = tempDoc.get();
 
@@ -937,10 +938,8 @@ export const make = <
         pendingCount: _pending.length,
       });
 
-      if (!transport.isConnected()) {
-        throw new NotConnectedError();
-      }
-
+      // Allow transactions even when disconnected - they will be queued
+      // Only require that we have been initialized at least once (have server state)
       if (_initState.type !== "ready") {
         throw new InvalidStateError("Client is not ready. Wait for initialization to complete.");
       }

package/src/client/WebSocketTransport.ts

@@ -458,11 +458,10 @@ export const make = (options: WebSocketTransportOptions): Transport.Transport =>
 
       if (_state.type === "connected") {
         sendRaw(message);
-      } else if (_state.type === "reconnecting") {
-        // Queue message for when we reconnect
+      } else {
+        // Queue message for when we reconnect (works for both reconnecting and disconnected states)
         _messageQueue.push(message);
       }
-      // If disconnected, silently drop (caller should check isConnected)
     },
 
     requestSnapshot: (): void => {
@@ -470,7 +469,8 @@ export const make = (options: WebSocketTransportOptions): Transport.Transport =>
 
       if (_state.type === "connected") {
         sendRaw(message);
-      } else if (_state.type === "reconnecting") {
+      } else {
+        // Queue for later
         _messageQueue.push(message);
       }
     },
@@ -546,9 +546,9 @@ export const make = (options: WebSocketTransportOptions): Transport.Transport =>
 
       if (_state.type === "connected") {
         sendRaw(message);
-      } else if (_state.type === "reconnecting") {
-        // Remove all set messages from the message queue
-        _messageQueue = _messageQueue.filter((message) => message.type !== "presence_set");
+      } else {
+        // Remove all set messages from the message queue (only keep latest)
+        _messageQueue = _messageQueue.filter((m) => m.type !== "presence_set");
         // Add the new presence set message to the queue
         _messageQueue.push(message);
       }
@@ -559,9 +559,9 @@ export const make = (options: WebSocketTransportOptions): Transport.Transport =>
 
       if (_state.type === "connected") {
         sendRaw(message);
-      } else if (_state.type === "reconnecting") {
+      } else {
         // Remove all clear messages from the message queue
-        _messageQueue = _messageQueue.filter((message) => message.type !== "presence_clear");
+        _messageQueue = _messageQueue.filter((m) => m.type !== "presence_clear");
         // Add the new presence clear message to the queue
         _messageQueue.push(message);
       }

package/src/primitives/Tree.ts

@@ -121,15 +121,128 @@ export type TreeNodeUpdateValue<TNode extends AnyTreeNodePrimitive> =
  * Uses StructSetInput directly so that:
  * - Fields that are required AND have no default must be provided
  * - Fields that are optional OR have defaults can be omitted
- * 
+ *
  * This bypasses the struct-level NeedsValue wrapper since tree inserts
  * always require a data object (even if empty for all-optional fields).
  */
-export type TreeNodeDataSetInput<TNode extends AnyTreeNodePrimitive> = 
+export type TreeNodeDataSetInput<TNode extends AnyTreeNodePrimitive> =
   TNode["data"] extends StructPrimitive<infer TFields, any, any>
     ? StructSetInput<TFields>
     : InferSetInput<TNode["data"]>;
 
+// =============================================================================
+// Nested Input Types for set() and default()
+// =============================================================================
+
+/**
+ * Type guard to check if a type is `any` or unknown (structural check).
+ * Returns true if T is `any`, false otherwise.
+ */
+type IsAny<T> = 0 extends (1 & T) ? true : false;
+
+/**
+ * Get children types, with special handling for self-referential nodes.
+ * When InferTreeNodeChildren returns `any` (from TreeNodePrimitive<..., any>),
+ * we fall back to using TNode itself as its own child type.
+ * This handles the common case of self-referential nodes like:
+ *   FolderNode = TreeNode("folder", { children: [TreeNodeSelf, FileNode] })
+ * Where FolderNode's TChildren is resolved to FolderNode | FileNode,
+ * but the self-referenced FolderNode has TChildren = any.
+ */
+type ResolveChildrenForInput<TNode extends AnyTreeNodePrimitive, TOriginalNode extends AnyTreeNodePrimitive> =
+  IsAny<InferTreeNodeChildren<TNode>> extends true
+    ? TOriginalNode // Self-reference: use the original node's type
+    : InferTreeNodeChildren<TNode>;
+
+/**
+ * Helper type that creates a properly typed node input for a specific node type.
+ * This is the "strict" version that enforces exact property matching.
+ *
+ * The TOriginalNode parameter is used to track the original root node type
+ * for proper self-reference resolution in deeply nested structures.
+ */
+type TreeNodeSetInputStrictWithRoot<TNode extends AnyTreeNodePrimitive, TOriginalNode extends AnyTreeNodePrimitive> = {
+  readonly type: InferTreeNodeType<TNode>;
+  readonly id?: string;
+  readonly children: TreeNodeSetInputUnionWithRoot<ResolveChildrenForInput<TNode, TOriginalNode>, TOriginalNode>[];
+} & TreeNodeDataSetInput<TNode>;
+
+/**
+ * Distributive conditional type that creates a union of TreeNodeSetInputStrict
+ * for each node type in the union. This ensures proper type discrimination.
+ *
+ * When TNode is a union (e.g., FolderNode | FileNode), this distributes to:
+ * TreeNodeSetInputStrict<FolderNode> | TreeNodeSetInputStrict<FileNode>
+ *
+ * This creates a proper discriminated union where excess property checking works.
+ */
+type TreeNodeSetInputUnionWithRoot<TNode extends AnyTreeNodePrimitive, TOriginalNode extends AnyTreeNodePrimitive> =
+  TNode extends AnyTreeNodePrimitive ? TreeNodeSetInputStrictWithRoot<TNode, TOriginalNode> : never;
+
+/**
+ * Helper type for single-parameter usage - uses TNode as its own original.
+ */
+type TreeNodeSetInputStrict<TNode extends AnyTreeNodePrimitive> =
+  TreeNodeSetInputStrictWithRoot<TNode, TNode>;
+
+/**
+ * Distributive conditional for single-parameter usage.
+ */
+export type TreeNodeSetInputUnion<TNode extends AnyTreeNodePrimitive> =
+  TNode extends AnyTreeNodePrimitive ? TreeNodeSetInputStrict<TNode> : never;
+
+/**
+ * Input type for a single node in a nested tree set/default operation.
+ *
+ * - `type` is REQUIRED - explicit type discriminator for the node
+ * - `id` is optional - auto-generated if not provided
+ * - `children` is a typed array of allowed child node inputs
+ * - Data fields are spread at the node level (like TreeNodeSnapshot)
+ *
+ * When TNode is a union type (e.g., from InferTreeNodeChildren), this properly
+ * distributes to create a discriminated union where:
+ * - Each variant has its specific `type` literal
+ * - Each variant has its specific data fields
+ * - Excess property checking works correctly
+ *
+ * @example
+ * ```typescript
+ * const input: TreeNodeSetInput<BoardNode> = {
+ *   type: "board",
+ *   name: "My Board",
+ *   children: [
+ *     { type: "column", name: "Todo", children: [] }
+ *   ]
+ * };
+ * ```
+ */
+export type TreeNodeSetInput<TNode extends AnyTreeNodePrimitive> = TreeNodeSetInputUnion<TNode>;
+
+/**
+ * Input type for tree set() and default() operations.
+ * Accepts a nested tree structure that will be converted to flat TreeState internally.
+ */
+export type TreeSetInput<TRoot extends AnyTreeNodePrimitive> = TreeNodeSetInput<TRoot>;
+
+/**
+ * Infer the set input type for a tree primitive.
+ */
+export type InferTreeSetInput<T extends TreePrimitive<any>> =
+  T extends TreePrimitive<infer TRoot> ? TreeSetInput<TRoot> : never;
+
+/**
+ * Internal type for processing any node input during conversion.
+ * This is only used internally in _convertNestedToFlat and is not exported.
+ * Allows us to keep the public TreeNodeSetInput<TNode> fully type-safe while
+ * having a runtime-compatible type for internal processing.
+ */
+type InternalNodeInput = {
+  readonly type: string;
+  readonly id?: string;
+  readonly children: InternalNodeInput[];
+  readonly [key: string]: unknown;
+};
+
 /**
  * Typed proxy for a specific node type - provides type-safe data access
  */
@@ -172,9 +285,9 @@ export interface TreeNodeProxyBase<_TRoot extends AnyTreeNodePrimitive> {
 export interface TreeProxy<TRoot extends AnyTreeNodePrimitive> {
   /** Gets the entire tree state (flat array of nodes) */
   get(): TreeState<TRoot>;
-  
-  /** Replaces the entire tree */
-  set(nodes: TreeState<TRoot>): void;
+
+  /** Replaces the entire tree with a nested input structure */
+  set(input: TreeSetInput<TRoot>): void;
   
   /** Gets the root node state */
   root(): TypedTreeNodeState<TRoot> | undefined;
@@ -258,16 +371,13 @@ export interface TreeProxy<TRoot extends AnyTreeNodePrimitive> {
 
 interface TreePrimitiveSchema<TRoot extends AnyTreeNodePrimitive> {
   readonly required: boolean;
-  readonly defaultValue: TreeState<TRoot> | undefined;
+  readonly defaultInput: TreeNodeSetInput<TRoot> | undefined;
   readonly root: TRoot;
   readonly validators: readonly Validator<TreeState<TRoot>>[];
 }
 
-/** Input type for tree set() - tree state */
-export type TreeSetInput<TRoot extends AnyTreeNodePrimitive> = TreeState<TRoot>;
-
-/** Input type for tree update() - same as set() for trees */
-export type TreeUpdateInput<TRoot extends AnyTreeNodePrimitive> = TreeState<TRoot>;
+/** Input type for tree update() - same as set() for trees (nested format) */
+export type TreeUpdateInput<TRoot extends AnyTreeNodePrimitive> = TreeNodeSetInput<TRoot>;
 
 export class TreePrimitive<TRoot extends AnyTreeNodePrimitive, TRequired extends boolean = false, THasDefault extends boolean = false>
   implements Primitive<TreeState<TRoot>, TreeProxy<TRoot>, TRequired, THasDefault, TreeSetInput<TRoot>, TreeUpdateInput<TRoot>>
@@ -322,11 +432,11 @@ export class TreePrimitive<TRoot extends AnyTreeNodePrimitive, TRequired extends
     });
   }
 
-  /** Set a default value for this tree */
-  default(defaultValue: TreeState<TRoot>): TreePrimitive<TRoot, TRequired, true> {
+  /** Set a default value for this tree (nested format) */
+  default(defaultInput: TreeNodeSetInput<TRoot>): TreePrimitive<TRoot, TRequired, true> {
     return new TreePrimitive({
       ...this._schema,
-      defaultValue,
+      defaultInput,
     });
   }
 
@@ -408,6 +518,78 @@ export class TreePrimitive<TRoot extends AnyTreeNodePrimitive, TRequired extends
     }
   }
 
+  /**
+   * Convert a nested TreeNodeSetInput to flat TreeState format.
+   * Recursively processes nodes, generating IDs and positions as needed.
+   *
+   * @param input - The root nested input to convert
+   * @param generateId - Optional ID generator (defaults to crypto.randomUUID)
+   * @returns Flat TreeState array
+   */
+  private _convertNestedToFlat(
+    input: TreeNodeSetInput<TRoot>,
+    generateId: () => string = () => crypto.randomUUID()
+  ): TreeState<TRoot> {
+    const result: TreeNodeState[] = [];
+    const seenIds = new Set<string>();
+
+    const processNode = (
+      nodeInput: InternalNodeInput,
+      parentId: string | null,
+      parentType: string | null,
+      leftPos: string | null,
+      rightPos: string | null
+    ): void => {
+      // Validate node type
+      this._validateChildType(parentType, nodeInput.type);
+
+      // Get the node primitive for this type
+      const nodePrimitive = this._getNodeTypePrimitive(nodeInput.type);
+
+      // Generate or use provided ID
+      const id = nodeInput.id ?? generateId();
+
+      // Check for duplicate IDs
+      if (seenIds.has(id)) {
+        throw new ValidationError(`Duplicate node ID: ${id}`);
+      }
+      seenIds.add(id);
+
+      // Generate position
+      const pos = generateTreePosBetween(leftPos, rightPos);
+
+      // Extract data fields (everything except type, id, and children)
+      const { type: _type, id: _id, children, ...dataFields } = nodeInput;
+
+      // Apply defaults to node data
+      const mergedData = applyDefaults(nodePrimitive.data as AnyPrimitive, dataFields);
+
+      // Add this node to result
+      result.push({
+        id,
+        type: nodeInput.type,
+        parentId,
+        pos,
+        data: mergedData,
+      });
+
+      // Process children recursively
+      let prevChildPos: string | null = null;
+      for (let i = 0; i < children.length; i++) {
+        const childInput = children[i]!;
+        // Each child gets a position after the previous child
+        processNode(childInput, id, nodeInput.type, prevChildPos, null);
+        // Update prevChildPos to the pos that was just assigned (it's the last item in result)
+        prevChildPos = result[result.length - 1]!.pos;
+      }
+    };
+
+    // Process root node (cast to InternalNodeInput for internal processing)
+    processNode(input as unknown as InternalNodeInput, null, null, null, null);
+
+    return result as TreeState<TRoot>;
+  }
+
   readonly _internal: PrimitiveInternal<TreeState<TRoot>, TreeProxy<TRoot>> = {
     createProxy: (
       env: ProxyEnvironment.ProxyEnvironment,
@@ -496,9 +678,11 @@ export class TreePrimitive<TRoot extends AnyTreeNodePrimitive, TRequired extends
           return getCurrentState();
         },
 
-        set: (nodes: TreeState<TRoot>) => {
+        set: (input: TreeSetInput<TRoot>) => {
+          // Convert nested input to flat TreeState using env.generateId for IDs
+          const flatState = this._convertNestedToFlat(input, env.generateId);
           env.addOperation(
-            Operation.fromDefinition(operationPath, this._opDefinitions.set, nodes)
+            Operation.fromDefinition(operationPath, this._opDefinitions.set, flatState)
           );
         },
 
@@ -1074,8 +1258,9 @@ export class TreePrimitive<TRoot extends AnyTreeNodePrimitive, TRequired extends
     },
 
     getInitialState: (): TreeState<TRoot> | undefined => {
-      if (this._schema.defaultValue !== undefined) {
-        return this._schema.defaultValue;
+      if (this._schema.defaultInput !== undefined) {
+        // Convert nested input to flat TreeState
+        return this._convertNestedToFlat(this._schema.defaultInput);
       }
 
       // Automatically create a root node with default data
@@ -1093,6 +1278,11 @@ export class TreePrimitive<TRoot extends AnyTreeNodePrimitive, TRequired extends
       }] as TreeState<TRoot>;
     },
 
+    convertSetInputToState: (input: unknown): TreeState<TRoot> => {
+      // Convert nested input format to flat TreeState
+      return this._convertNestedToFlat(input as TreeNodeSetInput<TRoot>);
+    },
+
     transformOperation: (
       clientOp: Operation.Operation<any, any, any>,
       serverOp: Operation.Operation<any, any, any>
@@ -1201,7 +1391,7 @@ export const Tree = <TRoot extends AnyTreeNodePrimitive>(
 ): TreePrimitive<TRoot, false, false> =>
   new TreePrimitive({
     required: false,
-    defaultValue: undefined,
+    defaultInput: undefined,
     root: options.root,
     validators: [],
   });

package/src/primitives/shared.ts

@@ -38,10 +38,19 @@ export interface Primitive<TState, TProxy, TRequired extends boolean = false, TH
     readonly applyOperation: (state: TState | undefined, operation: Operation.Operation<any, any, any>) => TState;
     /** Returns the initial/default state for this primitive */
     readonly getInitialState: () => TState | undefined;
+    /**
+     * Converts a set input value to state format.
+     * For most primitives, this is a simple pass-through with defaults applied.
+     * For Tree primitives, this converts nested input to flat TreeState.
+     *
+     * @param input - The set input value
+     * @returns The corresponding state value
+     */
+    readonly convertSetInputToState?: (input: unknown) => TState;
     /**
      * Transforms a client operation against a server operation.
      * Used for operational transformation (OT) conflict resolution.
-     * 
+     *
      * @param clientOp - The client's operation to transform
      * @param serverOp - The server's operation that has already been applied
      * @returns TransformResult indicating how the client operation should be handled

package/src/server/ServerDocument.ts

@@ -60,8 +60,8 @@ export type SubmitResult =
 export interface ServerDocumentOptions<TSchema extends Primitive.AnyPrimitive> {
   /** The schema defining the document structure */
   readonly schema: TSchema;
-  /** Initial state (optional, will use schema defaults if not provided) */
-  readonly initialState?: Primitive.InferState<TSchema>;
+  /** Initial value (optional, will use schema defaults if not provided) - uses set input format */
+  readonly initialState?: Primitive.InferSetInput<TSchema>;
   /** Initial version number (optional, defaults to 0) */
   readonly initialVersion?: number;
   /** Called when a transaction is successfully applied and should be broadcast */
@@ -177,8 +177,9 @@ export const make = <TSchema extends Primitive.AnyPrimitive>(
     }
 
     // Create a temporary document with current state to test the operations
+    // Use initialState (not initial) since currentState is already in flat state format
     const currentState = _document.get();
-    const tempDoc = Document.make(schema, { initial: currentState });
+    const tempDoc = Document.make(schema, { initialState: currentState });
 
     try {
       // Attempt to apply all operations