@voidhash/mimic 0.0.1-alpha.6 → 0.0.1-alpha.7

package/src/primitives/shared.ts

@@ -11,11 +11,18 @@ import * as Transform from "../Transform";
 /**
  * Base interface that all primitives must implement.
  * Provides type inference helpers and internal operations.
+ * 
+ * @typeParam TState - The state type this primitive holds
+ * @typeParam TProxy - The proxy type for interacting with this primitive
+ * @typeParam TDefined - Whether the value is guaranteed to be defined (via required() or default())
+ * @typeParam THasDefault - Whether this primitive has a default value
  */
-export interface Primitive<TState, TProxy> {
+export interface Primitive<TState, TProxy, TDefined extends boolean = false, THasDefault extends boolean = false> {
     readonly _tag: string;
     readonly _State: TState;
     readonly _Proxy: TProxy;
+    readonly _TDefined: TDefined;
+    readonly _THasDefault: THasDefault;
     readonly _internal: PrimitiveInternal<TState, TProxy>;
   }
   
@@ -46,17 +53,17 @@ export interface Primitive<TState, TProxy> {
   /**
    * Any primitive type - used for generic constraints.
    */
-  export type AnyPrimitive = Primitive<any, any>;
+  export type AnyPrimitive = Primitive<any, any, any, any>;
   
   /**
    * Infer the state type from a primitive.
    */
-  export type InferState<T> = T extends Primitive<infer S, any> ? S : never;
+  export type InferState<T> = T extends Primitive<infer S, any, any, any> ? S : never;
   
   /**
    * Infer the proxy type from a primitive.
    */
-  export type InferProxy<T> = T extends Primitive<any, infer P> ? P : never;
+  export type InferProxy<T> = T extends Primitive<any, infer P, any, any> ? P : never;
   
   /**
    * Helper type to conditionally add undefined based on TDefined.
@@ -69,9 +76,48 @@ export interface Primitive<TState, TProxy> {
    * Infer the snapshot type from a primitive.
    * The snapshot is a readonly, type-safe structure suitable for rendering.
    */
-  export type InferSnapshot<T> = T extends Primitive<any, infer P>
+  export type InferSnapshot<T> = T extends Primitive<any, infer P, any, any>
     ? P extends { toSnapshot(): infer S } ? S : never
     : never;
+
+  /**
+   * Extract THasDefault from a primitive.
+   */
+  export type HasDefault<T> = T extends Primitive<any, any, any, infer H> ? H : false;
+
+  /**
+   * Extract TDefined from a primitive.
+   */
+  export type IsDefined<T> = T extends Primitive<any, any, infer D, any> ? D : false;
+
+  /**
+   * Determines if a field is required for set() operations.
+   * A field is required if: TDefined is true AND THasDefault is false
+   */
+  export type IsRequiredForSet<T> = T extends Primitive<any, any, true, false> ? true : false;
+
+  /**
+   * Extract keys of fields that are required for set() (required without default).
+   */
+  export type RequiredSetKeys<TFields extends Record<string, AnyPrimitive>> = {
+    [K in keyof TFields]: IsRequiredForSet<TFields[K]> extends true ? K : never;
+  }[keyof TFields];
+
+  /**
+   * Extract keys of fields that are optional for set() (has default OR not required).
+   */
+  export type OptionalSetKeys<TFields extends Record<string, AnyPrimitive>> = {
+    [K in keyof TFields]: IsRequiredForSet<TFields[K]> extends true ? never : K;
+  }[keyof TFields];
+
+  /**
+   * Compute the input type for set() operations on a struct.
+   * Required fields (required without default) must be provided.
+   * Optional fields (has default or not required) can be omitted.
+   */
+  export type StructSetInput<TFields extends Record<string, AnyPrimitive>> = 
+    { readonly [K in RequiredSetKeys<TFields>]: InferState<TFields[K]> } &
+    { readonly [K in OptionalSetKeys<TFields>]?: InferState<TFields[K]> };
   
   // =============================================================================
   // Validation Errors
@@ -120,3 +166,58 @@ export function isCompatibleOperation(operation: Operation.Operation<any, any, a
   return values.some(value => value.kind === operation.kind);
 }
 
+// =============================================================================
+// Default Value Utilities
+// =============================================================================
+
+/**
+ * Applies default values to a partial input, recursively handling nested structs.
+ * 
+ * Uses a two-layer approach:
+ * 1. First, get the struct's initial state (which includes struct-level defaults)
+ * 2. Then, layer the provided values on top
+ * 3. Finally, ensure nested structs are recursively processed
+ * 
+ * @param primitive - The primitive definition containing field information
+ * @param value - The partial value provided by the user
+ * @returns The value with defaults applied for missing fields
+ */
+export function applyDefaults<T extends AnyPrimitive>(
+  primitive: T,
+  value: Partial<InferState<T>>
+): InferState<T> {
+  // Only structs need default merging
+  if (primitive._tag === "StructPrimitive") {
+    const structPrimitive = primitive as unknown as { 
+      fields: Record<string, AnyPrimitive>;
+      _internal: { getInitialState: () => Record<string, unknown> | undefined };
+    };
+    
+    // Start with the struct's initial state (struct-level default or field defaults)
+    const structInitialState = structPrimitive._internal.getInitialState() ?? {};
+    
+    // Layer the provided values on top of initial state
+    const result: Record<string, unknown> = { ...structInitialState, ...value };
+    
+    for (const key in structPrimitive.fields) {
+      const fieldPrimitive = structPrimitive.fields[key]!;
+      
+      if (result[key] === undefined) {
+        // Field still not provided after merging - try individual field default
+        const fieldDefault = fieldPrimitive._internal.getInitialState();
+        if (fieldDefault !== undefined) {
+          result[key] = fieldDefault;
+        }
+      } else if (fieldPrimitive._tag === "StructPrimitive" && typeof result[key] === "object" && result[key] !== null) {
+        // Recursively apply defaults to nested structs
+        result[key] = applyDefaults(fieldPrimitive, result[key] as Partial<InferState<typeof fieldPrimitive>>);
+      }
+    }
+    
+    return result as InferState<T>;
+  }
+  
+  // For non-struct primitives, return the value as-is
+  return value as InferState<T>;
+}
+

package/tests/primitives/Struct.test.ts

@@ -66,6 +66,46 @@ describe("StructPrimitive", () => {
       expect(operations[0]!.payload).toEqual({ name: "Alice", age: "30" });
     });
 
+    it("set() only requires fields that are required and without defaults", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make((op) => {
+        operations.push(op);
+      });
+
+      const structPrimitive = Primitive.Struct({
+        name: Primitive.String().required().default("John Doe"),
+        age: Primitive.Number().required(),
+        email: Primitive.String(),
+      });
+
+      const proxy = structPrimitive._internal.createProxy(env, OperationPath.make(""));
+      proxy.set({ age: 30 });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("struct.set");
+      expect(operations[0]!.payload).toEqual({ name: "John Doe", age: 30, email: undefined });
+    });
+
+    it("set() only requires fields that are required and without defaults", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make((op) => {
+        operations.push(op);
+      });
+
+      const structPrimitive = Primitive.Struct({
+        name: Primitive.String().required(),
+        age: Primitive.Number().required(),
+        email: Primitive.String(),
+      }).default({ name: "John Doe" });
+
+      const proxy = structPrimitive._internal.createProxy(env, OperationPath.make(""));
+      proxy.set({ age: 30 });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("struct.set");
+      expect(operations[0]!.payload).toEqual({ name: "John Doe", age: 30, email: undefined });
+    });
+
     it("multiple field sets generate separate operations", () => {
       const operations: Operation.Operation<any, any, any>[] = [];
       const env = ProxyEnvironment.make((op) => {
@@ -304,6 +344,216 @@ describe("StructPrimitive", () => {
       expect(typeof proxy.set).toBe("function");
     });
   });
+
+  describe("update", () => {
+    it("update() generates individual field operations", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make((op) => {
+        operations.push(op);
+      });
+
+      const structPrimitive = Primitive.Struct({
+        name: Primitive.String(),
+        email: Primitive.String(),
+      });
+
+      const proxy = structPrimitive._internal.createProxy(env, OperationPath.make(""));
+
+      proxy.update({ name: "John" });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("string.set");
+      expect(operations[0]!.payload).toBe("John");
+      expect(operations[0]!.path.toTokens()).toEqual(["name"]);
+    });
+
+    it("update() with multiple fields generates multiple operations", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make((op) => {
+        operations.push(op);
+      });
+
+      const structPrimitive = Primitive.Struct({
+        firstName: Primitive.String(),
+        lastName: Primitive.String(),
+        email: Primitive.String(),
+      });
+
+      const proxy = structPrimitive._internal.createProxy(env, OperationPath.make(""));
+
+      proxy.update({ firstName: "John", lastName: "Doe" });
+
+      expect(operations).toHaveLength(2);
+      expect(operations.map((op) => op.payload)).toContain("John");
+      expect(operations.map((op) => op.payload)).toContain("Doe");
+    });
+
+    it("update() skips undefined values", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make((op) => {
+        operations.push(op);
+      });
+
+      const structPrimitive = Primitive.Struct({
+        name: Primitive.String(),
+        email: Primitive.String(),
+      });
+
+      const proxy = structPrimitive._internal.createProxy(env, OperationPath.make(""));
+
+      proxy.update({ name: "John", email: undefined });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.payload).toBe("John");
+    });
+
+    it("update() recursively updates nested structs", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make((op) => {
+        operations.push(op);
+      });
+
+      const addressPrimitive = Primitive.Struct({
+        street: Primitive.String(),
+        city: Primitive.String(),
+        zip: Primitive.String(),
+      });
+
+      const personPrimitive = Primitive.Struct({
+        name: Primitive.String(),
+        address: addressPrimitive,
+      });
+
+      const proxy = personPrimitive._internal.createProxy(env, OperationPath.make(""));
+
+      // Partial update of nested struct - only city should be updated
+      proxy.update({ address: { city: "New York" } });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("string.set");
+      expect(operations[0]!.payload).toBe("New York");
+      expect(operations[0]!.path.toTokens()).toEqual(["address", "city"]);
+    });
+
+    it("update() handles deeply nested structs", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make((op) => {
+        operations.push(op);
+      });
+
+      const coordsPrimitive = Primitive.Struct({
+        lat: Primitive.String(),
+        lng: Primitive.String(),
+      });
+
+      const locationPrimitive = Primitive.Struct({
+        name: Primitive.String(),
+        coords: coordsPrimitive,
+      });
+
+      const personPrimitive = Primitive.Struct({
+        name: Primitive.String(),
+        location: locationPrimitive,
+      });
+
+      const proxy = personPrimitive._internal.createProxy(env, OperationPath.make(""));
+
+      proxy.update({ location: { coords: { lat: "40.7128" } } });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("string.set");
+      expect(operations[0]!.payload).toBe("40.7128");
+      expect(operations[0]!.path.toTokens()).toEqual(["location", "coords", "lat"]);
+    });
+
+    it("update() can update both nested and top-level fields", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make((op) => {
+        operations.push(op);
+      });
+
+      const addressPrimitive = Primitive.Struct({
+        city: Primitive.String(),
+        zip: Primitive.String(),
+      });
+
+      const personPrimitive = Primitive.Struct({
+        name: Primitive.String(),
+        address: addressPrimitive,
+      });
+
+      const proxy = personPrimitive._internal.createProxy(env, OperationPath.make(""));
+
+      proxy.update({ name: "Jane", address: { city: "Boston" } });
+
+      expect(operations).toHaveLength(2);
+
+      const nameOp = operations.find((op) => op.path.toTokens().join("/") === "name");
+      const cityOp = operations.find((op) => op.path.toTokens().join("/") === "address/city");
+
+      expect(nameOp).toBeDefined();
+      expect(nameOp!.payload).toBe("Jane");
+
+      expect(cityOp).toBeDefined();
+      expect(cityOp!.payload).toBe("Boston");
+    });
+
+    it("update() with empty object generates no operations", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make((op) => {
+        operations.push(op);
+      });
+
+      const structPrimitive = Primitive.Struct({
+        name: Primitive.String(),
+        email: Primitive.String(),
+      });
+
+      const proxy = structPrimitive._internal.createProxy(env, OperationPath.make(""));
+
+      proxy.update({});
+
+      expect(operations).toHaveLength(0);
+    });
+
+    it("update() ignores unknown fields", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make((op) => {
+        operations.push(op);
+      });
+
+      const structPrimitive = Primitive.Struct({
+        name: Primitive.String(),
+      });
+
+      const proxy = structPrimitive._internal.createProxy(env, OperationPath.make(""));
+
+      // Cast to any to bypass type checking for testing unknown fields
+      (proxy as any).update({ name: "John", unknownField: "value" });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.payload).toBe("John");
+    });
+
+    it("update() with nested path prefix", () => {
+      const operations: Operation.Operation<any, any, any>[] = [];
+      const env = ProxyEnvironment.make((op) => {
+        operations.push(op);
+      });
+
+      const structPrimitive = Primitive.Struct({
+        name: Primitive.String(),
+        email: Primitive.String(),
+      });
+
+      const proxy = structPrimitive._internal.createProxy(env, OperationPath.make("users/0"));
+
+      proxy.update({ name: "Updated" });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.path.toTokens()).toEqual(["users", "0", "name"]);
+    });
+  });
 });
 
 // =============================================================================

