ding-react-admin 1.0.0

package/src/data/dataUtils.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it, vi } from "vitest";
+import { pickBySources } from "../crud/utils/pickBySources";
+import { createRestResourceHandlers } from "./createRestResourceHandlers";
+import {
+  toDjangoRestOrdering,
+  toJsonApiSort,
+  toODataOrderBy,
+} from "./sortHelpers";
+
+describe("pickBySources", () => {
+  it("picks flat fields", () => {
+    const values = {
+      username: "jane",
+      email: "jane@example.com",
+      tenants: [{ id: 1 }],
+    };
+    expect(pickBySources(values, ["username", "email"])).toEqual({
+      username: "jane",
+      email: "jane@example.com",
+    });
+  });
+
+  it("picks nested fields", () => {
+    const values = {
+      invoiceLine: { product: "SKU-1", quantity: 2 },
+      extra: "ignored",
+    };
+    expect(pickBySources(values, ["invoiceLine.product", "invoiceLine.quantity"])).toEqual({
+      invoiceLine: { product: "SKU-1", quantity: 2 },
+    });
+  });
+
+  it("returns all values when no sources registered", () => {
+    const values = { a: 1, b: 2 };
+    expect(pickBySources(values, [])).toEqual(values);
+  });
+});
+
+describe("sort helpers", () => {
+  it("toDjangoRestOrdering", () => {
+    expect(toDjangoRestOrdering({ field: "username", order: "ASC" })).toBe(
+      "username",
+    );
+    expect(toDjangoRestOrdering({ field: "username", order: "DESC" })).toBe(
+      "-username",
+    );
+    expect(
+      toDjangoRestOrdering([
+        { field: "username", order: "ASC" },
+        { field: "date_joined", order: "DESC" },
+      ]),
+    ).toBe("username,-date_joined");
+  });
+
+  it("toODataOrderBy", () => {
+    expect(toODataOrderBy({ field: "username", order: "DESC" })).toBe(
+      "username desc",
+    );
+  });
+
+  it("toJsonApiSort", () => {
+    expect(toJsonApiSort({ field: "username", order: "DESC" })).toBe(
+      "-username",
+    );
+  });
+});
+
+describe("createRestResourceHandlers", () => {
+  it("passes form payload through on create/update", async () => {
+    const create = vi.fn(async (data) => ({ id: "1", ...data }));
+    const update = vi.fn(async (_id, data) => ({ id: "1", ...data }));
+
+    const handlers = createRestResourceHandlers({
+      list: async () => ({ data: [], total: 0 }),
+      retrieve: async () => ({ id: "1" }),
+      create,
+      update,
+      destroy: async () => {},
+    });
+
+    await handlers.create({ username: "jane" });
+    expect(create).toHaveBeenCalledWith({ username: "jane" });
+
+    await handlers.update({ id: "1", data: { email: "a@b.c" } });
+    expect(update).toHaveBeenCalledWith("1", { email: "a@b.c" });
+  });
+
+  it("applies transformCreate and transformUpdate when provided", async () => {
+    const create = vi.fn(async (data) => data);
+    const update = vi.fn(async (_id, data) => data);
+
+    const handlers = createRestResourceHandlers({
+      list: async () => ({ data: [], total: 0 }),
+      retrieve: async () => ({}),
+      create,
+      update,
+      destroy: async () => {},
+      transformCreate: (data) => ({ user: data }),
+      transformUpdate: (data) => ({ patch: data }),
+    });
+
+    await handlers.create({ username: "jane" });
+    expect(create).toHaveBeenCalledWith({ user: { username: "jane" } });
+
+    await handlers.update({ id: "1", data: { username: "bob" } });
+    expect(update).toHaveBeenCalledWith("1", { patch: { username: "bob" } });
+  });
+});

package/src/data/inMemoryList.ts

