@jskit-ai/database-runtime 0.1.4

package/package.descriptor.mjs

@@ -0,0 +1,89 @@
+export default Object.freeze({
+  packageVersion: 1,
+  packageId: "@jskit-ai/database-runtime",
+  version: "0.1.4",
+  dependsOn: [
+    "@jskit-ai/kernel"
+  ],
+  capabilities: {
+    provides: [
+      "runtime.database"
+    ],
+    requires: [
+      "runtime.database.driver"
+    ]
+  },
+  runtime: {
+    server: {
+      providerEntrypoint: "src/server/providers/DatabaseRuntimeServiceProvider.js",
+      providers: [
+        {
+          entrypoint: "src/server/providers/DatabaseRuntimeServiceProvider.js",
+          export: "DatabaseRuntimeServiceProvider"
+        }
+      ]
+    },
+    client: {
+      providers: []
+    }
+  },
+  metadata: {
+    apiSummary: {
+      surfaces: [
+        {
+          subpath: "./server",
+          summary: "Exports DatabaseRuntimeServiceProvider plus registerDatabaseRuntime for server container wiring."
+        },
+        {
+          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)."
+        }
+      ],
+      containerTokens: {
+        server: [
+          "runtime.database",
+          "runtime.database.driver"
+        ],
+        client: []
+      }
+    }
+  },
+  mutations: {
+    dependencies: {
+      runtime: {
+        "@jskit-ai/kernel": "0.1.4",
+        "dotenv": "^16.4.5",
+        "knex": "^3.1.0"
+      },
+      dev: {}
+    },
+    packageJson: {
+      scripts: {
+        "db:migrate": "knex --knexfile ./knexfile.js migrate:latest",
+        "db:migrate:rollback": "knex --knexfile ./knexfile.js migrate:rollback",
+        "db:migrate:status": "knex --knexfile ./knexfile.js migrate:list"
+      }
+    },
+    procfile: {},
+    files: [
+      {
+        from: "templates/knexfile.js",
+        to: "knexfile.js",
+        reason: "Install root Knex configuration so app scripts can run migrations through Knex CLI.",
+        category: "database-runtime",
+        id: "database-runtime-knexfile"
+      },
+      {
+        from: "templates/migrations/.gitkeep",
+        to: "migrations/.gitkeep",
+        reason: "Ensure migrations directory exists so Knex migration commands can run before any module installs migrations.",
+        category: "database-runtime",
+        id: "database-runtime-migrations-dir"
+      }
+    ]
+  }
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@jskit-ai/database-runtime",
+  "version": "0.1.4",
+  "type": "module",
+  "scripts": {
+    "test": "node --test"
+  },
+  "exports": {
+    "./client": "./src/client/index.js",
+    "./server/providers/DatabaseRuntimeServiceProvider": "./src/server/providers/DatabaseRuntimeServiceProvider.js",
+    "./shared": "./src/shared/index.js",
+    "./shared/dateUtils": "./src/shared/dateUtils.js",
+    "./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/runtime": "./src/shared/runtime.js",
+    "./shared/runtimeErrors": "./src/shared/runtimeErrors.js",
+    "./shared/transactionManager": "./src/shared/transactionManager.js",
+    "./shared/transactions": "./src/shared/transactions.js"
+  },
+  "dependencies": {
+    "@jskit-ai/kernel": "0.1.4"
+  }
+}

package/src/client/index.js

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

package/src/server/providers/DatabaseRuntimeServiceProvider.js

