@multiplatform.one/frappe 6.0.0

package/src/collection.spec.ts

@@ -0,0 +1,213 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { frappeCollectionOptions, createFrappeCollection } from "./collection";
+import type { SyncModule } from "./sync";
+import { Operation } from "./sync/types";
+import type { FrappeDocData } from "./common/types";
+
+interface TestDoc extends FrappeDocData {
+  name: string;
+  doctype: string;
+  title: string;
+  status: string;
+}
+
+function createMockSyncModule(): SyncModule {
+  const listeners = new Set<() => void>();
+  let subscriptionDocs: TestDoc[] = [];
+
+  return {
+    subscribe: vi.fn().mockImplementation(async () => {
+      return { subscriptionId: "sub-123" };
+    }),
+    unsubscribe: vi.fn(),
+    mutate: vi.fn().mockResolvedValue(undefined),
+    getDocsForSubscription: vi.fn().mockImplementation(() => subscriptionDocs),
+    subscribeStore: vi.fn().mockImplementation((listener: () => void) => {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    }),
+    backfill: vi.fn().mockResolvedValue(undefined),
+    replayPending: vi.fn().mockResolvedValue(undefined),
+    getDocFromCache: vi.fn(),
+    getSubscription: vi.fn(),
+    getPage: vi.fn().mockResolvedValue([]),
+    getNextBatch: vi.fn().mockResolvedValue([]),
+    getPageInfo: vi.fn(),
+    refetchDocs: vi.fn().mockResolvedValue(undefined),
+    resetCache: vi.fn(),
+    dispose: vi.fn().mockResolvedValue(undefined),
+    isLeader: vi.fn().mockReturnValue(false),
+    // Test helpers
+    _setDocs: (docs: TestDoc[]) => {
+      subscriptionDocs = docs;
+    },
+    _emitChange: () => {
+      for (const listener of listeners) listener();
+    },
+  } as unknown as SyncModule;
+}
+
+describe("frappeCollectionOptions", () => {
+  let mockSync: SyncModule;
+
+  beforeEach(() => {
+    mockSync = createMockSyncModule();
+  });
+
+  it("should return a valid collection config", () => {
+    const options = frappeCollectionOptions<TestDoc>("Task", {
+      sync: mockSync,
+    });
+
+    expect(options).toBeDefined();
+    expect(options.id).toBe("Task");
+    expect(options.getKey).toBeDefined();
+    expect(options.sync).toBeDefined();
+    expect(options.onInsert).toBeDefined();
+    expect(options.onUpdate).toBeDefined();
+    expect(options.onDelete).toBeDefined();
+  });
+
+  it("should use custom id when provided", () => {
+    const options = frappeCollectionOptions<TestDoc>("Task", {
+      sync: mockSync,
+      id: "custom-tasks",
+    });
+
+    expect(options.id).toBe("custom-tasks");
+  });
+
+  it("should extract key from doc name", () => {
+    const options = frappeCollectionOptions<TestDoc>("Task", {
+      sync: mockSync,
+    });
+
+    const doc = { name: "TASK-001", doctype: "Task", title: "Test", status: "Open" } as TestDoc;
+    expect(options.getKey(doc)).toBe("TASK-001");
+  });
+
+  it("onInsert should delegate to SyncModule.mutate with create operation", async () => {
+    const options = frappeCollectionOptions<TestDoc>("Task", {
+      sync: mockSync,
+    });
+
+    const mockTransaction = {
+      mutations: [
+        {
+          modified: { name: "TASK-001", doctype: "Task", title: "New Task", status: "Open" },
+        },
+      ],
+    };
+
+    await options.onInsert!({ transaction: mockTransaction } as any);
+
+    expect(mockSync.mutate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        operation: Operation.Create,
+        doc: expect.objectContaining({
+          doctype: "Task",
+          title: "New Task",
+        }),
+      }),
+    );
+  });
+
+  it("onUpdate should delegate to SyncModule.mutate with update operation", async () => {
+    const options = frappeCollectionOptions<TestDoc>("Task", {
+      sync: mockSync,
+    });
+
+    const mockTransaction = {
+      mutations: [
+        {
+          key: "TASK-001",
+          changes: { status: "Closed" },
+          modified: { name: "TASK-001", doctype: "Task", title: "Test", status: "Closed" },
+        },
+      ],
+    };
+
+    await options.onUpdate!({ transaction: mockTransaction } as any);
+
+    expect(mockSync.mutate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        operation: Operation.Update,
+        doc: expect.objectContaining({
+          doctype: "Task",
+          name: "TASK-001",
+        }),
+      }),
+    );
+  });
+
+  it("onDelete should delegate to SyncModule.mutate with delete operation", async () => {
+    const options = frappeCollectionOptions<TestDoc>("Task", {
+      sync: mockSync,
+    });
+
+    const mockTransaction = {
+      mutations: [
+        {
+          key: "TASK-001",
+        },
+      ],
+    };
+
+    await options.onDelete!({ transaction: mockTransaction } as any);
+
+    expect(mockSync.mutate).toHaveBeenCalledWith(
+      expect.objectContaining({
+        operation: Operation.Delete,
+        doc: expect.objectContaining({
+          doctype: "Task",
+          name: "TASK-001",
+        }),
+      }),
+    );
+  });
+
+  it("should pass fields and filters to subscription query", async () => {
+    const options = frappeCollectionOptions<TestDoc>("Task", {
+      sync: mockSync,
+      fields: ["name", "title", "status"],
+      filters: { status: "Open" },
+    });
+
+    // Trigger the sync function to create the subscription
+    const syncFn = options.sync!.sync;
+    const cleanup = syncFn({
+      begin: vi.fn(),
+      write: vi.fn(),
+      commit: vi.fn(),
+      markReady: vi.fn(),
+      truncate: vi.fn(),
+      collection: {} as any,
+    });
+
+    // Wait for async initSync to complete
+    await new Promise((resolve) => setTimeout(resolve, 10));
+
+    expect(mockSync.subscribe).toHaveBeenCalledWith(
+      expect.objectContaining({
+        doctype: "Task",
+        fields: ["name", "title", "status"],
+        filters: { status: "Open" },
+      }),
+    );
+
+    // Cleanup
+    if (typeof cleanup === "function") cleanup();
+  });
+});
+
+describe("createFrappeCollection", () => {
+  it("should create a TanStack DB collection", () => {
+    const mockSync = createMockSyncModule();
+
+    const collection = createFrappeCollection<TestDoc>("Task", {
+      sync: mockSync,
+    });
+
+    expect(collection).toBeDefined();
+  });
+});

