@multiplatform.one/frappe 6.0.0

package/src/sync/syncModule.spec.ts

@@ -0,0 +1,217 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { SyncModule } from "./index";
+import { BackfillScope } from "./types";
+import type { SubscriptionQuery } from "./types";
+
+vi.mock("@multiplatform.one/platform", () => ({
+  onAppFocus: vi.fn(() => vi.fn()),
+  onOnline: vi.fn(() => vi.fn()),
+  onVisibilityChange: vi.fn(() => vi.fn()),
+}));
+
+describe("SyncModule", () => {
+  let sync: SyncModule;
+  let mockDb: any;
+  let mockRealtime: any;
+
+  const mockDocs = [
+    { name: "doc1", doctype: "TestDoc", modified: "2024-01-01T09:00:00", title: "Doc 1" },
+    { name: "doc2", doctype: "TestDoc", modified: "2024-01-01T10:00:00", title: "Doc 2" },
+  ];
+
+  let uuidCount = 0;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    uuidCount = 0;
+
+    Object.defineProperty(global, "crypto", {
+      value: { randomUUID: vi.fn(() => `uuid-${++uuidCount}`) },
+      writable: true,
+    });
+
+    mockDb = {
+      getDoc: vi.fn().mockResolvedValue(mockDocs[0]),
+      getDocList: vi.fn().mockResolvedValue(mockDocs),
+      createDoc: vi.fn().mockResolvedValue(mockDocs[0]),
+      updateDoc: vi.fn().mockResolvedValue(mockDocs[0]),
+      deleteDoc: vi.fn().mockResolvedValue({}),
+      backfill: vi.fn().mockResolvedValue({ rows: [], checkpoint: "2024-01-01T12:00:00" }),
+      call: { post: vi.fn().mockResolvedValue({}) },
+    };
+
+    mockRealtime = {
+      on: vi.fn(),
+      off: vi.fn(),
+      emit: vi.fn(),
+      isHealthy: vi.fn(() => false),
+      connect: vi.fn(),
+      disconnect: vi.fn(),
+    };
+  });
+
+  afterEach(() => {
+    sync?.dispose();
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  function createSync(options = {}) {
+    return new SyncModule(mockDb, mockRealtime, options);
+  }
+
+  describe("subscribeStore and emit", () => {
+    it("subscribeStore adds listener and subscribe triggers emit which calls listener", async () => {
+      sync = createSync();
+      const listener = vi.fn();
+      sync.subscribeStore(listener);
+
+      const query: SubscriptionQuery = { doctype: "TestDoc", fields: ["title"] };
+      await sync.subscribe(query);
+
+      expect(listener).toHaveBeenCalled();
+    });
+
+    it("unsubscribe function removes listener", async () => {
+      sync = createSync();
+      const listener = vi.fn();
+      const unsub = sync.subscribeStore(listener);
+
+      unsub();
+
+      const query: SubscriptionQuery = { doctype: "TestDoc", fields: ["title"] };
+      await sync.subscribe(query);
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it("multiple listeners all called on emit", async () => {
+      sync = createSync();
+      const listener1 = vi.fn();
+      const listener2 = vi.fn();
+      const listener3 = vi.fn();
+      sync.subscribeStore(listener1);
+      sync.subscribeStore(listener2);
+      sync.subscribeStore(listener3);
+
+      const query: SubscriptionQuery = { doctype: "TestDoc", fields: ["title"] };
+      await sync.subscribe(query);
+
+      expect(listener1).toHaveBeenCalled();
+      expect(listener2).toHaveBeenCalled();
+      expect(listener3).toHaveBeenCalled();
+    });
+  });
+
+  describe("dispose", () => {
+    it("clears store listeners after dispose", async () => {
+      sync = createSync();
+      const listener = vi.fn();
+      sync.subscribeStore(listener);
+
+      await sync.dispose();
+      listener.mockClear();
+
+      await sync.subscribe({ doctype: "TestDoc" });
+
+      expect(listener).not.toHaveBeenCalled();
+    });
+
+    it("clears cdcInterval timer on dispose", async () => {
+      sync = createSync({ cdcInterval: 100 });
+      await sync.subscribe({ doctype: "TestDoc", fields: ["title"] });
+
+      mockDb.backfill.mockClear();
+      await vi.advanceTimersByTimeAsync(250);
+      const callsBefore = mockDb.backfill.mock.calls.length;
+      expect(callsBefore).toBeGreaterThan(0);
+
+      await sync.dispose();
+      mockDb.backfill.mockClear();
+
+      await vi.advanceTimersByTimeAsync(500);
+
+      expect(mockDb.backfill).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("cdcInterval", () => {
+    it("fires backfill periodically at the configured interval", async () => {
+      sync = createSync({ cdcInterval: 500 });
+      await sync.subscribe({ doctype: "TestDoc", fields: ["title"] });
+
+      mockDb.backfill.mockClear();
+
+      await vi.advanceTimersByTimeAsync(1500);
+
+      expect(mockDb.backfill).toHaveBeenCalledTimes(3);
+    });
+  });
+
+  describe("resetCache", () => {
+    it("clears subscriptions so getSubscription returns undefined", async () => {
+      sync = createSync();
+
+      const { subscriptionId } = await sync.subscribe({
+        doctype: "TestDoc",
+        fields: ["title"],
+      });
+
+      expect(sync.getSubscription(subscriptionId)).toBeDefined();
+
+      sync.resetCache();
+
+      expect(sync.getSubscription(subscriptionId)).toBeUndefined();
+    });
+
+    it("notifies store listeners on reset", async () => {
+      sync = createSync();
+      const listener = vi.fn();
+
+      await sync.subscribe({ doctype: "TestDoc" });
+      sync.subscribeStore(listener);
+
+      sync.resetCache();
+
+      expect(listener).toHaveBeenCalled();
+    });
+  });
+
+  describe("getPage and getNextBatch emit", () => {
+    it("getPage notifies store listeners", async () => {
+      sync = createSync();
+
+      const { subscriptionId } = await sync.subscribe({
+        doctype: "TestDoc",
+        fields: ["title"],
+        progressive: true,
+        limit: 10,
+      });
+
+      const listener = vi.fn();
+      sync.subscribeStore(listener);
+
+      await sync.getPage(subscriptionId, 1);
+
+      expect(listener).toHaveBeenCalled();
+    });
+
+    it("getNextBatch notifies store listeners", async () => {
+      sync = createSync();
+
+      const { subscriptionId } = await sync.subscribe({
+        doctype: "TestDoc",
+        fields: ["title"],
+        progressive: true,
+        limit: 10,
+      });
+
+      const listener = vi.fn();
+      sync.subscribeStore(listener);
+
+      await sync.getNextBatch(subscriptionId, "doc1", 5);
+
+      expect(listener).toHaveBeenCalled();
+    });
+  });
+});

package/src/sync/types.spec.ts

@@ -0,0 +1,276 @@
+import { describe, expect, it } from "vitest";
+import type { FrappeDocData } from "../common/types";
+import {
+  BackfillScope,
+  type CreateMutation,
+  type DeleteMutation,
+  type Mutation,
+  Operation,
+  Order,
+  type OrderBy,
+  type PageBoundaries,
+  PendingRehydrationType,
+  type Subscription,
+  type SubscriptionQuery,
+  type UpdateMutation,
+} from "./types";
+
+describe("Order enum", () => {
+  it("should have correct values", () => {
+    expect(Order.Asc).toBe("asc");
+    expect(Order.Desc).toBe("desc");
+  });
+
+  it("should be usable in OrderBy interface", () => {
+    const orderBy: OrderBy = {
+      field: "created",
+      order: Order.Desc,
+    };
+    expect(orderBy.field).toBe("created");
+    expect(orderBy.order).toBe("desc");
+  });
+
+  it("should accept string literals for order field names", () => {
+    const orderBy: OrderBy = {
+      field: "modified",
+      order: "asc" as Order,
+    };
+    expect(orderBy.order).toBe("asc");
+    expect(orderBy.order).toBe(Order.Asc);
+  });
+});
+
+describe("SubscriptionQuery", () => {
+  it("should use camelCase for all properties", () => {
+    const query: SubscriptionQuery = {
+      doctype: "Task",
+      fields: ["name", "status", "priority"],
+      filters: [["status", "=", "Open"]],
+      orderBy: {
+        field: "priority",
+        order: Order.Desc,
+      },
+      limitStart: 0,
+      limit: 20,
+    };
+    expect(query.limitStart).toBe(0);
+    expect(query.limit).toBe(20);
+    expect(Array.isArray(query.orderBy) ? query.orderBy[0].order : query.orderBy?.order).toBe(
+      "desc",
+    );
+  });
+
+  it("should handle optional properties", () => {
+    const minimalQuery: SubscriptionQuery = {
+      doctype: "Task",
+      fields: ["name"],
+    };
+    expect(minimalQuery.filters).toBeUndefined();
+    expect(minimalQuery.orderBy).toBeUndefined();
+    expect(minimalQuery.limitStart).toBeUndefined();
+    expect(minimalQuery.limit).toBeUndefined();
+  });
+
+  it("should support different filter formats", () => {
+    const arrayFilters: SubscriptionQuery = {
+      doctype: "Task",
+      fields: ["name"],
+      filters: [
+        ["status", "=", "Open"],
+        ["priority", ">", 5],
+      ],
+    };
+    const objectFilters: SubscriptionQuery = {
+      doctype: "Task",
+      fields: ["name"],
+      filters: {
+        status: "Open",
+        priority: 5,
+      },
+    };
+    expect(Array.isArray(arrayFilters.filters)).toBe(true);
+    expect(typeof objectFilters.filters).toBe("object");
+  });
+});
+
+describe("PageBoundaries", () => {
+  it("should track page boundaries correctly", () => {
+    const boundaries: PageBoundaries<FrappeDocData> = {
+      firstItem: { name: "TASK-001", doctype: "Task", priority: 10 },
+      lastItem: { name: "TASK-020", doctype: "Task", priority: 1 },
+      offset: 0,
+      pageSize: 20,
+      temporaryOverflow: 2,
+    };
+    expect(boundaries.firstItem?.name).toBe("TASK-001");
+    expect(boundaries.lastItem?.name).toBe("TASK-020");
+    expect(boundaries.temporaryOverflow).toBe(2);
+  });
+
+  it("should allow undefined items", () => {
+    const emptyBoundaries: PageBoundaries<FrappeDocData> = {
+      offset: 0,
+      pageSize: 20,
+    };
+    expect(emptyBoundaries.firstItem).toBeUndefined();
+    expect(emptyBoundaries.lastItem).toBeUndefined();
+  });
+});
+
+describe("Subscription", () => {
+  it("should contain all required fields", () => {
+    const subscription: Subscription = {
+      id: "sub-123",
+      query: {
+        doctype: "Task",
+        fields: ["name", "status"],
+        limitStart: 0,
+        limit: 20,
+      },
+      docIds: ["TASK-001", "TASK-002"],
+    };
+    expect(subscription.id).toBe("sub-123");
+    expect(subscription.query.doctype).toBe("Task");
+    expect(subscription.docIds).toHaveLength(2);
+  });
+
+  it("should support optional fields", () => {
+    const subscription: Subscription = {
+      id: "sub-456",
+      query: {
+        doctype: "Invoice",
+        fields: ["name"],
+      },
+      docIds: [],
+      checkpoint: "checkpoint-123",
+      cursor: "cursor-456",
+      boundaries: {
+        offset: 20,
+        pageSize: 20,
+      },
+      lockExpiry: Date.now() + 5000,
+      pendingRehydration: PendingRehydrationType.FullRefresh,
+    };
+    expect(subscription.checkpoint).toBe("checkpoint-123");
+    expect(subscription.cursor).toBe("cursor-456");
+    expect(subscription.pendingRehydration).toBe(PendingRehydrationType.FullRefresh);
+  });
+});
+
+describe("Mutation types", () => {
+  describe("CreateMutation", () => {
+    it("should have correct structure", () => {
+      const create: CreateMutation<FrappeDocData> = {
+        mutationId: "mut-001",
+        operation: Operation.Create,
+        doc: {
+          name: "TASK-001",
+          doctype: "Task",
+          subject: "New Task",
+          status: "Open",
+        },
+        affected: [],
+        version: "1",
+      };
+      expect(create.operation).toBe(Operation.Create);
+      expect(create.doc.name).toBe("TASK-001");
+      expect(create.doc.doctype).toBe("Task");
+      expect(create.doc.subject).toBe("New Task");
+      expect(create.doc.status).toBe("Open");
+    });
+  });
+
+  describe("UpdateMutation", () => {
+    it("should have correct structure", () => {
+      const update: UpdateMutation<FrappeDocData> = {
+        mutationId: "mut-002",
+        operation: Operation.Update,
+        doc: {
+          name: "TASK-001",
+          doctype: "Task",
+          status: "Completed",
+        },
+        affected: [],
+        version: "5",
+      };
+      expect(update.operation).toBe(Operation.Update);
+      expect(update.doc.name).toBe("TASK-001");
+      expect(update.version).toBe("5");
+    });
+  });
+
+  describe("DeleteMutation", () => {
+    it("should have correct structure", () => {
+      const deleteMutation: DeleteMutation<FrappeDocData> = {
+        mutationId: "mut-003",
+        operation: Operation.Delete,
+        doc: {
+          name: "TASK-001",
+          doctype: "Task",
+        },
+        affected: [],
+        version: "5",
+      };
+      expect(deleteMutation.operation).toBe(Operation.Delete);
+      expect(deleteMutation.doc.name).toBe("TASK-001");
+      expect((deleteMutation as any).values).toBeUndefined();
+    });
+  });
+
+  it("should support discriminated union", () => {
+    const mutations: Mutation<FrappeDocData>[] = [
+      {
+        mutationId: "1",
+        operation: Operation.Create,
+        doc: {
+          name: "TASK-001",
+          doctype: "Task",
+          status: "Open",
+        },
+        affected: [],
+      },
+      {
+        mutationId: "2",
+        operation: Operation.Update,
+        doc: {
+          name: "TASK-001",
+          doctype: "Task",
+          status: "Closed",
+        },
+        affected: [],
+      },
+      {
+        mutationId: "3",
+        operation: Operation.Delete,
+        doc: {
+          name: "TASK-001",
+          doctype: "Task",
+        },
+        affected: [],
+      },
+    ];
+    mutations.forEach((mutation) => {
+      switch (mutation.operation) {
+        case Operation.Create:
+          expect(mutation.doc.name).toBeDefined();
+          expect(mutation.doc.doctype).toBeDefined();
+          break;
+        case Operation.Update:
+          expect(mutation.doc.name).toBeDefined();
+          expect(mutation.doc.doctype).toBeDefined();
+          break;
+        case Operation.Delete:
+          expect(mutation.doc.name).toBeDefined();
+          expect((mutation as any).values).toBeUndefined();
+          break;
+      }
+    });
+  });
+});
+
+describe("BackfillScope enum", () => {
+  it("should have all scopes defined", () => {
+    expect(BackfillScope.All).toBe("all");
+    expect(BackfillScope.Doctypes).toBe("doctypes");
+  });
+});