@@ -0,0 +1,193 @@
+import { KERNEL_TOKENS } from "@jskit-ai/kernel/shared/support/tokens";
+import { symlinkSafeRequire } from "@jskit-ai/kernel/server/support";
+import * as databaseRuntime from "../../shared/index.js";
+import { createTransactionManager } from "../../shared/transactionManager.js";
+import {
+  normalizeText,
+  normalizeDatabaseClient,
+  toKnexClientId
+} from "../../shared/databaseClient.js";
+
+const DATABASE_RUNTIME_TOKEN = "runtime.database";
+const DATABASE_DRIVER_TOKEN = "runtime.database.driver";
+const MYSQL_DRIVER_TOKEN = "runtime.database.driver.mysql";
+const POSTGRES_DRIVER_TOKEN = "runtime.database.driver.postgres";
+
+const DATABASE_RUNTIME_SERVER_API = Object.freeze({
+  ...databaseRuntime
+});
+
+function resolveDatabaseEnv(scope) {
+  const envFromScope = scope?.has?.(KERNEL_TOKENS.Env) ? scope.make(KERNEL_TOKENS.Env) : {};
+  const source = envFromScope && typeof envFromScope === "object" ? envFromScope : {};
+  return {
+    ...process.env,
+    ...source
+  };
+}
+
+function resolveDriverDialectId(driver) {
+  const source = driver && typeof driver === "object" ? driver : {};
+  const fromConstant = normalizeDatabaseClient(source.DIALECT_ID || source.dialectId || source.dialect, {
+    allowEmpty: true
+  });
+  if (fromConstant) {
+    return fromConstant;
+  }
+  if (typeof source.getDialectId === "function") {
+    return normalizeDatabaseClient(source.getDialectId(), {
+      allowEmpty: true
+    });
+  }
+  return "";
+}
+
+function resolveRequiredEnvString(env, key) {
+  const value = normalizeText(env?.[key]);
+  if (!value) {
+    throw new Error(`${key} is required for database runtime.`);
+  }
+  return value;
+}
+
+function resolvePort(value, fallbackPort) {
+  const parsed = Number.parseInt(normalizeText(value), 10);
+  if (Number.isInteger(parsed) && parsed > 0) {
+    return parsed;
+  }
+  return fallbackPort;
+}
+
+function loadKnexFactory() {
+  let moduleValue;
+  try {
+    moduleValue = symlinkSafeRequire("knex");
+  } catch {
+    throw new Error(
+      "Knex package is not installed. Re-run `npx jskit update package database-runtime` to apply runtime dependencies."
+    );
+  }
+
+  const knexFactory =
+    typeof moduleValue === "function"
+      ? moduleValue
+      : typeof moduleValue?.default === "function"
+        ? moduleValue.default
+        : null;
+  if (!knexFactory) {
+    throw new Error("Knex package resolved but did not expose a callable factory.");
+  }
+
+  return knexFactory;
+}
+
+function resolveRegisteredDriver(scope) {
+  const drivers = resolveRegisteredDrivers(scope);
+  if (drivers.length === 1) {
+    return drivers[0];
+  }
+  if (drivers.length < 1) {
+    throw new Error("No database driver is registered. Install @jskit-ai/database-runtime-mysql or @jskit-ai/database-runtime-postgres.");
+  }
+
+  const env = resolveDatabaseEnv(scope);
+  const preferredClient = normalizeDatabaseClient(env.DB_CLIENT, {
+    allowEmpty: true
+  });
+  if (!preferredClient) {
+    throw new Error("Multiple database drivers are registered. Set DB_CLIENT to mysql2 or pg, or keep exactly one database runtime driver package installed.");
+  }
+
+  const matched = drivers.find((driver) => resolveDriverDialectId(driver) === preferredClient) || null;
+  if (!matched) {
+    throw new Error(`Multiple database drivers are registered, but DB_CLIENT="${preferredClient}" did not match any registered driver.`);
+  }
+
+  return matched;
+}
+
+function resolveRegisteredDrivers(scope) {
+  const drivers = [];
+
+  if (scope.has(MYSQL_DRIVER_TOKEN)) {
+    drivers.push(scope.make(MYSQL_DRIVER_TOKEN));
+  }
+
+  if (scope.has(POSTGRES_DRIVER_TOKEN)) {
+    drivers.push(scope.make(POSTGRES_DRIVER_TOKEN));
+  }
+
+  return drivers;
+}
+
+function resolveSingleRegisteredDriver(scope) {
+  return resolveRegisteredDriver(scope);
+}
+
+function createKnexConfig(scope) {
+  const env = resolveDatabaseEnv(scope);
+  const configuredClient = normalizeDatabaseClient(env.DB_CLIENT, {
+    allowEmpty: true
+  });
+  const driver = resolveRegisteredDriver(scope);
+  const dialectId = resolveDriverDialectId(driver);
+
+  if (!dialectId) {
+    throw new Error("Selected database driver did not expose a valid dialect id.");
+  }
+
+  if (configuredClient && configuredClient !== dialectId) {
+    throw new Error(`DB_CLIENT="${configuredClient}" does not match installed database driver "${dialectId}".`);
+  }
+
+  const client = toKnexClientId(dialectId);
+  const defaultPort = dialectId === "pg" ? 5432 : 3306;
+
+  return {
+    client,
+    connection: {
+      host: normalizeText(env.DB_HOST) || "localhost",
+      port: resolvePort(env.DB_PORT, defaultPort),
+      database: resolveRequiredEnvString(env, "DB_NAME"),
+      user: resolveRequiredEnvString(env, "DB_USER"),
+      password: String(env.DB_PASSWORD ?? "")
+    }
+  };
+}
+
+function createKnexInstance(scope) {
+  const knexFactory = loadKnexFactory();
+  const config = createKnexConfig(scope);
+  return knexFactory(config);
+}
+
+class DatabaseRuntimeServiceProvider {
+  static id = DATABASE_RUNTIME_TOKEN;
+
+  register(app) {
+    if (!app || typeof app.singleton !== "function" || typeof app.has !== "function") {
+      throw new Error("DatabaseRuntimeServiceProvider requires application singleton()/has().");
+    }
+
+    app.singleton(DATABASE_RUNTIME_TOKEN, () => DATABASE_RUNTIME_SERVER_API);
+
+    if (!app.has(DATABASE_DRIVER_TOKEN)) {
+      app.singleton(DATABASE_DRIVER_TOKEN, (scope) => resolveSingleRegisteredDriver(scope));
+    }
+
+    if (!app.has(KERNEL_TOKENS.Knex)) {
+      app.singleton(KERNEL_TOKENS.Knex, (scope) => createKnexInstance(scope));
+    }
+
+    if (!app.has(KERNEL_TOKENS.TransactionManager)) {
+      app.singleton(KERNEL_TOKENS.TransactionManager, (scope) => {
+        const knex = scope.make(KERNEL_TOKENS.Knex);
+        return createTransactionManager({ knex });
+      });
+    }
+  }
+
+  boot() {}
+}
+
+export { DatabaseRuntimeServiceProvider };

