@jskit-ai/crud 0.1.4

package/test/crudModuleConfig.test.js

@@ -0,0 +1,225 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  resolveCrudConfig,
+  resolveCrudSurfacePolicy,
+  resolveCrudConfigFromModules,
+  resolveCrudConfigsFromModules
+} from "../src/shared/crud/crudModuleConfig.js";
+
+test("resolveCrudConfig throws when namespace is missing", () => {
+  assert.throws(
+    () => resolveCrudConfig({}),
+    /requires a non-empty namespace/
+  );
+});
+
+test("resolveCrudConfig normalizes namespaced public settings", () => {
+  const config = resolveCrudConfig({
+    namespace: "CRM Team",
+    ownershipFilter: "public"
+  });
+
+  assert.equal(config.namespace, "crm-team");
+  assert.equal(config.ownershipFilter, "public");
+  assert.equal(config.workspaceScoped, false);
+  assert.equal(config.namespacePath, "/crm-team");
+  assert.equal(config.relativePath, "/crm-team");
+  assert.equal(config.apiBasePath, "/api/crm-team");
+  assert.equal(config.tableName, "crud_crm_team");
+  assert.equal(config.actionIdPrefix, "crud.crm_team");
+  assert.equal(config.contributorId, "crud.crm_team");
+  assert.equal(config.domain, "crud");
+});
+
+test("resolveCrudConfigsFromModules returns only crud module entries", () => {
+  const configs = resolveCrudConfigsFromModules({
+    "crud.customers": {
+      module: "crud",
+      namespace: "customers",
+      ownershipFilter: "workspace"
+    },
+    "crud.dragons": {
+      module: "crud",
+      namespace: "dragons",
+      ownershipFilter: "public"
+    },
+    "users.default": {
+      module: "users",
+      namespace: "ignored"
+    }
+  });
+
+  assert.deepEqual(configs.map((entry) => entry.namespace), ["customers", "dragons"]);
+  assert.deepEqual(configs.map((entry) => entry.ownershipFilter), ["workspace", "public"]);
+});
+
+test("resolveCrudConfigFromModules resolves explicit namespace", () => {
+  const config = resolveCrudConfigFromModules(
+    {
+      "crud.customers": {
+        module: "crud",
+        namespace: "customers",
+        ownershipFilter: "workspace"
+      },
+      "crud.dragons": {
+        module: "crud",
+        namespace: "dragons",
+        ownershipFilter: "workspace_user"
+      }
+    },
+    {
+      namespace: "dragons"
+    }
+  );
+
+  assert.ok(config);
+  assert.equal(config.namespace, "dragons");
+  assert.equal(config.ownershipFilter, "workspace_user");
+});
+
+test("resolveCrudConfigFromModules returns null without namespace when multiple crud entries exist", () => {
+  const config = resolveCrudConfigFromModules({
+    "crud.customers": {
+      module: "crud",
+      namespace: "customers",
+      ownershipFilter: "workspace"
+    },
+    "crud.dragons": {
+      module: "crud",
+      namespace: "dragons",
+      ownershipFilter: "workspace"
+    }
+  });
+
+  assert.equal(config, null);
+});
+
+test("resolveCrudConfigsFromModules rejects duplicate normalized namespaces", () => {
+  assert.throws(
+    () =>
+      resolveCrudConfigsFromModules({
+        "crud.customers": {
+          module: "crud",
+          namespace: "customers",
+          ownershipFilter: "workspace"
+        },
+        "crud.customers-copy": {
+          module: "crud",
+          namespace: "Customers",
+          ownershipFilter: "public"
+        }
+      }),
+    /Duplicate CRUD namespace/
+  );
+});
+
+test("resolveCrudConfigsFromModules rejects module entries without namespace", () => {
+  assert.throws(
+    () =>
+      resolveCrudConfigsFromModules({
+        "crud.invalid": {
+          module: "crud",
+          namespace: "",
+          ownershipFilter: "workspace"
+        }
+      }),
+    /requires a non-empty namespace/
+  );
+});
+
+test("resolveCrudSurfacePolicy resolves auto ownership filter from workspace surface metadata", () => {
+  const policy = resolveCrudSurfacePolicy(
+    {
+      surface: "admin",
+      ownershipFilter: "auto",
+      relativePath: "/crm/customers"
+    },
+    {
+      surfaceDefinitions: {
+        admin: { requiresWorkspace: true, requiresAuth: true, enabled: true }
+      },
+      defaultSurfaceId: "admin"
+    }
+  );
+
+  assert.equal(policy.surfaceId, "admin");
+  assert.equal(policy.ownershipFilter, "workspace");
+  assert.equal(policy.workspaceScoped, true);
+  assert.equal(policy.relativePath, "/crm/customers");
+});
+
+test("resolveCrudSurfacePolicy resolves auto ownership filter from auth-only surface metadata", () => {
+  const policy = resolveCrudSurfacePolicy(
+    {
+      surface: "console",
+      ownershipFilter: "auto",
+      relativePath: "/crm/customers"
+    },
+    {
+      surfaceDefinitions: {
+        console: { requiresWorkspace: false, requiresAuth: true, enabled: true }
+      },
+      defaultSurfaceId: "console"
+    }
+  );
+
+  assert.equal(policy.surfaceId, "console");
+  assert.equal(policy.ownershipFilter, "user");
+  assert.equal(policy.workspaceScoped, false);
+});
+
+test("resolveCrudSurfacePolicy rejects explicit workspace ownership filter on non-workspace surfaces", () => {
+  assert.throws(
+    () =>
+      resolveCrudSurfacePolicy(
+        {
+          surface: "console",
+          ownershipFilter: "workspace",
+          relativePath: "/crm/customers"
+        },
+        {
+          surfaceDefinitions: {
+            console: { requiresWorkspace: false, requiresAuth: true, enabled: true }
+          }
+        }
+      ),
+    /requires a workspace-enabled surface/
+  );
+});
+
+test("resolveCrudSurfacePolicy rejects unknown or disabled surfaces", () => {
+  assert.throws(
+    () =>
+      resolveCrudSurfacePolicy(
+        {
+          surface: "missing",
+          ownershipFilter: "auto",
+          relativePath: "/crm/customers"
+        },
+        {
+          surfaceDefinitions: {
+            console: { requiresWorkspace: false, requiresAuth: true, enabled: true }
+          }
+        }
+      ),
+    /cannot resolve surface "missing"/
+  );
+
+  assert.throws(
+    () =>
+      resolveCrudSurfacePolicy(
+        {
+          surface: "console",
+          ownershipFilter: "auto",
+          relativePath: "/crm/customers"
+        },
+        {
+          surfaceDefinitions: {
+            console: { requiresWorkspace: false, requiresAuth: true, enabled: false }
+          }
+        }
+      ),
+    /surface "console" is disabled/
+  );
+});

