@goplusvn/core 0.1.0 → 0.1.1

package/src/crud/lib/crud-utils.test.ts

@@ -0,0 +1,354 @@
+import { describe, it, expect } from "vitest";
+import {
+  buildQueryString,
+  parseQueryString,
+  applyFilterOperator,
+  validateFieldValue,
+  getFieldDefaultValue,
+  sortFieldsByOrder,
+  isCrudResponse,
+  getDefaultValues,
+  isFieldVisibleInTable,
+  isFieldVisibleInForm,
+  filterDisplayOnlyFields,
+} from "./crud-utils";
+import { formatFieldValue } from "./field-formatter";
+import type { FieldConfig, EntityConfig } from "../../types";
+
+describe("CrudUtils", () => {
+  describe("buildQueryString", () => {
+    it("should build basic query params", () => {
+      const params = { page: 1, pageSize: 10 };
+      const qs = buildQueryString(params);
+      expect(qs).toBe("page=1&pageSize=10");
+    });
+
+    it("should include search param", () => {
+      const params = { page: 1, pageSize: 10, search: "test" };
+      const qs = buildQueryString(params);
+      expect(qs).toContain("search=test");
+      expect(qs).toContain("q=test");
+    });
+
+    it("should include sort params", () => {
+      const params = {
+        page: 1,
+        pageSize: 10,
+        sort: { field: "name", direction: "asc" as const },
+      };
+      const qs = buildQueryString(params);
+      expect(qs).toContain("sortField=name");
+      expect(qs).toContain("sortDirection=asc");
+    });
+
+    it("should include filters", () => {
+      const filters = [
+        {
+          name: "status",
+          field: "status",
+          operator: "eq" as const,
+          value: "active",
+        },
+      ];
+      const params = { page: 1, pageSize: 10, filters };
+      const qs = buildQueryString(params);
+      expect(qs).toContain(
+        "filters=" + encodeURIComponent(JSON.stringify(filters)),
+      );
+    });
+  });
+
+  describe("parseQueryString", () => {
+    it("should parse basic params", () => {
+      const params = new URLSearchParams("page=2&pageSize=20");
+      const result = parseQueryString(params);
+      expect(result).toEqual({ page: 2, pageSize: 20 });
+    });
+
+    it("should parse search param", () => {
+      const params = new URLSearchParams("page=1&pageSize=10&search=hello");
+      const result = parseQueryString(params);
+      expect(result.search).toBe("hello");
+    });
+
+    it("should parse sort params", () => {
+      const params = new URLSearchParams(
+        "page=1&pageSize=10&sortField=name&sortDirection=desc",
+      );
+      const result = parseQueryString(params);
+      expect(result.sort).toEqual({ field: "name", direction: "desc" });
+    });
+  });
+
+  describe("getFieldDefaultValue", () => {
+    it("should return defaultValue if present", () => {
+      const field: FieldConfig = {
+        name: "test",
+        label: "Test",
+        type: "text",
+        defaultValue: "default",
+      };
+      expect(getFieldDefaultValue(field)).toBe("default");
+    });
+
+    it("should return defaults based on type", () => {
+      expect(
+        getFieldDefaultValue({ name: "n", label: "", type: "number" }),
+      ).toBe(0);
+      expect(
+        getFieldDefaultValue({ name: "b", label: "", type: "boolean" }),
+      ).toBe(false);
+      expect(
+        getFieldDefaultValue({ name: "s", label: "", type: "select" }),
+      ).toBe("");
+      expect(
+        getFieldDefaultValue({ name: "m", label: "", type: "multiselect" }),
+      ).toEqual([]);
+      expect(getFieldDefaultValue({ name: "d", label: "", type: "date" })).toBe(
+        null,
+      );
+      expect(getFieldDefaultValue({ name: "t", label: "", type: "text" })).toBe(
+        "",
+      );
+    });
+  });
+
+  describe("applyFilterOperator", () => {
+    it("should handle eq operator", () => {
+      expect(applyFilterOperator("test", "eq", "test")).toBe(true);
+      expect(applyFilterOperator("test", "eq", "other")).toBe(false);
+    });
+
+    it("should handle ne operator", () => {
+      expect(applyFilterOperator("test", "ne", "other")).toBe(true);
+      expect(applyFilterOperator("test", "ne", "test")).toBe(false);
+    });
+
+    it("should handle comparison operators", () => {
+      expect(applyFilterOperator(10, "gt", 5)).toBe(true);
+      expect(applyFilterOperator(10, "lt", 20)).toBe(true);
+      expect(applyFilterOperator(10, "gte", 10)).toBe(true);
+      expect(applyFilterOperator(10, "lte", 10)).toBe(true);
+    });
+
+    it("should handle contains operator", () => {
+      expect(applyFilterOperator("hello world", "contains", "hello")).toBe(
+        true,
+      );
+      expect(applyFilterOperator("hello world", "contains", "foo")).toBe(false);
+    });
+
+    it("should handle startsWith/endsWith", () => {
+      expect(applyFilterOperator("hello", "startsWith", "he")).toBe(true);
+      expect(applyFilterOperator("hello", "endsWith", "lo")).toBe(true);
+    });
+
+    it("should handle in/notIn", () => {
+      expect(applyFilterOperator("a", "in", ["a", "b"])).toBe(true);
+      expect(applyFilterOperator("c", "in", ["a", "b"])).toBe(false);
+      expect(applyFilterOperator("a", "notIn", ["b", "c"])).toBe(true);
+    });
+
+    it("should handle isNull/isNotNull", () => {
+      expect(applyFilterOperator(null, "isNull", true)).toBe(true);
+      expect(applyFilterOperator("val", "isNotNull", true)).toBe(true);
+    });
+
+    it("should handle between", () => {
+      expect(applyFilterOperator(5, "between", [1, 10])).toBe(true);
+      expect(applyFilterOperator(11, "between", [1, 10])).toBe(false);
+    });
+  });
+
+  describe("validateFieldValue", () => {
+    it("should validate required fields", () => {
+      const field: FieldConfig = {
+        name: "test",
+        label: "Test",
+        type: "text",
+        required: true,
+      };
+      expect(validateFieldValue(null, field).valid).toBe(false);
+      expect(validateFieldValue("", field).valid).toBe(false);
+      expect(validateFieldValue("value", field).valid).toBe(true);
+    });
+
+    it("should validate email", () => {
+      const field: FieldConfig = {
+        name: "email",
+        label: "Email",
+        type: "email",
+      };
+      expect(validateFieldValue("invalid", field).valid).toBe(false);
+      expect(validateFieldValue("test@example.com", field).valid).toBe(true);
+    });
+
+    it("should validate numbers", () => {
+      const field: FieldConfig = { name: "age", label: "Age", type: "number" };
+      expect(validateFieldValue("abc", field).valid).toBe(false);
+      expect(validateFieldValue("123", field).valid).toBe(true);
+    });
+
+    it("should validate url", () => {
+      const field: FieldConfig = {
+        name: "website",
+        label: "Website",
+        type: "url",
+      };
+      expect(validateFieldValue("not-a-url", field).valid).toBe(false);
+      expect(validateFieldValue("https://google.com", field).valid).toBe(true);
+    });
+  });
+
+  describe("sortFieldsByOrder", () => {
+    it("should sort fields by order", () => {
+      const fields: FieldConfig[] = [
+        { name: "c", label: "C", type: "text", order: 3 },
+        { name: "a", label: "A", type: "text", order: 1 },
+        { name: "b", label: "B", type: "text", order: 2 },
+      ];
+      const sorted = sortFieldsByOrder(fields);
+      expect(sorted[0].name).toBe("a");
+      expect(sorted[1].name).toBe("b");
+      expect(sorted[2].name).toBe("c");
+    });
+
+    it("should place undefined order last", () => {
+      const fields: FieldConfig[] = [
+        { name: "a", label: "A", type: "text", order: 1 },
+        { name: "b", label: "B", type: "text" },
+      ];
+      const sorted = sortFieldsByOrder(fields);
+      expect(sorted[0].name).toBe("a");
+      expect(sorted[1].name).toBe("b");
+    });
+  });
+
+  describe("isCrudResponse", () => {
+    it("should identify valid crud response", () => {
+      const valid = { data: [], total: 0, page: 1, pageSize: 10 };
+      expect(isCrudResponse(valid)).toBe(true);
+    });
+
+    it("should reject invalid response", () => {
+      expect(isCrudResponse(null)).toBe(false);
+      expect(isCrudResponse({})).toBe(false);
+      expect(isCrudResponse({ data: "not-array" })).toBe(false);
+    });
+  });
+
+  describe("getDefaultValues", () => {
+    it("should return default values from config", () => {
+      const config: EntityConfig = {
+        fields: [
+          { name: "name", label: "Name", type: "text", defaultValue: "John" },
+          { name: "age", label: "Age", type: "number" },
+        ],
+        apiEndpoint: "",
+        name: "",
+        label: "",
+        pluralLabel: "",
+        idField: "",
+        displayField: "",
+      } as any;
+      const defaults = getDefaultValues(config);
+      expect(defaults).toEqual({ name: "John", age: 0 });
+    });
+  });
+
+  describe("Visibility Checks", () => {
+    it("isFieldVisibleInTable", () => {
+      expect(
+        isFieldVisibleInTable({
+          name: "a",
+          label: "A",
+          type: "text",
+          hideInTable: true,
+        }),
+      ).toBe(false);
+      expect(
+        isFieldVisibleInTable({ name: "a", label: "A", type: "text" }),
+      ).toBe(true);
+    });
+
+    it("isFieldVisibleInForm", () => {
+      expect(
+        isFieldVisibleInForm({
+          name: "a",
+          label: "A",
+          type: "text",
+          hideInForm: true,
+        }),
+      ).toBe(false);
+      expect(
+        isFieldVisibleInForm({
+          name: "a",
+          label: "A",
+          type: "text",
+          isDisplayOnly: true,
+        }),
+      ).toBe(false);
+      expect(
+        isFieldVisibleInForm({ name: "a", label: "A", type: "text" }),
+      ).toBe(true);
+    });
+  });
+
+  describe("filterDisplayOnlyFields", () => {
+    it("should remove display-only fields", () => {
+      const config: EntityConfig = {
+        fields: [
+          { name: "a", label: "A", type: "text" },
+          { name: "b", label: "B", type: "text", isDisplayOnly: true },
+        ],
+        apiEndpoint: "",
+        name: "",
+        label: "",
+        pluralLabel: "",
+        idField: "",
+        displayField: "",
+      } as any;
+      const data = { a: 1, b: 2 };
+      const filtered = filterDisplayOnlyFields(data, config);
+      expect(filtered).toEqual({ a: 1 });
+    });
+  });
+
+  describe("formatFieldValue", () => {
+    it("should format values correctly", () => {
+      expect(
+        formatFieldValue(null, { name: "a", label: "", type: "text" }),
+      ).toBe("");
+      expect(
+        formatFieldValue(1000, { name: "a", label: "", type: "number" }),
+      ).toBe("1,000.00");
+      expect(
+        formatFieldValue(1000, { name: "a", label: "", type: "integer" }),
+      ).toBe("1,000");
+      expect(
+        formatFieldValue(true, { name: "a", label: "", type: "boolean" }),
+      ).toBe("Yes");
+      expect(
+        formatFieldValue(false, { name: "a", label: "", type: "boolean" }),
+      ).toBe("No");
+      // Date formatting depends on locale, but roughly:
+      const date = new Date("2023-01-01T00:00:00.000Z");
+      expect(
+        formatFieldValue(date.toISOString(), {
+          name: "a",
+          label: "",
+          type: "date",
+        }),
+      ).not.toBe("");
+
+      // Custom render
+      const field: FieldConfig = {
+        name: "a",
+        label: "",
+        type: "text",
+        renderCell: () => "Custom",
+      };
+      expect(formatFieldValue("val", field)).toBe("val");
+    });
+  });
+});

