@multiplatform.one/frappe 6.0.0

package/src/sync/mutations.spec.ts

@@ -0,0 +1,358 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { FrappeDocData } from "../common/types";
+import type { DbModule } from "../db";
+import type { RealtimeModule } from "../realtime";
+import { MutationEngine } from "./mutationEngine";
+import type { MutationJournal } from "./mutationJournal";
+import type { NormalizedCache } from "./normalizedCache";
+import type { SubscriptionManager } from "./subscriptionManager";
+import { Operation, Status } from "./types";
+import type { CreateMutation, DeleteMutation, SyncOptions, UpdateMutation } from "./types";
+
+describe("MutationEngine", () => {
+  let mutationEngine: MutationEngine;
+  let mockDb: DbModule;
+  let mockRealtime: RealtimeModule;
+  let mockCache: NormalizedCache;
+  let mockJournal: MutationJournal;
+  let mockSubscriptionManager: SubscriptionManager;
+  let options: SyncOptions;
+
+  beforeEach(() => {
+    mockDb = {
+      getDoc: vi.fn(),
+      setValue: vi.fn(),
+      createDoc: vi.fn(),
+      deleteDoc: vi.fn(),
+      updateDoc: vi.fn(),
+      exists: vi.fn(),
+      searchLink: vi.fn(),
+      getList: vi.fn(),
+      getCount: vi.fn(),
+      getCachedDoc: vi.fn(),
+      getCachedDocList: vi.fn(),
+      insertDoc: vi.fn(),
+      saveDoc: vi.fn(),
+      submitDoc: vi.fn(),
+      cancelDoc: vi.fn(),
+      getApiCount: vi.fn(),
+      getApiList: vi.fn(),
+      getApi: vi.fn(),
+      postApi: vi.fn(),
+      putApi: vi.fn(),
+      deleteApi: vi.fn(),
+    } as unknown as DbModule;
+    mockRealtime = {
+      isHealthy: vi.fn().mockReturnValue(true),
+      on: vi.fn(),
+      off: vi.fn(),
+      emit: vi.fn(),
+      socketio: undefined,
+    } as unknown as RealtimeModule;
+    mockCache = {
+      get: vi.fn(),
+      upsert: vi.fn(),
+      remove: vi.fn(),
+      clear: vi.fn(),
+      getAll: vi.fn(),
+      has: vi.fn(),
+      update: vi.fn(),
+    } as unknown as NormalizedCache;
+    mockJournal = {
+      add: vi.fn(),
+      confirm: vi.fn(),
+      fail: vi.fn(),
+      listPending: vi.fn().mockReturnValue([]),
+      clear: vi.fn(),
+      get: vi.fn(),
+      getAll: vi.fn(),
+      remove: vi.fn(),
+    } as unknown as MutationJournal;
+    mockSubscriptionManager = {
+      getAllSubscriptions: vi.fn().mockReturnValue(new Map()),
+      addSubscription: vi.fn(),
+      removeSubscription: vi.fn(),
+      getSubscription: vi.fn(),
+      updateSubscription: vi.fn(),
+      updateSubscriptionMembership: vi.fn(),
+      processOptimisticCreate: vi.fn(),
+      processDocumentDelete: vi.fn(),
+      removeFromAllSubscriptions: vi.fn(),
+    } as unknown as SubscriptionManager;
+    options = {
+      batchSize: 10,
+      batchDelay: 100,
+      versionField: "modified",
+      onMutationStart: vi.fn(),
+      onMutationSuccess: vi.fn(),
+      onMutationError: vi.fn(),
+      onConflict: vi.fn(),
+    };
+    const mockRehydrationManager = {
+      scheduleRehydration: vi.fn(),
+      registerTempIdMapping: vi.fn(),
+    } as any;
+    mutationEngine = new MutationEngine(
+      mockDb,
+      mockRealtime,
+      mockCache,
+      mockJournal,
+      mockSubscriptionManager,
+      mockRehydrationManager,
+      options,
+    );
+  });
+
+  describe("mutate", () => {
+    it("should handle create operation", async () => {
+      const mutation: CreateMutation<FrappeDocData> = {
+        mutationId: "mut-1",
+        operation: Operation.Create,
+        doc: {
+          doctype: "Task",
+          name: "temp-id",
+          title: "New Task",
+          status: "Open",
+        },
+        affected: [],
+      };
+      const createdDoc = {
+        doctype: "Task",
+        name: "TASK-001",
+        title: "New Task",
+        status: "Open",
+        modified: "2025-01-01 10:00:00",
+      };
+      vi.mocked(mockDb.createDoc).mockResolvedValue(createdDoc);
+      await mutationEngine.mutate(mutation);
+      expect(mockJournal.add).toHaveBeenCalledWith(
+        "mut-1",
+        expect.objectContaining({
+          doctype: "Task",
+          operation: Operation.Create,
+          values: {
+            doctype: "Task",
+            name: "temp-id",
+            title: "New Task",
+            status: "Open",
+          },
+          status: Status.Pending,
+        }),
+      );
+      // createDoc now takes just the doc object
+      expect(mockDb.createDoc).toHaveBeenCalledWith(
+        expect.objectContaining({
+          doctype: "Task",
+          title: "New Task",
+          status: "Open",
+        }),
+      );
+      expect(mockJournal.confirm).toHaveBeenCalledWith("mut-1");
+      expect(options.onMutationSuccess).toHaveBeenCalledWith(mutation);
+    });
+
+    it("should throw error for update without docname", async () => {
+      const mutation: UpdateMutation<FrappeDocData> = {
+        mutationId: "mut-4",
+        operation: Operation.Update,
+        doc: { doctype: "Task", name: "" },
+        affected: [],
+      } as UpdateMutation<FrappeDocData>;
+      await expect(mutationEngine.mutate(mutation)).rejects.toThrow(
+        "docname is required for update/delete operations",
+      );
+    });
+
+    it("should throw error for delete without docname", async () => {
+      const mutation: DeleteMutation<FrappeDocData> = {
+        mutationId: "mut-5",
+        operation: Operation.Delete,
+        doc: { doctype: "Task", name: "" },
+        affected: [],
+      } as DeleteMutation<FrappeDocData>;
+      await expect(mutationEngine.mutate(mutation)).rejects.toThrow(
+        "docname is required for update/delete operations",
+      );
+    });
+  });
+
+  describe("replayPending", () => {
+    it("should replay pending mutations in order", async () => {
+      const pending1 = {
+        id: "mut-1",
+        entry: {
+          mutationId: "mut-1",
+          doctype: "Task",
+          docname: "TASK-001",
+          operation: Operation.Update,
+          values: { doctype: "Task", name: "TASK-001", status: "InProgress" },
+          version: "2025-01-01 09:00:00",
+          status: Status.Pending,
+        },
+      };
+      const pending2 = {
+        id: "mut-2",
+        entry: {
+          mutationId: "mut-2",
+          doctype: "Task",
+          docname: "TASK-002",
+          operation: Operation.Update,
+          values: { doctype: "Task", name: "TASK-002", status: "Completed" },
+          version: "2025-01-01 09:30:00",
+          status: Status.Pending,
+        },
+      };
+      vi.mocked(mockJournal.listPending).mockReturnValue([pending1, pending2]);
+      vi.mocked(mockDb.updateDoc).mockResolvedValue({
+        doctype: "Task",
+        name: "TASK-001",
+      });
+      await mutationEngine.replayPending();
+      expect(mockDb.updateDoc).toHaveBeenCalledTimes(2);
+      // updateDoc now takes a single doc object with client_mutation_id and base_modified
+      expect(mockDb.updateDoc).toHaveBeenNthCalledWith(
+        1,
+        expect.objectContaining({
+          doctype: "Task",
+          name: "TASK-001",
+          status: "InProgress",
+          client_mutation_id: "mut-1",
+          base_modified: "2025-01-01 09:00:00",
+        }),
+      );
+      expect(mockDb.updateDoc).toHaveBeenNthCalledWith(
+        2,
+        expect.objectContaining({
+          doctype: "Task",
+          name: "TASK-002",
+          status: "Completed",
+          client_mutation_id: "mut-2",
+          base_modified: "2025-01-01 09:30:00",
+        }),
+      );
+    });
+
+    it("should handle create operations during replay", async () => {
+      const pending = {
+        id: "mut-1",
+        entry: {
+          mutationId: "mut-1",
+          doctype: "Task",
+          operation: Operation.Create,
+          values: {
+            doctype: "Task",
+            name: "temp-id",
+            title: "New Task",
+            status: "Open",
+          },
+          status: Status.Pending,
+        },
+      };
+      vi.mocked(mockJournal.listPending).mockReturnValue([pending]);
+      vi.mocked(mockDb.createDoc).mockResolvedValue({
+        doctype: "Task",
+        name: "TASK-001",
+      } as FrappeDocData);
+      await mutationEngine.replayPending();
+      // createDoc now takes a single doc object with client_mutation_id
+      expect(mockDb.createDoc).toHaveBeenCalledWith(
+        expect.objectContaining({
+          doctype: "Task",
+          title: "New Task",
+          status: "Open",
+          client_mutation_id: "mut-1",
+        }),
+      );
+    });
+
+    it("should handle delete operations during replay", async () => {
+      const pending = {
+        id: "mut-1",
+        entry: {
+          mutationId: "mut-1",
+          doctype: "Task",
+          docname: "TASK-001",
+          operation: Operation.Delete,
+          status: Status.Pending,
+        },
+      };
+      vi.mocked(mockJournal.listPending).mockReturnValue([pending]);
+      vi.mocked(mockDb.deleteDoc).mockResolvedValue({
+        message: "Deleted successfully",
+      });
+      await mutationEngine.replayPending();
+      // deleteDoc now takes a single doc object with client_mutation_id
+      expect(mockDb.deleteDoc).toHaveBeenCalledWith(
+        expect.objectContaining({
+          doctype: "Task",
+          name: "TASK-001",
+          client_mutation_id: "mut-1",
+        }),
+      );
+    });
+
+    it("should handle errors during replay", async () => {
+      const pending = {
+        id: "mut-1",
+        entry: {
+          mutationId: "mut-1",
+          doctype: "Task",
+          docname: "TASK-001",
+          operation: Operation.Update,
+          values: { doctype: "Task", name: "TASK-001", status: "InProgress" },
+          status: Status.Failed,
+          retryCount: 1,
+        },
+      };
+      const error = new Error("Network error");
+      vi.mocked(mockJournal.listPending).mockReturnValue([pending]);
+      vi.mocked(mockDb.updateDoc).mockRejectedValue(error);
+      await mutationEngine.replayPending();
+      expect(mockJournal.fail).toHaveBeenCalledWith("mut-1");
+    });
+  });
+
+  describe("batching", () => {
+    it("should respect batch configuration", async () => {
+      const batchingOptions: SyncOptions = {
+        ...options,
+
+        batchSize: 2,
+        batchDelay: 50,
+      };
+      const mockRehydrationManager = {
+        scheduleRehydration: vi.fn(),
+        registerTempIdMapping: vi.fn(),
+      } as any;
+      mutationEngine = new MutationEngine(
+        mockDb,
+        mockRealtime,
+        mockCache,
+        mockJournal,
+        mockSubscriptionManager,
+        mockRehydrationManager,
+        batchingOptions,
+      );
+      const mutation1: CreateMutation<FrappeDocData> = {
+        mutationId: "mut-1",
+        operation: Operation.Create,
+        doc: { doctype: "Task", name: "temp-1", title: "Task 1" },
+        affected: [],
+      };
+      const mutation2: CreateMutation<FrappeDocData> = {
+        mutationId: "mut-2",
+        operation: Operation.Create,
+        doc: { doctype: "Task", name: "temp-2", title: "Task 2" },
+        affected: [],
+      };
+      vi.mocked(mockDb.createDoc).mockResolvedValue({
+        doctype: "Task",
+        name: "TASK-001",
+      });
+      const promise1 = mutationEngine.mutate(mutation1);
+      const promise2 = mutationEngine.mutate(mutation2);
+      await Promise.all([promise1, promise2]);
+      expect(mockJournal.add).toHaveBeenCalledTimes(2);
+    });
+  });
+});

