@jskit-ai/database-runtime 0.1.4

package/test/providerRuntime.test.js

@@ -0,0 +1,174 @@
+import assert from "node:assert/strict";
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+
+import { KERNEL_TOKENS } from "@jskit-ai/kernel/shared/support/tokens";
+import { DatabaseRuntimeServiceProvider } from "../src/server/providers/DatabaseRuntimeServiceProvider.js";
+
+function createSingletonApp() {
+  const singletons = new Map();
+  const instances = new Map();
+
+  return {
+    has(token) {
+      return singletons.has(token) || instances.has(token);
+    },
+    singleton(token, factory) {
+      if (this.has(token)) {
+        throw new Error(`Token ${String(token)} is already registered.`);
+      }
+      singletons.set(token, {
+        factory,
+        resolved: false,
+        value: undefined
+      });
+    },
+    instance(token, value) {
+      if (this.has(token)) {
+        throw new Error(`Token ${String(token)} is already registered.`);
+      }
+      instances.set(token, value);
+    },
+    make(token) {
+      if (instances.has(token)) {
+        return instances.get(token);
+      }
+      if (!singletons.has(token)) {
+        throw new Error(`Token ${String(token)} is not registered.`);
+      }
+      const entry = singletons.get(token);
+      if (!entry.resolved) {
+        entry.value = entry.factory(this);
+        entry.resolved = true;
+        instances.set(token, entry.value);
+      }
+      return entry.value;
+    }
+  };
+}
+
+function createKnexStub() {
+  return {
+    async transaction(callback) {
+      return callback({ trxId: "trx-1" });
+    }
+  };
+}
+
+test("DatabaseRuntimeServiceProvider registers runtime api", () => {
+  const app = createSingletonApp();
+  const provider = new DatabaseRuntimeServiceProvider();
+  provider.register(app);
+
+  assert.equal(app.has("runtime.database"), true);
+  const api = app.make("runtime.database");
+  assert.equal(typeof api.createTransactionManager, "function");
+  assert.equal(typeof api.resolveRepoClient, "function");
+});
+
+test("DatabaseRuntimeServiceProvider registers transaction manager when Knex is pre-bound", async () => {
+  const app = createSingletonApp();
+  app.instance(KERNEL_TOKENS.Knex, createKnexStub());
+
+  const provider = new DatabaseRuntimeServiceProvider();
+  provider.register(app);
+
+  assert.equal(app.has(KERNEL_TOKENS.TransactionManager), true);
+  const transactionManager = app.make(KERNEL_TOKENS.TransactionManager);
+  const result = await transactionManager.inTransaction(async (trx) => trx.trxId);
+  assert.equal(result, "trx-1");
+});
+
+test("DatabaseRuntimeServiceProvider driver token resolves to registered mysql driver", () => {
+  const app = createSingletonApp();
+  app.instance("runtime.database.driver.mysql", Object.freeze({ DIALECT_ID: "mysql2" }));
+
+  const provider = new DatabaseRuntimeServiceProvider();
+  provider.register(app);
+
+  const driver = app.make("runtime.database.driver");
+  assert.deepEqual(driver, { DIALECT_ID: "mysql2" });
+});
+
+test("DatabaseRuntimeServiceProvider driver token throws when no driver registered", () => {
+  const app = createSingletonApp();
+  const provider = new DatabaseRuntimeServiceProvider();
+  provider.register(app);
+
+  assert.throws(() => app.make("runtime.database.driver"), /No database driver is registered\./);
+});
+
+test("DatabaseRuntimeServiceProvider driver token throws when multiple drivers are registered", () => {
+  const app = createSingletonApp();
+  app.instance("runtime.database.driver.mysql", Object.freeze({ DIALECT_ID: "mysql2" }));
+  app.instance("runtime.database.driver.postgres", Object.freeze({ DIALECT_ID: "pg" }));
+
+  const provider = new DatabaseRuntimeServiceProvider();
+  provider.register(app);
+
+  assert.throws(() => app.make("runtime.database.driver"), /Multiple database drivers are registered\./);
+});
+
+test("DatabaseRuntimeServiceProvider resolves knex from app root package context", async () => {
+  const appRoot = await mkdtemp(path.join(tmpdir(), "jskit-db-runtime-test-"));
+  const knexPackageDir = path.join(appRoot, "node_modules", "knex");
+  await mkdir(knexPackageDir, { recursive: true });
+  await writeFile(path.join(appRoot, "package.json"), JSON.stringify({ name: "runtime-app", private: true }), "utf8");
+  await writeFile(
+    path.join(knexPackageDir, "package.json"),
+    JSON.stringify({
+      name: "knex",
+      version: "0.0.0-test",
+      main: "index.js",
+      type: "commonjs"
+    }),
+    "utf8"
+  );
+  await writeFile(
+    path.join(knexPackageDir, "index.js"),
+    [
+      "module.exports = function knex(config) {",
+      "  return {",
+      "    __source: 'app-root-knex',",
+      "    __config: config,",
+      "    transaction: async function transaction(callback) {",
+      "      return callback({ trxId: 'trx-app-root' });",
+      "    }",
+      "  };",
+      "};",
+      ""
+    ].join("\n"),
+    "utf8"
+  );
+
+  const previousCwd = process.cwd();
+  try {
+    process.chdir(appRoot);
+
+    const app = createSingletonApp();
+    app.instance("runtime.database.driver.mysql", Object.freeze({ DIALECT_ID: "mysql2" }));
+    app.instance(KERNEL_TOKENS.Env, {
+      DB_HOST: "db.local",
+      DB_PORT: "3307",
+      DB_NAME: "appdb",
+      DB_USER: "appuser",
+      DB_PASSWORD: "apppass"
+    });
+
+    const provider = new DatabaseRuntimeServiceProvider();
+    provider.register(app);
+
+    const knex = app.make(KERNEL_TOKENS.Knex);
+    assert.equal(knex.__source, "app-root-knex");
+    assert.equal(knex.__config.client, "mysql2");
+    assert.equal(knex.__config.connection.host, "db.local");
+    assert.equal(knex.__config.connection.port, 3307);
+    assert.equal(knex.__config.connection.database, "appdb");
+    assert.equal(knex.__config.connection.user, "appuser");
+    assert.equal(knex.__config.connection.password, "apppass");
+  } finally {
+    process.chdir(previousCwd);
+  }
+});