@@ -0,0 +1,97 @@
+import type { GetListParams, Identifier, SortSpec } from "./dataProviderTypes";
+
+export function rowIdMatches(
+  rowId: string | number,
+  id: Identifier,
+): boolean {
+  return rowId === id || String(rowId) === String(id);
+}
+
+export function getById<T extends { id: string | number }>(
+  rows: T[],
+  id: Identifier,
+): T {
+  const row = rows.find((r) => rowIdMatches(r.id, id));
+  if (!row) throw new Error("Not found");
+  return row;
+}
+
+function sortRows<T extends Record<string, unknown>>(
+  rows: T[],
+  specs: SortSpec[],
+): T[] {
+  if (specs.length === 0) return rows;
+  const mul = (order: "ASC" | "DESC") => (order === "DESC" ? -1 : 1);
+  return [...rows].sort((a, b) => {
+    for (const { field, order } of specs) {
+      const av = a[field];
+      const bv = b[field];
+      if (av === bv) continue;
+      if (av == null) return -1 * mul(order);
+      if (bv == null) return 1 * mul(order);
+      if (typeof av === "number" && typeof bv === "number") {
+        return av < bv ? -mul(order) : mul(order);
+      }
+      const cmp = String(av).localeCompare(String(bv));
+      if (cmp !== 0) return cmp * mul(order);
+    }
+    return 0;
+  });
+}
+
+function matchFilterValue(rowVal: unknown, filterVal: unknown): boolean {
+  if (filterVal === undefined || filterVal === null || filterVal === "") {
+    return true;
+  }
+  if (Array.isArray(filterVal)) {
+    if (filterVal.length === 0) return true;
+    if (Array.isArray(rowVal)) {
+      return filterVal.some((fv) => rowVal.includes(fv));
+    }
+    return filterVal.includes(rowVal);
+  }
+  if (Array.isArray(rowVal)) {
+    return rowVal.includes(filterVal);
+  }
+  if (typeof filterVal === "string" && typeof rowVal === "string") {
+    return rowVal.toLowerCase().includes(filterVal.toLowerCase());
+  }
+  return rowVal === filterVal;
+}
+
+export function filterRows<T extends Record<string, unknown>>(
+  rows: T[],
+  filter?: Record<string, unknown>,
+): T[] {
+  if (!filter) return rows;
+  return rows.filter((row) =>
+    Object.entries(filter).every(([k, v]) => matchFilterValue(row[k], v)),
+  );
+}
+
+function paginate<T>(rows: T[], page: number, perPage: number) {
+  const start = (page - 1) * perPage;
+  return {
+    data: rows.slice(start, start + perPage),
+    total: rows.length,
+  };
+}
+
+/** Apply CRUD list filters, sort, and pagination to an in-memory row array. */
+export function applyInMemoryListParams<T extends Record<string, unknown>>(
+  rows: T[],
+  params: GetListParams,
+): { data: T[]; total: number } {
+  const { pagination, sort, filter } = params;
+  let out = filterRows(rows, filter);
+  if (sort) {
+    const specs = Array.isArray(sort) ? sort : [sort];
+    if (specs.length > 0 && specs[0]?.field) {
+      out = sortRows(out, specs);
+    }
+  }
+  if (pagination) {
+    return paginate(out, pagination.page, pagination.perPage);
+  }
+  return { data: out, total: out.length };
+}

