@jskit-ai/crud-core 0.1.40 → 0.1.41

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/crud-core",
-  version: "0.1.40",
+  version: "0.1.41",
   kind: "runtime",
   description: "Shared CRUD helpers used by CRUD modules.",
   dependsOn: [
@@ -26,7 +26,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/crud-core": "0.1.40"
+        "@jskit-ai/crud-core": "0.1.41"
       },
       dev: {}
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/crud-core",
-  "version": "0.1.40",
+  "version": "0.1.41",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -26,11 +26,12 @@
   },
   "dependencies": {
     "@tanstack/vue-query": "^5.90.5",
-    "@jskit-ai/kernel": "0.1.32",
-    "@jskit-ai/realtime": "0.1.31",
-    "@jskit-ai/shell-web": "0.1.31",
-    "@jskit-ai/users-core": "0.1.42",
-    "@jskit-ai/users-web": "0.1.47",
+    "@jskit-ai/database-runtime": "0.1.33",
+    "@jskit-ai/kernel": "0.1.33",
+    "@jskit-ai/realtime": "0.1.32",
+    "@jskit-ai/shell-web": "0.1.32",
+    "@jskit-ai/users-core": "0.1.43",
+    "@jskit-ai/users-web": "0.1.48",
     "typebox": "^1.0.81"
   }
 }

package/src/client/composables/createCrudClientSupport.js

@@ -113,7 +113,7 @@ function useCrudClientContext(source = {}) {
     return resolveCrudRecordPathTemplates(listPathTemplate, recordIdParam);
   }
 
-  function resolveRecordParams(recordIdLike = 0, { recordIdParam = defaultRecordIdParam } = {}) {
+  function resolveRecordParams(recordIdLike = "", { recordIdParam = defaultRecordIdParam } = {}) {
     return resolveCrudRecordPathParams(recordIdLike, recordIdParam);
   }
 
@@ -122,7 +122,7 @@ function useCrudClientContext(source = {}) {
     return crudListQueryKey(normalizedSurfaceId, workspaceSlugToken.value, crudConfig.namespace);
   }
 
-  function viewQueryKey(surfaceId = "", recordId = 0) {
+  function viewQueryKey(surfaceId = "", recordId = "") {
     const normalizedSurfaceId = String(surfaceId || paths.currentSurfaceId.value || "").trim();
     return crudViewQueryKey(normalizedSurfaceId, workspaceSlugToken.value, recordId, crudConfig.namespace);
   }

package/src/client/composables/crudClientSupportHelpers.js

@@ -1,4 +1,4 @@
-import { normalizeText, normalizeQueryToken } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeQueryToken, normalizeRecordId, normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
 import { normalizeRouteVisibilityToken } from "@jskit-ai/kernel/shared/support/visibility";
 import { formatDateTime } from "@jskit-ai/kernel/shared/support";
 import {
@@ -58,13 +58,13 @@ function crudListQueryKey(surfaceId = "", workspaceSlug = "", namespace = "") {
   ]);
 }
 
-function crudViewQueryKey(surfaceId = "", workspaceSlug = "", recordId = 0, namespace = "") {
+function crudViewQueryKey(surfaceId = "", workspaceSlug = "", recordId = "", namespace = "") {
   return Object.freeze([
     ...crudScopeQueryKey(namespace),
     "view",
     normalizeQueryToken(surfaceId),
     normalizeQueryToken(workspaceSlug),
-    Number(recordId) || 0
+    normalizeRecordId(recordId, { fallback: "0" })
   ]);
 }
 
@@ -87,8 +87,9 @@ function toRouteRecordId(value) {
     return toRouteRecordId(value[0]);
   }
 
-  const parsed = Number(value);
-  return Number.isInteger(parsed) && parsed > 0 ? parsed : 0;
+  return normalizeRecordId(value, {
+    fallback: ""
+  });
 }
 
 function normalizeCrudRouteParamName(value, { context = "normalizeCrudRouteParamName" } = {}) {
@@ -120,7 +121,7 @@ function resolveCrudRecordPathTemplates(relativePath = "", recordIdParam = "reco
   });
 }
 
