@multiplatform.one/frappe 6.0.0

package/src/sync/mutationJournal.spec.ts

@@ -0,0 +1,337 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { MutationJournal, type Pending, frappeSyncSequence } from "./mutationJournal";
+import { Operation, Status } from "./types";
+
+describe("MutationJournal", () => {
+  let journal: MutationJournal;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+    if (journal) {
+      journal.dispose();
+    }
+  });
+
+  describe("basic operations", () => {
+    beforeEach(() => {
+      journal = new MutationJournal({ enableAutoCleanup: false });
+    });
+
+    it("should add a pending entry", () => {
+      const entry: Pending = {
+        doctype: "Task",
+        docname: "TASK-001",
+        operation: Operation.Update,
+        status: Status.Pending,
+        values: { doctype: "Task", name: "TASK-001", status: "InProgress" },
+      };
+      journal.add("mut-1", entry);
+      const retrieved = journal.get("mut-1");
+      expect(retrieved).toBeDefined();
+      expect(retrieved?.doctype).toBe("Task");
+      expect(retrieved?.sequence).toBeDefined();
+      expect(retrieved?.createdAt).toBeDefined();
+      expect(retrieved?.ttl).toBeDefined();
+      expect(retrieved?.retryCount).toBe(0);
+    });
+
+    it("should confirm an entry", () => {
+      const entry: Pending = {
+        doctype: "Task",
+        operation: Operation.Create,
+        status: Status.Pending,
+      };
+      journal.add("mut-2", entry);
+      journal.confirm("mut-2");
+      const retrieved = journal.get("mut-2");
+      expect(retrieved).toBeUndefined();
+    });
+
+    it("should fail an entry and increment retry count", () => {
+      const entry: Pending = {
+        doctype: "Task",
+        operation: Operation.Update,
+        status: Status.Pending,
+      };
+      const error = new Error("Network error");
+      journal.add("mut-3", entry);
+      journal.fail("mut-3", error);
+      const retrieved = journal.get("mut-3");
+      expect(retrieved).toBeDefined();
+      expect(retrieved?.status).toBe(Status.Failed);
+      expect(retrieved?.error).toBe(error);
+      expect(retrieved?.retryCount).toBe(1);
+      journal.fail("mut-3", error);
+      const retrievedAgain = journal.get("mut-3");
+      expect(retrievedAgain?.retryCount).toBe(2);
+    });
+
+    it("should list pending entries in sequence order", () => {
+      const entry1: Pending = {
+        doctype: "Task",
+        operation: Operation.Create,
+        status: Status.Pending,
+      };
+      const entry2: Pending = {
+        doctype: "Task",
+        operation: Operation.Update,
+        status: Status.Failed,
+      };
+      const entry3: Pending = {
+        doctype: "Task",
+        operation: Operation.Delete,
+        status: Status.Confirmed,
+      };
+      const entry4: Pending = {
+        doctype: "Task",
+        operation: Operation.Update,
+        status: Status.Pending,
+      };
+      journal.add("mut-1", entry1);
+      journal.add("mut-2", entry2);
+      journal.add("mut-3", entry3);
+      journal.add("mut-4", entry4);
+      journal.confirm("mut-3");
+      const pending = journal.listPending();
+      expect(pending).toHaveLength(3);
+      expect(pending[0].id).toBe("mut-1");
+      expect(pending[1].id).toBe("mut-2");
+      expect(pending[2].id).toBe("mut-4");
+    });
+
+    it("should clear all entries", () => {
+      const entry1: Pending = {
+        doctype: "Task",
+        operation: Operation.Create,
+        status: Status.Pending,
+      };
+      const entry2: Pending = {
+        doctype: "Task",
+        operation: Operation.Update,
+        status: Status.Pending,
+      };
+      journal.add("mut-1", entry1);
+      journal.add("mut-2", entry2);
+      journal.clear();
+      expect(journal.get("mut-1")).toBeUndefined();
+      expect(journal.get("mut-2")).toBeUndefined();
+      expect(journal.listPending()).toHaveLength(0);
+    });
+  });
+
+  describe("TTL and expiration", () => {
+    it("should expire entries after TTL", () => {
+      journal = new MutationJournal({
+        ttl: 1000,
+        enableAutoCleanup: false,
+      });
+      const entry: Pending = {
+        doctype: "Task",
+        operation: Operation.Update,
+        status: Status.Pending,
+      };
+      journal.add("mut-1", entry);
+      expect(journal.get("mut-1")).toBeDefined();
+      vi.advanceTimersByTime(1001);
+      expect(journal.get("mut-1")).toBeUndefined();
+    });
+
+    it("should not return expired entries in listPending", () => {
+      journal = new MutationJournal({
+        ttl: 1000,
+        enableAutoCleanup: false,
+      });
+      const entry1: Pending = {
+        doctype: "Task",
+        operation: Operation.Create,
+        status: Status.Pending,
+      };
+      const entry2: Pending = {
+        doctype: "Task",
+        operation: Operation.Update,
+        status: Status.Pending,
+      };
+      journal.add("mut-1", entry1);
+      vi.advanceTimersByTime(500);
+      journal.add("mut-2", entry2);
+      vi.advanceTimersByTime(501);
+      const pending = journal.listPending();
+      expect(pending).toHaveLength(1);
+      expect(pending[0].id).toBe("mut-2");
+    });
+
+    it("should cleanup expired entries", () => {
+      journal = new MutationJournal({
+        ttl: 1000,
+        enableAutoCleanup: false,
+      });
+      const entry1: Pending = {
+        doctype: "Task",
+        operation: Operation.Create,
+        status: Status.Pending,
+      };
+      const entry2: Pending = {
+        doctype: "Task",
+        operation: Operation.Update,
+        status: Status.Pending,
+      };
+      journal.add("mut-1", entry1);
+      journal.add("mut-2", entry2);
+      vi.advanceTimersByTime(1001);
+      const cleaned = journal.cleanupExpired();
+      expect(cleaned).toBe(2);
+      expect(journal.listPending()).toHaveLength(0);
+    });
+  });
+
+  describe("auto cleanup", () => {
+    it("should automatically cleanup expired entries", () => {
+      journal = new MutationJournal({
+        ttl: 1000,
+        enableAutoCleanup: true,
+      });
+      const entry: Pending = {
+        doctype: "Task",
+        operation: Operation.Create,
+        status: Status.Pending,
+      };
+      journal.add("mut-1", entry);
+      vi.advanceTimersByTime(60001);
+      expect(journal.get("mut-1")).toBeUndefined();
+    });
+
+    it("should stop auto cleanup on dispose", () => {
+      journal = new MutationJournal({
+        enableAutoCleanup: true,
+      });
+      const stopAutoCleanupSpy = vi.spyOn(journal, "stopAutoCleanup");
+      journal.dispose();
+      expect(stopAutoCleanupSpy).toHaveBeenCalled();
+    });
+  });
+
+  describe("storage integration", () => {
+    it("should persist and load sequence number", () => {
+      const mockStorage = {
+        getItem: vi.fn().mockReturnValue("10"),
+        setItem: vi.fn(),
+        removeItem: vi.fn(),
+        clear: vi.fn(),
+        key: vi.fn(),
+        length: 0,
+      };
+      journal = new MutationJournal({
+        storage: mockStorage,
+        enableAutoCleanup: false,
+      });
+      expect(mockStorage.getItem).toHaveBeenCalledWith(frappeSyncSequence);
+      const entry: Pending = {
+        doctype: "Task",
+        operation: Operation.Create,
+        status: Status.Pending,
+      };
+      journal.add("mut-1", entry);
+      const retrieved = journal.get("mut-1");
+      expect(retrieved?.sequence).toBe(11);
+      expect(mockStorage.setItem).toHaveBeenCalledWith(frappeSyncSequence, "11");
+    });
+
+    it("should handle missing storage sequence gracefully", () => {
+      const mockStorage = {
+        getItem: vi.fn().mockReturnValue(null),
+        setItem: vi.fn(),
+        removeItem: vi.fn(),
+        clear: vi.fn(),
+        key: vi.fn(),
+        length: 0,
+      };
+      journal = new MutationJournal({
+        storage: mockStorage,
+        enableAutoCleanup: false,
+      });
+      const entry: Pending = {
+        doctype: "Task",
+        operation: Operation.Create,
+        status: Status.Pending,
+      };
+      journal.add("mut-1", entry);
+      const retrieved = journal.get("mut-1");
+      expect(retrieved?.sequence).toBe(1);
+    });
+  });
+
+  describe("sequence ordering", () => {
+    beforeEach(() => {
+      journal = new MutationJournal({ enableAutoCleanup: false });
+    });
+
+    it("should assign sequential numbers to entries", () => {
+      const entry1: Pending = {
+        doctype: "Task",
+        operation: Operation.Create,
+        status: Status.Pending,
+      };
+      const entry2: Pending = {
+        doctype: "Task",
+        operation: Operation.Update,
+        status: Status.Pending,
+      };
+      const entry3: Pending = {
+        doctype: "Task",
+        operation: Operation.Delete,
+        status: Status.Pending,
+      };
+      journal.add("mut-1", entry1);
+      journal.add("mut-2", entry2);
+      journal.add("mut-3", entry3);
+      const retrieved1 = journal.get("mut-1");
+      const retrieved2 = journal.get("mut-2");
+      const retrieved3 = journal.get("mut-3");
+      expect(retrieved1?.sequence).toBe(1);
+      expect(retrieved2?.sequence).toBe(2);
+      expect(retrieved3?.sequence).toBe(3);
+    });
+
+    it("should preserve sequence when provided", () => {
+      const entry: Pending = {
+        doctype: "Task",
+        operation: Operation.Create,
+        status: Status.Pending,
+        sequence: 100,
+      };
+      journal.add("mut-1", entry);
+      const retrieved = journal.get("mut-1");
+      expect(retrieved?.sequence).toBe(100);
+    });
+  });
+
+  describe("snapshot handling", () => {
+    beforeEach(() => {
+      journal = new MutationJournal({ enableAutoCleanup: false });
+    });
+
+    it("should store and retrieve snapshots", () => {
+      const snapshot = {
+        doctype: "Task",
+        name: "TASK-001",
+        title: "Original Task",
+        status: "Open",
+      };
+      const entry: Pending = {
+        doctype: "Task",
+        docname: "TASK-001",
+        operation: Operation.Update,
+        status: Status.Pending,
+        snapshot,
+        values: { doctype: "Task", name: "TASK-001", status: "Closed" },
+      };
+      journal.add("mut-1", entry);
+      const retrieved = journal.get("mut-1");
+      expect(retrieved?.snapshot).toEqual(snapshot);
+    });
+  });
+});