package/src/crud/lib/crud-utils.ts

@@ -0,0 +1,299 @@
+import type {
+  ActiveFilter,
+  CrudQueryParams,
+  EntityConfig,
+  FieldConfig,
+  FilterOperator,
+} from "../../types";
+
+/**
+ * Build query string from CrudQueryParams
+ */
+export function buildQueryString(params: CrudQueryParams): string {
+  const searchParams = new URLSearchParams();
+
+  searchParams.append("page", String(params.page));
+  searchParams.append("pageSize", String(params.pageSize));
+
+  // Add search parameter if it exists and is not empty
+  if (params.search && params.search.trim().length > 0) {
+    searchParams.append("search", params.search.trim());
+    // Also add 'q' parameter for backward compatibility with some APIs
+    searchParams.append("q", params.search.trim());
+  }
+
+  if (params.sort) {
+    searchParams.append("sortField", params.sort.field);
+    searchParams.append("sortDirection", params.sort.direction);
+  }
+
+  if (params.filters && params.filters.length > 0) {
+    searchParams.append("filters", JSON.stringify(params.filters));
+  }
+
+  return searchParams.toString();
+}
+
+/**
+ * Parse query string to CrudQueryParams
+ */
+export function parseQueryString(
+  searchParams: URLSearchParams,
+): CrudQueryParams {
+  const page = parseInt(searchParams.get("page") || "1", 10);
+  const pageSize = parseInt(searchParams.get("pageSize") || "10", 10);
+  const search = searchParams.get("search") || undefined;
+
+  let sort: CrudQueryParams["sort"] | undefined;
+  const sortField = searchParams.get("sortField");
+  const sortDirection = searchParams.get("sortDirection") as
+    | "asc"
+    | "desc"
+    | null;
+  if (sortField && sortDirection) {
+    sort = { field: sortField, direction: sortDirection };
+  }
+
+  let filters: ActiveFilter[] | undefined;
+  const filtersParam = searchParams.get("filters");
+  if (filtersParam) {
+    try {
+      filters = JSON.parse(filtersParam) as ActiveFilter[];
+    } catch {
+      filters = undefined;
+    }
+  }
+
+  return {
+    page,
+    pageSize,
+    ...(search && { search }),
+    ...(sort && { sort }),
+    ...(filters && filters.length > 0 && { filters }),
+  };
+}
+
+/**
+ * Apply filter operator to value
+ */
+export function applyFilterOperator(
+  value: unknown,
+  operator: FilterOperator,
+  filterValue: unknown,
+): boolean {
+  switch (operator) {
+    case "eq":
+      return value === filterValue;
+    case "ne":
+      return value !== filterValue;
+    case "gt":
+      return Number(value) > Number(filterValue);
+    case "gte":
+      return Number(value) >= Number(filterValue);
+    case "lt":
+      return Number(value) < Number(filterValue);
+    case "lte":
+      return Number(value) <= Number(filterValue);
+    case "contains":
+      return String(value)
+        .toLowerCase()
+        .includes(String(filterValue).toLowerCase());
+    case "startsWith":
+      return String(value)
+        .toLowerCase()
+        .startsWith(String(filterValue).toLowerCase());
+    case "endsWith":
+      return String(value)
+        .toLowerCase()
+        .endsWith(String(filterValue).toLowerCase());
+    case "in":
+      return Array.isArray(filterValue) && filterValue.includes(value);
+    case "notIn":
+      return Array.isArray(filterValue) && !filterValue.includes(value);
+    case "between":
+      if (Array.isArray(filterValue) && filterValue.length === 2) {
+        const [min, max] = filterValue;
+        return Number(value) >= Number(min) && Number(value) <= Number(max);
+      }
+      return false;
+    case "isNull":
+      return value === null || value === undefined;
+    case "isNotNull":
+      return value !== null && value !== undefined;
+    default:
+      return false;
+  }
+}
+
+/**
+ * Get default value for a field
+ */
+export function getFieldDefaultValue(field: FieldConfig): unknown {
+  if (field.defaultValue !== undefined) {
+    return field.defaultValue;
+  }
+
+  switch (field.type) {
+    case "number":
+    case "integer":
+      return 0;
+    case "boolean":
+      return false;
+    case "select":
+    case "multiselect":
+      return field.type === "multiselect" ? [] : "";
+    case "date":
+    case "datetime":
+    case "time":
+      return null;
+    case "textarea":
+      return "";
+    default:
+      return "";
+  }
+}
+
+/**
+ * Get default values for all fields in config
+ */
+export function getDefaultValues(
+  config: EntityConfig,
+): Record<string, unknown> {
+  const defaults: Record<string, unknown> = {};
+
+  config.fields.forEach((field) => {
+    if (!field.hideInForm) {
+      defaults[field.name] = getFieldDefaultValue(field);
+    }
+  });
+
+  return defaults;
+}
+
+/**
+ * Check if a field is visible in table
+ */
+export function isFieldVisibleInTable(field: FieldConfig): boolean {
+  return !field.hideInTable;
+}
+
+/**
+ * Check if a field is visible in form
+ */
+export function isFieldVisibleInForm(field: FieldConfig): boolean {
+  return !field.hideInForm && !field.isDisplayOnly;
+}
+
+/**
+ * Filter out display-only (DTO) fields from form data before submitting to API
+ * Display-only fields are computed/transformed fields, not actual entity fields
+ */
+export function filterDisplayOnlyFields(
+  data: Record<string, unknown>,
+  config: EntityConfig,
+): Record<string, unknown> {
+  const displayOnlyFieldNames = new Set(
+    config.fields
+      .filter((field) => field.isDisplayOnly)
+      .map((field) => field.name),
+  );
+
+  const filtered: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(data)) {
+    if (!displayOnlyFieldNames.has(key)) {
+      filtered[key] = value;
+    }
+  }
+
+  return filtered;
+}
+
+/**
+ * Sort fields by order property
+ * Fields without order will be placed after fields with order
+ * If multiple fields have the same order, maintain original array order
+ */
+export function sortFieldsByOrder(fields: FieldConfig[]): FieldConfig[] {
+  return [...fields].sort((a, b) => {
+    const orderA = a.order ?? 999;
+    const orderB = b.order ?? 999;
+
+    return orderA - orderB;
+  });
+}
+
+/**
+ * Validate field value
+ */
+export function validateFieldValue(
+  value: unknown,
+  field: FieldConfig,
+): { valid: boolean; error?: string } {
+  // Required check
+  if (
+    field.required &&
+    (value === null || value === undefined || value === "")
+  ) {
+    return {
+      valid: false,
+      error: `${field.label} is required`,
+    };
+  }
+
+  // Type-specific validation
+  switch (field.type) {
+    case "email":
+      if (value && typeof value === "string") {
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        if (!emailRegex.test(value)) {
+          return {
+            valid: false,
+            error: `${field.label} must be a valid email`,
+          };
+        }
+      }
+      break;
+    case "url":
+      if (value && typeof value === "string") {
+        try {
+          new URL(value);
+        } catch {
+          return {
+            valid: false,
+            error: `${field.label} must be a valid URL`,
+          };
+        }
+      }
+      break;
+    case "number":
+    case "integer":
+      if (value !== null && value !== undefined && value !== "") {
+        if (isNaN(Number(value))) {
+          return {
+            valid: false,
+            error: `${field.label} must be a number`,
+          };
+        }
+      }
+      break;
+  }
+
+  return { valid: true };
+}
+
+/**
+ * Type guard: Check if value is a valid CrudResponse
+ */
+export function isCrudResponse<T = unknown>(
+  value: unknown,
+): value is import("../../types").CrudResponse<T> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    "data" in value &&
+    "total" in value &&
+    "page" in value &&
+    "pageSize" in value &&
+    Array.isArray((value as { data: unknown }).data)
+  );
+}