package/src/data/parseFormErrorHelpers.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from "vitest";
+import {
+  parseDjangoDRFFormErrors,
+  parseDotNetFormErrors,
+  parseNodeFormErrors,
+} from "./parseFormErrorHelpers";
+
+const mainCtx = { resource: "users", mutation: "create" as const };
+const inlineCtx = {
+  resource: "invoice-lines",
+  mutation: "create" as const,
+  inlineArrayName: "__inline_invoice_lines",
+  rowIndex: 1,
+};
+
+describe("parseDjangoDRFFormErrors", () => {
+  it("maps field and non_field_errors", () => {
+    const parsed = parseDjangoDRFFormErrors(
+      {
+        body: {
+          email: ["Enter a valid email."],
+          non_field_errors: ["Cannot save"],
+        },
+      },
+      mainCtx,
+    );
+    expect(parsed).toEqual({
+      fields: { email: "Enter a valid email." },
+      global: ["Cannot save"],
+    });
+  });
+
+  it("prefixes inline row fields", () => {
+    const parsed = parseDjangoDRFFormErrors(
+      { body: { quantity: ["Must be positive"] } },
+      inlineCtx,
+    );
+    expect(parsed?.fields).toEqual({
+      "__inline_invoice_lines.1.quantity": "Must be positive",
+    });
+  });
+});
+
+describe("parseDotNetFormErrors", () => {
+  it("maps errors object with camelCase", () => {
+    const parsed = parseDotNetFormErrors(
+      {
+        body: {
+          errors: { Email: ["The Email field is required."] },
+        },
+      },
+      mainCtx,
+    );
+    expect(parsed?.fields).toEqual({
+      email: "The Email field is required.",
+    });
+  });
+});
+
+describe("parseNodeFormErrors", () => {
+  it("maps express-validator array", () => {
+    const parsed = parseNodeFormErrors(
+      {
+        body: {
+          errors: [{ path: "email", msg: "Invalid email" }],
+        },
+      },
+      mainCtx,
+    );
+    expect(parsed?.fields).toEqual({ email: "Invalid email" });
+  });
+
+  it("maps Joi details", () => {
+    const parsed = parseNodeFormErrors(
+      {
+        body: {
+          details: [{ message: "Required", path: ["email"] }],
+        },
+      },
+      mainCtx,
+    );
+    expect(parsed?.fields).toEqual({ email: "Required" });
+  });
+});

package/src/data/parseFormErrorHelpers.ts

