@multiplatform.one/frappe 6.0.0

package/src/sync/storage.spec.ts

@@ -0,0 +1,473 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { PlatformStorageKV, IndexedDBKV } from "./storage";
+
+vi.mock("@multiplatform.one/store", () => {
+  const mockStorage = new Map<string, string>();
+  return {
+    storage: {
+      getItem: vi.fn((key: string) => mockStorage.get(key) ?? null),
+      setItem: vi.fn((key: string, value: string) => mockStorage.set(key, value)),
+      removeItem: vi.fn((key: string) => mockStorage.delete(key)),
+    },
+    __mockStorage: mockStorage,
+  };
+});
+
+describe("PlatformStorageKV", () => {
+  let kv: PlatformStorageKV;
+  let mockStorageMap: Map<string, string>;
+
+  beforeEach(async () => {
+    const mod = await import("@multiplatform.one/store");
+    mockStorageMap = (mod as any).__mockStorage;
+    mockStorageMap.clear();
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    kv = new PlatformStorageKV();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("should get items from platform storage", async () => {
+    mockStorageMap.set("test-key", "test-value");
+    const result = await kv.getItem("test-key");
+    expect(result).toBe("test-value");
+  });
+
+  it("should return null for missing keys", async () => {
+    const result = await kv.getItem("non-existent");
+    expect(result).toBeNull();
+  });
+
+  it("should set items in platform storage", async () => {
+    await kv.setItem("test-key", "test-value");
+    expect(mockStorageMap.get("test-key")).toBe("test-value");
+  });
+
+  it("should remove items from platform storage", async () => {
+    mockStorageMap.set("test-key", "test-value");
+    await kv.removeItem("test-key");
+    expect(mockStorageMap.has("test-key")).toBe(false);
+  });
+
+  it("should handle getItem errors gracefully", async () => {
+    const { storage } = await import("@multiplatform.one/store");
+    vi.mocked(storage.getItem).mockImplementation(() => {
+      throw new Error("Storage error");
+    });
+    const result = await kv.getItem("test-key");
+    expect(result).toBeNull();
+    expect(console.warn).toHaveBeenCalled();
+  });
+
+  it("should handle setItem errors gracefully", async () => {
+    const { storage } = await import("@multiplatform.one/store");
+    vi.mocked(storage.setItem).mockImplementation(() => {
+      throw new Error("Storage error");
+    });
+    await kv.setItem("test-key", "test-value");
+    expect(console.warn).toHaveBeenCalled();
+  });
+
+  it("should handle removeItem errors gracefully", async () => {
+    const { storage } = await import("@multiplatform.one/store");
+    vi.mocked(storage.removeItem).mockImplementation(() => {
+      throw new Error("Storage error");
+    });
+    await kv.removeItem("test-key");
+    expect(console.warn).toHaveBeenCalled();
+  });
+});
+
+describe("IndexedDBKV", () => {
+  let storage: IndexedDBKV;
+  let mockDatabase: {
+    transaction: ReturnType<typeof vi.fn>;
+    objectStoreNames: {
+      contains: ReturnType<typeof vi.fn>;
+    };
+    createObjectStore: ReturnType<typeof vi.fn>;
+  };
+  let mockTransaction: IDBTransaction;
+  let mockObjectStore: {
+    get: ReturnType<typeof vi.fn>;
+    put: ReturnType<typeof vi.fn>;
+    delete: ReturnType<typeof vi.fn>;
+  };
+  let mockRequest: IDBRequest;
+
+  beforeEach(() => {
+    mockRequest = {
+      result: null,
+      error: null,
+      onsuccess: null,
+      onerror: null,
+    } as unknown as IDBRequest;
+    mockObjectStore = {
+      get: vi.fn().mockReturnValue(mockRequest),
+      put: vi.fn().mockReturnValue(mockRequest),
+      delete: vi.fn().mockReturnValue(mockRequest),
+    };
+    mockTransaction = {
+      objectStore: vi.fn().mockReturnValue(mockObjectStore),
+      error: null,
+      onerror: null,
+    } as unknown as IDBTransaction;
+    mockDatabase = {
+      transaction: vi.fn().mockReturnValue(mockTransaction),
+      objectStoreNames: {
+        contains: vi.fn().mockReturnValue(true),
+      },
+      createObjectStore: vi.fn(),
+    };
+    const mockOpenRequest = {
+      result: mockDatabase,
+      error: null,
+      onsuccess: null,
+      onerror: null,
+      onupgradeneeded: null,
+    } as unknown as IDBOpenDBRequest;
+    const mockIndexedDB = {
+      open: vi.fn().mockImplementation(() => {
+        setTimeout(() => {
+          if (mockOpenRequest.onsuccess) {
+            mockOpenRequest.onsuccess(new Event("success"));
+          }
+        }, 0);
+        return mockOpenRequest;
+      }),
+    } as unknown as IDBFactory;
+    (globalThis as { indexedDB?: IDBFactory }).indexedDB = mockIndexedDB;
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    (globalThis as { indexedDB?: IDBFactory }).indexedDB = undefined;
+  });
+
+  describe("initialization", () => {
+    it("should initialize with default database name", async () => {
+      storage = new IndexedDBKV();
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      expect(vi.mocked(globalThis.indexedDB!.open)).toHaveBeenCalledWith("frappe-sync", 1);
+    });
+
+    it("should initialize with custom database name", async () => {
+      storage = new IndexedDBKV("custom-db", "custom-store");
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      expect(vi.mocked(globalThis.indexedDB!.open)).toHaveBeenCalledWith("custom-db", 1);
+    });
+
+    it("should create object store on upgrade", async () => {
+      const mockOpenRequest = {
+        result: mockDatabase,
+        error: null,
+        onsuccess: null,
+        onerror: null,
+        onupgradeneeded: null,
+      } as unknown as IDBOpenDBRequest;
+      vi.mocked(globalThis.indexedDB!.open).mockReturnValue(mockOpenRequest);
+      mockDatabase.objectStoreNames.contains.mockReturnValue(false);
+      storage = new IndexedDBKV();
+      if (mockOpenRequest.onupgradeneeded) {
+        mockOpenRequest.onupgradeneeded({
+          type: "upgradeneeded",
+          newVersion: 1,
+          oldVersion: 0,
+        } as IDBVersionChangeEvent);
+      }
+      expect(mockDatabase.createObjectStore).toHaveBeenCalledWith("kv");
+    });
+
+    it("should handle IndexedDB not available", async () => {
+      (globalThis as { indexedDB?: IDBFactory }).indexedDB = undefined;
+      storage = new IndexedDBKV();
+      await expect(storage.getItem("test")).rejects.toThrow(
+        "IndexedDB not available in this environment",
+      );
+    });
+
+    it("should handle database open errors", async () => {
+      const mockOpenRequest = {
+        result: null,
+        error: new Error("Failed to open"),
+        onsuccess: null,
+        onerror: null,
+        onupgradeneeded: null,
+      } as unknown as IDBOpenDBRequest;
+      vi.mocked(globalThis.indexedDB!.open).mockReturnValue(mockOpenRequest);
+      storage = new IndexedDBKV();
+      setTimeout(() => {
+        if (mockOpenRequest.onerror) {
+          mockOpenRequest.onerror(new Event("error"));
+        }
+      }, 0);
+      await expect(storage.getItem("test")).rejects.toThrow("Failed to open");
+    });
+  });
+
+  describe("getItem", () => {
+    beforeEach(async () => {
+      storage = new IndexedDBKV();
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    });
+
+    it("should retrieve existing value", async () => {
+      const testValue = "test-value";
+      mockObjectStore.get.mockImplementation(() => {
+        const request = {
+          result: testValue,
+          error: null,
+          onsuccess: null,
+          onerror: null,
+        } as unknown as IDBRequest;
+        setTimeout(() => {
+          if (request.onsuccess) {
+            request.onsuccess(new Event("success"));
+          }
+        }, 0);
+        return request;
+      });
+      const result = await storage.getItem("test-key");
+      expect(result).toBe(testValue);
+      expect(mockDatabase.transaction).toHaveBeenCalledWith("kv", "readonly");
+      expect(mockObjectStore.get).toHaveBeenCalledWith("test-key");
+    });
+
+    it("should return null for non-existent key", async () => {
+      mockObjectStore.get.mockImplementation(() => {
+        const request = {
+          result: undefined,
+          error: null,
+          onsuccess: null,
+          onerror: null,
+        } as unknown as IDBRequest;
+        setTimeout(() => {
+          if (request.onsuccess) {
+            request.onsuccess(new Event("success"));
+          }
+        }, 0);
+        return request;
+      });
+      const result = await storage.getItem("non-existent");
+      expect(result).toBeNull();
+    });
+
+    it("should handle request errors", async () => {
+      mockObjectStore.get.mockImplementation(() => {
+        const request = {
+          result: null,
+          error: new Error("Get failed"),
+          onsuccess: null,
+          onerror: null,
+        } as unknown as IDBRequest;
+        setTimeout(() => {
+          if (request.onerror) {
+            request.onerror(new Event("error"));
+          }
+        }, 0);
+        return request;
+      });
+      await expect(storage.getItem("test-key")).rejects.toThrow("Get failed");
+    });
+
+    it("should handle transaction errors", async () => {
+      mockDatabase.transaction.mockImplementation(() => {
+        const transaction = {
+          objectStore: vi.fn().mockReturnValue(mockObjectStore),
+          error: new Error("Transaction failed"),
+          onerror: null,
+        } as unknown as IDBTransaction;
+        setTimeout(() => {
+          if (transaction.onerror) {
+            transaction.onerror(new Event("error"));
+          }
+        }, 0);
+        return transaction;
+      });
+      await expect(storage.getItem("test-key")).rejects.toThrow("Transaction failed");
+    });
+  });
+
+  describe("setItem", () => {
+    beforeEach(async () => {
+      storage = new IndexedDBKV();
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    });
+
+    it("should store value successfully", async () => {
+      mockObjectStore.put.mockImplementation(() => {
+        const request = {
+          result: undefined,
+          error: null,
+          onsuccess: null,
+          onerror: null,
+        } as unknown as IDBRequest;
+        setTimeout(() => {
+          if (request.onsuccess) {
+            request.onsuccess(new Event("success"));
+          }
+        }, 0);
+        return request;
+      });
+      await storage.setItem("test-key", "test-value");
+      expect(mockDatabase.transaction).toHaveBeenCalledWith("kv", "readwrite");
+      expect(mockObjectStore.put).toHaveBeenCalledWith("test-value", "test-key");
+    });
+
+    it("should handle put errors", async () => {
+      mockObjectStore.put.mockImplementation(() => {
+        const request = {
+          result: null,
+          error: new Error("Put failed"),
+          onsuccess: null,
+          onerror: null,
+        } as unknown as IDBRequest;
+        setTimeout(() => {
+          if (request.onerror) {
+            request.onerror(new Event("error"));
+          }
+        }, 0);
+        return request;
+      });
+      await expect(storage.setItem("test-key", "test-value")).rejects.toThrow("Put failed");
+    });
+
+    it("should handle large values", async () => {
+      const largeValue = "x".repeat(1024 * 1024);
+      mockObjectStore.put.mockImplementation(() => {
+        const request = {
+          result: undefined,
+          error: null,
+          onsuccess: null,
+          onerror: null,
+        } as unknown as IDBRequest;
+        setTimeout(() => {
+          if (request.onsuccess) {
+            request.onsuccess(new Event("success"));
+          }
+        }, 0);
+        return request;
+      });
+      await storage.setItem("large-key", largeValue);
+      expect(mockObjectStore.put).toHaveBeenCalledWith(largeValue, "large-key");
+    });
+  });
+
+  describe("removeItem", () => {
+    beforeEach(async () => {
+      storage = new IndexedDBKV();
+      await new Promise((resolve) => setTimeout(resolve, 10));
+    });
+
+    it("should delete value successfully", async () => {
+      mockObjectStore.delete.mockImplementation(() => {
+        const request = {
+          result: undefined,
+          error: null,
+          onsuccess: null,
+          onerror: null,
+        } as unknown as IDBRequest;
+        setTimeout(() => {
+          if (request.onsuccess) {
+            request.onsuccess(new Event("success"));
+          }
+        }, 0);
+        return request;
+      });
+      await storage.removeItem("test-key");
+      expect(mockDatabase.transaction).toHaveBeenCalledWith("kv", "readwrite");
+      expect(mockObjectStore.delete).toHaveBeenCalledWith("test-key");
+    });
+
+    it("should handle delete errors gracefully", async () => {
+      mockObjectStore.delete.mockImplementation(() => {
+        const request = {
+          result: null,
+          error: new Error("Delete failed"),
+          onsuccess: null,
+          onerror: null,
+        } as unknown as IDBRequest;
+        setTimeout(() => {
+          if (request.onerror) {
+            request.onerror(new Event("error"));
+          }
+        }, 0);
+        return request;
+      });
+      await storage.removeItem("test-key");
+      expect(console.warn).toHaveBeenCalledWith(
+        expect.stringContaining("IndexedDB removeItem failed"),
+        expect.any(Error),
+      );
+    });
+
+    it("should handle transaction errors gracefully", async () => {
+      mockDatabase.transaction.mockImplementation(() => {
+        const transaction = {
+          objectStore: vi.fn().mockReturnValue(mockObjectStore),
+          error: new Error("Transaction failed"),
+          onerror: null,
+        } as unknown as IDBTransaction;
+        setTimeout(() => {
+          if (transaction.onerror) {
+            transaction.onerror(new Event("error"));
+          }
+        }, 0);
+        return transaction;
+      });
+      await storage.removeItem("test-key");
+      expect(console.warn).toHaveBeenCalledWith(
+        expect.stringContaining("IndexedDB removeItem failed"),
+        expect.any(Error),
+      );
+    });
+  });
+
+  describe("concurrent operations", () => {
+    beforeEach(async () => {
+      storage = new IndexedDBKV();
+      await new Promise((resolve) => setTimeout(resolve, 10));
+      const createSuccessRequest = () => {
+        const request = {
+          result: "value",
+          error: null,
+          onsuccess: null,
+          onerror: null,
+        } as unknown as IDBRequest;
+        setTimeout(() => {
+          if (request.onsuccess) {
+            request.onsuccess(new Event("success"));
+          }
+        }, Math.random() * 10);
+        return request;
+      };
+      mockObjectStore.get.mockImplementation(createSuccessRequest);
+      mockObjectStore.put.mockImplementation(createSuccessRequest);
+      mockObjectStore.delete.mockImplementation(createSuccessRequest);
+    });
+
+    it("should handle concurrent reads", async () => {
+      const promises = Array.from({ length: 10 }, (_, i) => storage.getItem(`key-${i}`));
+      const results = await Promise.all(promises);
+      expect(results).toHaveLength(10);
+      expect(mockObjectStore.get).toHaveBeenCalledTimes(10);
+    });
+
+    it("should handle mixed concurrent operations", async () => {
+      const promises = [
+        storage.getItem("key1"),
+        storage.setItem("key2", "value2"),
+        storage.removeItem("key3"),
+        storage.getItem("key4"),
+        storage.setItem("key5", "value5"),
+      ];
+      await Promise.all(promises);
+      expect(mockObjectStore.get).toHaveBeenCalledTimes(2);
+      expect(mockObjectStore.put).toHaveBeenCalledTimes(2);
+      expect(mockObjectStore.delete).toHaveBeenCalledTimes(1);
+    });
+  });
+});

package/src/sync/storage.ts

@@ -0,0 +1,174 @@
+import { storage } from "@multiplatform.one/store";
+import type { KVStorage } from "./types";
+
+/**
+ * Platform-aware persistence adapter using @multiplatform.one/store.
+ *
+ * Uses MMKV on React Native and localStorage on web, provided by the
+ * store package's platform-specific storage module.
+ */
+export class PlatformStorageKV implements KVStorage {
+  async getItem(key: string): Promise<string | null> {
+    try {
+      return storage.getItem(key) ?? null;
+    } catch (err) {
+      console.warn(`Storage getItem failed for key "${key}":`, err);
+      return null;
+    }
+  }
+
+  async setItem(key: string, value: string): Promise<void> {
+    try {
+      storage.setItem(key, value);
+    } catch (err) {
+      console.warn(`Storage setItem failed for key "${key}":`, err);
+    }
+  }
+
+  async removeItem(key: string): Promise<void> {
+    try {
+      storage.removeItem(key);
+    } catch (err) {
+      console.warn(`Storage removeItem failed for key "${key}":`, err);
+    }
+  }
+}
+
+/**
+ * IndexedDB-based persistence adapter.
+ *
+ * This is the preferred storage option for modern browsers, providing
+ * robust asynchronous storage with proper transaction support and
+ * generous quota limits (typically hundreds of MB to GB).
+ *
+ * Characteristics:
+ * - **Asynchronous**: All operations are truly async and non-blocking
+ * - **Large Quota**: Usually 10% of available disk space (GB range)
+ * - **Transactional**: ACID guarantees for data consistency
+ * - **Structured**: Can store complex objects, not just strings
+ * - **Versioned**: Schema migrations supported through version upgrades
+ * - **Origin-isolated**: Each domain gets its own database namespace
+ *
+ * Architecture:
+ * - Database: "frappe-sync" (configurable)
+ * - Object Store: "kv" (simple key-value pairs)
+ * - No indexes: Simple string keys for sync state storage
+ *
+ * Transaction Model:
+ * - Read operations use "readonly" transactions (can run in parallel)
+ * - Write operations use "readwrite" transactions (serialized)
+ * - Failed operations automatically rollback the transaction
+ *
+ * Error Scenarios:
+ * - IndexedDB not available (older browsers, private browsing)
+ * - Database blocked by another connection
+ * - Quota exceeded (rare with generous limits)
+ * - Transaction abort due to concurrent modifications
+ * - Database corruption or version conflicts
+ *
+ * Performance Notes:
+ * - Connection pooling: Single database connection shared across operations
+ * - Async initialization: Database opens lazily on first access
+ * - Transaction batching: Consider batching multiple operations when possible
+ */
+export class IndexedDBKV implements KVStorage {
+  private dbPromise: Promise<IDBDatabase>;
+
+  constructor(
+    private readonly dbName = "frappe-sync",
+    private readonly store = "kv",
+  ) {
+    this.dbPromise = new Promise((resolve, reject) => {
+      if (typeof indexedDB === "undefined") {
+        reject(new Error("IndexedDB not available in this environment"));
+        return;
+      }
+      const openRequest = indexedDB.open(dbName, 1);
+      openRequest.onupgradeneeded = () => {
+        const database = openRequest.result;
+        if (!database.objectStoreNames.contains(store)) {
+          database.createObjectStore(store);
+        }
+      };
+      openRequest.onsuccess = () => {
+        resolve(openRequest.result);
+      };
+      openRequest.onerror = () => {
+        reject(openRequest.error || new Error("Failed to open IndexedDB"));
+      };
+    });
+  }
+
+  async getItem(key: string): Promise<string | null> {
+    const database = await this.dbPromise;
+    return new Promise<string | null>((resolve, reject) => {
+      const transaction = database.transaction(this.store, "readonly");
+      const objectStore = transaction.objectStore(this.store);
+      const getRequest = objectStore.get(key);
+      getRequest.onsuccess = () => {
+        resolve((getRequest.result as string) ?? null);
+      };
+      getRequest.onerror = () => {
+        reject(getRequest.error || new Error(`Failed to get key "${key}"`));
+      };
+      transaction.onerror = () => {
+        reject(transaction.error || new Error("Transaction failed"));
+      };
+    });
+  }
+
+  async setItem(key: string, value: string): Promise<void> {
+    const database = await this.dbPromise;
+    await new Promise<void>((resolve, reject) => {
+      const transaction = database.transaction(this.store, "readwrite");
+      const objectStore = transaction.objectStore(this.store);
+      const putRequest = objectStore.put(value, key);
+      putRequest.onsuccess = () => {
+        resolve();
+      };
+      putRequest.onerror = () => {
+        reject(putRequest.error || new Error(`Failed to set key "${key}"`));
+      };
+      transaction.onerror = () => {
+        reject(transaction.error || new Error("Transaction failed"));
+      };
+    });
+  }
+
+  /**
+   * Removes a key from IndexedDB.
+   * Uses a readwrite transaction with automatic error handling.
+   *
+   * @param key - The storage key to remove
+   */
+  async removeItem(key: string): Promise<void> {
+    try {
+      const database = await this.dbPromise;
+
+      await new Promise<void>((resolve, reject) => {
+        // Create readwrite transaction for this operation
+        const transaction = database.transaction(this.store, "readwrite");
+        const objectStore = transaction.objectStore(this.store);
+        const deleteRequest = objectStore.delete(key);
+
+        // Handle successful deletion
+        deleteRequest.onsuccess = () => {
+          resolve();
+        };
+
+        // Handle deletion errors
+        deleteRequest.onerror = () => {
+          reject(deleteRequest.error || new Error(`Failed to delete key "${key}"`));
+        };
+
+        // Handle transaction errors
+        transaction.onerror = () => {
+          reject(transaction.error || new Error("Transaction failed"));
+        };
+      });
+    } catch (err) {
+      console.warn(`IndexedDB removeItem failed for key "${key}":`, err);
+      // Don't throw - allow graceful degradation
+    }
+  }
+}