package/tests/primitives/Tree.test.ts

@@ -460,6 +460,128 @@ describe("TreePrimitive", () => {
       expect(withDefault._internal.getInitialState()).toEqual(defaultState);
     });
   });
+
+  describe("proxy - partial update", () => {
+    it("update() on TypedNodeProxy updates only specified fields", () => {
+      const initialState: Primitive.TreeState<typeof FolderNode> = [
+        { id: "root", type: "folder", parentId: null, pos: "a0", data: { name: "Root" } },
+        { id: "file1", type: "file", parentId: "root", pos: "a0", data: { name: "File1", size: 100 } },
+      ];
+      const { env, operations } = createEnvWithState(initialState);
+      const proxy = fileSystemTree._internal.createProxy(env, OperationPath.make(""));
+
+      // Use the update method via as()
+      const fileProxy = proxy.node("file1")!.as(FileNode);
+      fileProxy.update({ name: "UpdatedName" });
+
+      // Should generate only a string.set operation for the name field
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("string.set");
+      expect(operations[0]!.path.toTokens()).toEqual(["file1", "name"]);
+      expect(operations[0]!.payload).toBe("UpdatedName");
+    });
+
+    it("update() preserves other fields when updating partial data", () => {
+      const initialState: Primitive.TreeState<typeof FolderNode> = [
+        { id: "root", type: "folder", parentId: null, pos: "a0", data: { name: "Root" } },
+        { id: "file1", type: "file", parentId: "root", pos: "a0", data: { name: "File1", size: 100 } },
+      ];
+      const { env, operations } = createEnvWithState(initialState);
+      const proxy = fileSystemTree._internal.createProxy(env, OperationPath.make(""));
+
+      // Update only the size field
+      proxy.node("file1")!.as(FileNode).update({ size: 200 });
+
+      // Should generate only a number.set operation for the size field
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("number.set");
+      expect(operations[0]!.path.toTokens()).toEqual(["file1", "size"]);
+      expect(operations[0]!.payload).toBe(200);
+
+      // The name should remain unchanged in the state
+      const updatedState = proxy.get();
+      const file1 = updatedState.find(n => n.id === "file1");
+      expect(file1!.data).toEqual({ name: "File1", size: 200 });
+    });
+
+    it("update() handles multiple fields at once", () => {
+      const initialState: Primitive.TreeState<typeof FolderNode> = [
+        { id: "root", type: "folder", parentId: null, pos: "a0", data: { name: "Root" } },
+        { id: "file1", type: "file", parentId: "root", pos: "a0", data: { name: "File1", size: 100 } },
+      ];
+      const { env, operations } = createEnvWithState(initialState);
+      const proxy = fileSystemTree._internal.createProxy(env, OperationPath.make(""));
+
+      // Update both name and size
+      proxy.node("file1")!.as(FileNode).update({ name: "NewFile", size: 500 });
+
+      // Should generate two operations
+      expect(operations).toHaveLength(2);
+      
+      // Verify both fields were updated
+      const updatedState = proxy.get();
+      const file1 = updatedState.find(n => n.id === "file1");
+      expect(file1!.data).toEqual({ name: "NewFile", size: 500 });
+    });
+
+    it("updateAt() provides convenient partial update by node id", () => {
+      const initialState: Primitive.TreeState<typeof FolderNode> = [
+        { id: "root", type: "folder", parentId: null, pos: "a0", data: { name: "Root" } },
+        { id: "file1", type: "file", parentId: "root", pos: "a0", data: { name: "File1", size: 100 } },
+      ];
+      const { env, operations } = createEnvWithState(initialState);
+      const proxy = fileSystemTree._internal.createProxy(env, OperationPath.make(""));
+
+      // Use updateAt for convenience
+      proxy.updateAt("file1", FileNode, { name: "QuickUpdate" });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("string.set");
+      expect(operations[0]!.path.toTokens()).toEqual(["file1", "name"]);
+      expect(operations[0]!.payload).toBe("QuickUpdate");
+    });
+
+    it("updateAt() throws for wrong node type", () => {
+      const initialState: Primitive.TreeState<typeof FolderNode> = [
+        { id: "file1", type: "file", parentId: null, pos: "a0", data: { name: "File1", size: 100 } },
+      ];
+      const { env } = createEnvWithState(initialState);
+      const proxy = fileSystemTree._internal.createProxy(env, OperationPath.make(""));
+
+      // Trying to update a file node as a folder should throw
+      expect(() => proxy.updateAt("file1", FolderNode, { name: "NewName" })).toThrow(
+        Primitive.ValidationError
+      );
+    });
+
+    it("updateAt() throws for non-existent node", () => {
+      const initialState: Primitive.TreeState<typeof FolderNode> = [
+        { id: "root", type: "folder", parentId: null, pos: "a0", data: { name: "Root" } },
+      ];
+      const { env } = createEnvWithState(initialState);
+      const proxy = fileSystemTree._internal.createProxy(env, OperationPath.make(""));
+
+      expect(() => proxy.updateAt("nonexistent", FileNode, { name: "Name" })).toThrow(
+        Primitive.ValidationError
+      );
+    });
+
+    it("data.update() on at() proxy also works for partial updates", () => {
+      const initialState: Primitive.TreeState<typeof FolderNode> = [
+        { id: "root", type: "folder", parentId: null, pos: "a0", data: { name: "Root" } },
+        { id: "file1", type: "file", parentId: "root", pos: "a0", data: { name: "File1", size: 100 } },
+      ];
+      const { env, operations } = createEnvWithState(initialState);
+      const proxy = fileSystemTree._internal.createProxy(env, OperationPath.make(""));
+
+      // The at() method returns the data proxy which has update()
+      proxy.at("file1", FileNode).update({ size: 999 });
+
+      expect(operations).toHaveLength(1);
+      expect(operations[0]!.kind).toBe("number.set");
+      expect(operations[0]!.path.toTokens()).toEqual(["file1", "size"]);
+    });
+  });
 });
 
 // =============================================================================