@jskit-ai/database-runtime 0.1.4

package/src/shared/repositoryOptions.js

@@ -0,0 +1,200 @@
+function resolveQueryOptions(options = {}) {
+  if (!options || typeof options !== "object") {
+    return {
+      trx: null,
+      forUpdate: false
+    };
+  }
+
+  return {
+    trx: options.trx || null,
+    forUpdate: options.forUpdate === true
+  };
+}
+
+function resolveRepoClient(dbClient, options = {}) {
+  const { trx } = resolveQueryOptions(options);
+  return trx || dbClient;
+}
+
+function applyForUpdate(query, options = {}) {
+  const { forUpdate } = resolveQueryOptions(options);
+  if (forUpdate && typeof query?.forUpdate === "function") {
+    return query.forUpdate();
+  }
+
+  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) {
+    return fallback;
+  }
+
+  try {
+    const parsed = JSON.parse(source);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+      return parsed;
+    }
+  } catch {
+    return fallback;
+  }
+
+  return fallback;
+}
+
+function stringifyJsonObject(value, fallback = "{}") {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return fallback;
+  }
+
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return 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;
+  }
+
+  const source = String(value);
+  const normalized = trim ? source.trim() : source;
+  return normalized || null;
+}
+
+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({});
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return JSON.stringify(value);
+}
+
+export {
+  resolveQueryOptions,
+  resolveRepoClient,
+  applyForUpdate,
+  mapRowNullable,
+  parseJsonObject,
+  stringifyJsonObject,
+  parseMetadataJson,
+  stringifyMetadataJson,
+  normalizeMetadataJsonInput,
+  normalizeNullableString,
+  normalizeIdList,
+  normalizeCountRow,
+  parseJsonValue,
+  toDbJson
+};

package/src/shared/repositoryScope.js

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

@@ -0,0 +1,58 @@
+import { toDatabaseDateTimeUtc } from "./dateUtils.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 numericIds = ids.map((entry) => Number(entry.id)).filter((id) => Number.isInteger(id) && id > 0);
+  if (numericIds.length < 1) {
+    return 0;
+  }
+
+  const deleted = await client(tableName).whereIn("id", numericIds).del();
+  return normalizeDeletedRowCount(deleted);
+}
+
+const __testables = {
+  normalizeBatchSize,
+  normalizeCutoffDateOrThrow,
+  normalizeDeletedRowCount
+};
+
+export { normalizeBatchSize, normalizeCutoffDateOrThrow, normalizeDeletedRowCount, deleteRowsOlderThan, __testables };

package/src/shared/runtime.js

@@ -0,0 +1,59 @@
+import { KERNEL_TOKENS } from "@jskit-ai/kernel/shared/support/tokens";
+import { createTransactionManager } from "./transactionManager.js";
+import { DatabaseRuntimeError } from "./runtimeErrors.js";
+
+function ensureContainerInterface(app) {
+  if (
+    !app ||
+    typeof app.instance !== "function" ||
+    typeof app.singleton !== "function" ||
+    typeof app.make !== "function" ||
+    typeof app.has !== "function"
+  ) {
+    throw new DatabaseRuntimeError("registerDatabaseRuntime requires application instance/singleton/make/has methods.");
+  }
+}
+
+function ensureKnexInterface(knex) {
+  if (!knex || typeof knex.transaction !== "function") {
+    throw new DatabaseRuntimeError("registerDatabaseRuntime requires knex with transaction().");
+  }
+}
+
+function ensureKnexBinding(app, knex) {
+  if (!app.has(KERNEL_TOKENS.Knex)) {
+    app.instance(KERNEL_TOKENS.Knex, knex);
+    return;
+  }
+
+  const existingKnex = app.make(KERNEL_TOKENS.Knex);
+  if (existingKnex !== knex) {
+    throw new DatabaseRuntimeError("registerDatabaseRuntime received knex that differs from existing Knex binding.");
+  }
+}
+
+function ensureTransactionManagerBinding(app) {
+  if (app.has(KERNEL_TOKENS.TransactionManager)) {
+    return;
+  }
+
+  app.singleton(KERNEL_TOKENS.TransactionManager, (scope) => {
+    const knex = scope.make(KERNEL_TOKENS.Knex);
+    return createTransactionManager({ knex });
+  });
+}
+
+function registerDatabaseRuntime(app, { knex } = {}) {
+  ensureContainerInterface(app);
+  ensureKnexInterface(knex);
+
+  ensureKnexBinding(app, knex);
+  ensureTransactionManagerBinding(app);
+
+  return {
+    knex: app.make(KERNEL_TOKENS.Knex),
+    transactionManager: app.make(KERNEL_TOKENS.TransactionManager)
+  };
+}
+
+export { registerDatabaseRuntime };

