@jskit-ai/crud-core 0.1.31 → 0.1.32

package/src/server/repositorySupport.js

@@ -1,3 +1,4 @@
+import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
 import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { normalizeObjectInput } from "@jskit-ai/kernel/shared/validators/inputNormalization";
 import { toSnakeCase } from "@jskit-ai/kernel/shared/support/stringCase";
@@ -10,6 +11,28 @@ import { isCrudRuntimeOutputOnlyFieldKey } from "../shared/crudFieldMetaSupport.
 const DEFAULT_LIST_LIMIT = 20;
 const MAX_LIST_LIMIT = 100;
 
+function normalizeCrudListCursor(cursor = null, { allowEmpty = true } = {}) {
+  if (cursor === undefined || cursor === null) {
+    return allowEmpty === true ? 0 : null;
+  }
+
+  const normalizedCursor = typeof cursor === "string"
+    ? cursor.trim()
+    : cursor;
+  if (normalizedCursor === "" || normalizedCursor === 0 || normalizedCursor === "0") {
+    return allowEmpty === true ? 0 : null;
+  }
+
+  const numericCursor = Number(normalizedCursor);
+  if (!Number.isInteger(numericCursor) || numericCursor < 1) {
+    throw new AppError(400, "Invalid cursor.", {
+      code: "INVALID_CURSOR"
+    });
+  }
+
+  return numericCursor;
+}
+
 function normalizeCrudListLimit(value, { fallback = DEFAULT_LIST_LIMIT, max = MAX_LIST_LIMIT } = {}) {
   const parsed = Number(value);
   if (!Number.isInteger(parsed) || parsed < 1) {
@@ -222,6 +245,7 @@ function applyCrudListQueryFilters(
   {
     idColumn = "id",
     cursor = 0,
+    applyCursor = true,
     q = "",
     searchColumns = [],
     parentFilters = {},
@@ -280,11 +304,12 @@ function applyCrudListQueryFilters(
     });
   }
 
-  const numericCursor = Number(cursor);
-  const normalizedCursor = Number.isInteger(numericCursor) && numericCursor > 0 ? numericCursor : 0;
   const normalizedIdColumn = String(idColumn || "").trim() || "id";
-  if (normalizedCursor > 0) {
-    nextQuery = nextQuery.where(normalizedIdColumn, ">", normalizedCursor);
+  if (applyCursor !== false) {
+    const normalizedCursor = normalizeCrudListCursor(cursor);
+    if (normalizedCursor > 0) {
+      nextQuery = nextQuery.where(normalizedIdColumn, ">", normalizedCursor);
+    }
   }
 
   return nextQuery;
@@ -319,6 +344,7 @@ export {
   DEFAULT_LIST_LIMIT,
   MAX_LIST_LIMIT,
   normalizeCrudListLimit,
+  normalizeCrudListCursor,
   requireCrudTableName,
   deriveRepositoryMappingFromResource,
   applyCrudListQueryFilters,

package/src/server/serviceMethods.js

@@ -0,0 +1,140 @@
+import { AppError, createValidationError } from "@jskit-ai/kernel/server/runtime/errors";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import { requireCrudNamespace } from "../shared/crudNamespaceSupport.js";
+import { createCrudFieldAccessRuntime } from "./fieldAccess.js";
+
+function createCrudServiceRuntime(resource = {}, { context = "crudService" } = {}) {
+  const namespace = requireCrudNamespace(resource?.resource, { context: `${context} resource.resource` });
+  const fieldAccessRuntime = createCrudFieldAccessRuntime(resource, { context });
+
+  return Object.freeze({
+    context,
+    namespace,
+    resource,
+    fieldAccessRuntime
+  });
+}
+
+function requireCrudServiceRepository(runtime = {}, repository = null) {
+  if (!repository) {
+    throw new Error(`${runtime?.context || "crudService"} requires repository.`);
+  }
+  return repository;
+}
+
+async function crudServiceListRecords(runtime, repository, fieldAccess = {}, query = {}, options = {}) {
+  const resolvedRepository = requireCrudServiceRepository(runtime, repository);
+  const result = await resolvedRepository.list(query, options);
+  return runtime.fieldAccessRuntime.filterReadableListResult(result, fieldAccess, {
+    action: "list",
+    query,
+    options,
+    context: options?.context
+  });
+}
+
+async function crudServiceGetRecord(runtime, repository, fieldAccess = {}, recordId, options = {}) {
+  const resolvedRepository = requireCrudServiceRepository(runtime, repository);
+  const record = await resolvedRepository.findById(recordId, options);
+  if (!record) {
+    throw new AppError(404, "Record not found.");
+  }
+
+  return runtime.fieldAccessRuntime.filterReadableRecord(record, fieldAccess, {
+    action: "view",
+    recordId,
+    options,
+    context: options?.context
+  });
+}
+
+async function crudServiceCreateRecord(runtime, repository, fieldAccess = {}, payload = {}, options = {}) {
+  const resolvedRepository = requireCrudServiceRepository(runtime, repository);
+  const writablePayload = await runtime.fieldAccessRuntime.enforceWritablePayload(payload, fieldAccess, {
+    action: "create",
+    payload,
+    options,
+    context: options?.context
+  });
+  const record = await resolvedRepository.create(writablePayload, options);
+  if (!record) {
+    throw new Error(`${runtime.namespace}Service could not load the created record.`);
+  }
+  return runtime.fieldAccessRuntime.filterReadableRecord(record, fieldAccess, {
+    action: "create",
+    options,
+    context: options?.context
+  });
+}
+
+async function crudServiceUpdateRecord(runtime, repository, fieldAccess = {}, recordId, payload = {}, options = {}) {
+  const resolvedRepository = requireCrudServiceRepository(runtime, repository);
+  const existingRecord = await resolvedRepository.findById(recordId, options);
+  if (!existingRecord) {
+    throw new AppError(404, "Record not found.");
+  }
+
+  const writablePayload = await runtime.fieldAccessRuntime.enforceWritablePayload(payload, fieldAccess, {
+    action: "update",
+    recordId,
+    payload,
+    options,
+    context: options?.context,
+    existingRecord
+  });
+
+  const patchBodyValidator = runtime.resource?.operations?.patch?.bodyValidator;
+  let normalizedPatch = writablePayload;
+  if (patchBodyValidator && typeof patchBodyValidator.normalize === "function") {
+    try {
+      normalizedPatch = await patchBodyValidator.normalize(writablePayload, {
+        phase: "crudPatch",
+        action: "update",
+        recordId,
+        existingRecord,
+        context: options?.context
+      });
+    } catch (error) {
+      const explicitFieldErrors = isRecord(error?.fieldErrors)
+        ? error.fieldErrors
+        : (
+            isRecord(error?.details?.fieldErrors)
+              ? error.details.fieldErrors
+              : null
+          );
+      if (explicitFieldErrors) {
+        throw createValidationError(explicitFieldErrors);
+      }
+      throw error;
+    }
+  }
+
+  const record = await resolvedRepository.updateById(recordId, normalizedPatch, options);
+  if (!record) {
+    throw new AppError(404, "Record not found.");
+  }
+  return runtime.fieldAccessRuntime.filterReadableRecord(record, fieldAccess, {
+    action: "update",
+    recordId,
+    options,
+    context: options?.context
+  });
+}
+
+async function crudServiceDeleteRecord(runtime, repository, fieldAccess = {}, recordId, options = {}) {
+  const resolvedRepository = requireCrudServiceRepository(runtime, repository);
+  const deleted = await resolvedRepository.deleteById(recordId, options);
+  if (!deleted) {
+    throw new AppError(404, "Record not found.");
+  }
+  return deleted;
+}
+
+export {
+  createCrudServiceRuntime,
+  crudServiceListRecords,
+  crudServiceGetRecord,
+  crudServiceCreateRecord,
+  crudServiceUpdateRecord,
+  crudServiceDeleteRecord
+};

package/test/createCrudRepositoryFromResource.test.js

@@ -22,13 +22,39 @@ function createListKnexDouble(
     let firstMode = false;
     const whereGroup = {
       where(...args) {
+        if (args.length === 1 && typeof args[0] === "function") {
+          calls.push(["innerWhereCallback"]);
+          args[0](whereGroup);
+          return whereGroup;
+        }
         calls.push(["where", ...args]);
         return whereGroup;
       },
       orWhere(...args) {
+        if (args.length === 1 && typeof args[0] === "function") {
+          calls.push(["innerOrWhereCallback"]);
+          args[0](whereGroup);
+          return whereGroup;
+        }
         calls.push(["orWhere", ...args]);
         return whereGroup;
       },
+      whereNull(...args) {
+        calls.push(["whereNull", ...args]);
+        return whereGroup;
+      },
+      orWhereNull(...args) {
+        calls.push(["orWhereNull", ...args]);
+        return whereGroup;
+      },
+      whereNotNull(...args) {
+        calls.push(["whereNotNull", ...args]);
+        return whereGroup;
+      },
+      orWhereNotNull(...args) {
+        calls.push(["orWhereNotNull", ...args]);
+        return whereGroup;
+      },
       whereRaw(...args) {
         calls.push(["whereRaw", ...args]);
         return whereGroup;
@@ -49,6 +75,31 @@ function createListKnexDouble(
         calls.push(["where", ...args]);
         return query;
       },
+      orWhere(...args) {
+        if (args.length === 1 && typeof args[0] === "function") {
+          calls.push(["orWhereCallback"]);
+          args[0](whereGroup);
+          return query;
+        }
+        calls.push(["orWhere", ...args]);
+        return query;
+      },
+      whereNull(...args) {
+        calls.push(["whereNull", ...args]);
+        return query;
+      },
+      orWhereNull(...args) {
+        calls.push(["orWhereNull", ...args]);
+        return query;
+      },
+      whereNotNull(...args) {
+        calls.push(["whereNotNull", ...args]);
+        return query;
+      },
+      orWhereNotNull(...args) {
+        calls.push(["orWhereNotNull", ...args]);
+        return query;
+      },
       whereRaw(...args) {
         calls.push(["whereRaw", ...args]);
         return query;
@@ -57,6 +108,10 @@ function createListKnexDouble(
         calls.push(["orderBy", ...args]);
         return query;
       },
+      orderByRaw(...args) {
+        calls.push(["orderByRaw", ...args]);
+        return query;
+      },
       clearOrder() {
         calls.push(["clearOrder"]);
         return query;
@@ -570,6 +625,226 @@ test("createCrudRepositoryFromResource allows list tuning through list config",
   assert.ok(calls.some((call) => call[0] === "limit" && call[1] === 3));
 });
 
+test("createCrudRepositoryFromResource supports declarative ordered list pagination", async () => {
+  const createRepository = createCrudRepositoryFromResource(createResourceFixture(), {
+    list: {
+      defaultLimit: 2,
+      orderBy: [
+        { column: "created_at", direction: "desc" }
+      ]
+    }
+  });
+  const rows = [
+    { contact_id: 9, first_name: "Tina", created_at: "2026-04-05T10:00:00.000Z" },
+    { contact_id: 7, first_name: "Tony", created_at: "2026-04-04T09:00:00.000Z" },
+    { contact_id: 6, first_name: "Tom", created_at: "2026-04-03T08:00:00.000Z" }
+  ];
+  const { knex, calls } = createListKnexDouble(rows);
+  const repository = createRepository(knex);
+
+  const result = await repository.list();
+
+  assert.deepEqual(result, {
+    items: [
+      { id: 9, firstName: "Tina" },
+      { id: 7, firstName: "Tony" }
+    ],
+    nextCursor: Buffer.from(
+      JSON.stringify({ values: ["2026-04-04T09:00:00.000Z", 7] }),
+      "utf8"
+    ).toString("base64url")
+  });
+  assert.ok(calls.some((call) => call[0] === "orderByRaw" && call[1] === "?? is null asc" && call[2]?.[0] === "created_at"));
+  assert.ok(calls.some((call) => call[0] === "orderBy" && call[1] === "created_at" && call[2] === "desc"));
+  assert.ok(calls.some((call) => call[0] === "orderBy" && call[1] === "contact_id" && call[2] === "desc"));
+});
+
+test("createCrudRepositoryFromResource applies ordered cursors using the configured sort tuple", async () => {
+  const createRepository = createCrudRepositoryFromResource(createResourceFixture(), {
+    list: {
+      orderBy: [
+        { column: "created_at", direction: "desc" }
+      ]
+    }
+  });
+  const { knex, calls } = createListKnexDouble([
+    { contact_id: 6, first_name: "Tom", created_at: "2026-04-03T08:00:00.000Z" }
+  ]);
+  const repository = createRepository(knex);
+  const cursor = Buffer.from(
+    JSON.stringify({ values: ["2026-04-04T09:00:00.000Z", 7] }),
+    "utf8"
+  ).toString("base64url");
+
+  await repository.list({
+    cursor,
+    limit: 2
+  });
+
+  assert.ok(calls.some((call) => call[0] === "where" && call[1] === "created_at" && call[2] === "<" && call[3] === "2026-04-04T09:00:00.000Z"));
+  assert.ok(calls.some((call) => call[0] === "where" && call[1] === "created_at" && call[2] === "2026-04-04T09:00:00.000Z"));
+  assert.ok(calls.some((call) => call[0] === "where" && call[1] === "contact_id" && call[2] === "<" && call[3] === 7));
+  assert.ok(!calls.some((call) => call[0] === "where" && call[1] === "contact_id" && call[2] === ">" && call[3] === 7));
+});
+
+test("createCrudRepositoryFromResource rejects malformed ordered cursors", async () => {
+  const createRepository = createCrudRepositoryFromResource(createResourceFixture(), {
+    list: {
+      orderBy: [
+        { column: "created_at", direction: "desc" }
+      ]
+    }
+  });
+  const { knex } = createListKnexDouble([]);
+  const repository = createRepository(knex);
+
+  await assert.rejects(
+    () => repository.list({
+      cursor: "not-a-real-cursor",
+      limit: 2
+    }),
+    /Invalid cursor/
+  );
+});
+
+test("createCrudRepositoryFromResource preserves Date cursor values for datetime sort columns", async () => {
+  const createRepository = createCrudRepositoryFromResource(createResourceFixture(), {
+    list: {
+      defaultLimit: 2,
+      orderBy: [
+        { column: "created_at", direction: "desc" }
+      ]
+    }
+  });
+  const createdAt = new Date("2026-04-04T09:00:00.000Z");
+  const olderCreatedAt = new Date("2026-04-03T08:00:00.000Z");
+  const { knex, calls } = createListKnexDouble([
+    { contact_id: 9, first_name: "Tina", created_at: createdAt },
+    { contact_id: 7, first_name: "Tony", created_at: createdAt },
+    { contact_id: 6, first_name: "Tom", created_at: olderCreatedAt }
+  ]);
+  const repository = createRepository(knex);
+
+  const first = await repository.list();
+  const firstCallCount = calls.length;
+
+  await repository.list({
+    cursor: first.nextCursor,
+    limit: 2
+  });
+
+  const secondCallEntries = calls.slice(firstCallCount);
+  const afterCall = secondCallEntries.find((call) => (
+    call[0] === "where" &&
+    call[1] === "created_at" &&
+    call[2] === "<"
+  ));
+  const equalityCall = secondCallEntries.find((call) => (
+    call[0] === "where" &&
+    call[1] === "created_at" &&
+    call[2] instanceof Date
+  ));
+
+  assert.ok(first.nextCursor);
+  assert.ok(afterCall);
+  assert.ok(afterCall[3] instanceof Date);
+  assert.equal(afterCall[3].toISOString(), createdAt.toISOString());
+  assert.ok(equalityCall);
+  assert.equal(equalityCall[2].toISOString(), createdAt.toISOString());
+});
+
+test("createCrudRepositoryFromResource ordered cursors handle null primary sort values", async () => {
+  const createRepository = createCrudRepositoryFromResource(createResourceFixture(), {
+    list: {
+      orderBy: [
+        { column: "created_at", direction: "desc" }
+      ]
+    }
+  });
+  const { knex, calls } = createListKnexDouble([
+    { contact_id: 6, first_name: "Tom", created_at: null }
+  ]);
+  const repository = createRepository(knex);
+  const cursor = Buffer.from(
+    JSON.stringify({ values: [null, 7] }),
+    "utf8"
+  ).toString("base64url");
+
+  await repository.list({
+    cursor,
+    limit: 2
+  });
+
+  assert.ok(calls.some((call) => call[0] === "whereNull" && call[1] === "created_at"));
+  assert.ok(calls.some((call) => call[0] === "where" && call[1] === "contact_id" && call[2] === "<" && call[3] === 7));
+  assert.ok(!calls.some((call) => call[0] === "whereNotNull" && call[1] === "created_at"));
+});
+
+test("createCrudRepositoryFromResource keeps ordered cursor prefix grouping for multi-column sorts", async () => {
+  const createRepository = createCrudRepositoryFromResource(createResourceFixture(), {
+    list: {
+      orderBy: [
+        { column: "created_at", direction: "desc" },
+        { column: "last_name", direction: "desc" }
+      ]
+    }
+  });
+  const { knex, calls } = createListKnexDouble([
+    {
+      contact_id: 6,
+      first_name: "Tom",
+      last_name: "Taylor",
+      created_at: "2026-04-03T08:00:00.000Z"
+    }
+  ]);
+  const repository = createRepository(knex);
+  const cursor = Buffer.from(
+    JSON.stringify({ values: ["2026-04-04T09:00:00.000Z", "Taylor", 7] }),
+    "utf8"
+  ).toString("base64url");
+
+  await repository.list({
+    cursor,
+    limit: 2
+  });
+
+  const createdAtEqualityIndex = calls.findIndex((call) => (
+    call[0] === "where" &&
+    call[1] === "created_at" &&
+    call[2] === "2026-04-04T09:00:00.000Z"
+  ));
+  const nestedGroupIndex = calls.findIndex((call, index) => (
+    index > createdAtEqualityIndex &&
+    call[0] === "innerWhereCallback"
+  ));
+  const lastNameAfterIndex = calls.findIndex((call, index) => (
+    index > nestedGroupIndex &&
+    call[0] === "where" &&
+    call[1] === "last_name" &&
+    call[2] === "<" &&
+    call[3] === "Taylor"
+  ));
+  const lastNameEqualityIndex = calls.findIndex((call, index) => (
+    index > lastNameAfterIndex &&
+    call[0] === "where" &&
+    call[1] === "last_name" &&
+    call[2] === "Taylor"
+  ));
+  const idAfterIndex = calls.findIndex((call, index) => (
+    index > lastNameEqualityIndex &&
+    call[0] === "where" &&
+    call[1] === "contact_id" &&
+    call[2] === "<" &&
+    call[3] === 7
+  ));
+
+  assert.ok(createdAtEqualityIndex >= 0);
+  assert.ok(nestedGroupIndex > createdAtEqualityIndex);
+  assert.ok(lastNameAfterIndex > nestedGroupIndex);
+  assert.ok(lastNameEqualityIndex > lastNameAfterIndex);
+  assert.ok(idAfterIndex > lastNameEqualityIndex);
+});
+
 test("createCrudRepositoryFromResource exposes listByIds for lookup providers", async () => {
   const createRepository = createCrudRepositoryFromResource(createResourceFixture());
   const { knex, calls } = createListKnexDouble([
@@ -1487,6 +1762,37 @@ test("createCrudRepositoryFromResource create hooks keep write-key filtering and
   assert.ok(state.insertPayloads[0].updated_at);
 });
 
+test("createCrudRepositoryFromResource create hooks support finalizeInsertPayload after write-key filtering", async () => {
+  const createRepository = createCrudRepositoryFromResource(createWritableHookResourceFixture());
+  const { knex, state } = createListKnexDouble([
+    {
+      contact_id: 11,
+      first_name: "Tony",
+      created_at: "2026-01-01 00:00:00",
+      updated_at: "2026-01-01 00:00:00"
+    }
+  ], {
+    insertResult: [11]
+  });
+  const repository = createRepository(knex);
+
+  await repository.create({
+    firstName: "Tony",
+    hiddenOwnerId: 44
+  }, {}, {
+    finalizeInsertPayload(insertPayload = {}, context = {}) {
+      return {
+        ...insertPayload,
+        hidden_owner_id: context.payload?.hiddenOwnerId ?? null
+      };
+    }
+  });
+
+  assert.equal(state.insertPayloads.length, 1);
+  assert.equal(state.insertPayloads[0].first_name, "Tony");
+  assert.equal(state.insertPayloads[0].hidden_owner_id, 44);
+});
+
 test("createCrudRepositoryFromResource create hooks reject read-phase hook keys", async () => {
   const createRepository = createCrudRepositoryFromResource(createWritableHookResourceFixture());
   const { knex } = createListKnexDouble([

package/test/createCrudServiceFromResource.test.js

@@ -107,6 +107,98 @@ test("createCrudServiceFromResource delegates service methods and applies 404 se
   );
 });
 
+test("createCrudServiceFromResource passes existing records to patch normalization", async () => {
+  const normalizeCalls = [];
+  const updateCalls = [];
+  const { createBaseService } = createCrudServiceFromResource({
+    resource: "contacts",
+    operations: {
+      patch: {
+        bodyValidator: {
+          normalize(payload = {}, context = {}) {
+            normalizeCalls.push({
+              payload,
+              existingRecord: context.existingRecord
+            });
+            return {
+              ...payload,
+              name: `${payload.name} normalized`
+            };
+          }
+        }
+      }
+    }
+  });
+
+  const service = createBaseService({
+    repository: createRepositoryDouble({
+      async findById(recordId) {
+        return recordId === 1
+          ? { id: 1, name: "Existing" }
+          : null;
+      },
+      async updateById(recordId, payload) {
+        updateCalls.push({ recordId, payload });
+        return { id: 1, ...payload };
+      }
+    })
+  });
+
+  const record = await service.updateRecord(1, { name: "B" }, {});
+
+  assert.deepEqual(normalizeCalls, [
+    {
+      payload: { name: "B" },
+      existingRecord: { id: 1, name: "Existing" }
+    }
+  ]);
+  assert.deepEqual(updateCalls, [
+    {
+      recordId: 1,
+      payload: { name: "B normalized" }
+    }
+  ]);
+  assert.deepEqual(record, { id: 1, name: "B normalized" });
+});
+
+test("createCrudServiceFromResource maps patch field errors to validation errors", async () => {
+  const { createBaseService } = createCrudServiceFromResource({
+    resource: "contacts",
+    operations: {
+      patch: {
+        bodyValidator: {
+          normalize() {
+            const error = new Error("Validation failed.");
+            error.details = {
+              fieldErrors: {
+                name: "Invalid."
+              }
+            };
+            throw error;
+          }
+        }
+      }
+    }
+  });
+
+  const service = createBaseService({
+    repository: createRepositoryDouble({
+      async findById() {
+        return { id: 1, name: "Existing" };
+      }
+    })
+  });
+
+  await assert.rejects(
+    () => service.updateRecord(1, { name: "B" }, {}),
+    (error) => (
+      error?.status === 400 &&
+      error?.message === "Validation failed." &&
+      error?.details?.fieldErrors?.name === "Invalid."
+    )
+  );
+});
+
 test("createCrudServiceFromResource validates required inputs", async () => {
   assert.throws(
     () => createCrudServiceFromResource({}),