@jskit-ai/database-runtime 0.1.32 → 0.1.34

package/package.descriptor.mjs

@@ -1,7 +1,7 @@
 export default Object.freeze({
   packageVersion: 1,
   packageId: "@jskit-ai/database-runtime",
-  version: "0.1.32",
+  version: "0.1.34",
   kind: "runtime",
   dependsOn: [
     "@jskit-ai/kernel"
@@ -58,7 +58,7 @@ export default Object.freeze({
   mutations: {
     dependencies: {
       runtime: {
-        "@jskit-ai/kernel": "0.1.32",
+        "@jskit-ai/kernel": "0.1.34",
         "dotenv": "^16.4.5",
         "knex": "^3.1.0"
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/database-runtime",
-  "version": "0.1.32",
+  "version": "0.1.34",
   "type": "module",
   "scripts": {
     "test": "node --test"
@@ -25,6 +25,6 @@
     "./shared/transactions": "./src/shared/transactions.js"
   },
   "dependencies": {
-    "@jskit-ai/kernel": "0.1.32"
+    "@jskit-ai/kernel": "0.1.34"
   }
 }

package/src/server/providers/DatabaseRuntimeServiceProvider.js

@@ -5,7 +5,7 @@ import {
   normalizeDatabaseClient,
   toKnexClientId
 } from "../../shared/databaseClient.js";
-import { resolveDatabaseConnectionFromEnvironment } from "../../shared/databaseConnection.js";
+import { resolveKnexConnectionFromEnvironment } from "../../shared/databaseConnection.js";
 
 const DATABASE_RUNTIME_SERVER_API = Object.freeze({
   ...databaseRuntime
@@ -120,7 +120,8 @@ function createKnexConfig(scope) {
 
   const client = toKnexClientId(dialectId);
   const defaultPort = dialectId === "pg" ? 5432 : 3306;
-  const connection = resolveDatabaseConnectionFromEnvironment(env, {
+  const connection = resolveKnexConnectionFromEnvironment(env, {
+    client: dialectId,
     defaultPort,
     context: "database runtime"
   });

package/src/shared/databaseConnection.js

@@ -100,7 +100,6 @@ function resolveDatabaseConnectionFromEnvironment(
   const hasDbPassword = Object.prototype.hasOwnProperty.call(source, "DB_PASSWORD");
   const password = hasDbPassword ? String(source.DB_PASSWORD ?? "") : String(parsedUrl?.password || "");
 
-  // Knex may redefine connection.password as a hidden property; keep this mutable.
   return {
     host,
     port,
@@ -110,8 +109,38 @@ function resolveDatabaseConnectionFromEnvironment(
   };
 }
 
+function resolveKnexConnectionFromEnvironment(
+  env = {},
+  {
+    client = "",
+    defaultHost = "localhost",
+    defaultPort = 3306,
+    context = "database runtime"
+  } = {}
+) {
+  const resolvedClient = client
+    ? normalizeDatabaseClient(client, { allowEmpty: true })
+    : resolveDatabaseClientFromEnvironment(env, { allowEmpty: true });
+  const connection = resolveDatabaseConnectionFromEnvironment(env, {
+    defaultHost,
+    defaultPort,
+    context
+  });
+
+  if (resolvedClient === "mysql2") {
+    return {
+      ...connection,
+      supportBigNumbers: true,
+      bigNumberStrings: true
+    };
+  }
+
+  return connection;
+}
+
 export {
   parseDatabaseUrl,
   resolveDatabaseClientFromEnvironment,
-  resolveDatabaseConnectionFromEnvironment
+  resolveDatabaseConnectionFromEnvironment,
+  resolveKnexConnectionFromEnvironment
 };

package/src/shared/index.js

@@ -18,7 +18,8 @@ export { normalizeText, normalizeDatabaseClient, toKnexClientId } from "./databa
 export {
   parseDatabaseUrl,
   resolveDatabaseClientFromEnvironment,
-  resolveDatabaseConnectionFromEnvironment
+  resolveDatabaseConnectionFromEnvironment,
+  resolveKnexConnectionFromEnvironment
 } from "./databaseConnection.js";
 export { isDuplicateEntryError } from "./duplicateEntry.js";
 export { normalizePath, jsonTextExpression, whereJsonTextEquals } from "./json.js";
@@ -35,11 +36,14 @@ export {
   stringifyMetadataJson,
   normalizeMetadataJsonInput,
   normalizeNullableString,
+  normalizeDbRecordId,
+  resolveInsertedRecordId,
   normalizeIdList,
   normalizeCountRow,
   parseJsonValue,
   toDbJson,
-  runInTransaction
+  runInTransaction,
+  createWithTransaction
 } from "./repositoryOptions.js";
 export {
   normalizeBatchSize,

package/src/shared/repositoryOptions.js

@@ -1,3 +1,5 @@
+import { normalizeCanonicalRecordIdText } from "@jskit-ai/kernel/shared/support/normalize";
+
 function resolveQueryOptions(options = {}) {
   if (!options || typeof options !== "object") {
     return {
@@ -120,6 +122,44 @@ function normalizeNullableString(value, { trim = true } = {}) {
   return normalized || null;
 }
 
+function normalizeDbRecordId(value, { fallback = null } = {}) {
+  if (value == null) {
+    return fallback;
+  }
+
+  if (typeof value === "string") {
+    return normalizeCanonicalRecordIdText(value, { fallback });
+  }
+
+  if (typeof value === "number") {
+    if (!Number.isSafeInteger(value) || value < 1) {
+      return fallback;
+    }
+    return normalizeCanonicalRecordIdText(value, { fallback });
+  }
+
+  if (typeof value === "bigint") {
+    if (value < 1n) {
+      return fallback;
+    }
+    return normalizeCanonicalRecordIdText(value, { fallback });
+  }
+
+  if (typeof value === "object" && !Array.isArray(value) && Object.hasOwn(value, "id")) {
+    return normalizeDbRecordId(value.id, { fallback });
+  }
+
+  return normalizeCanonicalRecordIdText(value, { fallback });
+}
+
+function resolveInsertedRecordId(insertResult, { fallback = null } = {}) {
+  if (Array.isArray(insertResult) && insertResult.length > 0) {
+    return normalizeDbRecordId(insertResult[0], { fallback });
+  }
+
+  return normalizeDbRecordId(insertResult, { fallback });
+}
+
 function normalizeIdList(values, { parseValue } = {}) {
   const source = Array.isArray(values) ? values : [];
   const parser = typeof parseValue === "function" ? parseValue : (value) => value;
@@ -196,6 +236,12 @@ async function runInTransaction(knex, callback) {
   return knex.transaction(callback);
 }
 
+function createWithTransaction(knex) {
+  return function withTransaction(work) {
+    return runInTransaction(knex, work);
+  };
+}
+
 export {
   resolveQueryOptions,
   resolveRepoClient,
@@ -207,9 +253,12 @@ export {
   stringifyMetadataJson,
   normalizeMetadataJsonInput,
   normalizeNullableString,
+  normalizeDbRecordId,
+  resolveInsertedRecordId,
   normalizeIdList,
   normalizeCountRow,
   parseJsonValue,
   toDbJson,
-  runInTransaction
+  runInTransaction,
+  createWithTransaction
 };

package/src/shared/retention.js

@@ -1,4 +1,5 @@
 import { toDatabaseDateTimeUtc } from "./dateUtils.js";
+import { normalizeDbRecordId } from "./repositoryOptions.js";
 
 function normalizeBatchSize(value, { fallback = 1000, max = 10_000 } = {}) {
   const parsed = Number(value);
@@ -40,12 +41,12 @@ async function deleteRowsOlderThan({ client, tableName, dateColumn, cutoffDate,
     return 0;
   }
 
-  const numericIds = ids.map((entry) => Number(entry.id)).filter((id) => Number.isInteger(id) && id > 0);
-  if (numericIds.length < 1) {
+  const recordIds = ids.map((entry) => normalizeDbRecordId(entry?.id)).filter(Boolean);
+  if (recordIds.length < 1) {
     return 0;
   }
 
-  const deleted = await client(tableName).whereIn("id", numericIds).del();
+  const deleted = await client(tableName).whereIn("id", recordIds).del();
   return normalizeDeletedRowCount(deleted);
 }
 

package/src/shared/visibility.js

@@ -2,14 +2,14 @@ import { normalizeVisibilityContext } from "@jskit-ai/kernel/shared/support/visi
 
 const ALWAYS_FALSE_SQL = "1 = 0";
 const DEFAULT_VISIBILITY_COLUMNS = Object.freeze({
-  scopeOwnerId: "workspace_owner_id",
-  userOwnerId: "user_owner_id"
+  scopeOwnerId: "workspace_id",
+  userId: "user_id"
 });
 
 function applyVisibility(queryBuilder, visibilityContext = {}) {
   const context = normalizeVisibilityContext(visibilityContext);
   const workspaceColumn = DEFAULT_VISIBILITY_COLUMNS.scopeOwnerId;
-  const userColumn = DEFAULT_VISIBILITY_COLUMNS.userOwnerId;
+  const userColumn = DEFAULT_VISIBILITY_COLUMNS.userId;
 
   if (context.visibility === "public") {
     return queryBuilder;
@@ -23,17 +23,17 @@ function applyVisibility(queryBuilder, visibilityContext = {}) {
   }
 
   if (context.visibility === "user") {
-    if (!context.userOwnerId) {
+    if (!context.userId) {
       return queryBuilder.whereRaw(ALWAYS_FALSE_SQL);
     }
-    return queryBuilder.where(userColumn, context.userOwnerId);
+    return queryBuilder.where(userColumn, context.userId);
   }
 
-  if (!context.scopeOwnerId || !context.userOwnerId) {
+  if (!context.scopeOwnerId || !context.userId) {
     return queryBuilder.whereRaw(ALWAYS_FALSE_SQL);
   }
 
-  return queryBuilder.where(workspaceColumn, context.scopeOwnerId).where(userColumn, context.userOwnerId);
+  return queryBuilder.where(workspaceColumn, context.scopeOwnerId).where(userColumn, context.userId);
 }
 
 function applyVisibilityOwners(payload = {}, visibilityContext = {}) {
@@ -49,11 +49,11 @@ function applyVisibilityOwners(payload = {}, visibilityContext = {}) {
   if (context.visibility === "workspace" && !context.scopeOwnerId) {
     throw new Error("Visibility context requires scopeOwnerId.");
   }
-  if (context.visibility === "user" && !context.userOwnerId) {
-    throw new Error("Visibility context requires userOwnerId.");
+  if (context.visibility === "user" && !context.userId) {
+    throw new Error("Visibility context requires userId.");
   }
-  if (context.visibility === "workspace_user" && (!context.scopeOwnerId || !context.userOwnerId)) {
-    throw new Error("Visibility context requires scopeOwnerId and userOwnerId.");
+  if (context.visibility === "workspace_user" && (!context.scopeOwnerId || !context.userId)) {
+    throw new Error("Visibility context requires scopeOwnerId and userId.");
   }
 
   const ownedPayload = {
@@ -61,10 +61,10 @@ function applyVisibilityOwners(payload = {}, visibilityContext = {}) {
   };
 
   if (context.scopeOwnerId) {
-    ownedPayload.workspace_owner_id = context.scopeOwnerId;
+    ownedPayload.workspace_id = context.scopeOwnerId;
   }
-  if (context.userOwnerId) {
-    ownedPayload.user_owner_id = context.userOwnerId;
+  if (context.userId) {
+    ownedPayload.user_id = context.userId;
   }
 
   return ownedPayload;

package/templates/knexfile.js

@@ -4,7 +4,7 @@ import {
   normalizeText,
   toKnexClientId,
   resolveDatabaseClientFromEnvironment,
-  resolveDatabaseConnectionFromEnvironment
+  resolveKnexConnectionFromEnvironment
 } from "@jskit-ai/database-runtime/shared";
 
 const appRoot = process.cwd();
@@ -20,7 +20,8 @@ const migrationsDirectory = path.resolve(appRoot, normalizeText(process.env.DB_M
 
 export default {
   client,
-  connection: resolveDatabaseConnectionFromEnvironment(process.env, {
+  connection: resolveKnexConnectionFromEnvironment(process.env, {
+    client: dialectId,
     defaultPort,
     context: "knex migrations"
   }),

package/test/repositoryOptions.test.js

@@ -1,6 +1,11 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { parseMetadataJson, stringifyMetadataJson } from "../src/shared/repositoryOptions.js";
+import {
+  normalizeDbRecordId,
+  parseMetadataJson,
+  resolveInsertedRecordId,
+  stringifyMetadataJson
+} from "../src/shared/repositoryOptions.js";
 
 test("parseMetadataJson parses object-like metadata payloads", () => {
   assert.deepEqual(parseMetadataJson(""), {});
@@ -20,3 +25,18 @@ test("stringifyMetadataJson returns fallback for non-serializable values", () =>
   circular.self = circular;
   assert.equal(stringifyMetadataJson(circular), "{}");
 });
+
+test("normalizeDbRecordId preserves canonical DB ids and rejects unsafe JS numbers", () => {
+  const unsafeNumericId = Number(9007199254740993n);
+  assert.equal(normalizeDbRecordId("9007199254740993"), "9007199254740993");
+  assert.equal(normalizeDbRecordId(42), "42");
+  assert.equal(normalizeDbRecordId(42n), "42");
+  assert.equal(normalizeDbRecordId(unsafeNumericId), null);
+});
+
+test("resolveInsertedRecordId normalizes insert ids without accepting unsafe JS numbers", () => {
+  const unsafeNumericId = Number(9007199254740993n);
+  assert.equal(resolveInsertedRecordId(["9007199254740993"]), "9007199254740993");
+  assert.equal(resolveInsertedRecordId([42]), "42");
+  assert.equal(resolveInsertedRecordId([unsafeNumericId]), null);
+});

package/test/repositoryScope.test.js

@@ -37,7 +37,7 @@ test("createRepositoryScope builds explicit scoped query helpers", () => {
     }
   });
 
-  assert.deepEqual(calls, [["table", "contacts"], ["where", "workspace_owner_id", 12]]);
+  assert.deepEqual(calls, [["table", "contacts"], ["where", "workspace_id", "12"]]);
 });
 
 test("createRepositoryScope supports scopedById with custom id column", () => {
@@ -49,11 +49,11 @@ test("createRepositoryScope supports scopedById with custom id column", () => {
   scope.scopedById(33, {
     visibilityContext: {
       visibility: "user",
-      userOwnerId: 7
+      userId: 7
     }
   });
 
-  assert.deepEqual(calls, [["table", "contacts"], ["where", "user_owner_id", 7], ["where", "contact_id", 33]]);
+  assert.deepEqual(calls, [["table", "contacts"], ["where", "user_id", "7"], ["where", "contact_id", 33]]);
 });
 
 test("createRepositoryScope exposes applyToQuery and owner stamping", () => {
@@ -65,11 +65,11 @@ test("createRepositoryScope exposes applyToQuery and owner stamping", () => {
     visibilityContext: {
       visibility: "workspace_user",
       scopeOwnerId: 4,
-      userOwnerId: 9
+      userId: 9
     }
   });
 
-  assert.deepEqual(calls, [["where", "workspace_owner_id", 4], ["where", "user_owner_id", 9]]);
+  assert.deepEqual(calls, [["where", "workspace_id", "4"], ["where", "user_id", "9"]]);
 
   assert.deepEqual(
     scope.withOwners(
@@ -80,14 +80,14 @@ test("createRepositoryScope exposes applyToQuery and owner stamping", () => {
         visibilityContext: {
           visibility: "workspace_user",
           scopeOwnerId: 4,
-          userOwnerId: 9
+          userId: 9
         }
       }
     ),
     {
       name: "Ada",
-      workspace_owner_id: 4,
-      user_owner_id: 9
+      workspace_id: "4",
+      user_id: "9"
     }
   );
 

package/test/runtimeCore.test.js

@@ -5,7 +5,8 @@ import {
   BaseRepository,
   buildPaginationMeta,
   createTransactionManager,
-  registerDatabaseRuntime
+  createWithTransaction,
+  registerDatabaseRuntime,
 } from "../src/shared/index.js";
 
 function createKnexStub() {
@@ -74,6 +75,15 @@ test("base repository withTransaction delegates to transaction manager", async (
   assert.deepEqual(result, { id: "trx-1" });
 });
 
+test("createWithTransaction creates a reusable withTransaction function", async () => {
+  const knex = Object.assign(() => {
+    throw new Error("query execution not expected");
+  }, createKnexStub());
+  const withTransaction = createWithTransaction(knex);
+  const result = await withTransaction(async (trx) => ({ id: trx.trxId }));
+  assert.deepEqual(result, { id: "trx-1" });
+});
+
 test("pagination helpers generate stable metadata", () => {
   const meta = buildPaginationMeta({ total: 51, page: 2, pageSize: 25 });
   assert.deepEqual(meta, {

package/test/visibility.test.js

@@ -28,14 +28,14 @@ test("applyVisibility appends scope filters to query builders", () => {
     visibility: "workspace",
     scopeOwnerId: 12
   });
-  assert.deepEqual(workspaceQuery.calls, [["where", "workspace_owner_id", 12]]);
+  assert.deepEqual(workspaceQuery.calls, [["where", "workspace_id", "12"]]);
 
   const userQuery = createQueryBuilderStub();
   applyVisibility(userQuery, {
     visibility: "user",
-    userOwnerId: 7
+    userId: 7
   });
-  assert.deepEqual(userQuery.calls, [["where", "user_owner_id", 7]]);
+  assert.deepEqual(userQuery.calls, [["where", "user_id", "7"]]);
 
   const deniedQuery = createQueryBuilderStub();
   applyVisibility(deniedQuery, {
@@ -68,13 +68,13 @@ test("applyVisibilityOwners injects owner columns for write payloads", () => {
       {
         visibility: "workspace_user",
         scopeOwnerId: 4,
-        userOwnerId: 9
+        userId: 9
       }
     ),
     {
       name: "Alice",
-      workspace_owner_id: 4,
-      user_owner_id: 9
+      workspace_id: "4",
+      user_id: "9"
     }
   );
 
@@ -88,6 +88,6 @@ test("applyVisibilityOwners injects owner columns for write payloads", () => {
           visibility: "user"
         }
       ),
-    /requires userOwnerId/
+    /requires userId/
   );
 });