package/src/shared/databaseClient.js

@@ -0,0 +1,31 @@
+import { normalizeText } from "@jskit-ai/kernel/shared/support/normalize";
+
+function normalizeDatabaseClient(value, { allowEmpty = false } = {}) {
+  const normalized = normalizeText(value).toLowerCase();
+  if (!normalized) {
+    if (allowEmpty) {
+      return "";
+    }
+    throw new Error("DB_CLIENT is required. Use mysql2 or pg.");
+  }
+
+  if (normalized === "pg") {
+    return "pg";
+  }
+
+  if (normalized === "mysql2") {
+    return "mysql2";
+  }
+
+  throw new Error(`Unsupported DB_CLIENT "${normalized}". Use one of: mysql2, pg.`);
+}
+
+function toKnexClientId(databaseClient) {
+  return normalizeDatabaseClient(databaseClient);
+}
+
+export {
+  normalizeText,
+  normalizeDatabaseClient,
+  toKnexClientId
+};

package/src/shared/dateUtils.js

@@ -0,0 +1,57 @@
+function normalizeDateInput(value) {
+  if (!value) {
+    return null;
+  }
+
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    return null;
+  }
+
+  return date;
+}
+
+function toDateOrThrow(value) {
+  const date = value instanceof Date ? value : new Date(value);
+  if (Number.isNaN(date.getTime())) {
+    throw new TypeError("Invalid date value.");
+  }
+
+  return date;
+}
+
+function pad(value, size = 2) {
+  return String(value).padStart(size, "0");
+}
+
+function toIsoString(value) {
+  return toDateOrThrow(value).toISOString();
+}
+
+function toInsertDateTime(dateLike, fallback = new Date()) {
+  const normalized = normalizeDateInput(dateLike) || normalizeDateInput(fallback) || new Date();
+  return toDatabaseDateTimeUtc(normalized);
+}
+
+function toNullableDateTime(value) {
+  const normalized = normalizeDateInput(value);
+  if (!normalized) {
+    return null;
+  }
+  return toDatabaseDateTimeUtc(normalized);
+}
+
+function toDatabaseDateTimeUtc(value) {
+  const date = toDateOrThrow(value);
+  const year = date.getUTCFullYear();
+  const month = pad(date.getUTCMonth() + 1);
+  const day = pad(date.getUTCDate());
+  const hours = pad(date.getUTCHours());
+  const minutes = pad(date.getUTCMinutes());
+  const seconds = pad(date.getUTCSeconds());
+  const milliseconds = pad(date.getUTCMilliseconds(), 3);
+
+  return `${year}-${month}-${day} ${hours}:${minutes}:${seconds}.${milliseconds}`;
+}
+
+export { normalizeDateInput, toIsoString, toInsertDateTime, toNullableDateTime, toDatabaseDateTimeUtc };