package/src/sync/normalizedCache.spec.ts

@@ -0,0 +1,262 @@
+import { beforeEach, describe, expect, it } from "vitest";
+import { NormalizedCache } from "./normalizedCache";
+
+describe("NormalizedCache", () => {
+  let cache: NormalizedCache;
+
+  beforeEach(() => {
+    cache = new NormalizedCache();
+  });
+
+  describe("upsert", () => {
+    it("should insert a new document", () => {
+      const doc = {
+        name: "TASK-001",
+        doctype: "Task",
+        title: "Test Task",
+        status: "Open",
+      };
+      cache.upsert(doc);
+      const retrieved = cache.get({ doctype: "Task", name: "TASK-001" });
+      expect(retrieved).toEqual(doc);
+      expect(cache.state.Task.allIds).toContain("TASK-001");
+    });
+
+    it("should update an existing document", () => {
+      const originalDoc = {
+        name: "TASK-001",
+        doctype: "Task",
+        title: "Original Task",
+        status: "Open",
+      };
+      const updatedDoc = {
+        name: "TASK-001",
+        doctype: "Task",
+        title: "Updated Task",
+        status: "Closed",
+      };
+      cache.upsert(originalDoc);
+      cache.upsert(updatedDoc);
+      const retrieved = cache.get({ doctype: "Task", name: "TASK-001" });
+      expect(retrieved).toEqual(updatedDoc);
+      expect(cache.state.Task.allIds).toHaveLength(1);
+      expect(cache.state.Task.allIds).toContain("TASK-001");
+    });
+
+    it("should create bucket if it doesn't exist", () => {
+      expect(cache.state.Task).toBeUndefined();
+      const doc = {
+        name: "TASK-001",
+        doctype: "Task",
+        title: "Test Task",
+      };
+      cache.upsert(doc);
+      expect(cache.state.Task).toBeDefined();
+      expect(cache.state.Task.byId).toBeDefined();
+      expect(cache.state.Task.allIds).toBeDefined();
+    });
+
+    it("should handle document without name", () => {
+      const doc = {
+        doctype: "Task",
+        title: "Test Task",
+      } as any;
+      cache.upsert(doc);
+      expect(cache.state.Task).toBeDefined();
+      expect(cache.state.Task.allIds).toHaveLength(0);
+      expect(Object.keys(cache.state.Task.byId)).toHaveLength(0);
+    });
+
+    it("should handle multiple doctypes", () => {
+      const task = {
+        name: "TASK-001",
+        doctype: "Task",
+        title: "Test Task",
+      };
+      const project = {
+        name: "PROJ-001",
+        doctype: "Project",
+        title: "Test Project",
+      };
+      cache.upsert(task);
+      cache.upsert(project);
+      expect(cache.get({ doctype: "Task", name: "TASK-001" })).toEqual(task);
+      expect(cache.get({ doctype: "Project", name: "PROJ-001" })).toEqual(project);
+      expect(cache.state.Task.allIds).toContain("TASK-001");
+      expect(cache.state.Project.allIds).toContain("PROJ-001");
+    });
+  });
+
+  describe("get", () => {
+    it("should retrieve an existing document", () => {
+      const doc = {
+        name: "TASK-001",
+        doctype: "Task",
+        title: "Test Task",
+      };
+      cache.upsert(doc);
+      const retrieved = cache.get({ doctype: "Task", name: "TASK-001" });
+      expect(retrieved).toEqual(doc);
+    });
+
+    it("should return undefined for non-existent document", () => {
+      const retrieved = cache.get({ doctype: "Task", name: "TASK-999" });
+      expect(retrieved).toBeUndefined();
+    });
+
+    it("should return undefined for non-existent doctype", () => {
+      const retrieved = cache.get({
+        doctype: "NonExistentDoctype",
+        name: "DOC-001",
+      });
+      expect(retrieved).toBeUndefined();
+    });
+  });
+
+  describe("remove", () => {
+    it("should remove an existing document", () => {
+      const doc = {
+        name: "TASK-001",
+        doctype: "Task",
+        title: "Test Task",
+      };
+      cache.upsert(doc);
+      cache.remove({ doctype: "Task", name: "TASK-001" });
+      const retrieved = cache.get({ doctype: "Task", name: "TASK-001" });
+      expect(retrieved).toBeUndefined();
+      expect(cache.state.Task.allIds).not.toContain("TASK-001");
+    });
+
+    it("should handle removing non-existent document gracefully", () => {
+      const doc = {
+        name: "TASK-001",
+        doctype: "Task",
+        title: "Test Task",
+      };
+      cache.upsert(doc);
+      expect(() => cache.remove({ doctype: "Task", name: "TASK-999" })).not.toThrow();
+      expect(cache.get({ doctype: "Task", name: "TASK-001" })).toEqual(doc);
+    });
+
+    it("should handle removing from non-existent doctype gracefully", () => {
+      expect(() => cache.remove({ doctype: "NonExistentDoctype", name: "DOC-001" })).not.toThrow();
+    });
+
+    it("should properly update allIds when removing", () => {
+      const doc1 = {
+        name: "TASK-001",
+        doctype: "Task",
+        title: "Task 1",
+      };
+      const doc2 = {
+        name: "TASK-002",
+        doctype: "Task",
+        title: "Task 2",
+      };
+      const doc3 = {
+        name: "TASK-003",
+        doctype: "Task",
+        title: "Task 3",
+      };
+      cache.upsert(doc1);
+      cache.upsert(doc2);
+      cache.upsert(doc3);
+      expect(cache.state.Task.allIds).toHaveLength(3);
+      cache.remove({ doctype: "Task", name: "TASK-002" });
+      expect(cache.state.Task.allIds).toHaveLength(2);
+      expect(cache.state.Task.allIds).toContain("TASK-001");
+      expect(cache.state.Task.allIds).toContain("TASK-003");
+      expect(cache.state.Task.allIds).not.toContain("TASK-002");
+    });
+  });
+
+  describe("state management", () => {
+    it("should maintain separate buckets for different doctypes", () => {
+      const task1 = {
+        name: "TASK-001",
+        doctype: "Task",
+        title: "Task 1",
+      };
+      const task2 = {
+        name: "TASK-002",
+        doctype: "Task",
+        title: "Task 2",
+      };
+      const project = {
+        name: "PROJ-001",
+        doctype: "Project",
+        title: "Project 1",
+      };
+      cache.upsert(task1);
+      cache.upsert(task2);
+      cache.upsert(project);
+      expect(cache.state.Task.allIds).toHaveLength(2);
+      expect(cache.state.Project.allIds).toHaveLength(1);
+      expect(Object.keys(cache.state)).toHaveLength(2);
+    });
+
+    it("should maintain insertion order in allIds", () => {
+      const docs = [
+        { name: "TASK-003", doctype: "Task", title: "Task 3" },
+        { name: "TASK-001", doctype: "Task", title: "Task 1" },
+        { name: "TASK-002", doctype: "Task", title: "Task 2" },
+      ];
+      docs.forEach((doc) => cache.upsert(doc));
+      expect(cache.state.Task.allIds).toEqual(["TASK-003", "TASK-001", "TASK-002"]);
+    });
+
+    it("should not duplicate IDs when updating", () => {
+      const doc = {
+        name: "TASK-001",
+        doctype: "Task",
+        title: "Original",
+      };
+      cache.upsert(doc);
+      cache.upsert({ ...doc, title: "Updated 1" });
+      cache.upsert({ ...doc, title: "Updated 2" });
+      cache.upsert({ ...doc, title: "Updated 3" });
+      expect(cache.state.Task.allIds).toHaveLength(1);
+      expect(cache.state.Task.allIds).toContain("TASK-001");
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle empty string as document name", () => {
+      const doc = {
+        name: "",
+        doctype: "Task",
+        title: "Test Task",
+      };
+      cache.upsert(doc);
+      expect(cache.state.Task).toBeDefined();
+      expect(cache.state.Task.allIds).toHaveLength(0);
+      expect(Object.keys(cache.state.Task.byId)).toHaveLength(0);
+    });
+
+    it("should handle complex document structures", () => {
+      const doc = {
+        name: "TASK-001",
+        doctype: "Task",
+        title: "Complex Task",
+        metadata: {
+          created_by: "user@example.com",
+          tags: ["urgent", "important"],
+          nested: {
+            deeply: {
+              nested: "value",
+            },
+          },
+        },
+        items: [
+          { idx: 1, description: "Item 1" },
+          { idx: 2, description: "Item 2" },
+        ],
+      };
+      cache.upsert(doc);
+      const retrieved = cache.get({ doctype: "Task", name: "TASK-001" });
+      expect(retrieved).toEqual(doc);
+      expect(retrieved?.metadata).toEqual(doc.metadata);
+      expect(retrieved?.items).toEqual(doc.items);
+    });
+  });
+});