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

package/test/hiddenFields.test.js

@@ -0,0 +1,203 @@
+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 { countQueries } from "@jskit-ai/database-runtime/server/testDatabases";
+import { withoutHiddenFields } from "../src/server/index.js";
+import { createTestResourceRuntime } from "../src/test/index.js";
+
+const WORKSPACE_A = Object.freeze({ workspace: { id: "1" } });
+
+// Cards with a hidden owner, a hidden bearer token, a hidden flag, a hidden count and a hidden time: two in workspace
+// 1 and one in workspace 2.
+async function createCardFixture(t) {
+  const knex = knexLib({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true });
+  t.after(() => knex.destroy());
+  await knex.schema.createTable("cards", (table) => {
+    table.increments("id");
+    table.integer("workspace_id").notNullable();
+    table.string("title").notNullable();
+    table.string("public_token");
+    table.boolean("sent");
+    table.integer("views");
+    table.dateTime("issued_at");
+  });
+  await knex("cards").insert([
+    { workspace_id: 1, title: "Rex", public_token: "t1", sent: 1, views: 3 },
+    { workspace_id: 1, title: "Bo", public_token: "t2", sent: 0, views: null },
+    { workspace_id: 2, title: "Kit", public_token: "t3", sent: 1, views: 1 }
+  ]);
+  const resource = defineTableResource({
+    name: "cards",
+    tableName: "cards",
+    ownership: "workspace",
+    schema: {
+      workspaceId: { type: "id", required: true, hidden: true, storage: { column: "workspace_id" } },
+      title: { type: "string", required: true, search: true },
+      publicToken: { type: "string", nullable: true, hidden: true, storage: { column: "public_token" } },
+      sent: { type: "boolean", nullable: true, hidden: true },
+      views: { type: "integer", nullable: true, hidden: true },
+      issuedAt: { type: "dateTime", nullable: true, hidden: true, storage: { column: "issued_at" } }
+    }
+  });
+  const runtime = await createTestResourceRuntime({ knex });
+  const { cards } = await runtime.own("cards.feature", [resource]);
+  const system = runtime.declareSystemScope("cards.feature", "send each workspace its cards")("send the cards");
+  // The tables each SELECT reads, in order.
+  const selects = async (work) => (await countQueries(knex, work)).queries
+    .filter((sql) => /^select/iu.test(sql))
+    .map((sql) => [...sql.matchAll(/from `(\w+)`/gu)].map(([, table]) => table)[0]);
+  return { cards, resource, system, selects, options: { context: WORKSPACE_A } };
+}
+
+test("a handle's plain read answers the hidden fields its fields names, in one more statement, and no read without them does", async (t) => {
+  const { cards, system, selects, options } = await createCardFixture(t);
+  let card;
+  const plainRead = await selects(async () => {
+    card = await cards.get("1", {}, options);
+  });
+  assert.deepEqual(card, { id: "1", title: "Rex" });
+  assert.deepEqual(await selects(async () => {
+    card = await cards.get("1", { fields: ["title", "publicToken", "workspaceId"] }, options);
+  }), [...plainRead, "cards"]);
+  assert.deepEqual(card, { id: "1", title: "Rex", publicToken: "t1", workspaceId: "1" });
+  assert.equal(await cards.get("3", { fields: ["publicToken"] }, { ...options, missing: "skip" }), null);
+
+  const { records } = await cards.query({ fields: ["title", "sent", "views"], page: { size: 10 } }, options);
+  assert.deepEqual(records, [{ id: "1", title: "Rex", sent: true, views: 3 }, { id: "2", title: "Bo", sent: false, views: null }]);
+  assert.deepEqual(await cards.queryAll({ filters: { title: "Bo" }, fields: ["publicToken"] }, options), [{ id: "2", publicToken: "t2" }]);
+
+  // A system context reads every workspace's rows, and learns each one's owner.
+  const owners = await cards.queryAll({ fields: ["workspaceId"] }, { context: system });
+  assert.deepEqual(owners, [{ id: "1", workspaceId: "1" }, { id: "2", workspaceId: "1" }, { id: "3", workspaceId: "2" }]);
+
+  // The locks read them after the locking read, in the same transaction.
+  await cards.withTransaction(options, async (tx) => {
+    assert.deepEqual(await cards.lock("1", { ...tx, fields: ["publicToken"] }), { id: "1", publicToken: "t1" });
+    assert.deepEqual(await cards.lockMany(["1", "2"], { ...tx, fields: ["sent"] }), [{ id: "1", sent: true }, { id: "2", sent: false }]);
+    assert.deepEqual(await cards.lockWhere({ title: "Rex" }, { ...tx, fields: ["views"] }), [{ id: "1", views: 3 }]);
+    assert.deepEqual(await cards.claim({ filters: { title: "Bo" } }, { ...tx, fields: ["title", "publicToken"] }),
+      [{ id: "2", title: "Bo", publicToken: "t2" }]);
+  });
+});
+
+test("a JSON:API read never answers a hidden field, and a hidden field a read cannot decode is refused before it runs", async (t) => {
+  const { cards, selects, options } = await createCardFixture(t);
+  const document = await cards.query({ fields: ["title", "publicToken"], page: { size: 10 } }, { ...options, format: "jsonapi" });
+  assert.deepEqual(document.data.map(({ attributes }) => attributes), [{ title: "Rex" }, { title: "Bo" }]);
+  const one = await cards.get("1", { fields: ["title", "publicToken"] }, { ...options, format: "jsonapi" });
+  assert.deepEqual(one.data.attributes, { title: "Rex" });
+
+  assert.deepEqual(await selects(() => assert.rejects(cards.queryAll({ fields: ["issuedAt"] }, options),
+    /cards: fields names the hidden field "issuedAt", but a read answers a hidden field only when it is a stored id/u)), []);
+});
+
+test("withoutHiddenFields refuses another feature's read naming a hidden field, unless it runs in a system context", async (t) => {
+  const { cards, resource, system, options } = await createCardFixture(t);
+  const exposed = withoutHiddenFields(cards, resource);
+  await assert.rejects(exposed.get("1", { fields: ["title", "publicToken"] }, options),
+    /cards\.get\(\) fields names the hidden field "publicToken", which only the table's owner, or a system context, reads/u);
+  await assert.rejects(exposed.queryAll({ fields: ["workspaceId", "sent"] }, options), /hidden field "workspaceId", "sent"/u);
+  await assert.rejects(exposed.withTransaction(options, (tx) => exposed.lockMany(["1"], { ...tx, fields: ["publicToken"] })),
+    /cards\.lockMany\(\) fields names the hidden field "publicToken"/u);
+  assert.deepEqual(await exposed.get("1", { fields: ["title"] }, options), { id: "1", title: "Rex" });
+  assert.deepEqual(await exposed.queryAll({ filters: { title: "Kit" }, fields: ["workspaceId"] }, { context: system }),
+    [{ id: "3", workspaceId: "2" }]);
+  assert.deepEqual(await exposed.queryAll({ filters: { title: "Kit" }, fields: ["publicToken"] }, { context: system.forWorkspace("2") }),
+    [{ id: "3", publicToken: "t3" }]);
+  // Everything else is the repository's own, and a resource without hidden fields keeps its repository.
+  assert.equal(exposed.column("title"), cards.column("title"));
+  assert.equal(exposed.name, "cards");
+  assert.equal(Object.isFrozen(exposed), true);
+  const plain = defineTableResource({ name: "notes", tableName: "notes", ownership: "public", schema: { body: { type: "string" } } });
+  assert.equal(withoutHiddenFields(cards, plain), cards);
+});
+
+test("withoutHiddenFields refuses another feature's scopedQuery, whose builder carries the hidden columns, and the owner's join source still joins", async (t) => {
+  const { cards, resource, system, options } = await createCardFixture(t);
+  // The owner's join source, a method its decorateRepository adds with the handle it receives.
+  async function cardSource(alias, callOptions) {
+    const { query } = await cards.scopedQuery({ alias }, callOptions);
+    return { query, column: (field) => cards.column(field, alias) };
+  }
+  const exposed = withoutHiddenFields(Object.freeze({ ...cards, cardSource }), resource);
+
+  // Another feature's own builder would select the token: refused before it reads anything.
+  await assert.rejects(
+    (async () => (await exposed.scopedQuery({}, options)).query.select(exposed.column("publicToken")))(),
+    /cards\.scopedQuery\(\) answers every column, its hidden fields too, which only the table's owner, or a system context, reads/u
+  );
+  await assert.rejects(exposed.withTransaction(options, (tx) => exposed.scopedQuery({ alias: "c" }, tx)), /cards\.scopedQuery\(\)/u);
+
+  // A system context, and one it derived, still builds on it.
+  const { query: everyWorkspace } = await exposed.scopedQuery({}, { context: system });
+  assert.deepEqual((await everyWorkspace.count({ cards: exposed.column("id") }))[0].cards, 3);
+  const { query: workspaceTwo } = await exposed.scopedQuery({}, { context: system.forWorkspace("2") });
+  assert.deepEqual(await workspaceTwo.select({ title: exposed.column("title") }), [{ title: "Kit" }]);
+
+  // The cross-owner report pattern: the owner's method answers its scoped rows, which the report selects from.
+  const source = await exposed.cardSource("c", options);
+  const rows = await source.query.select({ title: source.column("title") }).orderBy(source.column("id"));
+  assert.deepEqual(rows, [{ title: "Rex" }, { title: "Bo" }]);
+});
+
+test("withoutHiddenFields answers raw(), column() and an owner's Knex values as they are, so another feature builds on them in a scoped query and a subquery", async (t) => {
+  const { cards, resource, options } = await createCardFixture(t);
+  async function cardSource(alias, callOptions) {
+    const { query } = await cards.scopedQuery({ alias }, callOptions);
+    return { query, column: (field) => cards.column(field, alias) };
+  }
+  // An owner's method answering a Knex value at once: an expression over its own column.
+  const lowerTitle = (alias) => cards.raw("LOWER(??)", [cards.column("title", alias)]);
+  const exposed = withoutHiddenFields(Object.freeze({ ...cards, cardSource, lowerTitle }), resource);
+
+  assert.equal(exposed.column("title", "c"), cards.column("title", "c"));
+  const shout = exposed.raw("UPPER(??)", [exposed.column("title", "c")]);
+  assert.equal(shout.then, undefined);
+  assert.equal(typeof exposed.lowerTitle("i").toSQL, "function");
+
+  // In the owner's scoped rows, as a select.
+  const source = await exposed.cardSource("c", options);
+  assert.deepEqual(await source.query.select({ shout }).orderBy(source.column("id")), [{ shout: "REX" }, { shout: "BO" }]);
+
+  // In a subquery: the cards of workspace 1 whose lower-cased title is "bo".
+  const outer = await exposed.cardSource("c", options);
+  const inner = await exposed.cardSource("i", options);
+  const matching = inner.query.select(inner.column("id")).where(exposed.lowerTitle("i"), exposed.raw("?", ["bo"]));
+  assert.deepEqual(await outer.query.whereIn(outer.column("id"), matching).select({ title: outer.column("title") }), [{ title: "Bo" }]);
+});
+
+test("withoutHiddenFields strips the hidden fields from every answer of a read the owner adds, unless it runs in a system context", async (t) => {
+  const { cards, resource, system, options } = await createCardFixture(t);
+  // The owner's decorateRepository reads: one forwarding the caller's params, the handle's own under another name, one
+  // answering a map, one in a sub-repository and one answering at once.
+  const owner = Object.freeze({
+    ...cards,
+    queryAllIncludingArchived: (params, callOptions) => cards.queryAll(params, callOptions),
+    everyCard: cards.queryAll,
+    async cardsByTitle(callOptions) {
+      const records = await cards.queryAll({ fields: ["title", "publicToken"] }, callOptions);
+      return new Map(records.map((record) => [record.title, record]));
+    },
+    archive: Object.freeze({ list: (callOptions) => cards.queryAll({ fields: ["title", "views"] }, callOptions) }),
+    tokenLength: (card) => String(card.publicToken).length
+  });
+  const exposed = withoutHiddenFields(owner, resource);
+
+  // Another feature's calls: no hidden field leaves, whatever the method's name or depth.
+  assert.deepEqual(await exposed.queryAllIncludingArchived({ filters: { title: "Rex" }, fields: ["title", "publicToken", "workspaceId"] }, options),
+    [{ id: "1", title: "Rex" }]);
+  assert.deepEqual(await exposed.everyCard({ filters: { title: "Bo" }, fields: ["publicToken"] }, options), [{ id: "2" }]);
+  assert.deepEqual([...(await exposed.cardsByTitle(options)).values()], [{ id: "1", title: "Rex" }, { id: "2", title: "Bo" }]);
+  assert.deepEqual(await exposed.archive.list(options), [{ id: "1", title: "Rex" }, { id: "2", title: "Bo" }]);
+  // A method that answers at once still does, and withTransaction answers the caller's own work as it is.
+  assert.equal(exposed.tokenLength({ publicToken: "abc" }), 3);
+  assert.deepEqual(await exposed.withTransaction(options, async () => ({ publicToken: "the caller's own" })), { publicToken: "the caller's own" });
+
+  // The owner, with its own repository, and a system context, or one it derived, still read them when named.
+  assert.deepEqual(await owner.queryAllIncludingArchived({ filters: { title: "Rex" }, fields: ["publicToken"] }, options),
+    [{ id: "1", publicToken: "t1" }]);
+  assert.deepEqual(await exposed.queryAllIncludingArchived({ filters: { title: "Kit" }, fields: ["publicToken", "workspaceId"] }, { context: system }),
+    [{ id: "3", publicToken: "t3", workspaceId: "2" }]);
+  assert.deepEqual(await exposed.archive.list({ context: system.forWorkspace("2") }), [{ id: "3", title: "Kit", views: 1 }]);
+});

package/test/i18nCatalog.test.js

@@ -0,0 +1,18 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { evaluateI18nCatalogContract } from "../../../tooling/test-support/i18nCatalogContract.mjs";
+
+const TEST_DIRECTORY = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(TEST_DIRECTORY, "..", "..", "..");
+
+test("resource-runtime English catalog matches its source", () => {
+  const { problems } = evaluateI18nCatalogContract({
+    repoRoot: REPO_ROOT,
+    packageDir: path.join(REPO_ROOT, "packages", "resource-runtime"),
+    // json-rest-api throws these; their English is fixed by the library.
+    externalCodes: ["REST_API_VERSION_CONFLICT", "REST_API_PRECONDITION_FAILED"]
+  });
+  assert.deepEqual(problems, []);
+});

package/test/lostInsertRace.test.js

@@ -0,0 +1,64 @@
+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 { isDuplicateEntryError, retryLostInsertRace } from "@jskit-ai/database-runtime/shared";
+import { createTestResourceRuntime } from "../src/test/index.js";
+
+const WORKSPACE_A = Object.freeze({ workspace: { id: "1" } });
+
+// Requests keyed by a request key, unique in each workspace: a repeated request finds its first answer by the key.
+async function createRequestFixture(t) {
+  const knex = knexLib({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true });
+  t.after(() => knex.destroy());
+  await knex.schema.createTable("requests", (table) => {
+    table.increments("id");
+    table.integer("workspace_id").notNullable();
+    table.string("request_key").notNullable();
+    table.integer("amount").notNullable();
+    table.unique(["workspace_id", "request_key"]);
+  });
+  const runtime = await createTestResourceRuntime({ knex });
+  const { requests } = await runtime.own("requests.feature", [defineTableResource({
+    name: "requests",
+    tableName: "requests",
+    ownership: "workspace",
+    schema: {
+      workspaceId: { type: "id", nullable: true, storage: { column: "workspace_id" } },
+      requestKey: { type: "string", required: true, search: true, storage: { column: "request_key" } },
+      amount: { type: "integer", required: true }
+    }
+  })]);
+  return { knex, requests };
+}
+
+test("retryLostInsertRace runs a transaction whose insert lost a unique race once more, and the rerun finds the winner", async (t) => {
+  const { knex, requests } = await createRequestFixture(t);
+  const options = { context: WORKSPACE_A };
+  // The winner commits after this request looked its key up: the first run reads no row, as a snapshot taken before
+  // that commit does, so its insert fails on the key and its transaction rolls back.
+  await requests.create({ requestKey: "k", amount: 5 }, options);
+  let runs = 0;
+  const answer = await retryLostInsertRace(options, () => requests.withTransaction(options, async (txOptions) => {
+    runs += 1;
+    const [existing] = runs === 1 ? [] : await requests.queryAll({ filters: { requestKey: "k" }, fields: ["amount"] }, txOptions);
+    if (existing) {
+      return existing;
+    }
+    await requests.create({ requestKey: "k", amount: 9 }, { ...txOptions, returning: "none" });
+    return null;
+  }));
+  assert.equal(runs, 2);
+  assert.equal(answer.amount, 5);
+  assert.deepEqual(await knex("requests").pluck("amount"), [5]);
+
+  // Inside the caller's transaction the failed insert fails that transaction: nothing runs again, and the caller
+  // gets the duplicate.
+  runs = 0;
+  await assert.rejects(requests.withTransaction(options, (outer) => retryLostInsertRace(outer, () => requests.withTransaction(outer, (txOptions) => {
+    runs += 1;
+    return requests.create({ requestKey: "k", amount: 1 }, { ...txOptions, returning: "none" });
+  }))), (error) => isDuplicateEntryError(error));
+  assert.equal(runs, 1);
+  assert.deepEqual(await knex("requests").pluck("amount"), [5]);
+});

package/test/manyRowWrites.mysql.test.js

@@ -0,0 +1,145 @@
+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 { requireTestDatabase } from "@jskit-ai/database-runtime/server/testDatabases";
+import { createTestResourceRuntime } from "../src/test/index.js";
+
+// patchWhere and deleteWhere on MySQL or MariaDB, under two concurrent writers: each checks its filters on the row
+// once it holds the row's lock, so of two writers whose filters both matched a row, the one that waited for the
+// other's lock leaves the row out when it no longer matches (a compare-and-set on the filters).
+
+const WORKSPACE = Object.freeze({ workspace: { id: "1" } });
+const RUNTIME_MYSQL = Object.freeze({ supportBigNumbers: true, bigNumberStrings: true, dateStrings: ["DATE"], timezone: "Z" });
+
+const slotResource = defineTableResource({
+  name: "slots",
+  tableName: "slots",
+  ownership: "workspace",
+  defaultSort: ["id"],
+  schema: {
+    id: { type: "id", primary: true },
+    workspaceId: { type: "id", nullable: true, search: true, storage: { column: "workspace_id" } },
+    status: { type: "string", defaultTo: "open", search: true },
+    takenBy: { type: "string", nullable: true, storage: { column: "taken_by" } }
+  }
+});
+
+/**
+ * A database of the test's own beside TEST_DB_NAME, with one slots table, dropped after the test. Every connection
+ * runs with MariaDB's innodb_snapshot_isolation set to `snapshotIsolation` (default off). A server without the
+ * setting (MySQL, older MariaDB) behaves as off, so asking it for on answers null.
+ */
+async function ownDatabase(context, suffix, { snapshotIsolation = false } = {}) {
+  const name = `${requireTestDatabase(process.env)}_${suffix}`;
+  const server = { host: process.env.DB_HOST, port: Number(process.env.DB_PORT) || 3306, user: process.env.DB_USER, password: process.env.DB_PASSWORD };
+  const admin = knexLib({ client: "mysql2", connection: server, pool: { min: 0, max: 1 } });
+  const [variables] = await admin.raw("SHOW VARIABLES LIKE 'innodb_snapshot_isolation'");
+  if (snapshotIsolation && variables.length === 0) {
+    await admin.destroy();
+    return null;
+  }
+  await admin.raw("DROP DATABASE IF EXISTS ??", [name]);
+  await admin.raw("CREATE DATABASE ??", [name]);
+  const setting = variables.length === 0 ? null : `SET SESSION innodb_snapshot_isolation = ${snapshotIsolation ? "ON" : "OFF"}`;
+  const knex = knexLib({
+    client: "mysql2",
+    connection: { ...server, database: name, ...RUNTIME_MYSQL },
+    pool: { min: 0, max: 6, ...(setting ? { afterCreate: (connection, done) => connection.query(setting, (error) => done(error, connection)) } : {}) }
+  });
+  context.after(async () => {
+    await knex.destroy();
+    await admin.raw("DROP DATABASE IF EXISTS ??", [name]);
+    await admin.destroy();
+  });
+  await knex.schema.createTable("slots", (table) => {
+    table.increments("id");
+    table.integer("workspace_id").nullable();
+    table.string("status").notNullable().defaultTo("open");
+    table.string("taken_by").nullable();
+  });
+  const runtime = await createTestResourceRuntime({ knex });
+  const { slots } = await runtime.own("slots.feature", [slotResource]);
+  return { knex, slots };
+}
+
+const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Waits until `count` transactions on this test's database wait for a row lock. A server that keeps INNODB_TRX from
+ * the test user gets a fixed pause instead, long enough for both writers to reach the lock.
+ */
+async function bothWaiting(knex, count) {
+  for (let waited = 0; waited < 10_000; waited += 25) {
+    let waiting;
+    try {
+      const [[row]] = await knex.raw(
+        "SELECT COUNT(*) AS waiting FROM information_schema.INNODB_TRX t JOIN information_schema.PROCESSLIST p " +
+        "ON p.ID = t.trx_mysql_thread_id WHERE t.trx_state = 'LOCK WAIT' AND p.DB = DATABASE()"
+      );
+      waiting = Number(row.waiting);
+    } catch {
+      await pause(500);
+      return;
+    }
+    if (waiting >= count) return;
+    await pause(25);
+  }
+  assert.fail(`${count} writers did not reach the row's lock within 10 s`);
+}
+
+/** Holds the row's lock while both writers start, until both wait on it, then lets them go one after the other. */
+async function raceOnLockedRow(knex, id, writers) {
+  const holder = await knex.transaction();
+  try {
+    await holder("slots").where({ id }).forUpdate().select("id");
+    const running = writers.map((write) => write().then((value) => ({ value }), (error) => ({ error })));
+    await bothWaiting(knex, writers.length);
+    await holder.commit();
+    return await Promise.all(running);
+  } finally {
+    if (!holder.isCompleted()) await holder.rollback();
+  }
+}
+
+async function takeTwice(t, suffix, options) {
+  const database = await ownDatabase(t, suffix, options);
+  if (!database) {
+    t.skip("the server has no innodb_snapshot_isolation setting");
+    return;
+  }
+  const { knex, slots } = database;
+  const [id] = await slots.createMany([{ status: "open" }], { context: WORKSPACE, returning: "ids" });
+  const take = (taker) => () => slots.patchWhere({ id, status: "open" }, { status: "taken", takenBy: taker }, { context: WORKSPACE, returning: "ids" });
+  const outcomes = await raceOnLockedRow(knex, id, [take("first"), take("second")]);
+  assert.deepEqual(outcomes.filter(({ error }) => error), [], "neither writer fails");
+  assert.deepEqual(outcomes.map(({ value }) => value.length).sort(), [0, 1], "exactly one writer takes the row");
+  const row = await knex("slots").where({ id }).first("status", "taken_by");
+  assert.equal(row.status, "taken");
+  assert.equal(row.taken_by, outcomes[0].value.length === 1 ? "first" : "second");
+}
+
+test("of two concurrent patchWhere calls whose filters both matched one row, exactly one writes it", async (t) => {
+  requireTestDatabase(process.env);
+  await takeTwice(t, "da_pw_race");
+});
+
+test("with innodb_snapshot_isolation on, the waiting patchWhere fails as changed since its read and runs again, leaving the row out", async (t) => {
+  requireTestDatabase(process.env);
+  await takeTwice(t, "da_pw_snapshot", { snapshotIsolation: true });
+});
+
+test("a deleteWhere whose filter matched a row a concurrent patchWhere changed leaves it in place", async (t) => {
+  requireTestDatabase(process.env);
+  const { knex, slots } = await ownDatabase(t, "da_dw_race");
+  const [id] = await slots.createMany([{ status: "open" }], { context: WORKSPACE, returning: "ids" });
+  const outcomes = await raceOnLockedRow(knex, id, [
+    () => slots.patchWhere({ id, status: "open" }, { status: "taken", takenBy: "first" }, { context: WORKSPACE, returning: "ids" }),
+    () => slots.deleteWhere({ id, status: "open" }, { context: WORKSPACE, returning: "ids" })
+  ]);
+  assert.deepEqual(outcomes.filter(({ error }) => error), []);
+  const [patched, deleted] = outcomes.map(({ value }) => value.length);
+  const row = await knex("slots").where({ id }).first("status");
+  // Whichever went first wins; the other finds the row changed (or gone) and leaves it.
+  assert.deepEqual([patched + deleted, row ? row.status : "deleted"], [1, patched === 1 ? "taken" : "deleted"]);
+});

package/test/queryFields.test.js

@@ -0,0 +1,68 @@
+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 { createTestResourceRuntime } from "../src/test/index.js";
+
+const WORKSPACE_A = Object.freeze({ workspace: { id: "1" } });
+
+test("a query field's select gets a value-only raw, column() and the read's filters, never Knex or its context", async (t) => {
+  const knex = knexLib({ client: "better-sqlite3", connection: { filename: ":memory:" }, useNullAsDefault: true });
+  t.after(() => knex.destroy());
+  await knex.schema.createTable("receivals", (table) => {
+    table.increments("id");
+    table.integer("workspace_id");
+    table.string("status").notNullable();
+    table.integer("received_weight").notNullable();
+    table.integer("processed_weight");
+  });
+  const receivalResource = defineTableResource({
+    name: "receivals",
+    tableName: "receivals",
+    ownership: "workspace",
+    schema: {
+      workspaceId: { type: "id", nullable: true, storage: { column: "workspace_id" } },
+      status: { type: "string", required: true, search: true },
+      receivedWeight: { type: "integer", required: true, storage: { column: "received_weight" } },
+      processedWeight: { type: "integer", nullable: true, storage: { column: "processed_weight" } },
+      remainingWeight: { type: "number", storage: { virtual: true } }
+    }
+  });
+  let tools;
+  const runtime = await createTestResourceRuntime({ knex });
+  const { receivals } = await runtime.own("receivals.feature", [{
+    resource: receivalResource,
+    queryFields: {
+      remainingWeight: {
+        type: "number",
+        select(given) {
+          tools = given;
+          return given.raw("?? - coalesce(??, 0)", [given.column("receivedWeight"), given.column("processedWeight")]);
+        }
+      }
+    }
+  }]);
+  const options = { context: WORKSPACE_A };
+  await receivals.createMany([
+    { status: "open", receivedWeight: 10, processedWeight: 4 },
+    { status: "open", receivedWeight: 7 },
+    { status: "closed", receivedWeight: 3, processedWeight: 3 }
+  ], options);
+
+  const open = await receivals.queryAll({ filters: { status: "open" }, fields: ["remainingWeight"] }, options);
+  assert.deepEqual(open.map(({ remainingWeight }) => remainingWeight), [6, 7]);
+  assert.deepEqual(Object.keys(tools).sort(), ["column", "filters", "raw"]);
+  assert.equal(tools.filters.status, "open");
+  assert.equal(Object.isFrozen(tools.filters), true);
+
+  // raw takes one SQL string and its bindings as an array, and is a value only: awaited, it answers itself and runs
+  // nothing; run as a statement, it throws.
+  assert.throws(() => tools.raw(42), /Query field "remainingWeight" raw\(\) takes one SQL expression as a string/u);
+  assert.throws(() => tools.raw("?? + 1"), /needs the bindings of its placeholders/u);
+  assert.throws(() => tools.raw("? + 1", { value: 1 }), /takes \(sql, bindings\)/u);
+  assert.throws(() => tools.raw("? + 1", [1], "extra"), /takes \(sql, bindings\)/u);
+  const statement = tools.raw("DELETE FROM receivals");
+  assert.equal(await statement, statement);
+  assert.throws(() => statement.asCallback(() => {}), /is a value inside a scoped query or a write/u);
+  assert.equal((await knex("receivals")).length, 3);
+});