@@ -0,0 +1,224 @@
+import type {
+  FormValidationErrors,
+  ParseFormErrorContext,
+} from "./dataProviderTypes";
+
+export function asStringMessages(value: unknown): string[] {
+  if (typeof value === "string") return [value];
+  if (Array.isArray(value)) {
+    const strings = value.filter((x) => typeof x === "string") as string[];
+    if (strings.length) return strings;
+  }
+  return [];
+}
+
+function toFieldValue(msgs: string[]): string | string[] {
+  return msgs.length === 1 ? msgs[0] : msgs;
+}
+
+/** Read JSON from `throw { body }` or axios-style `{ response: { data } }`. */
+export function getErrorBody(error: unknown): Record<string, unknown> | null {
+  if (!error || typeof error !== "object") return null;
+  const e = error as Record<string, unknown>;
+  if (e.body && typeof e.body === "object" && !Array.isArray(e.body)) {
+    return e.body as Record<string, unknown>;
+  }
+  const response = e.response;
+  if (response && typeof response === "object" && !Array.isArray(response)) {
+    const data = (response as Record<string, unknown>).data;
+    if (data && typeof data === "object" && !Array.isArray(data)) {
+      return data as Record<string, unknown>;
+    }
+  }
+  return null;
+}
+
+export function applyInlineFieldPaths(
+  fields: Record<string, string | string[]>,
+  ctx: ParseFormErrorContext,
+): Record<string, string | string[]> {
+  if (ctx.inlineArrayName == null || ctx.rowIndex == null) return fields;
+  const rowPrefix = `${ctx.inlineArrayName}.${ctx.rowIndex}.`;
+  const out: Record<string, string | string[]> = {};
+  for (const [source, message] of Object.entries(fields)) {
+    out[rowPrefix + source] = message;
+  }
+  return out;
+}
+
+export function finalizeFormErrors(
+  fields: Record<string, string | string[]>,
+  global: string[],
+  ctx: ParseFormErrorContext,
+): FormValidationErrors {
+  const fieldErrors = applyInlineFieldPaths(fields, ctx);
+  return {
+    fields: Object.keys(fieldErrors).length ? fieldErrors : undefined,
+    global: global.length ? global : undefined,
+  };
+}
+
+const DRF_GLOBAL_KEYS = new Set(["non_field_errors", "detail"]);
+
+/**
+ * Django REST framework validation body:
+ * `{ "email": ["Invalid"], "non_field_errors": ["…"] }`
+ */
+export function parseDjangoDRFFormErrors(
+  error: unknown,
+  ctx: ParseFormErrorContext,
+): FormValidationErrors | null {
+  const body = getErrorBody(error);
+  if (!body) return null;
+
+  const fields: Record<string, string | string[]> = {};
+  const global: string[] = [];
+
+  for (const [key, value] of Object.entries(body)) {
+    if (DRF_GLOBAL_KEYS.has(key)) {
+      global.push(...asStringMessages(value));
+      continue;
+    }
+    const msgs = asStringMessages(value);
+    if (msgs.length) fields[key] = toFieldValue(msgs);
+  }
+
+  if (!Object.keys(fields).length && !global.length) return null;
+  return finalizeFormErrors(fields, global, ctx);
+}
+
+export type DotNetFormErrorOptions = {
+  /** Map API property names to form `source` paths. */
+  fieldMap?: Record<string, string>;
+  /** `Email` → `email`. Default true. */
+  camelCase?: boolean;
+  /** Include `title` / `message` in global toasts. Default false (often generic). */
+  includeSummary?: boolean;
+};
+
+/**
+ * ASP.NET Core `ValidationProblemDetails`:
+ * `{ "errors": { "Email": ["The Email field is required."] } }`
+ */
+export function parseDotNetFormErrors(
+  error: unknown,
+  ctx: ParseFormErrorContext,
+  options?: DotNetFormErrorOptions,
+): FormValidationErrors | null {
+  const body = getErrorBody(error);
+  if (!body) return null;
+
+  const camelCase = options?.camelCase ?? true;
+  const fieldMap = options?.fieldMap;
+  const fields: Record<string, string | string[]> = {};
+  const global: string[] = [];
+
+  if (options?.includeSummary) {
+    global.push(...asStringMessages(body.title));
+    global.push(...asStringMessages(body.message));
+  }
+
+  const errors = body.errors;
+  if (errors && typeof errors === "object" && !Array.isArray(errors)) {
+    for (const [key, value] of Object.entries(errors as Record<string, unknown>)) {
+      const mappedKey =
+        fieldMap?.[key] ?? (camelCase ? camelCaseField(key) : key);
+      const msgs = asStringMessages(value);
+      if (msgs.length) fields[mappedKey] = toFieldValue(msgs);
+    }
+  }
+
+  if (!Object.keys(fields).length && !global.length) return null;
+  return finalizeFormErrors(fields, global, ctx);
+}
+
+export type NodeFormErrorOptions = {
+  fieldMap?: Record<string, string>;
+};
+
+/**
+ * Common Node / Express shapes:
+ * - `{ errors: { email: ["Invalid"] } }`
+ * - `{ errors: [{ path: "email", msg: "Invalid" }] }` (express-validator)
+ * - `{ details: [{ message: "…", path: ["email"] }] }` (Joi)
+ */
+export function parseNodeFormErrors(
+  error: unknown,
+  ctx: ParseFormErrorContext,
+  options?: NodeFormErrorOptions,
+): FormValidationErrors | null {
+  const body = getErrorBody(error);
+  if (!body) return null;
+
+  const fields: Record<string, string | string[]> = {};
+  const global: string[] = [];
+  const fieldMap = options?.fieldMap;
+
+  const errList = body.errors;
+  if (Array.isArray(errList)) {
+    for (const item of errList) {
+      if (!item || typeof item !== "object") continue;
+      const row = item as Record<string, unknown>;
+      const path =
+        (typeof row.path === "string" && row.path) ||
+        (typeof row.param === "string" && row.param) ||
+        (typeof row.field === "string" && row.field);
+      const msg =
+        asStringMessages(row.msg)[0] ?? asStringMessages(row.message)[0];
+      if (!msg) continue;
+      if (path) {
+        const key = fieldMap?.[path] ?? path;
+        mergeFieldMessage(fields, key, msg);
+      } else {
+        global.push(msg);
+      }
+    }
+  } else if (errList && typeof errList === "object") {
+    for (const [key, value] of Object.entries(errList as Record<string, unknown>)) {
+      const mappedKey = fieldMap?.[key] ?? key;
+      const msgs = asStringMessages(value);
+      if (msgs.length) fields[mappedKey] = toFieldValue(msgs);
+    }
+  }
+
+  const details = body.details;
+  if (Array.isArray(details)) {
+    for (const item of details) {
+      if (!item || typeof item !== "object") continue;
+      const row = item as Record<string, unknown>;
+      const pathParts = Array.isArray(row.path) ? row.path : [];
+      const path = pathParts.map((p) => String(p)).join(".");
+      const msg = asStringMessages(row.message)[0];
+      if (!msg) continue;
+      if (path) {
+        const key = fieldMap?.[path] ?? path;
+        fields[key] = msg;
+      } else {
+        global.push(msg);
+      }
+    }
+  }
+
+  global.push(...asStringMessages(body.error));
+
+  if (!Object.keys(fields).length && !global.length) return null;
+  return finalizeFormErrors(fields, global, ctx);
+}
+
+function mergeFieldMessage(
+  fields: Record<string, string | string[]>,
+  key: string,
+  msg: string,
+) {
+  const existing = fields[key];
+  if (!existing) {
+    fields[key] = msg;
+    return;
+  }
+  fields[key] = Array.isArray(existing) ? [...existing, msg] : [existing, msg];
+}
+
+function camelCaseField(key: string): string {
+  if (!key) return key;
+  return key.charAt(0).toLowerCase() + key.slice(1);
+}

