@jskit-ai/crud-server-generator 0.1.63 → 0.1.64

package/test/crudServerGuards.test.js

@@ -1,6 +1,5 @@
 import test, { after } from "node:test";
 import assert from "node:assert/strict";
-import { recordIdParamsValidator } from "@jskit-ai/kernel/shared/validators";
 import { createTemplateServerFixture } from "../test-support/templateServerFixture.js";
 
 const fixture = await createTemplateServerFixture();
@@ -10,6 +9,7 @@ const nonWorkspaceFixture = await createTemplateServerFixture({
 });
 const { createActions } = await fixture.importServerModule("actions.js");
 const { createRepository } = await fixture.importServerModule("repository.js");
+const { createService } = await fixture.importServerModule("service.js");
 const { createActions: createNonWorkspaceActions } = await nonWorkspaceFixture.importServerModule("actions.js");
 
 after(async () => {
@@ -17,47 +17,125 @@ after(async () => {
   await nonWorkspaceFixture.cleanup();
 });
 
-test("template createRepository defaults tableName from resource metadata", () => {
-  const query = {
-    select() {
-      return query;
-    },
-    where() {
-      return query;
-    },
-    orderBy() {
-      return query;
-    },
-    modify(callback) {
-      if (typeof callback === "function") {
-        callback(query);
+test("template createRepository passes a mutable JSKIT context into json-rest-api", async () => {
+  const calls = [];
+  const api = {
+    resources: {
+      customers: {
+        async query(params, context) {
+          context.method = "query";
+          calls.push({ params, context });
+          return { data: [] };
+        }
       }
-      return query;
+    }
+  };
+  const knex = {
+    async transaction(work) {
+      return work("trx");
+    }
+  };
+  const sourceContext = Object.freeze({
+    visibilityContext: Object.freeze({
+      visibility: "workspace",
+      scopeOwnerId: "7"
+    })
+  });
+
+  const repository = createRepository({ api, knex });
+  assert.equal(typeof repository.queryDocuments, "function");
+  await repository.queryDocuments(
+    {
+      q: "Merc",
+      cursor: "cursor_2",
+      limit: 10,
+      include: "workspace"
     },
-    limit() {
-      return query;
+    {
+      context: sourceContext
+    }
+  );
+
+  assert.deepEqual(calls[0].params, {
+    queryParams: {
+      filters: {
+        q: "Merc"
+      },
+      include: ["workspace"],
+      page: {
+        after: "cursor_2",
+        size: "10"
+      }
     },
-    then(resolve) {
-      return Promise.resolve([]).then(resolve);
+    transaction: null,
+    simplified: false
+  });
+  assert.notEqual(
+    calls[0].context,
+    sourceContext
+  );
+  assert.deepEqual(calls[0].context, {
+    method: "query",
+    visibilityContext: {
+      visibility: "workspace",
+      scopeOwnerId: "7"
+    }
+  });
+});
+
+test("template createRepository builds mutable JSON:API input documents for writes", async () => {
+  const calls = [];
+  const api = {
+    resources: {
+      customers: {
+        async post(params) {
+          calls.push(params);
+          return { data: { type: "customers", id: "1", attributes: { name: "Merc" } } };
+        }
+      }
     }
   };
-  const tables = [];
-  const knex = (tableName) => {
-    tables.push(tableName);
-    return query;
+  const knex = {
+    async transaction(work) {
+      return work("trx");
+    }
   };
 
-  const repository = createRepository(knex, {});
-  assert.equal(typeof repository.list, "function");
-  return repository.list({}).then(() => {
-    assert.equal(tables[0], "customers");
+  const repository = createRepository({ api, knex });
+  await repository.createDocument({ name: "Merc" }, {});
+
+  assert.equal(Object.isFrozen(calls[0].inputRecord), false);
+  assert.equal(Object.isFrozen(calls[0].inputRecord.data), false);
+  assert.equal(Object.isFrozen(calls[0].inputRecord.data.attributes), false);
+  assert.deepEqual(calls[0].inputRecord, {
+    data: {
+      type: "customers",
+      attributes: {
+        name: "Merc"
+      }
+    }
   });
 });
 
-test("template createActions requires explicit surface", () => {
-  assert.throws(
-    () => createActions({}),
-    /requires a non-empty surface/
+test("template createService turns missing resource records into 404 errors", async () => {
+  const service = createService({
+    customersRepository: {
+      async getDocumentById() {
+        return null;
+      },
+      async patchDocumentById() {
+        return null;
+      }
+    }
+  });
+
+  await assert.rejects(
+    () => service.getDocumentById("7", {}),
+    (error) => error?.status === 404 && error?.message === "Document not found."
+  );
+  await assert.rejects(
+    () => service.patchDocumentById("7", { name: "Merc" }, {}),
+    (error) => error?.status === 404 && error?.message === "Document not found."
   );
 });
 
@@ -76,18 +154,55 @@ test("template createActions requires namespaced CRUD permissions by default", (
   );
 });
 
+test("template list action strips workspaceSlug before calling the service", async () => {
+  const actions = createActions({ surface: "admin" });
+  const listAction = actions.find((action) => action.id === "crud.customers.list");
+  const calls = [];
+
+  await listAction.execute(
+    {
+      workspaceSlug: "acme",
+      q: "Merc",
+      include: "workspace"
+    },
+    { visibilityContext: { visibility: "workspace", scopeOwnerId: "7" } },
+    {
+      customersService: {
+        async queryDocuments(query, options) {
+          calls.push({ query, options });
+          return { kind: "document", value: { data: [] } };
+        }
+      }
+    }
+  );
+
+  assert.deepEqual(calls[0].query, {
+    q: "Merc",
+    include: "workspace"
+  });
+  assert.deepEqual(calls[0].options, {
+    context: {
+      visibilityContext: {
+        visibility: "workspace",
+        scopeOwnerId: "7"
+      }
+    }
+  });
+});
+
 test("template createActions omits workspace validators for non-workspace generation", () => {
   const actions = createNonWorkspaceActions({ surface: "home" });
 
-  assert.equal(Array.isArray(actions[0].inputValidator), true);
-  assert.equal(actions[0].inputValidator.length, 4);
-  assert.equal(Array.isArray(actions[1].inputValidator), true);
-  assert.equal(actions[1].inputValidator.length, 2);
-  assert.equal(actions[1].inputValidator[0], recordIdParamsValidator);
-  assert.deepEqual(Object.keys(actions[2].inputValidator), ["payload"]);
-  assert.equal(Array.isArray(actions[3].inputValidator), true);
-  assert.equal(actions[3].inputValidator.length, 2);
-  assert.equal(actions[3].inputValidator[0], recordIdParamsValidator);
-  assert.equal(actions[4].inputValidator, recordIdParamsValidator);
+  assert.equal(Array.isArray(actions[0].input), false);
+  assert.deepEqual(Object.keys(actions[0].input.schema.getFieldDefinitions()).sort(), ["contactId", "cursor", "include", "limit", "q"]);
+  assert.equal(Array.isArray(actions[1].input), false);
+  assert.deepEqual(Object.keys(actions[1].input.schema.getFieldDefinitions()).sort(), ["include", "recordId"]);
+  assert.equal(Array.isArray(actions[2].input), false);
+  assert.deepEqual(Object.keys(actions[2].input.schema.getFieldDefinitions()).sort(), ["contactId", "name"]);
+  assert.equal(actions[2].input.mode, "create");
+  assert.equal(Array.isArray(actions[3].input), false);
+  assert.deepEqual(Object.keys(actions[3].input.schema.getFieldDefinitions()).sort(), ["contactId", "name", "recordId"]);
+  assert.equal(Array.isArray(actions[4].input), false);
+  assert.deepEqual(Object.keys(actions[4].input.schema.getFieldDefinitions()), ["recordId"]);
   assert.equal(actions[0].permission.require, "authenticated");
 });

package/test/crudService.test.js

@@ -3,219 +3,137 @@ import assert from "node:assert/strict";
 import { createTemplateServerFixture } from "../test-support/templateServerFixture.js";
 
 const fixture = await createTemplateServerFixture();
-const { createService, serviceEvents } = await fixture.importServerModule("service.js");
+const { createService } = await fixture.importServerModule("service.js");
 
 after(async () => {
   await fixture.cleanup();
 });
 
-test("crudService delegates CRUD operations to the repository", async () => {
+test("crudService exposes the explicit JSON:API CRUD service contract", async () => {
   const calls = [];
   const customersRepository = {
-    async list(query) {
-      calls.push(["list", query]);
-      return { items: [], nextCursor: null };
+    async queryDocuments(query, options) {
+      calls.push(["queryDocuments", query, options]);
+      return { data: [] };
     },
-    async findById(recordId) {
-      calls.push(["findById", recordId]);
-      return { id: recordId, textField: "Example", dateField: "2026-03-11T00:00:00.000Z", numberField: 3 };
+    async getDocumentById(recordId, options) {
+      calls.push(["getDocumentById", recordId, options]);
+      return { data: { id: String(recordId) } };
     },
-    async create(payload) {
-      calls.push(["create", payload]);
-      return { id: 1, ...payload };
+    async createDocument(payload, options) {
+      calls.push(["createDocument", payload, options]);
+      return { data: { id: "1", attributes: payload } };
     },
-    async updateById(recordId, payload) {
-      calls.push(["updateById", recordId, payload]);
-      return { id: recordId, ...payload };
+    async patchDocumentById(recordId, payload, options) {
+      calls.push(["patchDocumentById", recordId, payload, options]);
+      return { data: { id: String(recordId), attributes: payload } };
     },
-    async deleteById(recordId) {
-      calls.push(["deleteById", recordId]);
-      return { id: recordId, deleted: true };
+    async deleteDocumentById(recordId, options) {
+      calls.push(["deleteDocumentById", recordId, options]);
+      return true;
     }
   };
 
   const service = createService({ customersRepository });
 
-  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(Object.keys(service), [
+    "queryDocuments",
+    "getDocumentById",
+    "createDocument",
+    "patchDocumentById",
+    "deleteDocumentById"
+  ]);
+  assert.equal(Object.isFrozen(service), true);
+
+  const options = {
+    trx: "trx-1",
+    context: { visibilityContext: { visibility: "workspace", scopeOwnerId: "7" } },
+    include: ["workspace"]
+  };
+  const listResult = await service.queryDocuments({ limit: 10 }, options);
+  const recordResult = await service.getDocumentById(3, options);
+  const createResult = await service.createDocument({ textField: "Example", dateField: "2026-03-11", numberField: 3 }, options);
+  const updateResult = await service.patchDocumentById(4, { textField: "Changed" }, options);
+  const deleteResult = await service.deleteDocumentById(5, options);
 
   assert.deepEqual(calls, [
-    ["list", { limit: 10 }],
-    ["findById", 3],
-    ["create", { textField: "Example", dateField: "2026-03-11", numberField: 3 }],
-    ["findById", 4],
-    ["updateById", 4, { textField: "Changed" }],
-    ["deleteById", 5]
+    ["queryDocuments", { limit: 10 }, { trx: "trx-1", context: { visibilityContext: { visibility: "workspace", scopeOwnerId: "7" } } }],
+    ["getDocumentById", 3, { trx: "trx-1", context: { visibilityContext: { visibility: "workspace", scopeOwnerId: "7" } }, include: ["workspace"] }],
+    ["createDocument", { textField: "Example", dateField: "2026-03-11", numberField: 3 }, { trx: "trx-1", context: { visibilityContext: { visibility: "workspace", scopeOwnerId: "7" } } }],
+    ["patchDocumentById", 4, { textField: "Changed" }, { trx: "trx-1", context: { visibilityContext: { visibility: "workspace", scopeOwnerId: "7" } } }],
+    ["deleteDocumentById", 5, { trx: "trx-1", context: { visibilityContext: { visibility: "workspace", scopeOwnerId: "7" } } }]
   ]);
+  assert.equal(listResult.__jskitJsonApiResult, true);
+  assert.equal(listResult.kind, "document");
+  assert.deepEqual(listResult.value, { data: [] });
+  assert.equal(recordResult.__jskitJsonApiResult, true);
+  assert.equal(recordResult.kind, "document");
+  assert.deepEqual(recordResult.value, { data: { id: "3" } });
+  assert.equal(createResult.__jskitJsonApiResult, true);
+  assert.equal(createResult.kind, "document");
+  assert.deepEqual(createResult.value, {
+    data: {
+      id: "1",
+      attributes: {
+        textField: "Example",
+        dateField: "2026-03-11",
+        numberField: 3
+      }
+    }
+  });
+  assert.equal(updateResult.__jskitJsonApiResult, true);
+  assert.equal(updateResult.kind, "document");
+  assert.deepEqual(updateResult.value, {
+    data: {
+      id: "4",
+      attributes: {
+        textField: "Changed"
+      }
+    }
+  });
+  assert.equal(deleteResult, null);
 });
 
-test("crudService throws 404 when a record is missing", async () => {
+test("crudService throws immediately when the repository dependency is missing", () => {
+  assert.throws(
+    () => createService({}),
+    /createService requires customersRepository\./
+  );
+});
+
+test("crudService throws 404 when a document is missing", async () => {
   const service = createService({
     customersRepository: {
-      async list() {
-        return { items: [], nextCursor: null };
+      async queryDocuments() {
+        return { data: [] };
       },
-      async findById() {
+      async getDocumentById() {
         return null;
       },
-      async create(payload) {
-        return { id: 1, ...payload };
+      async createDocument(payload) {
+        return { data: { id: "1", attributes: payload } };
       },
-      async updateById() {
+      async patchDocumentById() {
         return null;
       },
-      async deleteById() {
+      async deleteDocumentById() {
         return null;
       }
     }
   });
 
   await assert.rejects(
-    () => service.getRecord(9, {}),
-    (error) => error?.status === 404 && error?.message === "Record not found."
+    () => service.getDocumentById(9, {}),
+    (error) => error?.status === 404 && error?.message === "Document not found."
   );
 
   await assert.rejects(
-    () => service.updateRecord(9, { textField: "Changed" }, {}),
-    (error) => error?.status === 404 && error?.message === "Record not found."
+    () => service.patchDocumentById(9, { textField: "Changed" }, {}),
+    (error) => error?.status === 404 && error?.message === "Document not found."
   );
 
   await assert.rejects(
-    () => service.deleteRecord(9, {}),
-    (error) => error?.status === 404 && error?.message === "Record not found."
-  );
-});
-
-test("crudService exports default realtime events for create/update/delete", () => {
-  assert.equal(serviceEvents.createRecord[0].realtime.event, "customers.record.changed");
-  assert.equal(serviceEvents.updateRecord[0].realtime.event, "customers.record.changed");
-  assert.equal(serviceEvents.deleteRecord[0].realtime.event, "customers.record.changed");
-});
-
-test("crudService passes existing records into repository update options via the shared CRUD service", async () => {
-  const calls = [];
-  const service = createService({
-    customersRepository: {
-      async list() {
-        return { items: [], nextCursor: null };
-      },
-      async findById(recordId) {
-        calls.push(["findById", recordId]);
-        return {
-          id: recordId,
-          textField: "Existing",
-          dateField: "2026-03-11T00:00:00.000Z",
-          numberField: 3
-        };
-      },
-      async create(payload) {
-        return { id: 1, ...payload };
-      },
-      async updateById(recordId, payload, options = {}) {
-        calls.push(["updateById", recordId, payload, options]);
-        return {
-          id: recordId,
-          textField: payload.textField || "",
-          dateField: "2026-03-11T00:00:00.000Z",
-          numberField: payload.numberField ?? 0
-        };
-      },
-      async deleteById(recordId) {
-        return { id: recordId, deleted: true };
-      }
-    }
-  });
-
-  await service.updateRecord(4, { textField: "Changed" }, {});
-
-  assert.deepEqual(calls, [
-    ["findById", 4],
-    ["updateById", 4, { textField: "Changed" }, {
-      existingRecord: {
-        id: 4,
-        textField: "Existing",
-        dateField: "2026-03-11T00:00:00.000Z",
-        numberField: 3
-      }
-    }]
-  ]);
-});
-
-test("crudService supports optional fieldAccess hooks for writable filtering", async () => {
-  const calls = [];
-  const service = createService({
-    customersRepository: {
-      async list() {
-        return {
-          items: [
-            {
-              id: 1,
-              textField: "A",
-              dateField: "2026-03-11T00:00:00.000Z",
-              numberField: 1
-            }
-          ],
-          nextCursor: null
-        };
-      },
-      async findById() {
-        return {
-          id: 1,
-          textField: "A",
-          dateField: "2026-03-11T00:00:00.000Z",
-          numberField: 1
-        };
-      },
-      async create(payload) {
-        calls.push(payload);
-        return {
-          id: 1,
-          textField: payload.textField || "",
-          dateField: "2026-03-11T00:00:00.000Z",
-          numberField: payload.numberField ?? 0
-        };
-      },
-      async updateById(recordId, payload) {
-        calls.push([recordId, payload]);
-        return {
-          id: recordId,
-          textField: payload.textField || "",
-          dateField: "2026-03-11T00:00:00.000Z",
-          numberField: payload.numberField ?? 0
-        };
-      },
-      async deleteById(recordId) {
-        return { id: recordId, deleted: true };
-      }
-    },
-    fieldAccess: {
-      writable: () => ["textField"],
-      writeMode: "strip"
-    }
-  });
-
-  await service.createRecord(
-    {
-      textField: "Allowed",
-      numberField: 99
-    },
-    {}
-  );
-  await service.updateRecord(
-    2,
-    {
-      textField: "Updated",
-      numberField: 88
-    },
-    {}
+    () => service.deleteDocumentById(9, {}),
+    (error) => error?.status === 404 && error?.message === "Document not found."
   );
-
-  assert.deepEqual(calls, [
-    { textField: "Allowed" },
-    [2, { textField: "Updated" }]
-  ]);
 });

package/test/packageDescriptor.test.js

@@ -21,19 +21,11 @@ test("crud-server-generator surface option validates against enabled surface ids
   assert.equal(descriptor.metadata?.generatorSubcommands?.scaffold?.createTarget?.pathTemplate, "packages/${option:namespace|kebab}");
 });
 
-test("crud-server-generator installs listConfig alongside server templates", () => {
+test("crud-server-generator no longer installs a separate jsonRestResource server template", () => {
   const files = descriptor.mutations?.files || [];
-  const listConfigTemplate = files.find((entry) => entry.from === "templates/src/local-package/server/listConfig.js");
+  const jsonRestResourceTemplate = files.find((entry) => entry.from === "templates/src/local-package/server/jsonRestResource.js");
 
-  assert.ok(listConfigTemplate);
-  assert.equal(
-    listConfigTemplate.to,
-    "packages/${option:namespace|kebab}/src/server/listConfig.js"
-  );
-  assert.deepEqual(listConfigTemplate.templateContext, {
-    entrypoint: "src/server/buildTemplateContext.js",
-    export: "buildTemplateContext"
-  });
+  assert.equal(jsonRestResourceTemplate, undefined);
 });
 
 test("crud-server-generator wires action and role mutations through template context", () => {