package/src/shared/dialect.js

@@ -0,0 +1,25 @@
+function normalizeDialect(value) {
+  return String(value || "").trim().toLowerCase();
+}
+
+function detectDialectFromClient(client) {
+  const candidate =
+    client?.client?.config?.client ||
+    client?.client?.dialect ||
+    client?.client?.driverName ||
+    client?.client?.constructor?.name ||
+    "";
+
+  const normalized = normalizeDialect(candidate);
+  if (normalized.includes("postgres") || normalized === "pg") {
+    return "postgres";
+  }
+
+  if (normalized.includes("mysql") || normalized.includes("maria")) {
+    return "mysql";
+  }
+
+  return normalized;
+}
+
+export { normalizeDialect, detectDialectFromClient };

package/src/shared/duplicateEntry.js

@@ -0,0 +1,37 @@
+import { detectDialectFromClient, normalizeDialect } from "./dialect.js";
+
+function isMysqlDuplicateEntryError(error) {
+  const code = String(error?.code || "").trim().toUpperCase();
+  if (code === "ER_DUP_ENTRY") {
+    return true;
+  }
+
+  const errno = Number(error?.errno || error?.errorno || 0);
+  return errno === 1062;
+}
+
+function isPostgresDuplicateEntryError(error) {
+  const code = String(error?.code || "").trim();
+  return code === "23505";
+}
+
+function isDuplicateEntryError(error, { dialect = "", client = null } = {}) {
+  if (!error) {
+    return false;
+  }
+
+  const resolvedDialect =
+    normalizeDialect(dialect) || (client ? normalizeDialect(detectDialectFromClient(client)) : "");
+
+  if (resolvedDialect === "postgres") {
+    return isPostgresDuplicateEntryError(error);
+  }
+
+  if (resolvedDialect === "mysql") {
+    return isMysqlDuplicateEntryError(error);
+  }
+
+  return isMysqlDuplicateEntryError(error) || isPostgresDuplicateEntryError(error);
+}
+
+export { isDuplicateEntryError };

package/src/shared/index.js

@@ -0,0 +1,45 @@
+export {
+  DatabaseRuntimeError,
+  TransactionManagerError,
+  RepositoryError
+} from "./runtimeErrors.js";
+export { TransactionManager, createTransactionManager } from "./transactionManager.js";
+export { BaseRepository, buildPaginationMeta } from "./repository.js";
+export { registerDatabaseRuntime } from "./runtime.js";
+export {
+  normalizeDateInput,
+  toIsoString,
+  toInsertDateTime,
+  toNullableDateTime,
+  toDatabaseDateTimeUtc
+} from "./dateUtils.js";
+export { normalizeDialect, detectDialectFromClient } from "./dialect.js";
+export { normalizeText, normalizeDatabaseClient, toKnexClientId } from "./databaseClient.js";
+export { 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,
+  normalizeIdList,
+  normalizeCountRow,
+  parseJsonValue,
+  toDbJson
+} from "./repositoryOptions.js";
+export {
+  normalizeBatchSize,
+  normalizeCutoffDateOrThrow,
+  normalizeDeletedRowCount,
+  deleteRowsOlderThan,
+  __testables as retentionTestables
+} from "./retention.js";
+export { createRepoTransaction } from "./transactions.js";

package/src/shared/json.js

@@ -0,0 +1,41 @@
+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

@@ -0,0 +1,61 @@
+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 };