package/src/data/resourceHandlers.ts

@@ -0,0 +1,124 @@
+import type { PermissionsChecker } from "../context/PermissionsProvider";
+import type { ResourcePermissions } from "../permissions/resourcePermissions";
+import { checkResourcePermission } from "../permissions/resourcePermissions";
+import type {
+  CreateResult,
+  DataProvider,
+  DeleteResult,
+  GetListParams,
+  GetListResult,
+  GetOneResult,
+  Identifier,
+  ParseFormError,
+  UpdateParams,
+  UpdateResult,
+} from "./dataProviderTypes";
+
+export type ResourceAction = "list" | "read" | "add" | "change" | "delete";
+
+/** @deprecated Use per-resource `permissions` with `can` in combineResourceHandlers options. */
+export type ResourceGuard = (
+  resource: string,
+  action: ResourceAction,
+) => void;
+
+/** CRUD handlers for a single resource (no resource name on each method). */
+export type ResourceHandlers<
+  RecordType extends Record<string, unknown> = Record<string, unknown>,
+> = {
+  getList: (params: GetListParams) => Promise<GetListResult<RecordType>>;
+  getOne: (id: Identifier) => Promise<GetOneResult<RecordType>>;
+  create: (data: Partial<RecordType>) => Promise<CreateResult<RecordType>>;
+  update: (
+    params: UpdateParams<RecordType>,
+  ) => Promise<UpdateResult<RecordType>>;
+  delete: (id: Identifier) => Promise<DeleteResult<RecordType>>;
+};
+
+export type ResourceHandlerEntry =
+  | ResourceHandlers
+  | {
+      handlers: ResourceHandlers;
+      permissions?: ResourcePermissions;
+    };
+
+export type ResourceHandlerMap = Record<string, ResourceHandlerEntry>;
+
+export type CombineResourceHandlersOptions = {
+  /** Permission checker from PermissionsProvider wiring. */
+  can?: PermissionsChecker;
+  /** @deprecated Use per-resource `permissions` entries instead. */
+  guard?: ResourceGuard;
+  /** Wired to `ResourceForm` / `ResourceFormModal` save error handling. */
+  parseFormError?: ParseFormError;
+};
+
+function resolveEntry(entry: ResourceHandlerEntry): {
+  handlers: ResourceHandlers;
+  permissions?: ResourcePermissions;
+} {
+  if ("handlers" in entry) return entry;
+  return { handlers: entry };
+}
+
+function assertPermission(
+  can: PermissionsChecker | undefined,
+  permissions: ResourcePermissions | undefined,
+  slot: keyof ResourcePermissions,
+) {
+  if (!can || !permissions) return;
+  if (!checkResourcePermission(can, permissions, slot)) {
+    throw new Error("Forbidden");
+  }
+}
+
+/**
+ * Compose per-entity handlers into a react-admin-style `DataProvider`.
+ * Map an OpenAPI / tRPC / REST client in each entity module, then register here.
+ */
+export function combineResourceHandlers(
+  handlers: ResourceHandlerMap,
+  options?: CombineResourceHandlersOptions,
+): DataProvider {
+  const { can, guard, parseFormError } = options ?? {};
+
+  const resolve = (resource: string) => {
+    const entry = handlers[resource];
+    if (!entry) throw new Error(`Unknown resource: ${resource}`);
+    return resolveEntry(entry);
+  };
+
+  return {
+    async getList(resource, params) {
+      const { handlers: h, permissions } = resolve(resource);
+      guard?.(resource, "list");
+      assertPermission(can, permissions, "list");
+      return h.getList(params);
+    },
+    async getOne(resource, id) {
+      const { handlers: h, permissions } = resolve(resource);
+      guard?.(resource, "read");
+      assertPermission(can, permissions, "read");
+      return h.getOne(id);
+    },
+    async create(resource, data) {
+      const { handlers: h, permissions } = resolve(resource);
+      guard?.(resource, "add");
+      assertPermission(can, permissions, "add");
+      return h.create(data);
+    },
+    async update(resource, params) {
+      const { handlers: h, permissions } = resolve(resource);
+      guard?.(resource, "change");
+      assertPermission(can, permissions, "change");
+      return h.update(params);
+    },
+    async delete(resource, id) {
+      const { handlers: h, permissions } = resolve(resource);
+      guard?.(resource, "delete");
+      assertPermission(can, permissions, "delete");
+      return h.delete(id);
+    },
+    parseFormError,
+  };
+}