package/src/sync/mutationJournal.ts

@@ -0,0 +1,157 @@
+import type { FrappeDoc, FrappeDocData } from "../common/types";
+import type { Operation } from "./types";
+import { Status } from "./types";
+
+export const frappeSyncSequence = "frappe-sync-sequence";
+
+export interface Pending {
+  createdAt?: number;
+  docname?: string;
+  doctype: string;
+  error?: Error | { message: string; [key: string]: unknown };
+  operation: Operation;
+  retryCount?: number;
+  sequence?: number;
+  snapshot?: FrappeDoc<FrappeDocData>;
+  status: Status;
+  ttl?: number;
+  values?: FrappeDoc<FrappeDocData>;
+  version?: string;
+}
+
+export interface MutationJournalOptions {
+  enableAutoCleanup?: boolean;
+  storage?: Storage;
+  ttl?: number;
+}
+
+export class MutationJournal {
+  private cleanupTimer?: ReturnType<typeof setInterval>;
+  private ttl = 24 * 60 * 60 * 1000;
+  private pending = new Map<string, Pending>();
+  private sequenceNumber = 0;
+  private storage?: Storage;
+
+  constructor(options?: MutationJournalOptions) {
+    if (options?.ttl) {
+      this.ttl = options.ttl;
+    }
+    if (options?.storage) {
+      this.storage = options.storage;
+      this.loadSequenceNumber();
+    }
+    if (options?.enableAutoCleanup !== false) {
+      this.startAutoCleanup();
+    }
+  }
+
+  add(id: string, entry: Pending) {
+    if (entry.sequence === undefined) entry.sequence = this.getNextSequence();
+    if (entry.createdAt === undefined) entry.createdAt = Date.now();
+    if (entry.ttl === undefined) entry.ttl = this.ttl;
+    if (entry.retryCount === undefined) entry.retryCount = 0;
+    this.pending.set(id, entry);
+    this.persistSequenceNumber();
+  }
+
+  get(id: string) {
+    const entry = this.pending.get(id);
+    if (!entry) return undefined;
+    if (this.isExpired(entry)) {
+      this.pending.delete(id);
+      return undefined;
+    }
+    return entry;
+  }
+
+  confirm(id: string) {
+    const entry = this.pending.get(id);
+    if (!entry) return;
+    entry.status = Status.Confirmed;
+    this.pending.delete(id);
+  }
+
+  fail(id: string, err?: Error | { message: string; [key: string]: unknown }) {
+    const entry = this.pending.get(id);
+    if (!entry) return;
+    entry.status = Status.Failed;
+    entry.error = err;
+    entry.retryCount = (entry.retryCount || 0) + 1;
+    this.pending.set(id, entry);
+  }
+
+  listPending() {
+    const pending: Array<{ id: string; entry: Pending }> = [];
+    for (const [id, entry] of this.pending) {
+      if (this.isExpired(entry)) {
+        this.pending.delete(id);
+        continue;
+      }
+      if (entry.status === Status.Pending || entry.status === Status.Failed) {
+        pending.push({ id, entry });
+      }
+    }
+    pending.sort((a, b) => (a.entry.sequence || 0) - (b.entry.sequence || 0));
+    return pending;
+  }
+
+  getAllEntries(): Array<{ id: string; entry: Pending }> {
+    const entries: Array<{ id: string; entry: Pending }> = [];
+    for (const [id, entry] of this.pending) {
+      if (this.isExpired(entry)) continue;
+      entries.push({ id, entry });
+    }
+    return entries;
+  }
+
+  cleanupExpired() {
+    let cleaned = 0;
+    for (const [id, entry] of this.pending) {
+      if (this.isExpired(entry)) {
+        this.pending.delete(id);
+        cleaned++;
+      }
+    }
+    return cleaned;
+  }
+
+  stopAutoCleanup() {
+    if (this.cleanupTimer) {
+      clearInterval(this.cleanupTimer);
+      this.cleanupTimer = undefined;
+    }
+  }
+
+  clear() {
+    this.pending.clear();
+  }
+
+  dispose() {
+    this.stopAutoCleanup();
+    this.clear();
+  }
+
+  private getNextSequence() {
+    return ++this.sequenceNumber;
+  }
+
+  private isExpired(entry: Pending): boolean {
+    if (!entry.createdAt || !entry.ttl) return false;
+    return Date.now() > entry.createdAt + entry.ttl;
+  }
+
+  private startAutoCleanup() {
+    this.cleanupTimer = setInterval(() => this.cleanupExpired(), 60 * 60 * 1000);
+  }
+
+  private loadSequenceNumber() {
+    if (!this.storage) return;
+    const stored = this.storage.getItem(frappeSyncSequence);
+    if (stored) this.sequenceNumber = Number.parseInt(stored, 10) || 0;
+  }
+
+  private persistSequenceNumber() {
+    if (!this.storage) return;
+    this.storage.setItem(frappeSyncSequence, this.sequenceNumber.toString());
+  }
+}