package/src/shared/runtimeErrors.js

@@ -0,0 +1,12 @@
+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/transactionManager.js

@@ -0,0 +1,32 @@
+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().");
+    }
+
+    this.knex = knex;
+  }
+
+  async inTransaction(work, { trx = null } = {}) {
+    if (typeof work !== "function") {
+      throw new TransactionManagerError("inTransaction requires a callback function.");
+    }
+
+    if (trx) {
+      return work(trx);
+    }
+
+    return this.knex.transaction(async (nextTrx) => {
+      return work(nextTrx);
+    });
+  }
+}
+
+function createTransactionManager(options = {}) {
+  return new TransactionManager(normalizeObject(options));
+}
+
+export { TransactionManager, createTransactionManager };

package/src/shared/transactions.js

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

package/src/shared/visibility.js

@@ -0,0 +1,73 @@
+import { normalizeVisibilityContext } from "@jskit-ai/kernel/shared/support/visibility";
+
+const ALWAYS_FALSE_SQL = "1 = 0";
+const DEFAULT_VISIBILITY_COLUMNS = Object.freeze({
+  scopeOwnerId: "workspace_owner_id",
+  userOwnerId: "user_owner_id"
+});
+
+function applyVisibility(queryBuilder, visibilityContext = {}) {
+  const context = normalizeVisibilityContext(visibilityContext);
+  const workspaceColumn = DEFAULT_VISIBILITY_COLUMNS.scopeOwnerId;
+  const userColumn = DEFAULT_VISIBILITY_COLUMNS.userOwnerId;
+
+  if (context.visibility === "public") {
+    return queryBuilder;
+  }
+
+  if (context.visibility === "workspace") {
+    if (!context.scopeOwnerId) {
+      return queryBuilder.whereRaw(ALWAYS_FALSE_SQL);
+    }
+    return queryBuilder.where(workspaceColumn, context.scopeOwnerId);
+  }
+
+  if (context.visibility === "user") {
+    if (!context.userOwnerId) {
+      return queryBuilder.whereRaw(ALWAYS_FALSE_SQL);
+    }
+    return queryBuilder.where(userColumn, context.userOwnerId);
+  }
+
+  if (!context.scopeOwnerId || !context.userOwnerId) {
+    return queryBuilder.whereRaw(ALWAYS_FALSE_SQL);
+  }
+
+  return queryBuilder.where(workspaceColumn, context.scopeOwnerId).where(userColumn, context.userOwnerId);
+}
+
+function applyVisibilityOwners(payload = {}, visibilityContext = {}) {
+  const source = payload && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
+  const context = normalizeVisibilityContext(visibilityContext);
+
+  if (context.visibility === "public") {
+    return {
+      ...source
+    };
+  }
+
+  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 === "workspace_user" && (!context.scopeOwnerId || !context.userOwnerId)) {
+    throw new Error("Visibility context requires scopeOwnerId and userOwnerId.");
+  }
+
+  const ownedPayload = {
+    ...source
+  };
+
+  if (context.scopeOwnerId) {
+    ownedPayload.workspace_owner_id = context.scopeOwnerId;
+  }
+  if (context.userOwnerId) {
+    ownedPayload.user_owner_id = context.userOwnerId;
+  }
+
+  return ownedPayload;
+}
+
+export { DEFAULT_VISIBILITY_COLUMNS, applyVisibility, applyVisibilityOwners };

package/templates/knexfile.js

