@multiplatform.one/frappe 6.0.0

package/src/file.spec.ts

@@ -0,0 +1,347 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { HttpClient } from "./core/http";
+import { FileModule } from "./file";
+import type { UploadArgs } from "./file";
+
+describe("FileModule", () => {
+  let fileModule: FileModule;
+  let mockHttpClient: HttpClient;
+
+  beforeEach(() => {
+    mockHttpClient = {
+      get: vi.fn(),
+      post: vi.fn(),
+      put: vi.fn(),
+      delete: vi.fn(),
+      head: vi.fn(),
+      request: vi.fn(),
+      setToken: vi.fn(),
+    } as unknown as HttpClient;
+
+    fileModule = new FileModule(mockHttpClient);
+  });
+
+  describe("constructor", () => {
+    it("should initialize with http client", () => {
+      const instance = new FileModule(mockHttpClient);
+      expect(instance).toBeDefined();
+    });
+  });
+
+  describe("uploadFile", () => {
+    it("should upload a File with minimal args", async () => {
+      const file = new File(["test content"], "test.txt", {
+        type: "text/plain",
+      });
+      const args: UploadArgs = {};
+
+      const mockResponse = {
+        payload: {
+          message: "File uploaded successfully",
+          file_url: "/files/test.txt",
+        },
+        headers: new Headers(),
+        status: 200,
+      };
+
+      (mockHttpClient.post as any).mockResolvedValue(mockResponse);
+
+      const result = await fileModule.uploadFile(file, args);
+
+      expect(mockHttpClient.post).toHaveBeenCalledTimes(1);
+      const calledArgs = (mockHttpClient.post as any).mock.calls[0];
+      expect(calledArgs[0]).toBe("/api/method/upload_file");
+
+      const formData = calledArgs[1] as FormData;
+      expect(formData).toBeInstanceOf(FormData);
+      expect(formData.get("file")).toBe(file);
+
+      expect(result).toEqual(mockResponse);
+    });
+
+    it("should upload a Blob", async () => {
+      const blob = new Blob(["binary data"], {
+        type: "application/octet-stream",
+      });
+      const args: UploadArgs = {};
+
+      const mockResponse = {
+        payload: {
+          message: "File uploaded",
+        },
+        headers: new Headers(),
+        status: 200,
+      };
+
+      (mockHttpClient.post as any).mockResolvedValue(mockResponse);
+
+      await fileModule.uploadFile(blob, args);
+
+      const calledArgs = (mockHttpClient.post as any).mock.calls[0];
+      const formData = calledArgs[1] as FormData;
+      // FormData.append converts Blob to File in some environments
+      const uploadedFile = formData.get("file");
+      expect(uploadedFile).toBeDefined();
+      expect(uploadedFile).toHaveProperty("size", 11);
+      expect(uploadedFile).toHaveProperty("type", "application/octet-stream");
+    });
+
+    it("should include all upload args in FormData", async () => {
+      const file = new File(["content"], "document.pdf", {
+        type: "application/pdf",
+      });
+      const args: UploadArgs = {
+        isPrivate: true,
+        folder: "Home/Documents",
+        file_url: "/custom/path",
+        doctype: "Sales Invoice",
+        docname: "INV-001",
+        fieldname: "attachment",
+      };
+
+      const mockResponse = {
+        payload: { message: "Uploaded" },
+        headers: new Headers(),
+        status: 200,
+      };
+
+      (mockHttpClient.post as any).mockResolvedValue(mockResponse);
+
+      await fileModule.uploadFile(file, args);
+
+      const formData = (mockHttpClient.post as any).mock.calls[0][1] as FormData;
+      expect(formData.get("file")).toBe(file);
+      expect(formData.get("isPrivate")).toBe("true");
+      expect(formData.get("folder")).toBe("Home/Documents");
+      expect(formData.get("file_url")).toBe("/custom/path");
+      expect(formData.get("doctype")).toBe("Sales Invoice");
+      expect(formData.get("docname")).toBe("INV-001");
+      expect(formData.get("fieldname")).toBe("attachment");
+    });
+
+    it("should handle partial args", async () => {
+      const file = new File(["test"], "test.jpg", { type: "image/jpeg" });
+      const args: UploadArgs = {
+        isPrivate: false,
+        folder: "Public/Images",
+      };
+
+      const mockResponse = {
+        payload: { message: "Uploaded" },
+        headers: new Headers(),
+        status: 200,
+      };
+
+      (mockHttpClient.post as any).mockResolvedValue(mockResponse);
+
+      await fileModule.uploadFile(file, args);
+
+      const formData = (mockHttpClient.post as any).mock.calls[0][1] as FormData;
+      expect(formData.get("isPrivate")).toBe("false");
+      expect(formData.get("folder")).toBe("Public/Images");
+      expect(formData.get("doctype")).toBeNull();
+      expect(formData.get("docname")).toBeNull();
+    });
+
+    it("should skip null and undefined values in args", async () => {
+      const file = new File(["data"], "data.csv", { type: "text/csv" });
+      const args: UploadArgs = {
+        isPrivate: undefined,
+        folder: null as any,
+        doctype: "Test",
+      };
+
+      const mockResponse = {
+        payload: { message: "Uploaded" },
+        headers: new Headers(),
+        status: 200,
+      };
+
+      (mockHttpClient.post as any).mockResolvedValue(mockResponse);
+
+      await fileModule.uploadFile(file, args);
+
+      const formData = (mockHttpClient.post as any).mock.calls[0][1] as FormData;
+      expect(formData.get("isPrivate")).toBeNull();
+      expect(formData.get("folder")).toBeNull();
+      expect(formData.get("doctype")).toBe("Test");
+    });
+
+    it("should handle onProgress callback", async () => {
+      const file = new File(["content"], "upload.txt", { type: "text/plain" });
+      const args: UploadArgs = {};
+      const onProgress = vi.fn();
+
+      const mockResponse = {
+        payload: { message: "Uploaded" },
+        headers: new Headers(),
+        status: 200,
+      };
+
+      (mockHttpClient.post as any).mockResolvedValue(mockResponse);
+
+      await fileModule.uploadFile(file, args, onProgress);
+
+      // Note: The current implementation doesn't actually use onProgress
+      // This test is here to ensure the signature accepts the callback
+      expect(mockHttpClient.post).toHaveBeenCalled();
+    });
+
+    it("should handle large files", async () => {
+      const largeContent = Array.from({ length: 10000 }).fill("x").join("");
+      const file = new File([largeContent], "large.txt", {
+        type: "text/plain",
+      });
+      const args: UploadArgs = {
+        folder: "Large Files",
+      };
+
+      const mockResponse = {
+        payload: { message: "Large file uploaded" },
+        headers: new Headers(),
+        status: 200,
+      };
+
+      (mockHttpClient.post as any).mockResolvedValue(mockResponse);
+
+      await fileModule.uploadFile(file, args);
+
+      const formData = (mockHttpClient.post as any).mock.calls[0][1] as FormData;
+      expect(formData.get("file")).toBe(file);
+    });
+
+    it("should handle special characters in filenames", async () => {
+      const file = new File(["content"], "test file (2025) - copy.txt", {
+        type: "text/plain",
+      });
+      const args: UploadArgs = {};
+
+      const mockResponse = {
+        payload: { message: "Uploaded" },
+        headers: new Headers(),
+        status: 200,
+      };
+
+      (mockHttpClient.post as any).mockResolvedValue(mockResponse);
+
+      await fileModule.uploadFile(file, args);
+
+      const formData = (mockHttpClient.post as any).mock.calls[0][1] as FormData;
+      const uploadedFile = formData.get("file") as File;
+      expect(uploadedFile.name).toBe("test file (2025) - copy.txt");
+    });
+
+    it("should handle various file types", async () => {
+      const testCases = [
+        { content: "text", name: "doc.txt", type: "text/plain" },
+        { content: "{}", name: "data.json", type: "application/json" },
+        { content: "<html/>", name: "page.html", type: "text/html" },
+        { content: "binary", name: "image.png", type: "image/png" },
+        { content: "csv,data", name: "sheet.csv", type: "text/csv" },
+      ];
+
+      for (const testCase of testCases) {
+        const file = new File([testCase.content], testCase.name, {
+          type: testCase.type,
+        });
+
+        const mockResponse = {
+          payload: { message: "Uploaded" },
+          headers: new Headers(),
+          status: 200,
+        };
+
+        (mockHttpClient.post as any).mockResolvedValue(mockResponse);
+
+        await fileModule.uploadFile(file, {});
+
+        const formData = (mockHttpClient.post as any).mock.calls[
+          (mockHttpClient.post as any).mock.calls.length - 1
+        ][1] as FormData;
+        const uploadedFile = formData.get("file") as File;
+        expect(uploadedFile.type).toBe(testCase.type);
+      }
+    });
+
+    it("should handle upload errors", async () => {
+      const file = new File(["content"], "test.txt", { type: "text/plain" });
+      const args: UploadArgs = {};
+
+      const mockError = new Error("Upload failed: File too large");
+      (mockHttpClient.post as any).mockRejectedValue(mockError);
+
+      await expect(fileModule.uploadFile(file, args)).rejects.toThrow(
+        "Upload failed: File too large",
+      );
+    });
+
+    it("should handle network errors", async () => {
+      const file = new File(["content"], "test.txt", { type: "text/plain" });
+      const args: UploadArgs = {};
+
+      const mockError = new Error("Network error");
+      (mockHttpClient.post as any).mockRejectedValue(mockError);
+
+      await expect(fileModule.uploadFile(file, args)).rejects.toThrow("Network error");
+    });
+
+    it("should convert boolean isPrivate to string", async () => {
+      const file = new File(["content"], "private.txt", { type: "text/plain" });
+      const args: UploadArgs = {
+        isPrivate: true,
+      };
+
+      const mockResponse = {
+        payload: { message: "Uploaded" },
+        headers: new Headers(),
+        status: 200,
+      };
+
+      (mockHttpClient.post as any).mockResolvedValue(mockResponse);
+
+      await fileModule.uploadFile(file, args);
+
+      const formData = (mockHttpClient.post as any).mock.calls[0][1] as FormData;
+      expect(formData.get("isPrivate")).toBe("true");
+      expect(typeof formData.get("isPrivate")).toBe("string");
+    });
+
+    it("should handle empty file", async () => {
+      const file = new File([""], "empty.txt", { type: "text/plain" });
+      const args: UploadArgs = {};
+
+      const mockResponse = {
+        payload: { message: "Empty file uploaded" },
+        headers: new Headers(),
+        status: 200,
+      };
+
+      (mockHttpClient.post as any).mockResolvedValue(mockResponse);
+
+      await fileModule.uploadFile(file, args);
+
+      const formData = (mockHttpClient.post as any).mock.calls[0][1] as FormData;
+      const uploadedFile = formData.get("file") as File;
+      expect(uploadedFile.size).toBe(0);
+    });
+
+    it("should handle file with no type", async () => {
+      const file = new File(["content"], "unknown");
+      const args: UploadArgs = {};
+
+      const mockResponse = {
+        payload: { message: "Uploaded" },
+        headers: new Headers(),
+        status: 200,
+      };
+
+      (mockHttpClient.post as any).mockResolvedValue(mockResponse);
+
+      await fileModule.uploadFile(file, args);
+
+      const formData = (mockHttpClient.post as any).mock.calls[0][1] as FormData;
+      const uploadedFile = formData.get("file") as File;
+      expect(uploadedFile.type).toBe("");
+    });
+  });
+});

