@jskit-ai/crud-core 0.1.196 → 0.1.198

package/package.json

@@ -1,7 +1,10 @@
 {
   "name": "@jskit-ai/crud-core",
-  "version": "0.1.196",
+  "version": "0.1.198",
   "type": "module",
+  "engines": {
+    "node": ">=24.0.0"
+  },
   "scripts": {
     "test": "node --test"
   },
@@ -23,10 +26,11 @@
     "./server/routeContracts": "./src/server/routeContracts.js"
   },
   "dependencies": {
-    "@jskit-ai/database-runtime": "0.1.185",
-    "@jskit-ai/json-rest-api-core": "0.1.129",
-    "@jskit-ai/resource-crud-core": "0.1.127",
-    "json-rest-schema": "^1.0.17"
+    "@jskit-ai/database-runtime": "0.1.187",
+    "@jskit-ai/json-rest-api-core": "0.1.131",
+    "@jskit-ai/resource-crud-core": "0.1.129",
+    "json-rest-schema": "^1.0.17",
+    "json-rest-api": "2.0.0"
   },
   "description": "Shared server-side CRUD service, repository, route, and query helpers.",
   "jskit": {
@@ -45,7 +49,7 @@
     }
   },
   "peerDependencies": {
-    "@jskit-ai/http-runtime": "0.1.183",
-    "@jskit-ai/kernel": "0.1.185"
+    "@jskit-ai/http-runtime": "0.1.185",
+    "@jskit-ai/kernel": "0.1.187"
   }
 }

package/patterns/json-api-resource-package/example/packages/books/package.json