@@ -0,0 +1,49 @@
+import path from "node:path";
+import dotenv from "dotenv";
+import {
+  normalizeText,
+  normalizeDatabaseClient,
+  toKnexClientId
+} from "@jskit-ai/database-runtime/shared/databaseClient";
+
+function resolveRequiredEnvString(env, key) {
+  const value = normalizeText(env[key]);
+  if (!value) {
+    throw new Error(`${key} is required.`);
+  }
+  return value;
+}
+
+function resolvePort(value, fallbackPort) {
+  const parsed = Number.parseInt(normalizeText(value), 10);
+  if (Number.isInteger(parsed) && parsed > 0) {
+    return parsed;
+  }
+  return fallbackPort;
+}
+
+const appRoot = process.cwd();
+dotenv.config({
+  path: path.join(appRoot, ".env"),
+  quiet: true
+});
+
+const dialectId = normalizeDatabaseClient(process.env.DB_CLIENT);
+const client = toKnexClientId(dialectId);
+const defaultPort = dialectId === "pg" ? 5432 : 3306;
+const migrationsDirectory = path.resolve(appRoot, normalizeText(process.env.DB_MIGRATIONS_DIR) || "migrations");
+
+export default {
+  client,
+  connection: {
+    host: normalizeText(process.env.DB_HOST) || "localhost",
+    port: resolvePort(process.env.DB_PORT, defaultPort),
+    database: resolveRequiredEnvString(process.env, "DB_NAME"),
+    user: resolveRequiredEnvString(process.env, "DB_USER"),
+    password: String(process.env.DB_PASSWORD ?? "")
+  },
+  migrations: {
+    directory: migrationsDirectory,
+    extension: "cjs"
+  }
+};

package/templates/migrations/.gitkeep

@@ -0,0 +1 @@
+

package/test/dateUtils.test.js

@@ -0,0 +1,17 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { toIsoString, toDatabaseDateTimeUtc } from "../src/shared/dateUtils.js";
+
+test("toIsoString normalizes valid date input", () => {
+  assert.equal(toIsoString("2024-01-01T00:00:00.000Z"), "2024-01-01T00:00:00.000Z");
+});
+
+test("toDatabaseDateTimeUtc formats DATETIME(3) UTC string", () => {
+  assert.equal(toDatabaseDateTimeUtc("2024-01-01T00:00:00.000Z"), "2024-01-01 00:00:00.000");
+  assert.equal(toDatabaseDateTimeUtc(new Date("2024-01-01T01:02:03.045Z")), "2024-01-01 01:02:03.045");
+});
+
+test("date utils throw on invalid date", () => {
+  assert.throws(() => toIsoString("not-a-date"), /Invalid date value\./);
+  assert.throws(() => toDatabaseDateTimeUtc("not-a-date"), /Invalid date value\./);
+});

package/test/duplicateEntry.test.js

@@ -0,0 +1,10 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { isDuplicateEntryError } from "../src/shared/duplicateEntry.js";
+
+test("isDuplicateEntryError matches mysql and postgres duplicate signatures", () => {
+  assert.equal(isDuplicateEntryError({ code: "ER_DUP_ENTRY" }), true);
+  assert.equal(isDuplicateEntryError({ errno: 1062 }), true);
+  assert.equal(isDuplicateEntryError({ code: "23505" }), true);
+  assert.equal(isDuplicateEntryError({ code: "ER_PARSE_ERROR", errno: 1064 }), false);
+});

package/test/entrypoints.boundary.test.js

@@ -0,0 +1,34 @@
+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 { DatabaseRuntimeServiceProvider } from "../src/server/providers/DatabaseRuntimeServiceProvider.js";
+
+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["./server/providers/DatabaseRuntimeServiceProvider"],
+    "./src/server/providers/DatabaseRuntimeServiceProvider.js"
+  );
+  assert.equal(exportsMap["./shared"], "./src/shared/index.js");
+});
+
+test("client entrypoint exports no database runtime api", () => {
+  assert.deepEqual(Object.keys(clientApi), []);
+});
+
+test("server provider module exports service provider only", () => {
+  assert.equal(typeof DatabaseRuntimeServiceProvider, "function");
+});
+
+test("shared entrypoint exports shared database utilities only", () => {
+  assert.equal(typeof sharedApi.registerDatabaseRuntime, "function");
+  assert.equal(typeof sharedApi.createTransactionManager, "function");
+  assert.equal(typeof sharedApi.isDuplicateEntryError, "function");
+  assert.equal(typeof sharedApi.createRepositoryScope, "function");
+  assert.equal(typeof sharedApi.DatabaseRuntimeServiceProvider, "undefined");
+});

package/test/json.test.js

@@ -0,0 +1,9 @@
+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(""), []);
+});