package/src/file.ts

@@ -0,0 +1,27 @@
+import type { HttpClient } from "./core/http";
+
+export type UploadArgs = {
+  isPrivate?: boolean;
+  folder?: string;
+  file_url?: string;
+  doctype?: string;
+  docname?: string;
+  fieldname?: string;
+};
+
+export class FileModule {
+  constructor(private readonly http: HttpClient) {}
+
+  uploadFile(
+    file: File | Blob,
+    args: UploadArgs,
+    _onProgress?: (completed: number, total: number) => void,
+  ) {
+    const form = new FormData();
+    form.append("file", file as any);
+    Object.entries(args).forEach(([k, v]) => {
+      if (v != null) form.append(k, String(v));
+    });
+    return this.http.post("/api/method/upload_file", form);
+  }
+}

package/src/fixtureDb.ts

@@ -0,0 +1,208 @@
+/**
+ * DbModule adapter backed by a FixtureProvider.
+ *
+ * Implements the same interface as DbModule so that SyncModule works
+ * identically whether data comes from a live Frappe server or in-memory
+ * fixtures. This means virtual pagination, progressive cache, mutation
+ * journal, and devtools all work in fixture/Storybook mode.
+ */
+
+import type { FrappeDoc, FrappeDocData } from "./common/types";
+import type { ListOptions } from "./core/types";
+import type { BackfillArgs, BackfillResponse } from "./db";
+import type { FixtureProvider } from "./fixtures";
+import type { OrderBy } from "./sync/types";
+
+export class FixtureDbModule {
+  constructor(private readonly fixtures: FixtureProvider) {}
+
+  getAppName(): string | undefined {
+    return undefined;
+  }
+
+  getEndpoints() {
+    return {
+      createDoc: "fixture://createDoc",
+      updateDoc: "fixture://updateDoc",
+      deleteDoc: "fixture://deleteDoc",
+      backfill: "fixture://backfill",
+      getListWithCursor: "fixture://getListWithCursor",
+      batchMutations: "fixture://batchMutations",
+      listSince: "fixture://listSince",
+    };
+  }
+
+  async getDoc<Data extends FrappeDocData>(
+    doctype: string,
+    name: string,
+  ): Promise<FrappeDoc<Data>> {
+    const doc = await this.fixtures.getDoc<Data>(doctype, name);
+    if (!doc) throw new Error(`Document ${doctype}/${name} not found`);
+    return { ...doc, doctype, name } as FrappeDoc<Data>;
+  }
+
+  async getDocVersion(_doctype: string, _name: string): Promise<string | undefined> {
+    return undefined;
+  }
+
+  async getDocList<Data extends FrappeDocData>(
+    doctype: string,
+    options: ListOptions = {},
+  ): Promise<FrappeDoc<Data>[]> {
+    const fixtureOptions: Parameters<FixtureProvider["getList"]>[1] = {};
+
+    if (options.fields) fixtureOptions.fields = options.fields;
+    if (options.filters) fixtureOptions.filters = options.filters as any;
+    if (options.orderBy) fixtureOptions.orderBy = normalizeOrderBy(options.orderBy);
+    if (typeof options.limitStart === "number") fixtureOptions.limitStart = options.limitStart;
+    if (options.limit != null) fixtureOptions.limit = options.limit;
+
+    const docs = await this.fixtures.getList<Data>(doctype, fixtureOptions as any);
+    return docs.map((d) => ({ ...d, doctype, name: (d as any).name }) as FrappeDoc<Data>);
+  }
+
+  async getCount(
+    doctype: string,
+    filters?: Array<[string, string, unknown]> | Record<string, unknown>,
+  ): Promise<number> {
+    const docs = await this.fixtures.getList(doctype, {
+      filters: filters as any,
+    });
+    return docs.length;
+  }
+
+  async createDoc<Data extends FrappeDocData>(
+    doc: Partial<FrappeDoc<Data>> & Pick<FrappeDoc<Data>, "doctype" | "name">,
+  ): Promise<FrappeDoc<Data>> {
+    const { client_mutation_id: _, base_modified: _b, ...cleanDoc } = doc as any;
+    return this.fixtures.createDoc<FrappeDoc<Data>>(doc.doctype, cleanDoc);
+  }
+
+  async updateDoc<Data extends FrappeDocData>(
+    doc: Partial<FrappeDoc<Data>> & Pick<FrappeDoc<Data>, "doctype" | "name">,
+  ): Promise<FrappeDoc<Data>> {
+    const { client_mutation_id: _, base_modified: _b, doctype, name, ...data } = doc as any;
+    return this.fixtures.updateDoc<FrappeDoc<Data>>(doctype, name, data);
+  }
+
+  async deleteDoc<Data extends FrappeDocData>(doc: Pick<FrappeDoc<Data>, "doctype" | "name">) {
+    await this.fixtures.deleteDoc(doc.doctype, doc.name);
+    return { message: "ok" };
+  }
+
+  async renameDoc<Data extends FrappeDocData>(
+    _doc: Pick<FrappeDoc<Data>, "doctype" | "name">,
+    _newName: string,
+    _merge?: boolean,
+  ) {
+    return { message: "not supported in fixture mode" };
+  }
+
+  async backfill<Data extends FrappeDocData>(args: BackfillArgs): Promise<BackfillResponse<Data>> {
+    const docs = await this.fixtures.getList<Data>(args.doctype, {
+      fields: args.fields as any,
+      filters: args.filters as any,
+      limit: args.limit,
+    });
+    return {
+      rows: docs.map((d) => ({ ...d, doctype: args.doctype }) as FrappeDoc<Data>),
+      checkpoint: new Date().toISOString(),
+      deleted: [],
+    };
+  }
+
+  async getListWithCursor<Data extends FrappeDocData>(args: {
+    doctype: string;
+    fields?: readonly string[];
+    filters?: Array<[string, string, unknown]> | Record<string, unknown>;
+    cursor?: string | null;
+    limit?: number;
+    orderBy?: OrderBy;
+  }) {
+    const limit = args.limit ?? 100;
+    let limitStart = 0;
+    if (args.cursor) {
+      const allDocs = await this.fixtures.getList(args.doctype, {
+        filters: args.filters as any,
+        orderBy: args.orderBy ? normalizeOrderBy(args.orderBy) : undefined,
+      });
+      const cursorIdx = allDocs.findIndex((d: any) => d.name === args.cursor);
+      if (cursorIdx >= 0) limitStart = cursorIdx + 1;
+    }
+
+    const docs = await this.fixtures.getList<Data>(args.doctype, {
+      fields: args.fields as any,
+      filters: args.filters as any,
+      orderBy: args.orderBy ? normalizeOrderBy(args.orderBy) : undefined,
+      limitStart,
+      limit,
+    });
+
+    const data = docs.map((d) => ({ ...d, doctype: args.doctype }) as FrappeDoc<Data>);
+    const lastDoc = data.length > 0 ? data[data.length - 1] : null;
+
+    return {
+      data,
+      next_cursor: data.length === limit && lastDoc ? (lastDoc as any).name : null,
+    };
+  }
+
+  async batchMutations<Data extends FrappeDocData>(args: {
+    mutations: Array<{ type: string; doctype: string; name?: string; data?: Partial<Data> }>;
+    atomic?: boolean;
+  }) {
+    const results: Array<{ success: boolean; data?: FrappeDocData; error?: string }> = [];
+    for (const mutation of args.mutations) {
+      try {
+        if (mutation.type === "create") {
+          const doc = await this.fixtures.createDoc(mutation.doctype, {
+            ...mutation.data,
+            name: mutation.name,
+          } as any);
+          results.push({ success: true, data: doc });
+        } else if (mutation.type === "update" && mutation.name) {
+          const doc = await this.fixtures.updateDoc(
+            mutation.doctype,
+            mutation.name,
+            mutation.data as any,
+          );
+          results.push({ success: true, data: doc });
+        } else if (mutation.type === "delete" && mutation.name) {
+          await this.fixtures.deleteDoc(mutation.doctype, mutation.name);
+          results.push({ success: true });
+        }
+      } catch (err: any) {
+        results.push({ success: false, error: err.message });
+      }
+    }
+    return results;
+  }
+
+  async listSince<Data extends FrappeDocData>(args: {
+    doctype: string;
+    modifiedAfter?: string;
+    fields?: readonly string[];
+    filters?: Array<[string, string, unknown]> | Record<string, unknown>;
+    limit?: number;
+  }) {
+    const docs = await this.fixtures.getList<Data>(args.doctype, {
+      fields: args.fields as any,
+      filters: args.filters as any,
+      limit: args.limit,
+    });
+    return {
+      rows: docs.map((d) => ({ ...d, doctype: args.doctype }) as FrappeDoc<Data>),
+      deleted: [] as string[],
+      checkpoint: new Date().toISOString(),
+    };
+  }
+}
+
+function normalizeOrderBy(
+  orderBy: OrderBy,
+): { field: string; order: string } | Array<{ field: string; order: string }> {
+  if (Array.isArray(orderBy)) {
+    return orderBy.map((ob) => ({ field: ob.field, order: ob.order }));
+  }
+  return { field: orderBy.field, order: orderBy.order };
+}