@@ -8,8 +8,8 @@
     "./shared": "./src/shared/index.js"
   },
   "dependencies": {
-    "@jskit-ai/crud-core": "0.1.196",
-    "@jskit-ai/resource-crud-core": "0.1.127"
+    "@jskit-ai/crud-core": "0.1.198",
+    "@jskit-ai/resource-crud-core": "0.1.129"
   },
   "jskit": {
     "kind": "runtime",

package/src/server/defineCrudJsonApiFeature.js

@@ -233,7 +233,6 @@ function defineCrudJsonApiFeature({
       );
       const defaultRepository = createCrudJsonApiRepository({
         api: jsonRestApi,
-        knex: database.knex,
         resource,
         resourceScopeName
       });

package/src/server/jsonApiModule/actions.js

@@ -3,6 +3,7 @@ import {
   createSchema,
   recordIdParamsValidator
 } from "@jskit-ai/kernel/shared/validators";
+import { RestApiWriteError } from "json-rest-api";
 import { normalizeJsonApiFieldsets } from "@jskit-ai/kernel/shared/support/jsonApiFieldsets";
 import { createEntityChangedActionEvent } from "@jskit-ai/kernel/server/actions";
 import {
@@ -618,15 +619,22 @@ function createCrudJsonApiActions({
     }
     const result = mutation ? await repository.withTransaction(run) : await run();
     if (hooks.afterCommit) {
-      await hooks.afterCommit(createLifecycleContext({
-        operation,
-        input: value,
-        context,
-        resource,
-        repository,
-        service,
-        result
-      }));
+      try {
+        await hooks.afterCommit(createLifecycleContext({
+          operation,
+          input: value,
+          context,
+          resource,
+          repository,
+          service,
+          result
+        }));
+      } catch (error) {
+        throw new RestApiWriteError(`CRUD ${operation} afterCommit hook failed.`, {
+          cause: error,
+          transactionOutcome: "committed"
+        });
+      }
     }
     return result;
   }

package/src/server/jsonApiModule/repository.js

@@ -1,19 +1,14 @@
-import { createWithTransaction } from "@jskit-ai/database-runtime/shared";
 import {
   buildJsonRestQueryParams,
-  createJsonApiInputRecord,
   createJsonRestContext,
   returnBadRequestWhenJsonRestFieldsetInvalid,
   returnNullWhenJsonRestResourceMissing
 } from "@jskit-ai/json-rest-api-core/server/jsonRestApiHost";
 
-function createCrudJsonApiRepository({ api, knex, resource, resourceScopeName } = {}) {
+function createCrudJsonApiRepository({ api, resource, resourceScopeName } = {}) {
   if (!api) {
     throw new TypeError("createCrudJsonApiRepository requires api.");
   }
-  if (!knex) {
-    throw new TypeError("createCrudJsonApiRepository requires knex.");
-  }
   if (!resource || typeof resource !== "object" || Array.isArray(resource)) {
     throw new TypeError("createCrudJsonApiRepository requires resource.");
   }
@@ -22,7 +17,30 @@ function createCrudJsonApiRepository({ api, knex, resource, resourceScopeName }
     throw new TypeError("createCrudJsonApiRepository requires resourceScopeName.");
   }
 
-  const withTransaction = createWithTransaction(knex);
+  function withTransaction(work) {
+    return api.transaction(work);
+  }
+
+  function inputData(payload) {
+    const data = { ...payload };
+    for (const [fieldName, definition] of Object.entries(resource.schema || {})) {
+      if (!definition?.belongsTo || !Object.hasOwn(data, fieldName)) {
+        continue;
+      }
+      const relationshipName = definition.as || fieldName;
+      if (relationshipName === fieldName) {
+        continue;
+      }
+      if (Object.hasOwn(data, relationshipName)) {
+        throw new TypeError(`Provide either "${fieldName}" or "${relationshipName}", not both.`);
+      }
+      if (data[fieldName] !== undefined) {
+        data[relationshipName] = data[fieldName];
+      }
+      delete data[fieldName];
+    }
+    return data;
+  }
 
   function requireApiResource() {
     const apiResource = api.resources?.[scopeName];
@@ -38,7 +56,7 @@ function createCrudJsonApiRepository({ api, knex, resource, resourceScopeName }
         {
           queryParams: buildJsonRestQueryParams(scopeName, query),
           transaction: options.trx || null,
-          simplified: false
+          format: "jsonapi"
         },
         createJsonRestContext(options.context || null)
       )
@@ -53,7 +71,7 @@ function createCrudJsonApiRepository({ api, knex, resource, resourceScopeName }
             id: recordId,
             queryParams: buildJsonRestQueryParams(scopeName, query),
             transaction: options.trx || null,
-            simplified: false
+            format: "jsonapi"
           },
           createJsonRestContext(options.context || null)
         )
@@ -64,9 +82,10 @@ function createCrudJsonApiRepository({ api, knex, resource, resourceScopeName }
   async function createDocument(payload = {}, options = {}) {
     return requireApiResource().post(
       {
-        inputRecord: createJsonApiInputRecord(scopeName, payload, { resource }),
+        data: inputData(payload),
+        returning: "full",
         transaction: options.trx || null,
-        simplified: false
+        format: "jsonapi"
       },
       createJsonRestContext(options.context || null)
     );
@@ -82,9 +101,10 @@ function createCrudJsonApiRepository({ api, knex, resource, resourceScopeName }
       requireApiResource().patch(
         {
           id: recordId,
-          inputRecord: createJsonApiInputRecord(scopeName, sourcePatch, { resource }),
+          data: inputData(sourcePatch),
+          returning: "full",
           transaction: options.trx || null,
-          simplified: false
+          format: "jsonapi"
         },
         createJsonRestContext(options.context || null)
       )
@@ -96,8 +116,9 @@ function createCrudJsonApiRepository({ api, knex, resource, resourceScopeName }
       await requireApiResource().delete(
         {
           id: recordId,
+          returning: "none",
           transaction: options.trx || null,
-          simplified: false
+          format: "jsonapi"
         },
         createJsonRestContext(options.context || null)
       );

package/test/assistantPagination.integration.test.js

@@ -53,7 +53,7 @@ test("assistant list traverses real SQL pages with sparse fields and capped limi
   });
   const api = await createJsonRestApiHost({ knex });
   await addResourceIfMissing(api, "books", createJsonRestResourceScopeOptions(resource));
-  const repository = createCrudJsonApiRepository({ api, knex, resource, resourceScopeName: "books" });
+  const repository = createCrudJsonApiRepository({ api, resource, resourceScopeName: "books" });
   const service = createCrudJsonApiService({ repository });
   const actions = createActionCatalogue();
   actions.register({
@@ -141,8 +141,9 @@ test("assistant list traverses real SQL pages with sparse fields and capped limi
 
   await t.test("plain writes and JSON:API repository writes preserve full records", async () => {
     const created = await api.resources.books.post({
-      inputRecord: { id: "501", workspaceId: "1", name: "Plain record", createdAt: "2026-09-09T00:00:00.000Z" },
-      format: "plain"
+      data: { id: "501", workspaceId: "1", name: "Plain record", createdAt: "2026-09-09T00:00:00.000Z" },
+      format: "plain",
+      returning: "full"
     }, createJsonRestContext(context));
     assert.equal(created.id, "501");
     assert.equal(created.name, "Plain record");
@@ -155,7 +156,7 @@ test("assistant list traverses real SQL pages with sparse fields and capped limi
     assert.equal(document.data.id, "502");
     assert.equal(document.data.attributes.name, "JSON:API record");
     assert.equal((await api.resources.books.get({ id: "502", format: "plain" }, createJsonRestContext(context))).name, "JSON:API record");
-    await assert.rejects(knex.transaction(async (trx) => {
+    await assert.rejects(api.transaction(async (trx) => {
       await repository.patchDocumentById("502", { name: "Rolled back" }, { trx, context });
       throw new Error("Rollback proof");
     }), /Rollback proof/);

package/test/defineCrudJsonApiFeature.test.js

@@ -1,6 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { createSchema } from "json-rest-schema";
+import { RestApiWriteError } from "json-rest-api";
 
 import { createActionProvider } from "@jskit-ai/kernel/server/actions";
 import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
@@ -582,6 +583,80 @@ test("CRUD operation lifecycle does not run after or afterCommit when the transa
   assert.deepEqual(calls, ["transaction:begin", "before", "service"]);
 });
 
+test("CRUD afterCommit failures preserve the original cause and acknowledged commit", async () => {
+  for (const failure of [new Error("notification failed"), Object.freeze(new Error("frozen failure")), null, undefined]) {
+    let committed = false;
+    const actions = createCrudJsonApiActions({
+      namespace: "books",
+      resource: createBookResource(),
+      repository: {
+        async withTransaction(work) {
+          const result = await work({ id: "transaction" });
+          committed = true;
+          return result;
+        }
+      },
+      service: {
+        patchDocumentById(id, attributes) { return { data: { id, attributes } }; }
+      },
+      surface: "app",
+      operations: ["update"],
+      permissionForOperation: () => ({ require: "authenticated" }),
+      operationLifecycle: {
+        update: { afterCommit() { assert.equal(committed, true); throw failure; } }
+      }
+    });
+    await assert.rejects(
+      () => actions[0].execute({ recordId: "42", title: "Kindred" }, {}),
+      (error) => {
+        assert.ok(error instanceof RestApiWriteError);
+        assert.equal(error.transactionOutcome, "committed");
+        assert.equal(error.cause, failure);
+        return true;
+      }
+    );
+  }
+});
+
+test("CRUD failures before acknowledged commit are not marked committed", async () => {
+  for (const phase of ["before", "after", "commit"]) {
+    const failure = Object.freeze(new Error(`${phase} failed`));
+    let committed = false;
+    let afterCommitCalled = false;
+    const actions = createCrudJsonApiActions({
+      namespace: "books",
+      resource: createBookResource(),
+      repository: {
+        async withTransaction(work) {
+          const result = await work({ id: "transaction" });
+          if (phase === "commit") throw failure;
+          committed = true;
+          return result;
+        }
+      },
+      service: {
+        patchDocumentById(id, attributes) { return { data: { id, attributes } }; }
+      },
+      surface: "app",
+      operations: ["update"],
+      permissionForOperation: () => ({ require: "authenticated" }),
+      operationLifecycle: {
+        update: {
+          before() { if (phase === "before") throw failure; },
+          after() { if (phase === "after") throw failure; },
+          afterCommit() { afterCommitCalled = true; }
+        }
+      }
+    });
+    await assert.rejects(
+      () => actions[0].execute({ recordId: "42", title: "Kindred" }, {}),
+      (error) => error === failure && error.transactionOutcome === undefined
+    );
+    assert.equal(committed, false);
+    assert.equal(afterCommitCalled, false);
+  }
+});
+
 test("defineCrudJsonApiFeature exposes custom service methods as actions and optional routes", async () => {
   const routes = [];
   const calls = [];

package/test/jsonApiRepository.test.js

@@ -0,0 +1,186 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import knexLib from "knex";
+import {
+  createJsonRestApiHost,
+  createJsonRestResourceScopeOptions
+} from "@jskit-ai/json-rest-api-core/server/jsonRestApiHost";
+import { defineCrudResource } from "@jskit-ai/resource-crud-core/shared/crudResource";
+import { createCrudJsonApiActions } from "../src/server/jsonApiModule/actions.js";
+import { createCrudJsonApiRepository } from "../src/server/jsonApiModule/repository.js";
+import { createCrudJsonApiService } from "../src/server/jsonApiModule/service.js";
+
+function createRepositoryRecorder() {
+  const calls = [];
+  const response = { data: { type: "books", id: "7", attributes: { title: "Dune" } } };
+  const resource = {
+    schema: {
+      title: { type: "string" },
+      authorId: { type: "id", belongsTo: "authors", as: "author" }
+    }
+  };
+  const api = { resources: { books: {} }, transaction: (work) => work("managed") };
+  for (const method of ["get", "query", "post", "patch", "delete"]) {
+    api.resources.books[method] = async (params, context) => {
+      calls.push({ method, params, context });
+      return response;
+    };
+  }
+  return {
+    calls,
+    response,
+    repository: createCrudJsonApiRepository({ api, resource, resourceScopeName: "books" })
+  };
+}
+
+test("JSON:API repositories use plain input with explicit document responses", async () => {
+  const { repository, calls, response } = createRepositoryRecorder();
+  const context = Object.freeze({ scopeValues: Object.freeze({ workspaceId: "2" }) });
+  const payload = Object.freeze({ title: "Dune", authorId: 9, data: { edition: 1 } });
+  assert.equal(await repository.createDocument(payload, { trx: "managed", context }), response);
+  assert.deepEqual(calls[0].params, {
+    data: { title: "Dune", author: 9, data: { edition: 1 } },
+    returning: "full",
+    transaction: "managed",
+    format: "jsonapi"
+  });
+  assert.notEqual(calls[0].context, context);
+  assert.notEqual(calls[0].context.scopeValues, context.scopeValues);
+  assert.equal(payload.authorId, 9);
+  assert.equal(await repository.patchDocumentById("7", { authorId: null }), response);
+  assert.deepEqual(calls[1].params, {
+    id: "7",
+    data: { author: null },
+    returning: "full",
+    transaction: null,
+    format: "jsonapi"
+  });
+  await assert.rejects(
+    () => repository.createDocument({ authorId: "9", author: "10" }),
+    /Provide either "authorId" or "author", not both/
+  );
+  assert.equal(calls.length, 2);
+});
+
+test("JSON:API repository reads and empty patches retain their document contract", async () => {
+  const { repository, calls, response } = createRepositoryRecorder();
+  assert.equal(await repository.queryDocuments({ title: "Dune" }), response);
+  assert.equal(await repository.patchDocumentById("7", {}), response);
+  assert.equal(await repository.deleteDocumentById("7"), null);
+  assert.deepEqual(calls.map(({ method, params }) => ({ method, params })), [
+    { method: "query", params: { queryParams: { filters: { title: "Dune" } }, transaction: null, format: "jsonapi" } },
+    { method: "get", params: { id: "7", queryParams: {}, transaction: null, format: "jsonapi" } },
+    { method: "delete", params: { id: "7", returning: "none", transaction: null, format: "jsonapi" } }
+  ]);
+  assert.equal(await repository.withTransaction((trx) => trx), "managed");
+});
+
+async function createDatabaseRepository(t) {
+  const knex = knexLib({
+    client: "better-sqlite3",
+    connection: { filename: ":memory:" },
+    useNullAsDefault: true
+  });
+  t.after(() => knex.destroy());
+  await knex.schema.createTable("books", (table) => {
+    table.increments("id");
+    table.string("title").notNullable();
+  });
+  await knex.schema.createTable("audit_entries", (table) => {
+    table.increments("id");
+    table.string("message").notNullable();
+  });
+  const api = await createJsonRestApiHost({ knex });
+  const resource = { tableName: "books", schema: { title: { type: "string", required: true } } };
+  await api.addResource("books", createJsonRestResourceScopeOptions(resource));
+  const repository = createCrudJsonApiRepository({ api, resource, resourceScopeName: "books" });
+  return { api, knex, repository };
+}
+
+test("repository transactions commit resource writes and raw SQL before completion hooks", async (t) => {
+  const { api, knex, repository } = await createDatabaseRepository(t);
+  const committed = [];
+  await api.customize({ hooks: { afterCommit: ({ context }) => committed.push(context.method) } });
+  const document = await repository.withTransaction(async (trx) => {
+    const first = await repository.createDocument({ title: "Dune" }, { trx });
+    await repository.createDocument({ title: "Kindred" }, { trx });
+    await trx("audit_entries").insert({ message: "Created books" });
+    assert.deepEqual(committed, []);
+    return first;
+  });
+  assert.equal(document.data.attributes.title, "Dune");
+  assert.deepEqual(await knex("books").orderBy("id").pluck("title"), ["Dune", "Kindred"]);
+  assert.deepEqual(await knex("audit_entries").pluck("message"), ["Created books"]);
+  assert.deepEqual(committed, ["post", "post"]);
+});
+
+test("repository transactions roll back resource writes and raw SQL after a rejected participant", async (t) => {
+  const { knex, repository } = await createDatabaseRepository(t);
+  await assert.rejects(
+    () => repository.withTransaction(async (trx) => {
+      await repository.createDocument({ title: "Dune" }, { trx });
+      await trx("audit_entries").insert({ message: "Pending" });
+      await repository.createDocument({}, { trx });
+    }),
+    (error) => error.transactionOutcome === "rolledBack" && error.code === "REST_API_VALIDATION"
+  );
+  assert.deepEqual(await knex("books"), []);
+  assert.deepEqual(await knex("audit_entries"), []);
+});
+
+test("a missing write inside a managed transaction cannot become a successful null result", async (t) => {
+  const { knex, repository } = await createDatabaseRepository(t);
+  await assert.rejects(
+    () => repository.withTransaction(async (trx) => {
+      await repository.createDocument({ title: "Dune" }, { trx });
+      return repository.patchDocumentById("999", { title: "Missing" }, { trx });
+    }),
+    (error) => error.transactionOutcome === "rolledBack" && error.subtype === "not_found"
+  );
+  assert.deepEqual(await knex("books"), []);
+  assert.equal(await repository.patchDocumentById("999", { title: "Missing" }), null);
+});
+
+test("repository writes reject a raw transaction owner without inserting data", async (t) => {
+  const { knex, repository } = await createDatabaseRepository(t);
+  await knex.transaction(async (trx) => {
+    await assert.rejects(
+      () => repository.createDocument({ title: "Dune" }, { trx }),
+      (error) => error.code === "REST_API_VALIDATION" && error.transactionOutcome === "none"
+    );
+    assert.deepEqual(await trx("books"), []);
+  });
+  assert.deepEqual(await knex("books"), []);
+});
+
+test("a failing CRUD afterCommit hook reports committed and leaves the actual write stored", async (t) => {
+  const { knex, repository } = await createDatabaseRepository(t);
+  const book = await repository.createDocument({ title: "Dune" });
+  const failure = Object.freeze(new Error("Notification failed"));
+  const actions = createCrudJsonApiActions({
+    namespace: "books",
+    resource: defineCrudResource({
+      namespace: "books",
+      tableName: "books",
+      autofilter: "public",
+      schema: {
+        title: {
+          type: "string",
+          required: true,
+          operations: { output: { required: true }, create: { required: true }, patch: { required: false } }
+        }
+      }
+    }),
+    repository,
+    service: createCrudJsonApiService({ repository }),
+    surface: "app",
+    operations: ["update"],
+    permissionForOperation: () => ({ require: "authenticated" }),
+    operationLifecycle: { update: { afterCommit() { throw failure; } } }
+  });
+  await assert.rejects(
+    () => actions[0].execute({ recordId: book.data.id, title: "Kindred" }, {}),
+    (error) => error.transactionOutcome === "committed" && error.cause === failure
+  );
+  assert.equal((await knex("books").where({ id: book.data.id }).first()).title, "Kindred");
+});