package/test/crudResource.test.js

@@ -0,0 +1,41 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { crudResource } from "../src/shared/crud/crudResource.js";
+
+test("crudResource normalizes create payload", () => {
+  const normalized = crudResource.operations.create.bodyValidator.normalize({
+    textField: "  Example text  ",
+    dateField: "2026-03-11",
+    numberField: "42.5"
+  });
+
+  assert.deepEqual(normalized, {
+    textField: "Example text",
+    dateField: "2026-03-11 00:00:00.000",
+    numberField: 42.5
+  });
+});
+
+test("crudResource normalizes list output", () => {
+  const normalized = crudResource.operations.list.outputValidator.normalize({
+    items: [
+      {
+        id: "7",
+        textField: " Example text ",
+        dateField: "2026-03-10",
+        numberField: "99",
+        createdAt: "2026-03-11 00:00:00.000",
+        updatedAt: "2026-03-11 00:00:00.000"
+      }
+    ],
+    nextCursor: " 8 "
+  });
+
+  assert.equal(normalized.items[0].id, 7);
+  assert.equal(normalized.items[0].textField, "Example text");
+  assert.equal(normalized.items[0].dateField, "2026-03-10T00:00:00.000Z");
+  assert.equal(normalized.items[0].numberField, 99);
+  assert.match(normalized.items[0].createdAt, /T/);
+  assert.match(normalized.items[0].updatedAt, /T/);
+  assert.equal(normalized.nextCursor, "8");
+});

package/test/crudServerGuards.test.js

@@ -0,0 +1,61 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createActions } from "../src/server/actions.js";
+import { createActionIds } from "../src/server/actionIds.js";
+import { createRepository } from "../src/server/repository.js";
+import { registerRoutes } from "../src/server/registerRoutes.js";
+
+test("createActionIds requires explicit actionIdPrefix", () => {
+  assert.throws(
+    () => createActionIds(""),
+    /requires actionIdPrefix/
+  );
+});
+
+test("createRepository requires explicit tableName", () => {
+  const knex = () => {
+    throw new Error("not expected");
+  };
+
+  assert.throws(
+    () => createRepository(knex, {}),
+    /requires tableName/
+  );
+});
+
+test("createActions requires explicit surface", () => {
+  assert.throws(
+    () =>
+      createActions({
+        actionIdPrefix: "crud.customers"
+      }),
+    /requires a non-empty surface/
+  );
+});
+
+test("registerRoutes requires explicit routeRelativePath and actionIds", () => {
+  const app = {
+    make() {
+      return {
+        register() {}
+      };
+    }
+  };
+
+  assert.throws(
+    () => registerRoutes(app, {}),
+    /requires routeRelativePath/
+  );
+
+  assert.throws(
+    () =>
+      registerRoutes(app, {
+        routeRelativePath: "/customers",
+        routeSurfaceRequiresWorkspace: true,
+        actionIds: {
+          list: "crud.customers.list"
+        }
+      }),
+    /requires actionIds.view/
+  );
+});

