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

package/src/server/handleGuards.js

@@ -0,0 +1,226 @@
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import { passedOn } from "@jskit-ai/resource-core/shared/callOptions";
+import { isSystemContext } from "./contexts.js";
+import { MissingScopeError } from "./errors.js";
+import { resolveUserScopeValue, resolveWorkspaceScopeValue } from "./resourceHost.js";
+
+// The checks that keep a handle's calls inside their scope: a call never reaches rows beyond
+// the caller's because a context, a filter value or an expression was missing or misused.
+
+// The owners a context must name for each ownership. A context naming none of them would match the rows whose owner is
+// null; a workspace_or_shared table reads exactly those shared rows without a workspace, and refuses writes there.
+const REQUIRED_OWNERS = Object.freeze({
+  public: Object.freeze([]),
+  workspace: Object.freeze(["workspace"]),
+  user: Object.freeze(["user"]),
+  workspace_user: Object.freeze(["workspace", "user"]),
+  workspace_or_shared: Object.freeze([])
+});
+const OWNER_RESOLVERS = Object.freeze({ workspace: resolveWorkspaceScopeValue, user: resolveUserScopeValue });
+
+/**
+ * Refuses a context, other than a system context, that names no owner the table's ownership needs.
+ * @param {string} name The resource's name.
+ * @param {string} ownership
+ * @param {object | null | undefined} context
+ */
+function requireOwners(name, ownership, context) {
+  if (isSystemContext(context)) {
+    return;
+  }
+  const missing = REQUIRED_OWNERS[ownership].find((owner) => !OWNER_RESOLVERS[owner](context));
+  if (missing) {
+    throw new MissingScopeError(name, missing);
+  }
+}
+
+/**
+ * Refuses a filter whose value is undefined, at any depth. json-rest-api drops such a filter, so a caller's missing
+ * value would widen the selection to every row it owns instead of none.
+ * @param {string} name
+ * @param {string} caller
+ * @param {unknown} filters
+ * @param {string} [path]
+ */
+function requireDefinedFilters(name, caller, filters, path = "filters") {
+  if (!isRecord(filters)) {
+    return filters;
+  }
+  for (const [key, value] of Object.entries(filters)) {
+    if (value === undefined) {
+      throw new TypeError(`${name}.${caller}() ${path}.${key} is undefined: pass its value, or leave the filter out.`);
+    }
+    requireDefinedFilters(name, caller, value, `${path}.${key}`);
+  }
+  return filters;
+}
+
+
+/**
+ * A filtered write's selection: its filters, or every owned row when they are empty and `all: true` says so. An
+ * undefined filter value is refused, so a missing value never counts as a filter yet selects every row.
+ * @param {string} name The resource's name.
+ * @param {string} operation
+ * @param {unknown} filters
+ * @param {{ all?: boolean }} options
+ */
+function whereSelection(name, operation, filters, options) {
+  if (!isRecord(filters)) {
+    throw new TypeError(`${name}.${operation}() takes filters as an object.`);
+  }
+  if (options.missing !== undefined) {
+    throw new TypeError(`${name}.${operation}() changes the rows the filters select when it runs, so it takes no missing.`);
+  }
+  requireDefinedFilters(name, operation, filters);
+  if (Object.keys(filters).length > 0) {
+    if (options.all !== undefined) {
+      throw new TypeError(`${name}.${operation}() takes filters or all: true, not both.`);
+    }
+    return { filters };
+  }
+  if (options.all !== true) {
+    throw new TypeError(`${name}.${operation}() with empty filters changes every row the caller owns; pass all: true to mean it.`);
+  }
+  return { all: true };
+}
+
+/**
+ * An upsert matches rows by its conflict keys alone, so its rows carry no id, which could name another owner's
+ * record, unless the id is the one key: json-rest-api allows that only on a table with no owners and no row policy.
+ * @param {string} name
+ * @param {unknown[]} rows
+ * @param {{ keys?: unknown }} onConflict
+ * @param {string | undefined} idProperty
+ */
+function requireUpsertRows(name, rows, onConflict, idProperty) {
+  const keys = Array.isArray(onConflict.keys) ? onConflict.keys : [];
+  const byId = keys.length === 1 && (keys[0] === "id" || keys[0] === idProperty);
+  if (!byId && rows.some((row) => isRecord(row) && Object.hasOwn(row, "id"))) {
+    throw new TypeError(
+      `${name}.createMany() with onConflict takes rows without an id; the conflict keys find the existing rows. ` +
+        "Only onConflict: { keys: [\"id\"] }, on a table with no owners, matches rows by their id."
+    );
+  }
+}
+
+// The keys of a call's options, which get() takes third, after its params.
+const OPTION_KEYS = Object.freeze(["context", "trx", "format", "missing", "returning"]);
+
+/**
+ * get(), patch(), delete() and lock() throw json-rest-api's not-found error for
+ * a missing or hidden row, or answer null with `missing: "skip"`.
+ * @param {string} name
+ * @param {string} caller
+ * @param {unknown} [missing]
+ * @returns {"throw" | "skip"}
+ */
+function missingOf(name, caller, missing = "throw") {
+  if (missing !== "throw" && missing !== "skip") {
+    throw new TypeError(`${name}.${caller}() missing is "throw" (the default) or "skip". Received: ${JSON.stringify(missing)}`);
+  }
+  return missing;
+}
+
+/**
+ * Refuses get(id, options): get takes its options third, after its params.
+ * @param {string} name
+ * @param {unknown} params
+ */
+function requireReadParams(name, params) {
+  if (isRecord(params) && OPTION_KEYS.some((key) => Object.hasOwn(params, key))) {
+    throw new TypeError(`${name}.get() takes (id, params, options), and options go third: get(id, {}, options).`);
+  }
+}
+
+/**
+ * Refuses a write condition that the options name with no value (`{ lockVersion: undefined }`, `{ onlyIf: undefined }`,
+ * often a field read under the wrong name): run without it, the write would drop the condition it was meant to carry,
+ * and a patch with no changes would only read. A call without the condition leaves the key out.
+ * @param {string} name The resource's name.
+ * @param {string} method The handle method, such as "patch".
+ * @param {Record<string, unknown>} options
+ * @param {string[]} keys The condition keys the method takes.
+ */
+function requireConditionValues(name, method, options, keys) {
+  for (const key of keys) {
+    if (Object.hasOwn(options, key) && options[key] === undefined) {
+      throw new TypeError(`${name}.${method}() options.${key} is undefined. Give it a value, or leave the key out for a ${method} without it.`);
+    }
+  }
+}
+
+/**
+ * Refuses lockVersion or onlyIf, named at all, on a write that cannot compare them: run without them, the write would
+ * change or delete the rows whatever they hold.
+ * @param {string} name The resource's name.
+ * @param {string} method The handle method, such as "delete".
+ * @param {Record<string, unknown>} options
+ * @param {string[]} keys The conditions the method cannot compare.
+ * @param {string} instead What the caller does instead.
+ */
+function refuseConditions(name, method, options, keys, instead) {
+  const named = keys.filter((key) => Object.hasOwn(options, key));
+  if (named.length > 0) {
+    throw new TypeError(`${name}.${method}() cannot compare ${named.join(" or ")}, so it refuses rather than write without them. ${instead}`);
+  }
+}
+
+/**
+ * Refuses a patch's lockVersion or onlyIf named with no value (see requireConditionValues); a lockVersion without a
+ * lockVersionField, or one that is not a version, or changes that write the version the patch advances itself; and an
+ * onlyIf that is not an object of field values.
+ * @param {string} name
+ * @param {string} lockVersionField
+ * @param {Record<string, unknown>} attributes
+ * @param {{ lockVersion?: unknown, onlyIf?: unknown }} options The patch's options.
+ */
+function requirePatchConditions(name, lockVersionField, attributes, options) {
+  requireConditionValues(name, "patch", options, ["lockVersion", "onlyIf"]);
+  const { lockVersion, onlyIf } = options;
+  if (lockVersion !== undefined) {
+    if (!lockVersionField) {
+      throw new TypeError(`${name}.patch() lockVersion needs the resource to name its lockVersionField.`);
+    }
+    if (!Number.isSafeInteger(lockVersion) || Number(lockVersion) < 0) {
+      throw new TypeError(`${name}.patch() lockVersion must be a non-negative integer. Received: ${lockVersion}`);
+    }
+    if (Object.hasOwn(attributes, lockVersionField)) {
+      throw new TypeError(`${name}.patch() advances ${lockVersionField} itself, so the attributes must leave it out.`);
+    }
+  }
+  if (onlyIf !== undefined && !isRecord(onlyIf)) {
+    throw new TypeError(`${name}.patch() onlyIf must be an object of field values.`);
+  }
+}
+
+/**
+ * The answer format a handle call asks for: "jsonapi" (the CRUD service's documents) or, by default, "plain" (records).
+ * @param {string} name The resource's name.
+ * @param {{ format?: string }} options
+ */
+function formatOf(name, options) {
+  if (options.format !== undefined && options.format !== "jsonapi") {
+    throw new TypeError(`${name} options.format is "jsonapi" (the CRUD service's documents) or absent (records).`);
+  }
+  return options.format === "jsonapi" ? "jsonapi" : "plain";
+}
+
+/**
+ * Whether the filters give an empty list to a filter that matches one of a list (the id filter, or any filter whose
+ * search entry says `filterOperator: "in"`): such a read matches no row, so the handle answers it without a statement.
+ * @param {unknown} filters
+ * @param {{ searchSchemaStructure?: Record<string, { filterOperator?: string }> }} schemaInfo The table's compiled
+ *   json-rest-api schema (`vars.schemaInfo`).
+ */
+function matchesNoRow(filters, schemaInfo) {
+  if (!isRecord(filters)) {
+    return false;
+  }
+  const search = schemaInfo.searchSchemaStructure || {};
+  return Object.entries(filters).some(([key, value]) => Array.isArray(value) && value.length === 0 && search[key]?.filterOperator === "in");
+}
+
+export {
+  formatOf, matchesNoRow, missingOf, refuseConditions, requireConditionValues, requireDefinedFilters, requireOwners, requirePatchConditions,
+  requireReadParams, requireUpsertRows, passedOn, whereSelection
+};