package/src/data/sortHelpers.ts

@@ -0,0 +1,48 @@
+import type { SortSpec } from "./dataProviderTypes";
+
+function normalizeSort(sort?: SortSpec | SortSpec[]): SortSpec[] {
+  if (!sort) return [];
+  return Array.isArray(sort) ? sort : [sort];
+}
+
+/**
+ * Django REST Framework `ordering` query param.
+ * ASC → `username`; DESC → `-username`; multi → `username,-date_joined`.
+ */
+export function toDjangoRestOrdering(
+  sort?: SortSpec | SortSpec[],
+): string | undefined {
+  const specs = normalizeSort(sort);
+  if (specs.length === 0) return undefined;
+  return specs
+    .map((s) => (s.order === "DESC" ? `-${s.field}` : s.field))
+    .join(",");
+}
+
+/**
+ * OData `$orderby` query param.
+ * ASC → `username asc`; DESC → `username desc`.
+ */
+export function toODataOrderBy(
+  sort?: SortSpec | SortSpec[],
+): string | undefined {
+  const specs = normalizeSort(sort);
+  if (specs.length === 0) return undefined;
+  return specs
+    .map((s) => `${s.field} ${s.order === "DESC" ? "desc" : "asc"}`)
+    .join(",");
+}
+
+/**
+ * Common JSON:API `sort` query param.
+ * ASC → `username`; DESC → `-username`.
+ */
+export function toJsonApiSort(
+  sort?: SortSpec | SortSpec[],
+): string | undefined {
+  const specs = normalizeSort(sort);
+  if (specs.length === 0) return undefined;
+  return specs
+    .map((s) => (s.order === "DESC" ? `-${s.field}` : s.field))
+    .join(",");
+}