package/test/repositoryOptions.test.js

@@ -0,0 +1,22 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { parseMetadataJson, stringifyMetadataJson } from "../src/shared/repositoryOptions.js";
+
+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), "{}");
+});

package/test/repositoryScope.test.js

@@ -0,0 +1,103 @@
+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_owner_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",
+      userOwnerId: 7
+    }
+  });
+
+  assert.deepEqual(calls, [["table", "contacts"], ["where", "user_owner_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,
+      userOwnerId: 9
+    }
+  });
+
+  assert.deepEqual(calls, [["where", "workspace_owner_id", 4], ["where", "user_owner_id", 9]]);
+
+  assert.deepEqual(
+    scope.withOwners(
+      {
+        name: "Ada"
+      },
+      {
+        visibilityContext: {
+          visibility: "workspace_user",
+          scopeOwnerId: 4,
+          userOwnerId: 9
+        }
+      }
+    ),
+    {
+      name: "Ada",
+      workspace_owner_id: 4,
+      user_owner_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

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

package/test/runtimeCore.test.js

@@ -0,0 +1,98 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { KERNEL_TOKENS } from "@jskit-ai/kernel/shared/support/tokens";
+import {
+  BaseRepository,
+  buildPaginationMeta,
+  createTransactionManager,
+  registerDatabaseRuntime
+} from "../src/shared/index.js";
+
+function createKnexStub() {
+  return {
+    async transaction(callback) {
+      return callback({ trxId: "trx-1" });
+    }
+  };
+}
+
+function createSingletonApp() {
+  const singletons = new Map();
+  const instances = new Map();
+
+  return {
+    has(token) {
+      return singletons.has(token) || instances.has(token);
+    },
+    instance(token, value) {
+      if (this.has(token)) {
+        throw new Error(`Token ${String(token)} is already registered.`);
+      }
+      instances.set(token, value);
+    },
+    singleton(token, factory) {
+      if (this.has(token)) {
+        throw new Error(`Token ${String(token)} is already registered.`);
+      }
+      singletons.set(token, {
+        factory,
+        resolved: false,
+        value: undefined
+      });
+    },
+    make(token) {
+      if (instances.has(token)) {
+        return instances.get(token);
+      }
+      if (!singletons.has(token)) {
+        throw new Error(`Token ${String(token)} is not registered.`);
+      }
+      const entry = singletons.get(token);
+      if (!entry.resolved) {
+        entry.value = entry.factory(this);
+        entry.resolved = true;
+        instances.set(token, entry.value);
+      }
+      return entry.value;
+    }
+  };
+}
+
+test("transaction manager wraps callback in knex transaction", async () => {
+  const manager = createTransactionManager({ knex: createKnexStub() });
+  const result = await manager.inTransaction(async (trx) => ({ ok: true, trx }));
+  assert.equal(result.ok, true);
+  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("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
+  });
+});
+
+test("registerDatabaseRuntime binds knex and transaction manager tokens", () => {
+  const app = createSingletonApp();
+  const knex = createKnexStub();
+
+  const runtime = registerDatabaseRuntime(app, { knex });
+  assert.strictEqual(runtime.knex, knex);
+  assert.equal(typeof runtime.transactionManager.inTransaction, "function");
+  assert.strictEqual(app.make(KERNEL_TOKENS.Knex), knex);
+});

package/test/visibility.test.js

@@ -0,0 +1,93 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { applyVisibility, applyVisibilityOwners } from "../src/shared/visibility.js";
+
+function createQueryBuilderStub() {
+  return {
+    calls: [],
+    where(...args) {
+      this.calls.push(["where", ...args]);
+      return this;
+    },
+    whereRaw(sql) {
+      this.calls.push(["whereRaw", sql]);
+      return this;
+    }
+  };
+}
+
+test("applyVisibility appends scope filters to query builders", () => {
+  const publicQuery = createQueryBuilderStub();
+  applyVisibility(publicQuery, {
+    visibility: "public"
+  });
+  assert.deepEqual(publicQuery.calls, []);
+
+  const workspaceQuery = createQueryBuilderStub();
+  applyVisibility(workspaceQuery, {
+    visibility: "workspace",
+    scopeOwnerId: 12
+  });
+  assert.deepEqual(workspaceQuery.calls, [["where", "workspace_owner_id", 12]]);
+
+  const userQuery = createQueryBuilderStub();
+  applyVisibility(userQuery, {
+    visibility: "user",
+    userOwnerId: 7
+  });
+  assert.deepEqual(userQuery.calls, [["where", "user_owner_id", 7]]);
+
+  const deniedQuery = createQueryBuilderStub();
+  applyVisibility(deniedQuery, {
+    visibility: "workspace_user",
+    scopeOwnerId: 3
+  });
+  assert.deepEqual(deniedQuery.calls, [["whereRaw", "1 = 0"]]);
+});
+
+test("applyVisibilityOwners injects owner columns for write payloads", () => {
+  assert.deepEqual(
+    applyVisibilityOwners(
+      {
+        name: "Alice"
+      },
+      {
+        visibility: "public"
+      }
+    ),
+    {
+      name: "Alice"
+    }
+  );
+
+  assert.deepEqual(
+    applyVisibilityOwners(
+      {
+        name: "Alice"
+      },
+      {
+        visibility: "workspace_user",
+        scopeOwnerId: 4,
+        userOwnerId: 9
+      }
+    ),
+    {
+      name: "Alice",
+      workspace_owner_id: 4,
+      user_owner_id: 9
+    }
+  );
+
+  assert.throws(
+    () =>
+      applyVisibilityOwners(
+        {
+          name: "Alice"
+        },
+        {
+          visibility: "user"
+        }
+      ),
+    /requires userOwnerId/
+  );
+});