package/src/collection.ts

@@ -0,0 +1,328 @@
+import type { CollectionConfig, SyncConfig } from "@tanstack/db";
+import { createCollection } from "@tanstack/db";
+import type { FrappeDocData } from "./common/types";
+import type { FixtureProvider } from "./fixtures";
+import type { SyncModule } from "./sync";
+import { Operation } from "./sync/types";
+import type { SubscriptionQuery } from "./sync/types";
+
+/**
+ * Configuration for creating a Frappe-backed TanStack DB collection.
+ *
+ * @typeParam TDoc - The document type stored in the collection
+ */
+export interface FrappeCollectionOptionsConfig<
+  _TDoc extends object & { name: string; doctype: string },
+> {
+  /** The Frappe SyncModule instance to use for data sync */
+  sync: SyncModule;
+  /** Fields to subscribe to from the doctype */
+  fields?: readonly string[];
+  /** Frappe filters to apply to the subscription */
+  filters?: Record<string, unknown> | Array<[string, string, unknown]>;
+  /** Optional override for the collection id (defaults to doctype) */
+  id?: string;
+  /** Order-by configuration */
+  orderBy?: SubscriptionQuery["orderBy"];
+  /** Limit for the subscription */
+  limit?: number;
+}
+
+/**
+ * Creates TanStack DB collection options wired to Frappe's SyncModule.
+ *
+ * This follows TanStack DB's collection options creator pattern (Pattern B),
+ * where mutation handlers are built-in and delegate to SyncModule.
+ *
+ * @typeParam TDoc - The Frappe document type
+ * @param doctype - The Frappe doctype name (e.g. "ToDo", "Pokemon")
+ * @param config - Configuration for the collection
+ * @returns A CollectionConfig object suitable for `createCollection()`
+ *
+ * @example
+ * ```typescript
+ * const pokemonCollection = createCollection(
+ *   frappeCollectionOptions<Pokemon>("Pokemon", {
+ *     sync: syncModule,
+ *     fields: ["name", "pokemon_name", "poke_id"],
+ *   })
+ * );
+ * ```
+ */
+export function frappeCollectionOptions<TDoc extends object & { name: string; doctype: string }>(
+  doctype: string,
+  config: FrappeCollectionOptionsConfig<TDoc>,
+): CollectionConfig<TDoc, string> {
+  const { sync: syncModule, fields, filters, orderBy, limit } = config;
+
+  const syncFn: SyncConfig<TDoc, string>["sync"] = (params) => {
+    const { begin, write, commit, markReady } = params;
+
+    let subscriptionId: string | undefined;
+    let storeUnsubscribe: (() => void) | undefined;
+    let lastKnownNames = new Set<string>();
+
+    async function initSync() {
+      try {
+        // Subscribe to the SyncModule for this doctype
+        const query: SubscriptionQuery = {
+          doctype,
+          fields: fields as readonly string[] | undefined,
+          filters,
+          orderBy,
+          limit,
+        };
+
+        const result = await syncModule.subscribe<TDoc>(query);
+        subscriptionId = result.subscriptionId;
+
+        // Seed initial data from the subscription
+        const initialDocs = syncModule.getDocsForSubscription<TDoc>(subscriptionId);
+        if (initialDocs.length > 0) {
+          begin();
+          for (const doc of initialDocs) {
+            write({ type: "insert", value: doc as TDoc });
+            lastKnownNames.add(doc.name);
+          }
+          commit();
+        }
+
+        // Listen for SyncModule store changes and forward to collection
+        storeUnsubscribe = syncModule.subscribeStore(() => {
+          if (!subscriptionId) return;
+
+          const currentDocs = syncModule.getDocsForSubscription<TDoc>(subscriptionId);
+          const currentNames = new Set(currentDocs.map((d) => d.name));
+
+          begin();
+
+          // Upsert current docs
+          for (const doc of currentDocs) {
+            if (lastKnownNames.has(doc.name)) {
+              write({ type: "update", value: doc as TDoc });
+            } else {
+              write({ type: "insert", value: doc as TDoc });
+            }
+          }
+
+          // Delete docs that disappeared
+          for (const name of lastKnownNames) {
+            if (!currentNames.has(name)) {
+              write({
+                type: "delete",
+                value: { name, doctype } as unknown as TDoc,
+              });
+            }
+          }
+
+          commit();
+          lastKnownNames = currentNames;
+        });
+      } catch (error) {
+        console.error(`[frappe-collection] Initial sync failed for ${doctype}:`, error);
+      } finally {
+        markReady();
+      }
+    }
+
+    initSync();
+
+    // Return cleanup function
+    return () => {
+      if (storeUnsubscribe) {
+        storeUnsubscribe();
+        storeUnsubscribe = undefined;
+      }
+      if (subscriptionId) {
+        syncModule.unsubscribe(subscriptionId);
+        subscriptionId = undefined;
+      }
+    };
+  };
+
+  return {
+    id: config.id ?? doctype,
+    getKey: (doc: TDoc) => doc.name,
+    sync: { sync: syncFn },
+
+    onInsert: async ({ transaction }) => {
+      for (const mutation of transaction.mutations) {
+        const doc = mutation.modified;
+        await syncModule.mutate({
+          mutationId: crypto.randomUUID?.() ?? Math.random().toString(36).substring(2),
+          operation: Operation.Create,
+          doc: { ...doc, doctype } as FrappeDocData,
+        });
+      }
+    },
+
+    onUpdate: async ({ transaction }) => {
+      for (const mutation of transaction.mutations) {
+        const doc = mutation.changes ?? mutation.modified;
+        const name = mutation.key as string;
+        await syncModule.mutate({
+          mutationId: crypto.randomUUID?.() ?? Math.random().toString(36).substring(2),
+          operation: Operation.Update,
+          doc: { ...doc, doctype, name } as FrappeDocData,
+        });
+      }
+    },
+
+    onDelete: async ({ transaction }) => {
+      for (const mutation of transaction.mutations) {
+        const name = mutation.key as string;
+        await syncModule.mutate({
+          mutationId: crypto.randomUUID?.() ?? Math.random().toString(36).substring(2),
+          operation: Operation.Delete,
+          doc: { doctype, name } as FrappeDocData,
+        });
+      }
+    },
+  };
+}
+
+/**
+ * Creates a TanStack DB Collection backed by a Frappe doctype via SyncModule.
+ *
+ * Convenience wrapper that calls `createCollection(frappeCollectionOptions(...))`.
+ *
+ * @typeParam TDoc - The Frappe document type
+ * @param doctype - The Frappe doctype name
+ * @param config - Configuration for the collection
+ * @returns A TanStack DB Collection instance
+ *
+ * @example
+ * ```typescript
+ * const pokemonCollection = createFrappeCollection<Pokemon>("Pokemon", {
+ *   sync: syncModule,
+ *   fields: ["name", "pokemon_name", "poke_id"],
+ * });
+ *
+ * // Use with useLiveQuery
+ * const { data } = useLiveQuery((q) =>
+ *   q.from({ pokemon: pokemonCollection })
+ * );
+ *
+ * // Direct mutations
+ * pokemonCollection.insert({ name: "pikachu", doctype: "Pokemon", ... });
+ * ```
+ */
+export function createFrappeCollection<TDoc extends object & { name: string; doctype: string }>(
+  doctype: string,
+  config: FrappeCollectionOptionsConfig<TDoc>,
+) {
+  return createCollection<TDoc, string>(frappeCollectionOptions<TDoc>(doctype, config));
+}
+
+/**
+ * Configuration for creating a fixture-backed TanStack DB collection.
+ * Used when fixtures are provided (e.g. in Storybook or tests).
+ */
+export interface FixtureCollectionOptionsConfig<
+  _TDoc extends object & { name: string; doctype: string },
+> {
+  /** The fixture provider to use for data */
+  fixtures: FixtureProvider;
+  /** Fields to load from the doctype */
+  fields?: readonly string[];
+  /** Frappe filters to apply */
+  filters?: Record<string, unknown> | Array<[string, string, unknown]>;
+  /** Optional override for the collection id */
+  id?: string;
+  /** Order-by configuration */
+  orderBy?: SubscriptionQuery["orderBy"];
+  /** Limit for the query */
+  limit?: number;
+  /** Offset for pagination */
+  limitStart?: number;
+}
+
+/**
+ * Creates TanStack DB collection options wired to a FixtureProvider.
+ * Used when config.fixtures is set (e.g. in tests or Storybook).
+ */
+export function fixtureCollectionOptions<TDoc extends object & { name: string; doctype: string }>(
+  doctype: string,
+  config: FixtureCollectionOptionsConfig<TDoc>,
+): CollectionConfig<TDoc, string> {
+  const { fixtures, fields, filters, orderBy, limit, limitStart } = config;
+
+  const syncFn: SyncConfig<TDoc, string>["sync"] = (params) => {
+    const { begin, write, commit, markReady } = params;
+
+    async function initSync() {
+      try {
+        const orderByForFixture =
+          orderBy && !Array.isArray(orderBy)
+            ? { field: orderBy.field, order: String(orderBy.order) }
+            : Array.isArray(orderBy)
+              ? orderBy.map((ob) => ({ field: ob.field, order: String(ob.order) }))
+              : undefined;
+
+        const docs = await fixtures.getList<TDoc>(doctype, {
+          fields,
+          filters: filters as Partial<TDoc> | Array<[string, string, any]> | undefined,
+          orderBy: orderByForFixture,
+          limitStart,
+          limit,
+        });
+
+        if (docs.length > 0) {
+          begin();
+          for (const doc of docs) {
+            const fullDoc = { ...doc, doctype } as TDoc;
+            write({ type: "insert", value: fullDoc });
+          }
+          commit();
+        }
+      } catch (error) {
+        console.error(`[frappe-collection] Fixture sync failed for ${doctype}:`, error);
+      } finally {
+        markReady();
+      }
+    }
+
+    initSync();
+
+    return () => {};
+  };
+
+  return {
+    id: config.id ?? doctype,
+    getKey: (doc: TDoc) => doc.name,
+    sync: { sync: syncFn },
+
+    onInsert: async ({ transaction }) => {
+      for (const mutation of transaction.mutations) {
+        const doc = mutation.modified;
+        await fixtures.createDoc(doctype, { ...doc, doctype });
+      }
+    },
+
+    onUpdate: async ({ transaction }) => {
+      for (const mutation of transaction.mutations) {
+        const doc = mutation.changes ?? mutation.modified;
+        const name = mutation.key as string;
+        await fixtures.updateDoc(doctype, name, { ...doc, doctype });
+      }
+    },
+
+    onDelete: async ({ transaction }) => {
+      for (const mutation of transaction.mutations) {
+        const name = mutation.key as string;
+        await fixtures.deleteDoc(doctype, name);
+      }
+    },
+  };
+}
+
+/**
+ * Creates a TanStack DB Collection backed by a FixtureProvider.
+ * Used when config.fixtures is set (e.g. in tests or Storybook).
+ */
+export function createFixtureCollection<TDoc extends object & { name: string; doctype: string }>(
+  doctype: string,
+  config: FixtureCollectionOptionsConfig<TDoc>,
+) {
+  return createCollection<TDoc, string>(fixtureCollectionOptions<TDoc>(doctype, config));
+}