@jskit-ai/resource-runtime 0.0.0-stage → 0.2.12

package/src/test/index.js

@@ -0,0 +1,122 @@
+import { AssertionError } from "node:assert";
+import { ActionProvider } from "@jskit-ai/kernel/server/actions";
+import { EventProvider } from "@jskit-ai/kernel/server/runtime";
+import { silentLogger } from "@jskit-ai/kernel/server/runtime/logger";
+import { createCapabilityRuntime, defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import { requireTestDatabase, tableNames, TestDatabaseMissingError } from "@jskit-ai/database-runtime/server/testDatabases";
+import { createResourceHost } from "../server/resourceHost.js";
+import { createResourceRuntime } from "../server/resourceRuntime.js";
+import { expectFlatQueries } from "./expectFlatQueries.js";
+import { expectScoped } from "./expectScoped.js";
+
+// Tables every migrated database has that no feature owns: the migration ledger.
+const MIGRATION_TABLES = Object.freeze(["knex_migrations", "knex_migrations_lock"]);
+
+/**
+ * A resource runtime on the test's own Knex, for a package test that owns
+ * tables without booting a server: `runtime.own(featureId, owns)` answers handles.
+ * With `createTables`, own() also creates each owned table from its resource's
+ * schema, for a SQLite test whose shipped migrations are written for another database.
+ * `hostHooks` are json-rest-api hooks the test installs on the runtime's host,
+ * such as an afterCommit that fails on request.
+ * @param {object} options
+ * @param {import("knex").Knex} options.knex
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeLogger} [options.logger]
+ * @param {number} [options.requestRowLimit]
+ * @param {number} [options.serverPageSize]
+ * @param {boolean} [options.createTables]
+ * @param {Record<string, Function>} [options.hostHooks]
+ */
+async function createTestResourceRuntime({ knex, logger = silentLogger, requestRowLimit, serverPageSize, createTables = false, hostHooks }) {
+  const api = await createResourceHost({ knex, logger });
+  if (hostHooks) {
+    await api.customize({ hooks: hostHooks });
+  }
+  const runtime = createResourceRuntime({ api, requestRowLimit, serverPageSize });
+  if (!createTables) {
+    return runtime;
+  }
+  return Object.freeze({
+    ...runtime,
+    async own(featureId, owns) {
+      const handles = await runtime.own(featureId, owns);
+      for (const name of Object.keys(handles)) {
+        await api.resources[name].createKnexTable();
+      }
+      return handles;
+    }
+  });
+}
+
+/**
+ * Starts features as an application's server does, on the test's own Knex and
+ * without HTTP: the kernel orders them by what they require, the resource
+ * runtime gives each owner its handles and system context (with `createTables`,
+ * it also creates each owned table from its resource), and every boot runs, so
+ * a registry that seals at boot, such as `crud.contracts`, is sealed. The
+ * runtime's events and actions are started with them; `inputs` give anything
+ * else the features require, by capability id, and `requires` names what the
+ * test reads, as a feature's own requires do. `stop()` shuts them down.
+ * @template {Record<string, string>} R
+ * @param {object} options
+ * @param {import("knex").Knex} options.knex
+ * @param {ReadonlyArray<ReturnType<typeof defineProvider>>} options.features The features and providers under test.
+ * @param {R} [options.requires] What the test reads: local name to capability id.
+ * @param {Record<string, unknown>} [options.inputs] Capability values given as they are, by capability id.
+ * @param {boolean} [options.createTables]
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeLogger} [options.logger]
+ * @returns {Promise<{ capabilities: { [K in keyof R]: any }, resources: ReturnType<typeof createResourceRuntime>, stop: () => Promise<unknown> }>}
+ */
+async function startTestFeatures({ knex, features, requires = {}, inputs = {}, createTables = false, logger = silentLogger }) {
+  const resources = await createTestResourceRuntime({ knex, logger, createTables });
+  let capabilities = {};
+  const reader = defineProvider({
+    id: "test.features.reader",
+    requires,
+    /** @param {Record<string, unknown>} values The capabilities the test reads. */
+    setup(values) {
+      capabilities = Object.freeze({ ...values });
+      return {};
+    }
+  });
+  const runtime = createCapabilityRuntime({
+    inputs: { "runtime.logger": logger, ...inputs, "runtime.resources": resources },
+    providers: [EventProvider, ActionProvider, ...features, reader]
+  });
+  await runtime.start();
+  return Object.freeze({
+    capabilities,
+    resources,
+    stop: () => runtime.shutdown()
+  });
+}
+
+/**
+ * Fails when the migrated test database holds a table no feature owns and no
+ * package declares as infrastructure (the migration ledger always is).
+ * @param {object} options
+ * @param {import("knex").Knex} options.knex The test database.
+ * @param {{ ownedTables(): ReadonlyArray<{ tableName: string }> }} options.runtime The resource runtime every feature owned its tables through.
+ * @param {ReadonlyArray<string>} [options.infrastructureTables] Tables a package keeps outside resources, such as sessions of a sign-in library.
+ * @param {import("@jskit-ai/kernel/server/types").RuntimeEnv} options.environment The test's environment, such as `process.env`.
+ */
+async function expectEveryTableOwned({ knex, runtime, infrastructureTables = [], environment }) {
+  requireTestDatabase(environment);
+  const accounted = new Set([...MIGRATION_TABLES, ...infrastructureTables, ...runtime.ownedTables().map(({ tableName }) => tableName)]);
+  const unowned = (await tableNames(knex)).filter((table) => !accounted.has(table));
+  if (unowned.length > 0) {
+    throw new AssertionError({
+      message: `Tables no feature owns: ${unowned.join(", ")}. Each table is a table resource one feature owns, or a declared infrastructure table.`
+    });
+  }
+}
+
+export {
+  TestDatabaseMissingError,
+  createTestResourceRuntime,
+  expectEveryTableOwned,
+  expectFlatQueries,
+  expectScoped,
+  requireTestDatabase,
+  startTestFeatures
+};

package/test/callSettings.test.js

@@ -0,0 +1,99 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import knexLib from "knex";
+import { defineTableResource } from "@jskit-ai/resource-core/shared/tableResource";
+import { passedOn } from "../src/server/index.js";
+import { createTestResourceRuntime } from "../src/test/index.js";
+
+// A call's settings (returning, missing, format, lockVersion...) are for that one call. What it hands on, to the work
+// of a transaction, to an afterWrite hook or to the handle's own nested calls, is its context and transaction only.
+
+const WORKSPACE = Object.freeze({ context: Object.freeze({ workspace: { id: "1" } }) });
+// Every setting a caller may have spread into the options it hands on.
+const SETTINGS = Object.freeze({ returning: "none", missing: "skip", format: "jsonapi", fields: ["title"], lockVersion: 3 });
+const notFound = (error) => error.code === "REST_API_RESOURCE" && error.subtype === "not_found";
+
+async function createNotes(t, hooks) {
+  const knex = knexLib({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true });
+  t.after(() => knex.destroy());
+  await knex.schema.createTable("notes", (table) => {
+    table.increments("id");
+    table.integer("workspace_id").nullable();
+    table.string("title").notNullable();
+    table.integer("lock_version").notNullable().defaultTo(0);
+  });
+  await knex.schema.createTable("counters", (table) => {
+    table.string("id").primary();
+    table.integer("value").notNullable();
+  });
+  // lockOrCreate creates on the id alone, so it runs on a table without owners.
+  const counters = defineTableResource({
+    name: "counters",
+    tableName: "counters",
+    ownership: "public",
+    schema: { id: { type: "string", primary: true }, value: { type: "integer", required: true } }
+  });
+  const resource = defineTableResource({
+    name: "notes",
+    tableName: "notes",
+    ownership: "workspace",
+    lockVersionField: "lockVersion",
+    schema: {
+      id: { type: "id", primary: true },
+      workspaceId: { type: "id", nullable: true, search: true, storage: { column: "workspace_id" } },
+      title: { type: "string", required: true, search: true },
+      lockVersion: { type: "integer", defaultTo: 0, storage: { column: "lock_version" } }
+    }
+  });
+  const runtime = await createTestResourceRuntime({ knex });
+  const owned = await runtime.own("notes.feature", [hooks ? { resource, hooks } : resource, { normalizeId: String, resource: counters }]);
+  return { notes: owned.notes, counters: owned.counters };
+}
+
+test("withTransaction's work receives the context and the transaction, never the caller's settings", async (t) => {
+  const { notes } = await createNotes(t);
+  const keys = await notes.withTransaction({ ...WORKSPACE, ...SETTINGS }, async (txOptions) => {
+    // A create inside answers its record: an outer returning: "none" never reached it.
+    const created = await notes.create({ title: "inside" }, txOptions);
+    assert.equal(created.title, "inside");
+    // A get of a missing record throws: an outer missing: "skip" never reached it.
+    await assert.rejects(notes.get("999", {}, txOptions), notFound);
+    // Inside the caller's transaction too.
+    const nested = await notes.withTransaction({ ...txOptions, ...SETTINGS }, async (inner) => Object.keys(inner).sort());
+    assert.deepEqual(nested, ["context", "trx"]);
+    return Object.keys(txOptions).sort();
+  });
+  assert.deepEqual(keys, ["context", "trx"]);
+  assert.deepEqual(Object.keys(passedOn({ ...WORKSPACE, ...SETTINGS })), ["context"]);
+});
+
+test("an afterWrite hook and lockOrCreate's work receive only the context and the transaction", async (t) => {
+  const seen = [];
+  const { notes, counters } = await createNotes(t, { afterWrite: ({ options }) => { seen.push(Object.keys(options).sort()); } });
+  await notes.create({ title: "hooked" }, { ...WORKSPACE, returning: "id" });
+  await notes.withTransaction(WORKSPACE, (txOptions) => notes.create({ title: "inside" }, { ...txOptions, returning: "none" }));
+  assert.deepEqual(seen, [["context", "trx"], ["context", "trx"]]);
+
+  const outside = await counters.lockOrCreate({ id: "visits", value: 0 }, { ...WORKSPACE, returning: "none" }, (row, txOptions) => Object.keys(txOptions).sort());
+  assert.deepEqual(outside, ["context", "trx"]);
+  const inside = await counters.withTransaction(WORKSPACE, (txOptions) => counters.lockOrCreate(
+    { id: "visits", value: 5 },
+    { ...txOptions, returning: "none" },
+    (row, work) => [row.value, Object.keys(work).sort()]
+  ));
+  assert.deepEqual(inside, [0, ["context", "trx"]]);
+});
+
+test("findOrCreate answers the record under an outer returning: none, and a patch keeps its own format", async (t) => {
+  const { notes } = await createNotes(t);
+  const found = await notes.findOrCreate({ id: 7, title: "first" }, { ...WORKSPACE, returning: "none" });
+  assert.equal(found.title, "first");
+  assert.equal((await notes.findOrCreate({ id: 7, title: "again" }, { ...WORKSPACE, returning: "none" })).title, "first");
+
+  // The patch's own settings still reach its own write and read inside the transaction it opens for its lockVersion.
+  const document = await notes.patch(7, { title: "second" }, { ...WORKSPACE, lockVersion: 0, format: "jsonapi" });
+  assert.equal(document.data.attributes.title, "second");
+  const advanced = await notes.patch(7, {}, { ...WORKSPACE, lockVersion: 1, format: "jsonapi" });
+  assert.equal(advanced.data.attributes.lockVersion, 2);
+  assert.equal((await notes.patch(7, {}, { ...WORKSPACE, format: "jsonapi" })).data.id, "7");
+});