package/test/crudService.test.js

@@ -0,0 +1,83 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { createService } from "../src/server/service.js";
+
+test("crudService delegates CRUD operations to the repository", async () => {
+  const calls = [];
+  const crudRepository = {
+    async list(query) {
+      calls.push(["list", query]);
+      return { items: [], nextCursor: null };
+    },
+    async findById(recordId) {
+      calls.push(["findById", recordId]);
+      return { id: recordId, textField: "Example", dateField: "2026-03-11T00:00:00.000Z", numberField: 3 };
+    },
+    async create(payload) {
+      calls.push(["create", payload]);
+      return { id: 1, ...payload };
+    },
+    async updateById(recordId, payload) {
+      calls.push(["updateById", recordId, payload]);
+      return { id: recordId, ...payload };
+    },
+    async deleteById(recordId) {
+      calls.push(["deleteById", recordId]);
+      return { id: recordId, deleted: true };
+    }
+  };
+
+  const service = createService({ crudRepository });
+
+  const options = {};
+  await service.listRecords({ limit: 10 }, options);
+  await service.getRecord(3, options);
+  await service.createRecord({ textField: "Example", dateField: "2026-03-11", numberField: 3 }, options);
+  await service.updateRecord(4, { textField: "Changed" }, options);
+  await service.deleteRecord(5, options);
+
+  assert.deepEqual(calls, [
+    ["list", { limit: 10 }],
+    ["findById", 3],
+    ["create", { textField: "Example", dateField: "2026-03-11", numberField: 3 }],
+    ["updateById", 4, { textField: "Changed" }],
+    ["deleteById", 5]
+  ]);
+});
+
+test("crudService throws 404 when a record is missing", async () => {
+  const service = createService({
+    crudRepository: {
+      async list() {
+        return { items: [], nextCursor: null };
+      },
+      async findById() {
+        return null;
+      },
+      async create(payload) {
+        return { id: 1, ...payload };
+      },
+      async updateById() {
+        return null;
+      },
+      async deleteById() {
+        return null;
+      }
+    }
+  });
+
+  await assert.rejects(
+    () => service.getRecord(9, {}),
+    (error) => error?.status === 404 && error?.message === "Record not found."
+  );
+
+  await assert.rejects(
+    () => service.updateRecord(9, { textField: "Changed" }, {}),
+    (error) => error?.status === 404 && error?.message === "Record not found."
+  );
+
+  await assert.rejects(
+    () => service.deleteRecord(9, {}),
+    (error) => error?.status === 404 && error?.message === "Record not found."
+  );
+});

package/test/routeInputContracts.test.js

