@jskit-ai/database-runtime 0.1.244 → 0.1.246

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@jskit-ai/database-runtime",
-  "version": "0.1.244",
+  "version": "0.1.246",
   "type": "module",
   "scripts": {
     "test": "node --test --test-concurrency=1"
   },
   "exports": {
-    "./client": "./src/client/index.js",
     "./server/providers/DatabaseProvider": "./src/server/providers/DatabaseProvider.js",
     "./server/databaseSetup": "./src/server/databaseSetup.js",
     "./server/knexMigrationConfig": "./src/server/knexMigrationConfig.js",
@@ -15,15 +14,8 @@
     "./shared/databaseClient": "./src/shared/databaseClient.js",
     "./shared/dialect": "./src/shared/dialect.js",
     "./shared/duplicateEntry": "./src/shared/duplicateEntry.js",
-    "./shared/json": "./src/shared/json.js",
-    "./shared/repository": "./src/shared/repository.js",
-    "./shared/repositoryScope": "./src/shared/repositoryScope.js",
     "./shared/repositoryOptions": "./src/shared/repositoryOptions.js",
-    "./shared/visibility": "./src/shared/visibility.js",
-    "./shared/retention": "./src/shared/retention.js",
-    "./shared/runtimeErrors": "./src/shared/runtimeErrors.js",
-    "./shared/transactionManager": "./src/shared/transactionManager.js",
-    "./shared/transactions": "./src/shared/transactions.js"
+    "./shared/visibility": "./src/shared/visibility.js"
   },
   "dependencies": {
     "knex": "^3.1.0"
@@ -55,8 +47,8 @@
       "apiSummary": {
         "surfaces": [
           {
-            "subpath": "./server",
-            "summary": "Provides the cohesive runtime.database capability with Knex, transactions, the selected driver, and repository utilities."
+            "subpath": "./server/providers/DatabaseProvider",
+            "summary": "Provides the runtime.database capability: the selected driver, its Knex client and a transaction manager."
           },
           {
             "subpath": "./server/databaseSetup",
@@ -68,17 +60,13 @@
           },
           {
             "subpath": "./shared",
-            "summary": "Exports shared Knex runtime utilities (transaction manager, repository helpers, retention/json/date/dialect helpers)."
-          },
-          {
-            "subpath": "./client",
-            "summary": "Exports no runtime API today (reserved client entrypoint)."
+            "summary": "Exports shared repository helpers (transactions, record ids, JSON columns, visibility, duplicate-entry detection and date/time serialization)."
           }
         ]
       }
     }
   },
   "peerDependencies": {
-    "@jskit-ai/kernel": "0.1.244"
+    "@jskit-ai/kernel": "0.1.246"
   }
 }

package/src/server/providers/DatabaseProvider.js

@@ -1,5 +1,4 @@
 import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
-import * as databaseUtilities from "../../shared/index.js";
 import { normalizeDatabaseClient, toKnexClientId } from "../../shared/databaseClient.js";
 import { resolveKnexConnectionFromEnvironment } from "../../shared/databaseConnection.js";
 import { createTransactionManager } from "../../shared/transactionManager.js";