package/src/server/handleHidden.js

@@ -0,0 +1,309 @@
+import { RestApiResourceError } from "json-rest-api";
+import { isRecord } from "@jskit-ai/kernel/shared/support/normalize";
+import { isJobContext } from "./contexts.js";
+import { namedFields } from "./handleRecords.js";
+
+// A hidden field (`hidden: true`) is one json-rest-api never selects or answers, so no request, CRUD route or JSON:API
+// document carries it. A handle's plain read still answers one when its `fields` names it, for the table's owner and
+// for system work: the owner's own commands (a bearer token it checks) and a job that must learn each row's owner.
+
+// The hidden field types a read answers: their stored values read as json-rest-api reads them without decoding.
+const READABLE_TYPES = Object.freeze(new Set(["id", "string", "integer", "number", "boolean"]));
+// The records each statement of the hidden fields' read covers.
+const RECORDS_PER_READ = 1000;
+// Where each read takes `fields` and where its options, by argument position.
+const FIELD_READS = Object.freeze({
+  get: Object.freeze({ fieldsAt: 1, optionsAt: 2 }),
+  query: Object.freeze({ fieldsAt: 0, optionsAt: 1 }),
+  queryAll: Object.freeze({ fieldsAt: 0, optionsAt: 1 }),
+  lock: Object.freeze({ fieldsAt: 1, optionsAt: 1 }),
+  lockMany: Object.freeze({ fieldsAt: 1, optionsAt: 1 }),
+  lockWhere: Object.freeze({ fieldsAt: 1, optionsAt: 1 }),
+  claim: Object.freeze({ fieldsAt: 1, optionsAt: 1 })
+});
+
+/**
+ * The resource's hidden fields a read's `fields` names.
+ * @param {{ name: string, schema: Record<string, any> }} resource
+ * @param {unknown} fields
+ */
+function namedHiddenFields(resource, fields) {
+  const named = namedFields(resource, fields);
+  return named ? [...named].filter((field) => resource.schema[field]?.hidden === true) : [];
+}
+
+/**
+ * A hidden field's stored value as a read answers it, as json-rest-api reads its type: an id as text, a whole
+ * number or a non-decimal number as a number (text past the safe integers), 0 and 1 as booleans.
+ * @param {unknown} value
+ * @param {{ type: string, precision?: number, scale?: number }} definition
+ */
+function storedValue(value, { type, precision, scale }) {
+  if (value == null) {
+    return null;
+  }
+  if (type === "id") {
+    return String(value);
+  }
+  if (type === "boolean") {
+    return value === 1 || value === "1" ? true : value === 0 || value === "0" ? false : value;
+  }
+  const decimal = precision !== undefined && scale !== undefined;
+  if ((type === "integer" || type === "number") && typeof value === "string" && !decimal) {
+    const number = Number(value);
+    return value.trim() !== "" && Number.isFinite(number) && (!Number.isInteger(number) || Number.isSafeInteger(number)) ? number : value;
+  }
+  return value;
+}
+
+/**
+ * A handle's reads of the hidden fields a plain read's `fields` names, which json-rest-api leaves out: one more
+ * statement per 1,000 records, on the table as scopedQuery() gives it (the caller's ownership and the row policy
+ * applied), in the call's transaction.
+ * @param {object} dependencies
+ * @param {{ name: string, schema: Record<string, any> }} dependencies.resource
+ * @param {(params: { filters: object }, options: object) => Promise<{ query: any }>} dependencies.scopedQuery
+ * @param {(field: string) => string} dependencies.column
+ */
+function createHiddenFieldReads({ resource, scopedQuery, column }) {
+  /**
+   * The hidden fields a plain read names, checked before it runs: each is a stored id, string, number or boolean.
+   * @param {unknown} fields
+   * @param {string | undefined} format
+   */
+  function named(fields, format) {
+    if (format === "jsonapi") {
+      return [];
+    }
+    const hidden = namedHiddenFields(resource, fields);
+    for (const field of hidden) {
+      const definition = resource.schema[field];
+      if (!READABLE_TYPES.has(definition.type) || definition.virtual === true || definition.storage?.virtual === true) {
+        throw new TypeError(
+          `${resource.name}: fields names the hidden field "${field}", but a read answers a hidden field only when it ` +
+            "is a stored id, string, integer, number or boolean."
+        );
+      }
+    }
+    return hidden;
+  }
+
+  /**
+   * The records, each with the hidden fields added. A record whose row the added statement no longer sees (deleted
+   * since, outside a transaction) is left out.
+   * @param {Array<Record<string, any>>} records
+   * @param {string[]} hidden
+   * @param {{ context?: object | null, trx?: object | null }} options
+   */
+  async function add(records, hidden, options) {
+    if (hidden.length < 1 || records.length < 1) {
+      return records;
+    }
+    const rows = new Map();
+    const ids = records.map(({ id }) => id);
+    for (let start = 0; start < ids.length; start += RECORDS_PER_READ) {
+      const { query } = await scopedQuery({ filters: { id: ids.slice(start, start + RECORDS_PER_READ) } }, options);
+      const read = await query.select({ id: column("id"), ...Object.fromEntries(hidden.map((field) => [field, column(field)])) });
+      for (const row of read) {
+        rows.set(String(row.id), row);
+      }
+    }
+    return records.flatMap((record) => {
+      const row = rows.get(String(record.id));
+      return row
+        ? [{ ...record, ...Object.fromEntries(hidden.map((field) => [field, storedValue(row[field], resource.schema[field])])) }]
+        : [];
+    });
+  }
+
+  /**
+   * One record with the hidden fields added. A record deleted since it was read is missing: null with
+   * `missing: "skip"`, else json-rest-api's not-found error.
+   * @param {Record<string, any>} record
+   * @param {string[]} hidden
+   * @param {{ context?: object | null, trx?: object | null, missing?: "throw" | "skip" }} options
+   */
+  async function addOne(record, hidden, options) {
+    const [read] = await add([record], hidden, options);
+    if (read || options.missing === "skip") {
+      return read ?? null;
+    }
+    throw new RestApiResourceError("Resource not found", { subtype: "not_found", resourceType: resource.name, resourceId: record.id });
+  }
+
+  return Object.freeze({
+    named,
+    add,
+    addOne
+  });
+}
+
+// Every resource handle's scopedQuery, whose builder carries every column, and its withTransaction and lockOrCreate,
+// which answer the caller's own work: withoutHiddenFields tells them by identity, under any name.
+const HANDLE_SCOPED_QUERIES = new WeakSet();
+const HANDLE_WORK_RUNNERS = new WeakSet();
+// The names an owner's own wrappers of those runners keep.
+const WORK_RUNNER_NAMES = Object.freeze(new Set(["withTransaction", "lockOrCreate"]));
+
+/**
+ * Records a new handle's scopedQuery, withTransaction and lockOrCreate for withoutHiddenFields.
+ * @param {{ scopedQuery: Function, withTransaction: Function, lockOrCreate: Function }} handle
+ */
+function markHandleFunctions({ scopedQuery, withTransaction, lockOrCreate }) {
+  HANDLE_SCOPED_QUERIES.add(scopedQuery);
+  HANDLE_WORK_RUNNERS.add(withTransaction);
+  HANDLE_WORK_RUNNERS.add(lockOrCreate);
+}
+
+/**
+ * Whether a function answered a Knex value (a raw expression, a column's builder, a query builder an owner's join
+ * source answers) rather than rows: a value for the caller's own query, which it builds on and never awaits.
+ * @param {unknown} value
+ */
+function isKnexValue(value) {
+  // readable-check: allow method-probe - data: Knex raw expressions and query builders compile through toSQL()
+  return isRecord(value) && typeof value.toSQL === "function";
+}
+
+/** @param {unknown} value */
+function isPlainRecord(value) {
+  if (!isRecord(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/**
+ * The value without the hidden fields, wherever a plain record in it, or in its arrays and maps, carries one: a copy
+ * of what changed (frozen when the original was), the value itself when nothing did. Builders, dates and other
+ * instances are left as they are.
+ * @param {unknown} value
+ * @param {Set<string>} hidden
+ * @param {WeakMap<object, unknown>} [seen]
+ */
+function withoutHiddenValues(value, hidden, seen = new WeakMap()) {
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  if (seen.has(value)) {
+    return seen.get(value);
+  }
+  seen.set(value, value);
+  let changed = false;
+  const strip = (entry) => {
+    const next = withoutHiddenValues(entry, hidden, seen);
+    changed ||= next !== entry;
+    return next;
+  };
+  let copy;
+  if (Array.isArray(value)) {
+    copy = value.map(strip);
+  } else if (value instanceof Map) {
+    copy = new Map([...value].map(([key, entry]) => [key, strip(entry)]));
+  } else if (isPlainRecord(value)) {
+    copy = Object.create(Object.getPrototypeOf(value));
+    for (const [key, entry] of Object.entries(value)) {
+      if (hidden.has(key)) {
+        changed = true;
+      } else {
+        copy[key] = strip(entry);
+      }
+    }
+  } else {
+    return value;
+  }
+  const result = !changed ? value : Object.isFrozen(value) && !(value instanceof Map) ? Object.freeze(copy) : copy;
+  seen.set(value, result);
+  return result;
+}
+
+/**
+ * The repository an owner gives other features (a CRUD feature's `resourceApi.repository`): every function it holds,
+ * its sub-repositories' included, answers without the hidden fields of the tables the owner owns, and a read whose
+ * `fields` names a hidden field of the resource, or any scopedQuery() (its builder carries every column, hidden ones
+ * too), is refused, unless the call runs in a system context or one it derived (its options, the last record it
+ * takes). So a read the owner adds in decorateRepository cannot hand a hidden field out either; the owner's own
+ * code, its join sources included, reads with the repository itself. withTransaction and lockOrCreate answer the
+ * caller's own work as it is, and a function answering a Knex value (raw(), a join source's builder) answers it as
+ * it is, unawaited. A repository whose tables have no hidden fields stays as it is.
+ * @template {object} T
+ * @param {T} repository
+ * @param {{ name: string, schema: Record<string, any> } | ReadonlyArray<{ name: string, schema: Record<string, any> }>} resources
+ *   The resource the repository serves, or it first and the other tables its owner owns.
+ * @returns {T}
+ */
+function withoutHiddenFields(repository, resources) {
+  const owned = [resources].flat();
+  const hidden = new Set(owned.flatMap(({ schema }) => Object.keys(schema).filter((field) => schema[field]?.hidden === true)));
+  if (!isRecord(repository) || hidden.size < 1) {
+    return repository;
+  }
+  return guardedRepository(repository, owned[0], hidden, new WeakSet());
+}
+
+/**
+ * @param {object} repository
+ * @param {{ name: string, schema: Record<string, any> } | null} resource The resource whose reads it refuses by name; none for a sub-repository.
+ * @param {Set<string>} hidden
+ * @param {WeakSet<object>} guarded
+ */
+function guardedRepository(repository, resource, hidden, guarded) {
+  guarded.add(repository);
+  const descriptors = Object.getOwnPropertyDescriptors(repository);
+  for (const [key, descriptor] of Object.entries(descriptors)) {
+    const { value } = descriptor;
+    // readable-check: allow method-probe - data: every function a repository holds is guarded, whatever its name
+    if (typeof value === "function") {
+      descriptors[key] = { ...descriptor, value: guardedFunction(repository, key, value, resource, hidden) };
+    } else if (isPlainRecord(value) && !guarded.has(value)) {
+      descriptors[key] = { ...descriptor, value: guardedRepository(value, null, hidden, guarded) };
+    }
+  }
+  return Object.freeze(Object.create(Object.getPrototypeOf(repository), descriptors));
+}
+
+/**
+ * @param {object} repository
+ * @param {string} key
+ * @param {Function} call
+ * @param {{ name: string, schema: Record<string, any> } | null} resource
+ * @param {Set<string>} hidden
+ */
+function guardedFunction(repository, key, call, resource, hidden) {
+  const label = `${resource?.name ?? "repository"}.${key}()`;
+  const fieldRead = resource && Object.hasOwn(FIELD_READS, key) ? FIELD_READS[key] : null;
+  const builder = HANDLE_SCOPED_QUERIES.has(call) || (resource !== null && key === "scopedQuery");
+  const work = HANDLE_WORK_RUNNERS.has(call) || WORK_RUNNER_NAMES.has(key);
+  return function callWithoutHiddenFields(...args) {
+    const options = fieldRead ? args[fieldRead.optionsAt] : args.findLast(isRecord);
+    if (isJobContext(options?.context)) {
+      return call.apply(repository, args);
+    }
+    if (builder) {
+      return Promise.reject(new TypeError(
+        `${label} answers every column, its hidden fields too, which only the table's owner, or a system context, ` +
+          "reads: ask the owner for a method answering the rows or a join source."
+      ));
+    }
+    const named = fieldRead ? namedHiddenFields(resource, args[fieldRead.fieldsAt]?.fields) : [];
+    if (named.length > 0) {
+      return Promise.reject(new TypeError(
+        `${label} fields names the hidden field ${named.map((field) => `"${field}"`).join(", ")}, ` +
+          "which only the table's owner, or a system context, reads."
+      ));
+    }
+    const answer = call.apply(repository, args);
+    // A runner's answer is the caller's own work, and a Knex value (raw(), or an owner's join source answering a
+    // builder) carries no rows: both pass as they are, unawaited, so a builder never runs here.
+    if (work || isKnexValue(answer)) {
+      return answer;
+    }
+    // readable-check: allow method-probe - data: a repository's method may answer at once or with a promise
+    return typeof answer?.then === "function"
+      ? answer.then((value) => withoutHiddenValues(value, hidden))
+      : withoutHiddenValues(answer, hidden);
+  };
+}
+
+export { createHiddenFieldReads, markHandleFunctions, withoutHiddenFields };

package/src/server/handleLocks.js

@@ -0,0 +1,103 @@
+import { missingOf, requireDefinedFilters } from "./handleGuards.js";
+import { handleRecords, sparseFieldset, textList } from "./handleRecords.js";
+
+/**
+ * A handle's locking reads: lock, lockMany, lockWhere and claim. Each needs the
+ * caller's transaction (`options.trx`), locks only rows the caller may see, and
+ * reads the fields `options.fields` names, or every field a one-record read
+ * answers, so a belongs-to field left out costs no check that its related
+ * record is visible.
+ * @param {object} dependencies
+ * @param {string} dependencies.name The resource's name.
+ * @param {{ name: string, schema: Record<string, any> }} dependencies.resource
+ * @param {() => Record<string, (params: object, context: object) => Promise<{ data: unknown[] }>>} dependencies.jsonRest
+ *   The table's json-rest-api resource.
+ * @param {(params: { fields?: unknown }, kind: "view") => unknown} dependencies.readFields The fields a read names.
+ * @param {(options: object) => object} dependencies.contextOf The call's json-rest-api context, after its scope checks.
+ * @param {ReturnType<typeof import("./handleHidden.js").createHiddenFieldReads>} dependencies.hiddenFields The hidden
+ *   fields `options.fields` names, read after the lock.
+ */
+function createLockReads({ name, resource, jsonRest, readFields, contextOf, hiddenFields }) {
+  // A locking read (json-rest-api's lockByIds, lockWhere or claim) of the fields options.fields names, as records.
+  async function lockRead(method, read, options) {
+    const hidden = hiddenFields.named(options.fields, "plain");
+    const fields = readFields({ fields: options.fields }, "view");
+    const { data } = await jsonRest()[method]({
+      ...read,
+      transaction: options.trx,
+      format: "plain",
+      ...(fields ? { queryParams: { fields: sparseFieldset(resource, fields) } } : {})
+    }, contextOf(options));
+    return hiddenFields.add(handleRecords(resource, data, { fields }), hidden, options);
+  }
+
+  /**
+   * Locks the visible rows among the ids, in id order, and answers them; hidden or missing ids throw, or are
+   * left out with `missing: "skip"`. MySQL locks every listed id, a hidden one too: take ids from scoped reads.
+   * `fields` names the fields the lock reads, so a belongs-to field left out costs no check that its related
+   * record is visible; without it every field is read.
+   * @param {unknown[]} ids
+   * @param {{ context?: object | null, trx: object, missing?: "throw" | "skip", fields?: string[] }} options
+   */
+  async function lockMany(ids, options) {
+    return lockRead("lockByIds", { ids, ...(options.missing ? { missing: options.missing } : {}) }, options);
+  }
+
+  /**
+   * Locks the record's row until the transaction ends and answers it as the
+   * lock saw it. Needs options.trx. A missing or hidden record throws
+   * json-rest-api's not-found error, or answers null with `missing: "skip"`.
+   * `fields` reads only the fields the work needs (see lockMany).
+   * @param {unknown} id
+   * @param {{ context?: object | null, trx: object, missing?: "throw" | "skip", fields?: string[] }} options
+   */
+  async function lock(id, options) {
+    missingOf(name, "lock", options.missing);
+    const [record] = await lockMany([id], options);
+    return record ?? null;
+  }
+
+  /**
+   * Locks the caller's rows the filters select until the transaction ends, in id
+   * order, and answers them; it waits for transactions holding them, so a row that
+   * starts to match meanwhile is locked too. At most 1,000 rows (RestApiRowLimitError
+   * past that). It does not lock rows inserted later: unique numbers take a unique
+   * index, or a counter row taken with lock(). On MySQL it needs an index starting
+   * with the ownership columns (no owners: with a filtered column), or it refuses.
+   * `fields` reads only the fields the work needs (see lockMany).
+   * @param {object} filters
+   * @param {{ context?: object | null, trx: object, fields?: string[] }} options
+   */
+  async function lockWhere(filters, options) {
+    requireDefinedFilters(name, "lockWhere", filters);
+    return lockRead("lockWhere", { filters }, options);
+  }
+
+  /**
+   * Takes up to `take` (default 1) of the rows the filters select that no
+   * other transaction holds, in `sort` order, locked until the transaction ends.
+   * `fields` reads only the fields the work needs (see lockMany).
+   * @param {{ filters: object, sort?: string | string[], take?: number }} params
+   * @param {{ context?: object | null, trx: object, fields?: string[] }} options
+   */
+  async function claim({ filters, sort, take } = {}, options, ...rest) {
+    if (rest.length > 0) {
+      throw new TypeError(`${name}.claim() takes ({ filters, sort, take }, options).`);
+    }
+    requireDefinedFilters(name, "claim", filters);
+    return lockRead("claim", {
+      filters,
+      ...(take === undefined ? {} : { limit: take }),
+      ...(sort === undefined ? {} : { sort: textList(sort) })
+    }, options);
+  }
+
+  return Object.freeze({
+    lock,
+    lockMany,
+    lockWhere,
+    claim
+  });
+}
+
+export { createLockReads };