-function resolveCrudRecordPathParams(recordIdLike = 0, recordIdParam = "recordId") {
+function resolveCrudRecordPathParams(recordIdLike = "", recordIdParam = "recordId") {
   const normalizedRecordIdParam = normalizeCrudRouteParamName(recordIdParam, {
     context: "resolveCrudRecordPathParams"
   });
@@ -130,7 +131,7 @@ function resolveCrudRecordPathParams(recordIdLike = 0, recordIdParam = "recordId
   }
 
   return Object.freeze({
-    [normalizedRecordIdParam]: String(normalizedRecordId)
+    [normalizedRecordIdParam]: normalizedRecordId
   });
 }
 

package/src/server/createCrudRepositoryFromResource.js

@@ -8,6 +8,7 @@ import {
   crudRepositoryUpdateById,
   crudRepositoryDeleteById
 } from "./repositoryMethods.js";
+import { createWithTransaction } from "@jskit-ai/database-runtime/shared";
 
 function createCrudRepositoryFromResource(resource = {}, { context = "crudRepository", list = {} } = {}) {
   const runtime = createCrudRepositoryRuntime(resource, {
@@ -19,6 +20,7 @@ function createCrudRepositoryFromResource(resource = {}, { context = "crudReposi
     if (typeof knex !== "function") {
       throw new TypeError("crudRepository requires knex.");
     }
+    const withTransaction = createWithTransaction(knex);
 
     async function listRecords(query = {}, callOptions = {}, hooks = null) {
       return crudRepositoryList(runtime, knex, query, options, callOptions, hooks);
@@ -49,6 +51,7 @@ function createCrudRepositoryFromResource(resource = {}, { context = "crudReposi
     }
 
     return Object.freeze({
+      withTransaction,
       list: listRecords,
       findById,
       listByIds,

package/src/server/lookupHydration.js

@@ -529,7 +529,7 @@ function resolveLookupVisibilityContext(
     nextVisibilityContext.scopeOwnerId = parentVisibilityContext.scopeOwnerId;
   }
   if (providerOwnershipFilter === "user" || providerOwnershipFilter === "workspace_user") {
-    nextVisibilityContext.userOwnerId = parentVisibilityContext.userOwnerId;
+    nextVisibilityContext.userId = parentVisibilityContext.userId;
   }
 
   return nextVisibilityContext;

package/src/server/repositoryMethods.js

@@ -1,7 +1,7 @@
-import { toInsertDateTime } from "@jskit-ai/database-runtime/shared";
+import { resolveInsertedRecordId, toInsertDateTime } from "@jskit-ai/database-runtime/shared";
 import { applyVisibility, applyVisibilityOwners } from "@jskit-ai/database-runtime/shared/visibility";
 import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
-import { normalizeText, normalizeUniqueTextList } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeRecordId, normalizeText, normalizeUniqueTextList } from "@jskit-ai/kernel/shared/support/normalize";
 import { Check, Errors } from "typebox/value";
 import {
   DEFAULT_LIST_LIMIT,
@@ -29,6 +29,14 @@ const ORDERED_LIST_CURSOR_VALUE_TYPE_KEY = "__jskitCursorValueType";
 const ORDERED_LIST_CURSOR_VALUE_KEY = "value";
 const ORDERED_LIST_CURSOR_VALUE_TYPE_DATE = "date";
 
+function requireCrudRecordId(value, { context = "crudRepository" } = {}) {
+  const recordId = normalizeRecordId(value, { fallback: null });
+  if (!recordId) {
+    throw new TypeError(`${context} requires recordId.`);
+  }
+  return recordId;
+}
+
 function resolveRepositoryDefaults(resource = {}, repositoryMapping = {}) {
   const resourceName = normalizeText(resource.resource);
   const tableName = normalizeText(resource.tableName) || resourceName;
@@ -757,7 +765,12 @@ async function crudRepositoryList(runtime, knex, query = {}, repositoryOptions =
   const pageRows = hasMore ? rows.slice(0, normalizedLimit) : rows;
   const items = [];
   for (const row of pageRows) {
-    const mappedRecord = mapRecordRow(row, runtime.mapping.outputKeys, runtime.mapping.columnOverrides);
+    const mappedRecord = mapRecordRow(
+      row,
+      runtime.mapping.outputKeys,
+      runtime.mapping.columnOverrides,
+      { recordIdKeys: runtime.mapping.outputRecordIdKeys }
+    );
     if (!mappedRecord) {
       continue;
     }
@@ -855,6 +868,7 @@ async function crudRepositoryList(runtime, knex, query = {}, repositoryOptions =
 
 async function crudRepositoryFindById(runtime, knex, recordId, repositoryOptions = {}, callOptions = {}, hooks = null) {
   const { client, tableName, idColumn, visible } = resolveCrudRepositoryCall(runtime, knex, repositoryOptions, callOptions);
+  const normalizedRecordId = requireCrudRecordId(recordId, { context: "crudRepositoryFindById" });
   const methodHooks = normalizeCrudRepositoryHooks(
     hooks,
     ["modifyQuery", "afterQuery", "transformReturnedRecord", "finalizeOutput"],
@@ -895,12 +909,17 @@ async function crudRepositoryFindById(runtime, knex, recordId, repositoryOptions
   dbQuery = dbQuery
     .where(visible)
     .where({
-      [idColumn]: Number(recordId)
+      [idColumn]: normalizedRecordId
     });
 
   const row = await dbQuery.first();
 
-  const mappedRecord = mapRecordRow(row, runtime.mapping.outputKeys, runtime.mapping.columnOverrides);
+  const mappedRecord = mapRecordRow(
+    row,
+    runtime.mapping.outputKeys,
+    runtime.mapping.columnOverrides,
+    { recordIdKeys: runtime.mapping.outputRecordIdKeys }
+  );
   let records = [];
   if (mappedRecord) {
     const normalizedRecord = await normalizeRepositoryOutputRecord(runtime, mappedRecord, {
@@ -1032,7 +1051,12 @@ async function crudRepositoryListByIds(runtime, knex, ids = [], repositoryOption
 
   const records = [];
   for (const row of rows) {
-    const mappedRecord = mapRecordRow(row, runtime.mapping.outputKeys, runtime.mapping.columnOverrides);
+    const mappedRecord = mapRecordRow(
+      row,
+      runtime.mapping.outputKeys,
+      runtime.mapping.columnOverrides,
+      { recordIdKeys: runtime.mapping.outputRecordIdKeys }
+    );
     if (!mappedRecord) {
       continue;
     }
@@ -1206,7 +1230,11 @@ async function crudRepositoryCreate(runtime, knex, payload = {}, repositoryOptio
   );
   createQuery = createHookResult.queryBuilder;
 
-  const [recordId] = await createQuery.insert(withOwners);
+  const insertResult = await createQuery.insert(withOwners);
+  const recordId = resolveInsertedRecordId(insertResult, { fallback: null });
+  if (!recordId) {
+    throw new Error("crudRepositoryCreate could not resolve inserted id.");
+  }
 
   const createdRecord = await crudRepositoryFindById(runtime, knex, recordId, repositoryOptions, {
     ...callOptions,
@@ -1237,6 +1265,7 @@ async function crudRepositoryCreate(runtime, knex, payload = {}, repositoryOptio
 
 async function crudRepositoryUpdateById(runtime, knex, recordId, patch = {}, repositoryOptions = {}, callOptions = {}, hooks = null) {
   const { client, tableName, idColumn, visible } = resolveCrudRepositoryCall(runtime, knex, repositoryOptions, callOptions);
+  const normalizedRecordId = requireCrudRecordId(recordId, { context: "crudRepositoryUpdateById" });
   const methodHooks = normalizeCrudRepositoryHooks(hooks, ["modifyPatch", "modifyQuery", "afterWrite"], {
     context: "crudRepositoryUpdateById"
   });
@@ -1299,7 +1328,7 @@ async function crudRepositoryUpdateById(runtime, knex, recordId, patch = {}, rep
   updateQuery = updateQuery
     .where(visible)
     .where({
-      [idColumn]: Number(recordId)
+      [idColumn]: normalizedRecordId
     });
 
   await updateQuery.update(dbPatch);
@@ -1333,6 +1362,7 @@ async function crudRepositoryUpdateById(runtime, knex, recordId, patch = {}, rep
 
 async function crudRepositoryDeleteById(runtime, knex, recordId, repositoryOptions = {}, callOptions = {}, hooks = null) {
   const { client, tableName, idColumn, visible } = resolveCrudRepositoryCall(runtime, knex, repositoryOptions, callOptions);
+  const normalizedRecordId = requireCrudRecordId(recordId, { context: "crudRepositoryDeleteById" });
   const methodHooks = normalizeCrudRepositoryHooks(hooks, ["modifyQuery", "finalizeOutput", "afterWrite"], {
     context: "crudRepositoryDeleteById"
   });
@@ -1394,7 +1424,7 @@ async function crudRepositoryDeleteById(runtime, knex, recordId, repositoryOptio
   deleteQuery = deleteQuery
     .where(visible)
     .where({
-      [idColumn]: Number(recordId)
+      [idColumn]: normalizedRecordId
     });
 
   await deleteQuery.delete();

package/src/server/repositorySupport.js

@@ -1,5 +1,7 @@
+import { normalizeDbRecordId } from "@jskit-ai/database-runtime/shared";
 import { AppError } from "@jskit-ai/kernel/server/runtime/errors";
-import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { RECORD_ID_PATTERN } from "@jskit-ai/kernel/shared/validators";
+import { normalizeRecordId, 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";
 import {
@@ -13,24 +15,24 @@ const MAX_LIST_LIMIT = 100;
 
 function normalizeCrudListCursor(cursor = null, { allowEmpty = true } = {}) {
   if (cursor === undefined || cursor === null) {
-    return allowEmpty === true ? 0 : null;
+    return allowEmpty === true ? "" : null;
   }
 
   const normalizedCursor = typeof cursor === "string"
     ? cursor.trim()
     : cursor;
   if (normalizedCursor === "" || normalizedCursor === 0 || normalizedCursor === "0") {
-    return allowEmpty === true ? 0 : null;
+    return allowEmpty === true ? "" : null;
   }
 
-  const numericCursor = Number(normalizedCursor);
-  if (!Number.isInteger(numericCursor) || numericCursor < 1) {
+  const recordId = normalizeRecordId(normalizedCursor, { fallback: null });
+  if (!recordId) {
     throw new AppError(400, "Invalid cursor.", {
       code: "INVALID_CURSOR"
     });
   }
 
-  return numericCursor;
+  return recordId;
 }
 
 function normalizeCrudListLimit(value, { fallback = DEFAULT_LIST_LIMIT, max = MAX_LIST_LIMIT } = {}) {
@@ -152,6 +154,29 @@ function schemaIncludesStringType(schema = {}) {
   return variants.some((entry) => schemaIncludesStringType(entry));
 }
 
+function schemaIncludesRecordIdType(schema = {}) {
+  if (!schema || typeof schema !== "object" || Array.isArray(schema)) {
+    return false;
+  }
+
+  const type = Array.isArray(schema.type)
+    ? schema.type.map((entry) => normalizeText(entry).toLowerCase()).filter(Boolean)
+    : normalizeText(schema.type).toLowerCase();
+  const hasStringType = Array.isArray(type)
+    ? type.includes("string")
+    : type === "string";
+  if (hasStringType && normalizeText(schema.pattern) === RECORD_ID_PATTERN) {
+    return true;
+  }
+
+  const variants = Array.isArray(schema.anyOf)
+    ? schema.anyOf
+    : Array.isArray(schema.oneOf)
+      ? schema.oneOf
+      : [];
+  return variants.some((entry) => schemaIncludesRecordIdType(entry));
+}
+
 function deriveRepositoryMappingFromResource(resource = {}, { context = "crudRepository" } = {}) {
   if (!resource || typeof resource !== "object" || Array.isArray(resource)) {
     throw new TypeError(`${context} requires resource object.`);
@@ -214,20 +239,33 @@ function deriveRepositoryMappingFromResource(resource = {}, { context = "crudRep
     parentFilterColumns[key] = columnName;
   }
 
+  const outputRecordIdKeys = [];
+  for (const [key, schema] of Object.entries(outputProperties)) {
+    if (schemaIncludesRecordIdType(schema)) {
+      outputRecordIdKeys.push(key);
+    }
+  }
+
   return Object.freeze({
     outputKeys,
     writeKeys,
     columnOverrides: Object.freeze(columnOverrides),
     listSearchColumns: Object.freeze(listSearchColumns),
-    parentFilterColumns: Object.freeze(parentFilterColumns)
+    parentFilterColumns: Object.freeze(parentFilterColumns),
+    outputRecordIdKeys: Object.freeze(outputRecordIdKeys)
   });
 }
 
-function mapRecordRow(row, fieldKeys = [], overrides = {}) {
+function mapRecordRow(row, fieldKeys = [], overrides = {}, { recordIdKeys = [] } = {}) {
   if (!row) {
     return null;
   }
 
+  const recordIdKeySet = new Set(
+    (Array.isArray(recordIdKeys) ? recordIdKeys : [])
+      .map((key) => String(key || "").trim())
+      .filter(Boolean)
+  );
   const mapped = {};
   for (const key of fieldKeys) {
     const normalizedKey = String(key || "").trim();
@@ -235,7 +273,15 @@ function mapRecordRow(row, fieldKeys = [], overrides = {}) {
     if (!normalizedKey || !columnName) {
       continue;
     }
-    mapped[normalizedKey] = row[columnName];
+
+    const rawValue = row[columnName];
+    if (recordIdKeySet.has(normalizedKey)) {
+      const normalizedIdValue = normalizeDbRecordId(rawValue, { fallback: null });
+      mapped[normalizedKey] = normalizedIdValue || rawValue;
+      continue;
+    }
+
+    mapped[normalizedKey] = rawValue;
   }
   return mapped;
 }
@@ -244,7 +290,7 @@ function applyCrudListQueryFilters(
   query,
   {
     idColumn = "id",
-    cursor = 0,
+    cursor = "",
     applyCursor = true,
     q = "",
     searchColumns = [],
@@ -307,7 +353,7 @@ function applyCrudListQueryFilters(
   const normalizedIdColumn = String(idColumn || "").trim() || "id";
   if (applyCursor !== false) {
     const normalizedCursor = normalizeCrudListCursor(cursor);
-    if (normalizedCursor > 0) {
+    if (normalizedCursor) {
       nextQuery = nextQuery.where(normalizedIdColumn, ">", normalizedCursor);
     }
   }

package/test/createCrudClientSupport.test.js

@@ -61,7 +61,7 @@ test("crudListQueryKey and crudViewQueryKey normalize cache keys", () => {
     "view",
     "admin",
     "tonymobily3",
-    12
+    "12"
   ]);
 });
 
@@ -85,9 +85,9 @@ test("invalidateCrudQueries invalidates by CRUD namespace scope key", async () =
 });
 
 test("toRouteRecordId parses scalar and array params safely", () => {
-  assert.equal(toRouteRecordId("42"), 42);
-  assert.equal(toRouteRecordId(["7"]), 7);
-  assert.equal(toRouteRecordId("not-a-number"), 0);
+  assert.equal(toRouteRecordId("42"), "42");
+  assert.equal(toRouteRecordId(["7"]), "7");
+  assert.equal(toRouteRecordId("not-a-number"), "");
 });
 
 test("normalizeCrudRouteParamName validates route parameter names", () => {
@@ -114,7 +114,7 @@ test("resolveCrudRecordPathTemplates supports custom route parameter names", ()
 });
 
 test("resolveCrudRecordPathParams maps record ids to selected route parameter names", () => {
-  assert.deepEqual(resolveCrudRecordPathParams(42, "addressId"), { addressId: "42" });
+  assert.deepEqual(resolveCrudRecordPathParams("42", "addressId"), { addressId: "42" });
   assert.deepEqual(resolveCrudRecordPathParams("7", "recordId"), { recordId: "7" });
   assert.deepEqual(resolveCrudRecordPathParams("invalid", "addressId"), {});
 });

package/test/createCrudRepositoryFromResource.test.js

@@ -1,7 +1,20 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import { RECORD_ID_PATTERN } from "@jskit-ai/kernel/shared/validators";
 import { createCrudRepositoryFromResource } from "../src/server/createCrudRepositoryFromResource.js";
 
+const recordIdSchema = Object.freeze({
+  type: "string",
+  pattern: RECORD_ID_PATTERN
+});
+
+const nullableRecordIdSchema = Object.freeze({
+  anyOf: [
+    recordIdSchema,
+    { type: "null" }
+  ]
+});
+
 function createListKnexDouble(
   rows = [],
   {
@@ -185,7 +198,7 @@ function createResourceFixture() {
           schema: {
             type: "object",
             properties: {
-              id: { type: "integer" },
+              id: recordIdSchema,
               firstName: { type: "string" }
             }
           }
@@ -222,10 +235,10 @@ function createLookupResourceFixture() {
           schema: {
             type: "object",
             properties: {
-              id: { type: "integer" },
+              id: recordIdSchema,
               firstName: { type: "string" },
-              primaryVetId: { type: "integer" },
-              secondaryVetId: { type: ["integer", "null"] },
+              primaryVetId: recordIdSchema,
+              secondaryVetId: nullableRecordIdSchema,
               lookups: {
                 type: "object"
               }
@@ -239,8 +252,8 @@ function createLookupResourceFixture() {
             type: "object",
             properties: {
               firstName: { type: "string" },
-              primaryVetId: { type: "integer" },
-              secondaryVetId: { type: "integer" }
+              primaryVetId: recordIdSchema,
+              secondaryVetId: recordIdSchema
             }
           }
         }
@@ -289,10 +302,10 @@ function createLookupResourceWithCustomContainerKeyFixture() {
           schema: {
             type: "object",
             properties: {
-              id: { type: "integer" },
+              id: recordIdSchema,
               firstName: { type: "string" },
-              primaryVetId: { type: "integer" },
-              secondaryVetId: { type: "integer" },
+              primaryVetId: recordIdSchema,
+              secondaryVetId: recordIdSchema,
               lookupData: {
                 type: "object"
               }
@@ -306,8 +319,8 @@ function createLookupResourceWithCustomContainerKeyFixture() {
             type: "object",
             properties: {
               firstName: { type: "string" },
-              primaryVetId: { type: "integer" },
-              secondaryVetId: { type: "integer" }
+              primaryVetId: recordIdSchema,
+              secondaryVetId: recordIdSchema
             }
           }
         }
@@ -351,7 +364,7 @@ function createCollectionLookupResourceFixture() {
           schema: {
             type: "object",
             properties: {
-              id: { type: "integer" },
+              id: recordIdSchema,
               firstName: { type: "string" },
               lookups: {
                 type: "object"
@@ -400,9 +413,9 @@ function createPetsLookupBackToContactsResourceFixture() {
           schema: {
             type: "object",
             properties: {
-              id: { type: "integer" },
+              id: recordIdSchema,
               name: { type: "string" },
-              customerId: { type: "integer" },
+              customerId: recordIdSchema,
               lookups: {
                 type: "object"
               }
@@ -450,14 +463,14 @@ function createNormalizedResourceFixture() {
           schema: {
             type: "object",
             properties: {
-              id: { type: "integer" },
+              id: recordIdSchema,
               firstName: { type: "string" }
             },
             required: ["id", "firstName"]
           },
           normalize(payload = {}) {
             return {
-              id: Number(payload.id),
+              id: String(payload.id || ""),
               firstName: String(payload.firstName || "").trim()
             };
           }
@@ -494,7 +507,7 @@ function createWritableHookResourceFixture() {
           schema: {
             type: "object",
             properties: {
-              id: { type: "integer" },
+              id: recordIdSchema,
               firstName: { type: "string" },
               createdAt: { type: "string" },
               updatedAt: { type: "string" }
@@ -545,7 +558,7 @@ test("createCrudRepositoryFromResource requires table metadata from resource", (
               schema: {
                 type: "object",
                 properties: {
-                  id: { type: "integer" }
+                  id: recordIdSchema
                 }
               }
             }
@@ -576,21 +589,21 @@ test("createCrudRepositoryFromResource defaults table and id columns from resour
   const repository = createRepository(knex);
 
   const result = await repository.list({
-    cursor: 2,
+    cursor: "2",
     q: "to"
   });
 
   assert.deepEqual(result, {
     items: [
       {
-        id: 3,
+        id: "3",
         firstName: "Tony"
       }
     ],
     nextCursor: null
   });
   assert.equal(calls[0][1], "contacts_table");
-  assert.ok(calls.some((call) => call[0] === "where" && call[1] === "contact_id" && call[2] === ">" && call[3] === 2));
+  assert.ok(calls.some((call) => call[0] === "where" && call[1] === "contact_id" && call[2] === ">" && call[3] === "2"));
 });
 
 test("createCrudRepositoryFromResource createRepository requires knex", () => {
@@ -601,6 +614,22 @@ test("createCrudRepositoryFromResource createRepository requires knex", () => {
   );
 });
 
+test("createCrudRepositoryFromResource adds withTransaction to repository instances", async () => {
+  const createRepository = createCrudRepositoryFromResource(createResourceFixture());
+  const knex = Object.assign(() => {
+    throw new Error("query execution not expected");
+  }, {
+    async transaction(work) {
+      return work({ trxId: "trx-1" });
+    }
+  });
+
+  const repository = createRepository(knex);
+  assert.equal(typeof repository.withTransaction, "function");
+  const result = await repository.withTransaction(async (trx) => ({ id: trx.trxId }));
+  assert.deepEqual(result, { id: "trx-1" });
+});
+
 test("createCrudRepositoryFromResource allows list tuning through list config", async () => {
   const createRepository = createCrudRepositoryFromResource(createResourceFixture(), {
     list: {
@@ -646,8 +675,8 @@ test("createCrudRepositoryFromResource supports declarative ordered list paginat
 
   assert.deepEqual(result, {
     items: [
-      { id: 9, firstName: "Tina" },
-      { id: 7, firstName: "Tony" }
+      { id: "9", firstName: "Tina" },
+      { id: "7", firstName: "Tony" }
     ],
     nextCursor: Buffer.from(
       JSON.stringify({ values: ["2026-04-04T09:00:00.000Z", 7] }),
@@ -855,11 +884,11 @@ test("createCrudRepositoryFromResource exposes listByIds for lookup providers",
   ]);
   const repository = createRepository(knex);
 
-  const records = await repository.listByIds([3, 3, 4]);
+  const records = await repository.listByIds(["3", "3", "4"]);
 
   assert.equal(records.length, 1);
   assert.deepEqual(records[0], {
-    id: 3,
+    id: "3",
     firstName: "Tony"
   });
   assert.ok(calls.some((call) => call[0] === "whereIn" && call[1] === "contact_id"));
@@ -879,7 +908,7 @@ test("createCrudRepositoryFromResource exposes listByForeignIds for arbitrary ou
 
   assert.equal(records.length, 1);
   assert.deepEqual(records[0], {
-    id: 3,
+    id: "3",
     firstName: "Tony"
   });
   assert.ok(calls.some((call) => call[0] === "whereIn" && call[1] === "first_name"));
@@ -913,7 +942,7 @@ test("createCrudRepositoryFromResource listByIds fails fast when valueKey is not
 
   await assert.rejects(
     () =>
-      repository.listByIds([3], {
+      repository.listByIds(["3"], {
         valueKey: "externalCustomerId"
       }),
     /valueKey "externalCustomerId" to exist in output schema/
@@ -930,10 +959,10 @@ test("createCrudRepositoryFromResource normalizes listByIds output using resourc
   ]);
   const repository = createRepository(knex);
 
-  const result = await repository.listByIds([3]);
+  const result = await repository.listByIds(["3"]);
   assert.deepEqual(result, [
     {
-      id: 3,
+      id: "3",
       firstName: "Tony"
     }
   ]);
@@ -943,14 +972,14 @@ test("createCrudRepositoryFromResource fails when mapped output violates resourc
   const createRepository = createCrudRepositoryFromResource(createResourceFixture());
   const { knex } = createListKnexDouble([
     {
-      contact_id: "3",
+      contact_id: "invalid-id",
       first_name: "Tony"
     }
   ]);
   const repository = createRepository(knex);
 
   await assert.rejects(
-    () => repository.listByIds([3]),
+    () => repository.listByIds(["3"]),
     /output validation failed/
   );
 });
@@ -983,8 +1012,8 @@ test("createCrudRepositoryFromResource hydrates lookup relations by default and
             options
           });
           return [
-            { id: 10, name: "Vet A" },
-            { id: 12, name: "Vet B" }
+            { id: "10", name: "Vet A" },
+            { id: "12", name: "Vet B" }
           ];
         }
       };
@@ -994,16 +1023,16 @@ test("createCrudRepositoryFromResource hydrates lookup relations by default and
   const result = await repository.list({});
 
   assert.equal(lookupCalls.length, 1);
-  assert.deepEqual(lookupCalls[0].ids, [10, 12]);
+  assert.deepEqual(lookupCalls[0].ids, ["10", "12"]);
   assert.equal(lookupCalls[0].options.include, "*");
   assert.equal(lookupCalls[0].options.lookupDepth, 1);
   assert.equal(lookupCalls[0].options.lookupMaxDepth, 3);
   assert.deepEqual(result.items[0].lookups, {
-    primaryVetId: { id: 10, name: "Vet A" },
-    secondaryVetId: { id: 12, name: "Vet B" }
+    primaryVetId: { id: "10", name: "Vet A" },
+    secondaryVetId: { id: "12", name: "Vet B" }
   });
   assert.deepEqual(result.items[1].lookups, {
-    primaryVetId: { id: 10, name: "Vet A" },
+    primaryVetId: { id: "10", name: "Vet A" },
     secondaryVetId: null
   });
 });
@@ -1023,8 +1052,8 @@ test("createCrudRepositoryFromResource writes hydrated lookups into custom outpu
       return {
         async listByIds() {
           return [
-            { id: 10, name: "Vet A" },
-            { id: 12, name: "Vet B" }
+            { id: "10", name: "Vet A" },
+            { id: "12", name: "Vet B" }
           ];
         }
       };
@@ -1034,8 +1063,8 @@ test("createCrudRepositoryFromResource writes hydrated lookups into custom outpu
   const result = await repository.list({});
   assert.equal(Object.hasOwn(result.items[0], "lookups"), false);
   assert.deepEqual(result.items[0].lookupData, {
-    primaryVetId: { id: 10, name: "Vet A" },
-    secondaryVetId: { id: 12, name: "Vet B" }
+    primaryVetId: { id: "10", name: "Vet A" },
+    secondaryVetId: { id: "12", name: "Vet B" }
   });
 });
 
@@ -1113,7 +1142,7 @@ test("createCrudRepositoryFromResource forwards nested include paths to child lo
             ids,
             options
           });
-          return [{ id: 10, name: "Vet A" }, { id: 12, name: "Vet B" }];
+          return [{ id: "10", name: "Vet A" }, { id: "12", name: "Vet B" }];
         }
       };
     }
@@ -1147,7 +1176,7 @@ test("createCrudRepositoryFromResource forwards wildcard nested include paths to
             ids,
             options
           });
-          return [{ id: 10, name: "Vet A" }, { id: 12, name: "Vet B" }];
+          return [{ id: "10", name: "Vet A" }, { id: "12", name: "Vet B" }];
         }
       };
     }
@@ -1182,7 +1211,7 @@ test("createCrudRepositoryFromResource remaps child lookup visibility for public
             ids,
             options
           });
-          return [{ id: 10, name: "Vet A" }, { id: 12, name: "Vet B" }];
+          return [{ id: "10", name: "Vet A" }, { id: "12", name: "Vet B" }];
         }
       };
     }
@@ -1222,7 +1251,7 @@ test("createCrudRepositoryFromResource remaps child lookup visibility for worksp
             ids,
             options
           });
-          return [{ id: 10, name: "Vet A" }, { id: 12, name: "Vet B" }];
+          return [{ id: "10", name: "Vet A" }, { id: "12", name: "Vet B" }];
         }
       };
     }
@@ -1232,7 +1261,7 @@ test("createCrudRepositoryFromResource remaps child lookup visibility for worksp
     visibilityContext: {
       visibility: "workspace_user",
       scopeOwnerId: "workspace-1",
-      userOwnerId: "user-1"
+      userId: "user-1"
     }
   });
 
@@ -1299,9 +1328,9 @@ test("createCrudRepositoryFromResource hydrates collection relations through lis
             options
           });
           return [
-            { id: 11, name: "Milo", customerId: 3 },
-            { id: 12, name: "Luna", customerId: 3 },
-            { id: 20, name: "Ruby", customerId: 4 }
+            { id: "11", name: "Milo", customerId: "3" },
+            { id: "12", name: "Luna", customerId: "3" },
+            { id: "20", name: "Ruby", customerId: "4" }
           ];
         }
       };
@@ -1313,7 +1342,7 @@ test("createCrudRepositoryFromResource hydrates collection relations through lis
   });
 
   assert.equal(lookupCalls.length, 1);
-  assert.deepEqual(lookupCalls[0].ids, [3, 4]);
+  assert.deepEqual(lookupCalls[0].ids, ["3", "4"]);
   assert.equal(lookupCalls[0].options.include, "none");
   assert.equal(lookupCalls[0].options.valueKey, "customerId");
   assert.deepEqual(result.items[0].lookups?.pets?.map((item) => item.name), ["Milo", "Luna"]);
@@ -1402,7 +1431,7 @@ test("createCrudRepositoryFromResource forwards configured lookup maxDepth to ch
             ids,
             options
           });
-          return [{ id: 10, name: "Vet A" }, { id: 12, name: "Vet B" }];
+          return [{ id: "10", name: "Vet A" }, { id: "12", name: "Vet B" }];
         }
       };
     }
@@ -1598,7 +1627,7 @@ test("createCrudRepositoryFromResource list hooks keep visibility and canonical
   const repository = createRepository(knex);
 
   await repository.list({
-    cursor: 2,
+    cursor: "2",
     limit: 5
   }, {
     visibilityContext: {
@@ -1612,8 +1641,8 @@ test("createCrudRepositoryFromResource list hooks keep visibility and canonical
     }
   });
 
-  assert.ok(calls.some((call) => call[0] === "where" && call[1] === "contact_id" && call[2] === ">" && call[3] === 2));
-  assert.ok(calls.some((call) => call[0] === "where" && call[1] === "workspace_owner_id" && call[2] === "workspace-1"));
+  assert.ok(calls.some((call) => call[0] === "where" && call[1] === "contact_id" && call[2] === ">" && call[3] === "2"));
+  assert.ok(calls.some((call) => call[0] === "where" && call[1] === "workspace_id" && call[2] === "workspace-1"));
   assert.ok(calls.some((call) => call[0] === "clearOrder"));
   assert.ok(calls.some((call) => call[0] === "clear" && call[1] === "limit"));
   assert.ok(calls.some((call) => call[0] === "orderBy" && call[1] === "contact_id" && call[2] === "asc"));
@@ -1630,7 +1659,7 @@ test("createCrudRepositoryFromResource findById hooks keep visibility and id pre
   ]);
   const repository = createRepository(knex);
 
-  await repository.findById(7, {
+  await repository.findById("7", {
     visibilityContext: {
       visibility: "workspace",
       scopeOwnerId: "workspace-1"
@@ -1643,8 +1672,8 @@ test("createCrudRepositoryFromResource findById hooks keep visibility and id pre
   });
 
   assert.ok(calls.some((call) => call[0] === "where" && call[1] === "contact_id" && call[2] === 999));
-  assert.ok(calls.some((call) => call[0] === "where" && call[1] === "workspace_owner_id" && call[2] === "workspace-1"));
-  assert.ok(calls.some((call) => call[0] === "where" && call[1]?.contact_id === 7));
+  assert.ok(calls.some((call) => call[0] === "where" && call[1] === "workspace_id" && call[2] === "workspace-1"));
+  assert.ok(calls.some((call) => call[0] === "where" && call[1]?.contact_id === "7"));
 });
 
 test("createCrudRepositoryFromResource findById hooks share state between query and transformReturnedRecord", async () => {
@@ -1657,7 +1686,7 @@ test("createCrudRepositoryFromResource findById hooks share state between query
   ]);
   const repository = createRepository(knex);
 
-  const record = await repository.findById(7, {}, {
+  const record = await repository.findById("7", {}, {
     modifyQuery(_dbQuery, context = {}) {
       context.state.recordTag = "from-state";
     },
@@ -1712,7 +1741,7 @@ test("createCrudRepositoryFromResource listByIds hooks support afterQuery/transf
     }
   });
 
-  assert.deepEqual(items.map((item) => item.id), [4, 3]);
+  assert.deepEqual(items.map((item) => item.id), ["4", "3"]);
   assert.deepEqual(items.map((item) => item.nameTag), ["SAM", "TONY"]);
 });
 
@@ -1742,7 +1771,7 @@ test("createCrudRepositoryFromResource create hooks keep write-key filtering and
       return {
         ...payload,
         unexpectedField: "blocked",
-        workspaceOwnerId: "blocked"
+        workspaceId: "blocked"
       };
     },
     modifyQuery(_dbQuery, context = {}) {
@@ -1756,8 +1785,8 @@ test("createCrudRepositoryFromResource create hooks keep write-key filtering and
   assert.deepEqual(state.insertPayloads[0].first_name, "Tony");
   assert.equal(Object.hasOwn(state.insertPayloads[0], "unexpectedField"), false);
   assert.equal(Object.hasOwn(state.insertPayloads[0], "unexpectedFieldFromQuery"), false);
-  assert.equal(Object.hasOwn(state.insertPayloads[0], "workspaceOwnerId"), false);
-  assert.equal(state.insertPayloads[0].workspace_owner_id, "workspace-1");
+  assert.equal(Object.hasOwn(state.insertPayloads[0], "workspaceId"), false);
+  assert.equal(state.insertPayloads[0].workspace_id, "workspace-1");
   assert.ok(state.insertPayloads[0].created_at);
   assert.ok(state.insertPayloads[0].updated_at);
 });
@@ -1855,7 +1884,7 @@ test("createCrudRepositoryFromResource create hooks support afterWrite and canon
   assert.equal(afterWriteCalls.length, 1);
   assert.equal(afterWriteCalls[0].operation, "create");
   assert.equal(afterWriteCalls[0].createdName, "Tony");
-  assert.equal(afterWriteCalls[0].recordId, 11);
+  assert.equal(afterWriteCalls[0].recordId, "11");
 });
 
 test("createCrudRepositoryFromResource update hooks keep write-key filtering and by-id visibility constraints", async () => {
@@ -1870,7 +1899,7 @@ test("createCrudRepositoryFromResource update hooks keep write-key filtering and
   ]);
   const repository = createRepository(knex);
 
-  await repository.updateById(11, {
+  await repository.updateById("11", {
     firstName: "Tony"
   }, {
     visibilityContext: {
@@ -1899,8 +1928,8 @@ test("createCrudRepositoryFromResource update hooks keep write-key filtering and
   assert.equal(Object.hasOwn(state.updatePayloads[0], "unexpectedFieldFromQuery"), false);
   assert.ok(state.updatePayloads[0].updated_at);
   assert.ok(calls.some((call) => call[0] === "where" && call[1] === "vip" && call[2] === 1));
-  assert.ok(calls.some((call) => call[0] === "where" && call[1] === "workspace_owner_id" && call[2] === "workspace-1"));
-  assert.ok(calls.some((call) => call[0] === "where" && call[1]?.contact_id === 11));
+  assert.ok(calls.some((call) => call[0] === "where" && call[1] === "workspace_id" && call[2] === "workspace-1"));
+  assert.ok(calls.some((call) => call[0] === "where" && call[1]?.contact_id === "11"));
 });
 
 test("createCrudRepositoryFromResource update hooks reject read-phase hook keys", async () => {
@@ -1916,7 +1945,7 @@ test("createCrudRepositoryFromResource update hooks reject read-phase hook keys"
   const repository = createRepository(knex);
 
   await assert.rejects(
-    () => repository.updateById(11, {
+    () => repository.updateById("11", {
       firstName: "Tony"
     }, {}, {
       transformReturnedRecord(record = {}) {
@@ -1940,7 +1969,7 @@ test("createCrudRepositoryFromResource update hooks support afterWrite and canon
   const repository = createRepository(knex);
   const afterWriteCalls = [];
 
-  const record = await repository.updateById(11, {
+  const record = await repository.updateById("11", {
     firstName: "Tony"
   }, {}, {
     modifyPatch(patch = {}, context = {}) {
@@ -1961,7 +1990,7 @@ test("createCrudRepositoryFromResource update hooks support afterWrite and canon
   assert.equal(afterWriteCalls.length, 1);
   assert.equal(afterWriteCalls[0].operation, "update");
   assert.deepEqual(afterWriteCalls[0].patchKeys, ["firstName"]);
-  assert.equal(afterWriteCalls[0].recordId, 11);
+  assert.equal(afterWriteCalls[0].recordId, "11");
 });
 
 test("createCrudRepositoryFromResource delete hooks run through callOptions.trx client", async () => {
@@ -1980,7 +2009,7 @@ test("createCrudRepositoryFromResource delete hooks run through callOptions.trx
   ]);
   const repository = createRepository(baseKnex.knex);
 
-  await repository.deleteById(3, {
+  await repository.deleteById("3", {
     trx: trxKnex.knex,
     visibilityContext: {
       visibility: "workspace",
@@ -2010,7 +2039,7 @@ test("createCrudRepositoryFromResource delete hooks support afterWrite", async (
   const repository = createRepository(knex);
   const afterWriteCalls = [];
 
-  const result = await repository.deleteById(3, {}, {
+  const result = await repository.deleteById("3", {}, {
     afterWrite(meta = {}, context = {}) {
       context.state.deletedId = meta?.output?.id || null;
       afterWriteCalls.push({
@@ -2023,7 +2052,7 @@ test("createCrudRepositoryFromResource delete hooks support afterWrite", async (
   assert.equal(result.deleted, true);
   assert.equal(afterWriteCalls.length, 1);
   assert.equal(afterWriteCalls[0].operation, "delete");
-  assert.equal(afterWriteCalls[0].deletedId, 3);
+  assert.equal(afterWriteCalls[0].deletedId, "3");
 });
 
 test("createCrudRepositoryFromResource delete hooks support finalizeOutput for record and null flows", async () => {
@@ -2038,7 +2067,7 @@ test("createCrudRepositoryFromResource delete hooks support finalizeOutput for r
   const presentRepository = createRepository(presentKnex.knex);
   const missingRepository = createRepository(missingKnex.knex);
 
-  const deletedOutput = await presentRepository.deleteById(3, {}, {
+  const deletedOutput = await presentRepository.deleteById("3", {}, {
     finalizeOutput(output) {
       return output
         ? { ...output, status: "deleted" }
@@ -2046,7 +2075,7 @@ test("createCrudRepositoryFromResource delete hooks support finalizeOutput for r
     }
   });
 
-  const missingOutput = await missingRepository.deleteById(3, {}, {
+  const missingOutput = await missingRepository.deleteById("3", {}, {
     finalizeOutput(output) {
       return output === null ? { deleted: false } : output;
     }

package/test/repositorySupport.test.js

@@ -89,8 +89,8 @@ test("normalizeCrudListLimit enforces fallback and max", () => {
 });
 
 test("normalizeCrudListCursor rejects malformed id cursors", () => {
-  assert.equal(normalizeCrudListCursor("7"), 7);
-  assert.equal(normalizeCrudListCursor(""), 0);
+  assert.equal(normalizeCrudListCursor("7"), "7");
+  assert.equal(normalizeCrudListCursor(""), "");
   assert.throws(
     () => normalizeCrudListCursor("abc"),
     /Invalid cursor/
@@ -147,7 +147,7 @@ test("applyCrudListQueryFilters applies search and cursor filters", () => {
     ["whereGroup"],
     ["innerWhere", "first_name", "like", "%ani%"],
     ["innerOrWhere", "last_name", "like", "%ani%"],
-    ["where", "id", ">", 3]
+    ["where", "id", ">", "3"]
   ]);
 });