@@ -0,0 +1,211 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { KERNEL_TOKENS } from "@jskit-ai/kernel/shared/support/tokens";
+import { registerRoutes } from "../src/server/registerRoutes.js";
+
+function createReplyDouble() {
+  return {
+    statusCode: 200,
+    payload: null,
+    code(statusCode) {
+      this.statusCode = statusCode;
+      return this;
+    },
+    send(payload) {
+      this.payload = payload;
+      return this;
+    }
+  };
+}
+
+function findRoute(routes, method, path) {
+  return routes.find((route) => route.method === method && route.path === path) || null;
+}
+
+test("crud routes build create/update action input with explicit payload and patch keys", async () => {
+  const registeredRoutes = [];
+  const router = {
+    register(method, path, route, handler) {
+      registeredRoutes.push({
+        method,
+        path,
+        route,
+        handler
+      });
+    }
+  };
+  const app = {
+    make(token) {
+      if (token !== KERNEL_TOKENS.HttpRouter) {
+        throw new Error(`Unexpected token: ${String(token)}`);
+      }
+      return router;
+    }
+  };
+
+  registerRoutes(app, {
+    routeRelativePath: "/customers",
+    routeSurfaceRequiresWorkspace: true,
+    actionIds: {
+      list: "crud.customers.list",
+      view: "crud.customers.view",
+      create: "crud.customers.create",
+      update: "crud.customers.update",
+      delete: "crud.customers.delete"
+    }
+  });
+
+  const createRoute = findRoute(registeredRoutes, "POST", "/api/w/:workspaceSlug/workspace/customers");
+  const updateRoute = findRoute(registeredRoutes, "PATCH", "/api/w/:workspaceSlug/workspace/customers/:recordId");
+  assert.ok(createRoute);
+  assert.ok(updateRoute);
+
+  const calls = [];
+  const executeAction = async (payload) => {
+    calls.push(payload);
+    return {};
+  };
+
+  await createRoute.handler(
+    {
+      input: {
+        params: { workspaceSlug: "acme" },
+        body: { textField: "A", dateField: "2026-03-11", numberField: 2 }
+      },
+      executeAction
+    },
+    createReplyDouble()
+  );
+  await updateRoute.handler(
+    {
+      input: {
+        params: { workspaceSlug: "acme", recordId: 12 },
+        body: { textField: "Renamed" }
+      },
+      executeAction
+    },
+    createReplyDouble()
+  );
+
+  assert.deepEqual(calls[0].input, {
+    workspaceSlug: "acme",
+    payload: { textField: "A", dateField: "2026-03-11", numberField: 2 }
+  });
+  assert.deepEqual(calls[1].input, {
+    workspaceSlug: "acme",
+    recordId: 12,
+    patch: { textField: "Renamed" }
+  });
+});
+
+test("crud routes omit workspaceSlug for non-workspace calls and apply configured route surface", async () => {
+  const registeredRoutes = [];
+  const router = {
+    register(method, path, route, handler) {
+      registeredRoutes.push({
+        method,
+        path,
+        route,
+        handler
+      });
+    }
+  };
+  const app = {
+    make(token) {
+      if (token !== KERNEL_TOKENS.HttpRouter) {
+        throw new Error(`Unexpected token: ${String(token)}`);
+      }
+      return router;
+    }
+  };
+
+  registerRoutes(app, {
+    routeRelativePath: "/customers",
+    routeSurface: "console",
+    actionIds: {
+      list: "crud.customers.list",
+      view: "crud.customers.view",
+      create: "crud.customers.create",
+      update: "crud.customers.update",
+      delete: "crud.customers.delete"
+    }
+  });
+
+  const createRoute = findRoute(registeredRoutes, "POST", "/api/customers");
+  assert.ok(createRoute);
+  assert.equal(createRoute.route.surface, "console");
+
+  const calls = [];
+  const executeAction = async (payload) => {
+    calls.push(payload);
+    return {};
+  };
+
+  await createRoute.handler(
+    {
+      input: {
+        params: {},
+        body: { textField: "A", dateField: "2026-03-11", numberField: 2 }
+      },
+      executeAction
+    },
+    createReplyDouble()
+  );
+
+  assert.deepEqual(calls[0].input, {
+    payload: { textField: "A", dateField: "2026-03-11", numberField: 2 }
+  });
+});
+
+test("crud routes normalize route ownership filter values before registering visibility", () => {
+  const registeredRoutes = [];
+  const router = {
+    register(method, path, route, handler) {
+      registeredRoutes.push({
+        method,
+        path,
+        route,
+        handler
+      });
+    }
+  };
+  const app = {
+    make(token) {
+      if (token !== KERNEL_TOKENS.HttpRouter) {
+        throw new Error(`Unexpected token: ${String(token)}`);
+      }
+      return router;
+    }
+  };
+
+  registerRoutes(app, {
+    routeRelativePath: "/customers",
+    routeOwnershipFilter: " Workspace_User ",
+    actionIds: {
+      list: "crud.customers.list",
+      view: "crud.customers.view",
+      create: "crud.customers.create",
+      update: "crud.customers.update",
+      delete: "crud.customers.delete"
+    }
+  });
+  registerRoutes(app, {
+    routeRelativePath: "/customers-public",
+    routeOwnershipFilter: "not-a-real-filter",
+    actionIds: {
+      list: "crud.customers-public.list",
+      view: "crud.customers-public.view",
+      create: "crud.customers-public.create",
+      update: "crud.customers-public.update",
+      delete: "crud.customers-public.delete"
+    }
+  });
+
+  const workspaceUserRoute = findRoute(registeredRoutes, "GET", "/api/customers");
+  const fallbackPublicRoute = findRoute(registeredRoutes, "GET", "/api/customers-public");
+
+  assert.ok(workspaceUserRoute);
+  assert.ok(fallbackPublicRoute);
+  assert.equal(workspaceUserRoute.route.visibility, "workspace_user");
+  assert.equal(fallbackPublicRoute.route.visibility, "public");
+});