@@ -34,7 +33,6 @@ function createDatabase({ driver, env }) {
   const transactionManager = createTransactionManager({ knex });
 
   return Object.freeze({
-    ...databaseUtilities,
     driver,
     knex,
     transactionManager

package/src/shared/databaseClient.js

@@ -25,7 +25,6 @@ function toKnexClientId(databaseClient) {
 }
 
 export {
-  normalizeText,
   normalizeDatabaseClient,
   toKnexClientId
 };

package/src/shared/databaseConnection.js

@@ -1,4 +1,5 @@
-import { normalizeDatabaseClient, normalizeText } from "./databaseClient.js";
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+import { normalizeDatabaseClient } from "./databaseClient.js";
 
 const DATABASE_URL_PROTOCOL_TO_CLIENT = Object.freeze({
   "mysql:": "mysql2",

package/src/shared/dateUtils.js

@@ -203,14 +203,6 @@ function toInsertDateTime(dateLike, fallback = new Date()) {
   return toDatabaseDateTimeUtc(normalized);
 }
 
-function toNullableDateTime(value) {
-  const normalized = normalizeDateInput(value);
-  if (!normalized) {
-    return null;
-  }
-  return toDatabaseDateTimeUtc(normalized);
-}
-
 function toDatabaseDateTimeUtc(value) {
   if (value == null) {
     return null;
@@ -222,6 +214,9 @@ function toDatabaseDateTimeUtc(value) {
 
   const date = toDateOrThrow(value);
   const year = date.getUTCFullYear();
+  if (year < 0 || year > 9999) {
+    throw new TypeError("Invalid date-time value.");
+  }
   const month = pad(date.getUTCMonth() + 1);
   const day = pad(date.getUTCDate());
   const hours = pad(date.getUTCHours());
@@ -229,14 +224,12 @@ function toDatabaseDateTimeUtc(value) {
   const seconds = pad(date.getUTCSeconds());
   const milliseconds = pad(date.getUTCMilliseconds(), 3);
 
-  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}.${milliseconds}`;
+  return `${pad(year, 4)}-${month}-${day} ${hours}:${minutes}:${seconds}.${milliseconds}`;
 }
 
 export {
-  normalizeDateInput,
   toIsoString,
   toInsertDateTime,
-  toNullableDateTime,
   toDatabaseDateTimeUtc,
   toJsonDate,
   toJsonTime,

package/src/shared/index.js

@@ -1,58 +1,25 @@
 export {
-  DatabaseRuntimeError,
-  TransactionManagerError,
-  RepositoryError
-} from "./runtimeErrors.js";
-export { TransactionManager, createTransactionManager } from "./transactionManager.js";
-export { BaseRepository, buildPaginationMeta } from "./repository.js";
-export {
-  normalizeDateInput,
   toIsoString,
   toInsertDateTime,
-  toNullableDateTime,
   toDatabaseDateTimeUtc,
   toJsonDate,
   toJsonTime,
   toJsonDateTime
 } from "./dateUtils.js";
 export { normalizeDialect, detectDialectFromClient } from "./dialect.js";
-export { normalizeText, normalizeDatabaseClient, toKnexClientId } from "./databaseClient.js";
-export {
-  parseDatabaseUrl,
-  resolveDatabaseClientFromEnvironment,
-  resolveDatabaseConnectionFromEnvironment,
-  resolveKnexConnectionFromEnvironment
-} from "./databaseConnection.js";
+export { normalizeDatabaseClient, toKnexClientId } from "./databaseClient.js";
 export { findDuplicateEntryError, isDuplicateEntryError } from "./duplicateEntry.js";
-export { normalizePath, jsonTextExpression, whereJsonTextEquals } from "./json.js";
 export { DEFAULT_VISIBILITY_COLUMNS, applyVisibility, applyVisibilityOwners } from "./visibility.js";
-export { createRepositoryScope } from "./repositoryScope.js";
 export {
   resolveQueryOptions,
   resolveRepoClient,
   applyForUpdate,
-  mapRowNullable,
   parseJsonObject,
   stringifyJsonObject,
-  parseMetadataJson,
-  stringifyMetadataJson,
-  normalizeMetadataJsonInput,
   normalizeNullableString,
   normalizeDbRecordId,
   resolveInsertedRecordId,
-  normalizeIdList,
-  normalizeCountRow,
-  parseJsonValue,
   toDbJson,
   runInTransaction,
-  createWithTransaction,
-  lockScopedRecordId
+  createWithTransaction
 } from "./repositoryOptions.js";
-export {
-  normalizeBatchSize,
-  normalizeCutoffDateOrThrow,
-  normalizeDeletedRowCount,
-  deleteRowsOlderThan,
-  __testables as retentionTestables
-} from "./retention.js";
-export { createRepoTransaction } from "./transactions.js";

package/src/shared/repositoryOptions.js

@@ -28,19 +28,6 @@ function applyForUpdate(query, options = {}) {
   return query;
 }
 
-function mapRowNullable(mapper) {
-  if (typeof mapper !== "function") {
-    throw new TypeError("mapRowNullable requires a mapper function.");
-  }
-
-  return function mapNullableRow(row) {
-    if (!row) {
-      return null;
-    }
-    return mapper(row);
-  };
-}
-
 function parseJsonObject(value, fallback = {}) {
   const source = String(value || "").trim();
   if (!source) {
@@ -71,47 +58,6 @@ function stringifyJsonObject(value, fallback = "{}") {
   }
 }
 
-function parseMetadataJson(value, fallback = {}) {
-  const source = String(value || "").trim();
-  if (!source) {
-    return fallback;
-  }
-
-  try {
-    const parsed = JSON.parse(source);
-    return parsed && typeof parsed === "object" ? parsed : fallback;
-  } catch {
-    return fallback;
-  }
-}
-
-function stringifyMetadataJson(metadata, fallback = "{}") {
-  if (!metadata || typeof metadata !== "object") {
-    return fallback;
-  }
-
-  try {
-    return JSON.stringify(metadata);
-  } catch {
-    return fallback;
-  }
-}
-
-function normalizeMetadataJsonInput(value, fallback = null) {
-  if (value == null) {
-    return fallback;
-  }
-  if (typeof value === "string") {
-    return value;
-  }
-
-  try {
-    return JSON.stringify(value);
-  } catch {
-    return fallback;
-  }
-}
-
 function normalizeNullableString(value, { trim = true } = {}) {
   if (value == null) {
     return null;
@@ -160,58 +106,6 @@ function resolveInsertedRecordId(insertResult, { fallback = null } = {}) {
   return normalizeDbRecordId(insertResult, { fallback });
 }
 
-function normalizeIdList(values, { parseValue } = {}) {
-  const source = Array.isArray(values) ? values : [];
-  const parser = typeof parseValue === "function" ? parseValue : (value) => value;
-  const normalized = source.map((value) => parser(value)).filter(Boolean);
-  return Array.from(new Set(normalized));
-}
-
-function normalizeCountRow(row) {
-  const values = Object.values(row || {});
-  if (values.length < 1) {
-    return 0;
-  }
-
-  const parsed = Number(values[0]);
-  return Number.isFinite(parsed) && parsed >= 0 ? parsed : 0;
-}
-
-function parseJsonValue(value, fallback = null, options = {}) {
-  const source = options && typeof options === "object" ? options : {};
-  const effectiveFallback = Object.hasOwn(source, "fallback") ? source.fallback : fallback;
-  const allowNull = source.allowNull === true;
-  const allowObject = source.allowObject !== false;
-  const trim = source.trim !== false;
-
-  if (value == null) {
-    return effectiveFallback;
-  }
-
-  if (allowObject && typeof value === "object") {
-    return value;
-  }
-
-  let text = String(value || "");
-  if (trim) {
-    text = text.trim();
-  }
-
-  if (!text) {
-    return effectiveFallback;
-  }
-
-  try {
-    const parsed = JSON.parse(text);
-    if (parsed == null && !allowNull) {
-      return effectiveFallback;
-    }
-    return parsed;
-  } catch {
-    return effectiveFallback;
-  }
-}
-
 function toDbJson(value) {
   if (value == null) {
     return JSON.stringify({});
@@ -242,60 +136,16 @@ function createWithTransaction(knex) {
   };
 }
 
-function requireSqlIdentifier(value, label) {
-  const identifier = String(value || "").trim();
-  if (!/^[A-Za-z_][A-Za-z0-9_]*$/u.test(identifier)) {
-    throw new TypeError(`${label} must be a safe SQL identifier.`);
-  }
-  return identifier;
-}
-
-async function lockScopedRecordId({
-  trx,
-  tableName,
-  recordId,
-  scopeId,
-  idColumn = "id",
-  scopeColumn = "workspace_id"
-} = {}) {
-  if (typeof trx !== "function") {
-    throw new TypeError("lockScopedRecordId requires a transaction.");
-  }
-  const table = requireSqlIdentifier(tableName, "lockScopedRecordId tableName");
-  const recordKey = requireSqlIdentifier(idColumn, "lockScopedRecordId idColumn");
-  const scopeKey = requireSqlIdentifier(scopeColumn, "lockScopedRecordId scopeColumn");
-  const normalizedRecordId = normalizeDbRecordId(recordId);
-  const normalizedScopeId = normalizeDbRecordId(scopeId);
-  if (!normalizedRecordId || !normalizedScopeId) {
-    return null;
-  }
-  const row = await trx(table)
-    .select(recordKey)
-    .where(recordKey, normalizedRecordId)
-    .andWhere(scopeKey, normalizedScopeId)
-    .forUpdate()
-    .first();
-  return normalizeDbRecordId(row?.[recordKey]);
-}
-
 export {
   resolveQueryOptions,
   resolveRepoClient,
   applyForUpdate,
-  mapRowNullable,
   parseJsonObject,
   stringifyJsonObject,
-  parseMetadataJson,
-  stringifyMetadataJson,
-  normalizeMetadataJsonInput,
   normalizeNullableString,
   normalizeDbRecordId,
   resolveInsertedRecordId,
-  normalizeIdList,
-  normalizeCountRow,
-  parseJsonValue,
   toDbJson,
   runInTransaction,
-  createWithTransaction,
-  lockScopedRecordId
+  createWithTransaction
 };

package/src/shared/transactionManager.js

@@ -1,10 +1,9 @@
 import { normalizeObject } from "@jskit-ai/kernel/shared/support/normalize";
-import { TransactionManagerError } from "./runtimeErrors.js";
 
 class TransactionManager {
   constructor({ knex } = {}) {
     if (!knex || typeof knex.transaction !== "function") {
-      throw new TransactionManagerError("TransactionManager requires knex with transaction().");
+      throw new TypeError("TransactionManager requires knex with transaction().");
     }
 
     this.knex = knex;
@@ -12,7 +11,7 @@ class TransactionManager {
 
   async inTransaction(work, { trx = null } = {}) {
     if (typeof work !== "function") {
-      throw new TransactionManagerError("inTransaction requires a callback function.");
+      throw new TypeError("inTransaction requires a callback function.");
     }
 
     if (trx) {

package/src/shared/visibility.js

@@ -61,10 +61,10 @@ function applyVisibilityOwners(payload = {}, visibilityContext = {}) {
   };
 
   if (context.scopeOwnerId) {
-    ownedPayload.workspace_id = context.scopeOwnerId;
+    ownedPayload[DEFAULT_VISIBILITY_COLUMNS.scopeOwnerId] = context.scopeOwnerId;
   }
   if (context.userId) {
-    ownedPayload.user_id = context.userId;
+    ownedPayload[DEFAULT_VISIBILITY_COLUMNS.userId] = context.userId;
   }
 
   return ownedPayload;

package/test/dateUtils.test.js

@@ -18,6 +18,13 @@ test("toDatabaseDateTimeUtc formats DATETIME(3) UTC string", () => {
   assert.equal(toDatabaseDateTimeUtc(new Date("2024-01-01T01:02:03.045Z")), "2024-01-01 01:02:03.045");
 });
 
+test("toDatabaseDateTimeUtc pads years below 1000 and rejects years outside 0..9999", () => {
+  assert.equal(toDatabaseDateTimeUtc("0999-01-01T00:00:00.000Z"), "0999-01-01 00:00:00.000");
+  assert.equal(toDatabaseDateTimeUtc(new Date("0005-01-01T00:00:00.000Z")), "0005-01-01 00:00:00.000");
+  assert.throws(() => toDatabaseDateTimeUtc(new Date("+010000-01-01T00:00:00.000Z")), /Invalid date-time value/);
+  assert.throws(() => toDatabaseDateTimeUtc(new Date("-000001-01-01T00:00:00.000Z")), /Invalid date-time value/);
+});
+
 test("toDatabaseDateTimeUtc preserves nullable empty values", () => {
   assert.equal(toDatabaseDateTimeUtc(null), null);
   assert.equal(toDatabaseDateTimeUtc(undefined), null);

package/test/entrypoints.boundary.test.js

@@ -2,7 +2,6 @@ import assert from "node:assert/strict";
 import { readFile } from "node:fs/promises";
 import test from "node:test";
 
-import * as clientApi from "../src/client/index.js";
 import * as sharedApi from "../src/shared/index.js";
 import { DatabaseProvider } from "../src/server/providers/DatabaseProvider.js";
 
@@ -10,15 +9,15 @@ test("package exports include explicit shared and provider entrypoints", async (
   const packageJson = JSON.parse(await readFile(new URL("../package.json", import.meta.url), "utf8"));
   const exportsMap = packageJson && typeof packageJson === "object" ? packageJson.exports : {};
   assert.equal(exportsMap["./server"], undefined);
+  assert.equal(exportsMap["./client"], undefined);
   assert.equal(
     exportsMap["./server/providers/DatabaseProvider"],
     "./src/server/providers/DatabaseProvider.js"
   );
   assert.equal(exportsMap["./shared"], "./src/shared/index.js");
-});
-
-test("client entrypoint exports no database runtime api", () => {
-  assert.deepEqual(Object.keys(clientApi), []);
+  for (const surface of packageJson.jskit.metadata.apiSummary.surfaces) {
+    assert.ok(exportsMap[surface.subpath], `apiSummary names a real export: ${surface.subpath}`);
+  }
 });
 
 test("server provider module exports one declarative provider", () => {
@@ -27,8 +26,11 @@ test("server provider module exports one declarative provider", () => {
 });
 
 test("shared entrypoint exports shared database utilities only", () => {
-  assert.equal(typeof sharedApi.createTransactionManager, "function");
+  assert.equal(typeof sharedApi.createWithTransaction, "function");
   assert.equal(typeof sharedApi.isDuplicateEntryError, "function");
-  assert.equal(typeof sharedApi.createRepositoryScope, "function");
+  assert.equal(typeof sharedApi.toDatabaseDateTimeUtc, "function");
   assert.equal(typeof sharedApi.DatabaseProvider, "undefined");
+  for (const removed of ["normalizeText", "retentionTestables", "createTransactionManager", "createRepositoryScope", "BaseRepository"]) {
+    assert.equal(typeof sharedApi[removed], "undefined", removed);
+  }
 });

package/test/providerRuntime.test.js

@@ -110,7 +110,7 @@ test("DatabaseProvider exposes one cohesive database capability", async () => {
       timezone: "Z"
     });
     assert.equal(typeof database.transactionManager.inTransaction, "function");
-    assert.equal(typeof database.resolveRepoClient, "function");
+    assert.deepEqual(Object.keys(database).sort(), ["driver", "knex", "transactionManager"]);
 
     await runtime.shutdown();
     assert.equal(database.knex.destroyCalls, 1);

package/test/repositoryOptions.test.js

@@ -1,48 +1,10 @@
 import test from "node:test";
 import assert from "node:assert/strict";
 import {
-  lockScopedRecordId,
   normalizeDbRecordId,
-  parseMetadataJson,
-  resolveInsertedRecordId,
-  stringifyMetadataJson
+  resolveInsertedRecordId
 } from "../src/shared/repositoryOptions.js";
 
-function fakeLockTransaction(row = null) {
-  const calls = [];
-  const query = {
-    select(value) { calls.push(["select", value]); return this; },
-    where(key, value) { calls.push(["where", key, value]); return this; },
-    andWhere(key, value) { calls.push(["andWhere", key, value]); return this; },
-    forUpdate() { calls.push(["forUpdate"]); return this; },
-    async first() { calls.push(["first"]); return row; }
-  };
-  const trx = (table) => {
-    calls.push(["table", table]);
-    return query;
-  };
-  return { calls, trx };
-}
-
-test("parseMetadataJson parses object-like metadata payloads", () => {
-  assert.deepEqual(parseMetadataJson(""), {});
-  assert.deepEqual(parseMetadataJson("{"), {});
-  assert.deepEqual(parseMetadataJson("{\"source\":\"console\"}"), { source: "console" });
-  assert.deepEqual(parseMetadataJson("[1,2,3]"), [1, 2, 3]);
-});
-
-test("stringifyMetadataJson serializes metadata payloads", () => {
-  assert.equal(stringifyMetadataJson(null), "{}");
-  assert.equal(stringifyMetadataJson({ source: "console" }), "{\"source\":\"console\"}");
-  assert.equal(stringifyMetadataJson([1, 2, 3]), "[1,2,3]");
-});
-
-test("stringifyMetadataJson returns fallback for non-serializable values", () => {
-  const circular = {};
-  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");
@@ -57,33 +19,3 @@ test("resolveInsertedRecordId normalizes insert ids without accepting unsafe JS
   assert.equal(resolveInsertedRecordId([42]), "42");
   assert.equal(resolveInsertedRecordId([unsafeNumericId]), null);
 });
-
-test("lockScopedRecordId locks an exact record inside its owner scope", async () => {
-  const { calls, trx } = fakeLockTransaction({ id: "42" });
-  assert.equal(await lockScopedRecordId({
-    trx,
-    tableName: "daycare_events",
-    recordId: 42,
-    scopeId: 7
-  }), "42");
-  assert.deepEqual(calls, [
-    ["table", "daycare_events"],
-    ["select", "id"],
-    ["where", "id", "42"],
-    ["andWhere", "workspace_id", "7"],
-    ["forUpdate"],
-    ["first"]
-  ]);
-});
-
-test("lockScopedRecordId rejects missing transactions and unsafe identifiers", async () => {
-  await assert.rejects(
-    () => lockScopedRecordId({ tableName: "records", recordId: 1, scopeId: 1 }),
-    /requires a transaction/u
-  );
-  const { trx } = fakeLockTransaction();
-  await assert.rejects(
-    () => lockScopedRecordId({ trx, tableName: "records; drop table", recordId: 1, scopeId: 1 }),
-    /safe SQL identifier/u
-  );
-});

package/test/runtimeCore.test.js

@@ -1,12 +1,8 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import {
-  BaseRepository,
-  buildPaginationMeta,
-  createTransactionManager,
-  createWithTransaction
-} from "../src/shared/index.js";
+import { createWithTransaction } from "../src/shared/index.js";
+import { createTransactionManager } from "../src/shared/transactionManager.js";
 
 function createKnexStub() {
   return {
@@ -23,15 +19,6 @@ test("transaction manager wraps callback in knex transaction", async () => {
   assert.equal(result.trx.trxId, "trx-1");
 });
 
-test("base repository withTransaction delegates to transaction manager", async () => {
-  const knex = createKnexStub();
-  const transactionManager = createTransactionManager({ knex });
-  const repo = new BaseRepository({ knex, transactionManager });
-
-  const result = await repo.withTransaction(async (trx) => ({ id: trx.trxId }));
-  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");
@@ -40,15 +27,3 @@ test("createWithTransaction creates a reusable withTransaction function", async
   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, {
-    total: 51,
-    page: 2,
-    pageSize: 25,
-    pageCount: 3,
-    hasPrev: true,
-    hasNext: true
-  });
-});

package/src/client/index.js

@@ -1 +0,0 @@
-export {};

package/src/shared/json.js

@@ -1,41 +0,0 @@
-import { detectDialectFromClient } from "./dialect.js";
-
-function normalizePath(path) {
-  if (Array.isArray(path)) {
-    return path.map((part) => String(part || "").trim()).filter(Boolean);
-  }
-
-  const source = String(path || "").trim();
-  if (!source) {
-    return [];
-  }
-
-  return source
-    .split(".")
-    .map((part) => String(part || "").trim())
-    .filter(Boolean);
-}
-
-function jsonTextExpression({ client, column, path }) {
-  const normalizedPath = normalizePath(path);
-  if (!column || normalizedPath.length < 1) {
-    throw new TypeError("jsonTextExpression requires column and path.");
-  }
-
-  const dialect = detectDialectFromClient(client);
-  if (dialect === "postgres") {
-    const pgPath = normalizedPath.map((part) => part.replace(/[{}]/g, "")).join(",");
-    return client.raw("?? #>> ?", [column, `{${pgPath}}`]);
-  }
-
-  const mysqlPath = `$.${normalizedPath.join(".")}`;
-  return client.raw("JSON_UNQUOTE(JSON_EXTRACT(??, ?))", [column, mysqlPath]);
-}
-
-function whereJsonTextEquals(query, { column, path, value }) {
-  const expression = jsonTextExpression({ client: query.client, column, path });
-  query.whereRaw(`${expression.sql} = ?`, [...expression.bindings, String(value || "")]);
-  return query;
-}
-
-export { normalizePath, jsonTextExpression, whereJsonTextEquals };

package/src/shared/repository.js

@@ -1,61 +0,0 @@
-import { normalizeInteger, normalizeObject } from "@jskit-ai/kernel/shared/support/normalize";
-import { RepositoryError } from "./runtimeErrors.js";
-
-function buildPaginationMeta({ total, page, pageSize } = {}) {
-  const normalizedTotal = Math.max(0, normalizeInteger(total, { fallback: 0 }));
-  const normalizedPageSize = Math.max(1, normalizeInteger(pageSize, { fallback: 25 }));
-  const normalizedPage = Math.max(1, normalizeInteger(page, { fallback: 1 }));
-  const pageCount = Math.max(1, Math.ceil(normalizedTotal / normalizedPageSize));
-
-  return Object.freeze({
-    total: normalizedTotal,
-    page: Math.min(normalizedPage, pageCount),
-    pageSize: normalizedPageSize,
-    pageCount,
-    hasPrev: normalizedPage > 1,
-    hasNext: normalizedPage < pageCount
-  });
-}
-
-class BaseRepository {
-  constructor({ knex, transactionManager } = {}) {
-    if (!knex) {
-      throw new RepositoryError("BaseRepository requires knex.");
-    }
-    if (!transactionManager || typeof transactionManager.inTransaction !== "function") {
-      throw new RepositoryError("BaseRepository requires transactionManager.inTransaction().");
-    }
-
-    this.knex = knex;
-    this.transactionManager = transactionManager;
-  }
-
-  async withTransaction(work, options = {}) {
-    if (typeof work !== "function") {
-      throw new RepositoryError("withTransaction requires a callback.");
-    }
-
-    return this.transactionManager.inTransaction(work, normalizeObject(options));
-  }
-
-  paginateRows(rows = [], options = {}) {
-    const sourceRows = Array.isArray(rows) ? rows : [];
-    const pageSize = Math.max(1, normalizeInteger(options.pageSize, { fallback: 25 }));
-    const page = Math.max(1, normalizeInteger(options.page, { fallback: 1 }));
-    const meta = buildPaginationMeta({
-      total: sourceRows.length,
-      page,
-      pageSize
-    });
-
-    const start = (meta.page - 1) * meta.pageSize;
-    const end = start + meta.pageSize;
-
-    return Object.freeze({
-      rows: Object.freeze(sourceRows.slice(start, end)),
-      meta
-    });
-  }
-}
-
-export { BaseRepository, buildPaginationMeta };

package/src/shared/repositoryScope.js

@@ -1,62 +0,0 @@
-import { resolveRepoClient } from "./repositoryOptions.js";
-import { applyVisibility, applyVisibilityOwners } from "./visibility.js";
-
-function normalizeTableName(value) {
-  const normalized = String(value || "").trim();
-  if (!normalized) {
-    throw new TypeError("createRepositoryScope requires tableName.");
-  }
-  return normalized;
-}
-
-function normalizeIdColumn(value) {
-  const normalized = String(value || "").trim();
-  return normalized || "id";
-}
-
-function createRepositoryScope(knex, tableName, options = {}) {
-  if (typeof knex !== "function") {
-    throw new TypeError("createRepositoryScope requires knex.");
-  }
-
-  const source = options && typeof options === "object" && !Array.isArray(options) ? options : {};
-  const resolvedTableName = normalizeTableName(tableName);
-  const resolvedIdColumn = normalizeIdColumn(source.idColumn);
-
-  function clientOf(queryOptions = {}) {
-    return resolveRepoClient(knex, queryOptions);
-  }
-
-  function table(queryOptions = {}) {
-    return clientOf(queryOptions)(resolvedTableName);
-  }
-
-  function applyToQuery(queryBuilder, queryOptions = {}) {
-    return applyVisibility(queryBuilder, queryOptions.visibilityContext);
-  }
-
-  function scoped(queryOptions = {}) {
-    return applyToQuery(table(queryOptions), queryOptions);
-  }
-
-  function scopedById(recordId, queryOptions = {}) {
-    return scoped(queryOptions).where(resolvedIdColumn, recordId);
-  }
-
-  function withOwners(payload = {}, queryOptions = {}) {
-    return applyVisibilityOwners(payload, queryOptions.visibilityContext);
-  }
-
-  return Object.freeze({
-    tableName: resolvedTableName,
-    idColumn: resolvedIdColumn,
-    clientOf,
-    table,
-    applyToQuery,
-    scoped,
-    scopedById,
-    withOwners
-  });
-}
-
-export { createRepositoryScope };

package/src/shared/retention.js

@@ -1,59 +0,0 @@
-import { toDatabaseDateTimeUtc } from "./dateUtils.js";
-import { normalizeDbRecordId } from "./repositoryOptions.js";
-
-function normalizeBatchSize(value, { fallback = 1000, max = 10_000 } = {}) {
-  const parsed = Number(value);
-  if (!Number.isInteger(parsed) || parsed < 1) {
-    return fallback;
-  }
-
-  return Math.min(parsed, max);
-}
-
-function normalizeCutoffDateOrThrow(value) {
-  const parsed = value instanceof Date ? value : new Date(value);
-  if (Number.isNaN(parsed.getTime())) {
-    throw new TypeError("Invalid cutoff date.");
-  }
-
-  return parsed;
-}
-
-function normalizeDeletedRowCount(value) {
-  const parsed = Number(value);
-  if (!Number.isFinite(parsed) || parsed < 0) {
-    return 0;
-  }
-
-  return parsed;
-}
-
-async function deleteRowsOlderThan({ client, tableName, dateColumn, cutoffDate, batchSize, applyFilters }) {
-  const normalizedCutoff = toDatabaseDateTimeUtc(normalizeCutoffDateOrThrow(cutoffDate));
-  const normalizedBatchSize = normalizeBatchSize(batchSize);
-  let query = client(tableName).where(dateColumn, "<", normalizedCutoff);
-  if (typeof applyFilters === "function") {
-    query = applyFilters(query);
-  }
-
-  const ids = await query.orderBy("id", "asc").limit(normalizedBatchSize).select("id");
-  if (!Array.isArray(ids) || ids.length < 1) {
-    return 0;
-  }
-
-  const recordIds = ids.map((entry) => normalizeDbRecordId(entry?.id)).filter(Boolean);
-  if (recordIds.length < 1) {
-    return 0;
-  }
-
-  const deleted = await client(tableName).whereIn("id", recordIds).del();
-  return normalizeDeletedRowCount(deleted);
-}
-
-const __testables = {
-  normalizeBatchSize,
-  normalizeCutoffDateOrThrow,
-  normalizeDeletedRowCount
-};
-
-export { normalizeBatchSize, normalizeCutoffDateOrThrow, normalizeDeletedRowCount, deleteRowsOlderThan, __testables };

package/src/shared/runtimeErrors.js

@@ -1,12 +0,0 @@
-class DatabaseRuntimeError extends Error {
-  constructor(message, details = {}) {
-    super(String(message || "Database runtime error."));
-    this.name = this.constructor.name;
-    this.details = details && typeof details === "object" ? { ...details } : {};
-  }
-}
-
-class TransactionManagerError extends DatabaseRuntimeError {}
-class RepositoryError extends DatabaseRuntimeError {}
-
-export { DatabaseRuntimeError, TransactionManagerError, RepositoryError };

package/src/shared/transactions.js

@@ -1,11 +0,0 @@
-function createRepoTransaction(dbClient) {
-  return async function repoTransaction(callback) {
-    if (typeof dbClient?.transaction === "function") {
-      return dbClient.transaction(callback);
-    }
-
-    return callback(dbClient);
-  };
-}
-
-export { createRepoTransaction };

package/test/json.test.js

@@ -1,9 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { normalizePath } from "../src/shared/json.js";
-
-test("normalizePath accepts string and array forms", () => {
-  assert.deepEqual(normalizePath("a.b.c"), ["a", "b", "c"]);
-  assert.deepEqual(normalizePath(["a", "b", "c"]), ["a", "b", "c"]);
-  assert.deepEqual(normalizePath(""), []);
-});

package/test/repositoryScope.test.js

@@ -1,103 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { createRepositoryScope } from "../src/shared/repositoryScope.js";
-
-function createQueryBuilder(calls) {
-  return {
-    where(...args) {
-      calls.push(["where", ...args]);
-      return this;
-    },
-    whereRaw(sql) {
-      calls.push(["whereRaw", sql]);
-      return this;
-    }
-  };
-}
-
-function createKnexStub() {
-  const calls = [];
-
-  function knex(tableName) {
-    calls.push(["table", tableName]);
-    return createQueryBuilder(calls);
-  }
-
-  return { knex, calls };
-}
-
-test("createRepositoryScope builds explicit scoped query helpers", () => {
-  const { knex, calls } = createKnexStub();
-  const scope = createRepositoryScope(knex, "contacts");
-
-  scope.scoped({
-    visibilityContext: {
-      visibility: "workspace",
-      scopeOwnerId: 12
-    }
-  });
-
-  assert.deepEqual(calls, [["table", "contacts"], ["where", "workspace_id", "12"]]);
-});
-
-test("createRepositoryScope supports scopedById with custom id column", () => {
-  const { knex, calls } = createKnexStub();
-  const scope = createRepositoryScope(knex, "contacts", {
-    idColumn: "contact_id"
-  });
-
-  scope.scopedById(33, {
-    visibilityContext: {
-      visibility: "user",
-      userId: 7
-    }
-  });
-
-  assert.deepEqual(calls, [["table", "contacts"], ["where", "user_id", "7"], ["where", "contact_id", 33]]);
-});
-
-test("createRepositoryScope exposes applyToQuery and owner stamping", () => {
-  const { knex, calls } = createKnexStub();
-  const scope = createRepositoryScope(knex, "contacts");
-  const queryBuilder = createQueryBuilder(calls);
-
-  scope.applyToQuery(queryBuilder, {
-    visibilityContext: {
-      visibility: "workspace_user",
-      scopeOwnerId: 4,
-      userId: 9
-    }
-  });
-
-  assert.deepEqual(calls, [["where", "workspace_id", "4"], ["where", "user_id", "9"]]);
-
-  assert.deepEqual(
-    scope.withOwners(
-      {
-        name: "Ada"
-      },
-      {
-        visibilityContext: {
-          visibility: "workspace_user",
-          scopeOwnerId: 4,
-          userId: 9
-        }
-      }
-    ),
-    {
-      name: "Ada",
-      workspace_id: "4",
-      user_id: "9"
-    }
-  );
-
-  assert.equal(scope.clientOf(), knex);
-  assert.equal(typeof scope.table, "function");
-});
-
-test("createRepositoryScope validates required inputs", () => {
-  const { knex } = createKnexStub();
-
-  assert.throws(() => createRepositoryScope(null, "contacts"), /requires knex/);
-  assert.throws(() => createRepositoryScope(knex, ""), /requires tableName/);
-});

package/test/retention.test.js

@@ -1,21 +0,0 @@
-import test from "node:test";
-import assert from "node:assert/strict";
-import { normalizeBatchSize, normalizeCutoffDateOrThrow, normalizeDeletedRowCount } from "../src/shared/retention.js";
-
-test("normalizeBatchSize clamps to configured max", () => {
-  assert.equal(normalizeBatchSize(undefined, { fallback: 100, max: 500 }), 100);
-  assert.equal(normalizeBatchSize(0, { fallback: 100, max: 500 }), 100);
-  assert.equal(normalizeBatchSize(250, { fallback: 100, max: 500 }), 250);
-  assert.equal(normalizeBatchSize(700, { fallback: 100, max: 500 }), 500);
-});
-
-test("normalizeCutoffDateOrThrow validates date", () => {
-  assert.ok(normalizeCutoffDateOrThrow("2024-01-01T00:00:00.000Z") instanceof Date);
-  assert.throws(() => normalizeCutoffDateOrThrow("invalid"), /Invalid cutoff date\./);
-});
-
-test("normalizeDeletedRowCount returns bounded non-negative number", () => {
-  assert.equal(normalizeDeletedRowCount(3), 3);
-  assert.equal(normalizeDeletedRowCount(-1), 0);
-  assert.equal(normalizeDeletedRowCount("x"), 0);
-});