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

package/src/server/handleHidden.js

@@ -0,0 +1,410 @@
+import { RestApiResourceError, readOnlyQueryBuilder } 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;
+
+/**
+ * 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"]));
+// The builders a handle's joinSource() answers, which carry the table's visible columns only: the one query builder
+// withoutHiddenFields hands another feature.
+const JOIN_SOURCES = new WeakSet();
+
+/**
+ * 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);
+}
+
+/**
+ * A handle's joinSource(): the table as a join source for another owner's report, which joins it in its own
+ * statement. It answers `{ query, column }`: the rows scopedQuery() gives under `alias` (the caller's ownership, the
+ * row policy and `filters` applied) with the stored columns a read answers only, never a hidden one, and
+ * `column(field)` naming each under that alias. A CRUD feature's repository answers it to any feature, where it
+ * refuses scopedQuery(). The builder comes wrapped, since a builder is thenable.
+ * @param {object} dependencies
+ * @param {{ knex: { instance: any } }} dependencies.api
+ * @param {{ name: string, schema: Record<string, any> }} dependencies.resource
+ * @param {() => { vars: { schemaInfo: { schemaStructure: Record<string, any> } } }} dependencies.jsonRest
+ * @param {(params: { alias: string, filters?: object }, options: object) => Promise<{ query: any }>} dependencies.scopedQuery
+ * @param {(field: string, alias?: string) => string} dependencies.column
+ */
+function createJoinSource({ api, resource, jsonRest, scopedQuery, column }) {
+  const { name } = resource;
+  /**
+   * @param {{ alias: string, filters?: object }} params
+   * @param {{ context?: object | null, trx?: object | null }} [options]
+   * @returns {Promise<Readonly<{ query: any, column: (field: string) => string }>>}
+   */
+  return async function joinSource({ alias, filters } = {}, options = {}) {
+    if (typeof alias !== "string" || !alias) {
+      throw new TypeError(`${name}.joinSource() needs the alias the report joins the ${name} under.`);
+    }
+    const { query } = await scopedQuery({ alias, ...(filters === undefined ? {} : { filters }) }, options);
+    const { schemaStructure } = jsonRest().vars.schemaInfo;
+    const visible = Object.keys(schemaStructure).filter((field) => {
+      const definition = schemaStructure[field];
+      return field !== "id" && definition.hidden !== true && definition.virtual !== true && !definition.belongsToPolymorphic;
+    });
+    // The scoped rows' visible columns, as a derived table under the alias: nothing a caller adds reaches the others.
+    const source = readOnlyQueryBuilder(
+      (options.trx || api.knex.instance).from(query.select(["id", ...visible].map((field) => column(field, alias))).as(alias)),
+      { resourceType: name }
+    );
+    JOIN_SOURCES.add(source);
+    return Object.freeze({
+      query: source,
+      column(field) {
+        if (resource.schema[field]?.hidden === true) {
+          throw new TypeError(`${name}.joinSource() carries no hidden field, so it has no column for "${field}".`);
+        }
+        return column(field, alias);
+      }
+    });
+  };
+}
+
+/**
+ * The field names a call's `fields` names: a list of names, names separated by commas, or a sparse fieldset (each
+ * resource type's names, separated by commas).
+ * @param {unknown} fields
+ * @returns {string[]}
+ */
+function fieldNames(fields) {
+  if (typeof fields === "string") {
+    return fields.split(",").map((field) => field.trim());
+  }
+  if (Array.isArray(fields)) {
+    return fields.filter((field) => typeof field === "string");
+  }
+  return isRecord(fields)
+    ? Object.values(fields).flatMap((names) => (typeof names === "string" || Array.isArray(names) ? fieldNames(names) : []))
+    : [];
+}
+
+/**
+ * Whether a function answered a Knex value (a raw expression, a column's builder, a joinSource()'s query builder)
+ * 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";
+}
+
+/**
+ * A Knex value another feature may build on, as it is: a raw expression or a column's reference, or a joinSource()'s
+ * builder. Any other query builder (a scopedQuery()'s, or one the owner built) can select every column of its table,
+ * the hidden ones too, so it is refused.
+ * @param {any} value A Knex value (see isKnexValue).
+ * @param {string} label
+ */
+function withoutFullBuilder(value, label) {
+  // readable-check: allow method-probe - data: a Knex query builder, unlike a raw expression, takes where()
+  if (typeof value.where === "function" && !JOIN_SOURCES.has(value)) {
+    throw new TypeError(
+      `${label} answers a query builder, which can select every column, the hidden fields too, which only the table's ` +
+        "owner, or a system context, reads: answer the table's joinSource({ alias }, options), which carries its visible " +
+        "columns only."
+    );
+  }
+  return value;
+}
+
+/** @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. A query builder in it that is no
+ * joinSource()'s is refused (see withoutFullBuilder); raw expressions, dates and other instances are left as they are.
+ * @param {unknown} value
+ * @param {Set<string>} hidden
+ * @param {string} label
+ * @param {WeakMap<object, unknown>} [seen]
+ */
+function withoutHiddenValues(value, hidden, label, seen = new WeakMap()) {
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  if (isKnexValue(value)) {
+    return withoutFullBuilder(value, label);
+  }
+  if (seen.has(value)) {
+    return seen.get(value);
+  }
+  seen.set(value, value);
+  let changed = false;
+  const strip = (entry) => {
+    const next = withoutHiddenValues(entry, hidden, label, 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. A call whose
+ * `fields` (in any record it takes) names one of those hidden fields is refused before it runs, whatever the method,
+ * so a read the owner adds in decorateRepository that forwards the caller's `fields` fails loudly rather than answer
+ * the field as undefined; so is any scopedQuery(), and an answer holding a query builder other than a joinSource()'s
+ * (either can select every column, hidden ones too). A call in a system context or one it derived, in any record it
+ * takes, runs as it is. The owner's own code 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 joinSource()'s builder) answers it
+ * as it is, unawaited. A repository whose tables have no hidden fields stays as it is. Hidden fields are told by
+ * name, so a field one owned table hides and another shows is refused here, when the feature's repository is built.
+ * @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;
+  }
+  for (const { name, schema } of owned) {
+    const shown = Object.keys(schema).find((field) => hidden.has(field) && schema[field]?.hidden !== true);
+    if (shown) {
+      const hiders = owned.filter((other) => other.schema[shown]?.hidden === true).map((other) => other.name);
+      throw new TypeError(
+        `${name}.${shown} is a visible field, but ${hiders.join(", ")}, which the same feature owns, hides a field of that ` +
+          `name; its repository strips hidden fields by name from every answer, so ${name}.${shown} would never reach ` +
+          "another feature: hide it in both tables, or rename one of them."
+      );
+    }
+  }
+  return guardedRepository(repository, owned[0], hidden, new WeakSet());
+}
+
+/**
+ * @param {object} repository
+ * @param {{ name: string, schema: Record<string, any> } | null} resource The resource it serves, which names its methods
+ *   in errors and whose scopedQuery it refuses under that name too; 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 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) {
+    // A system context, or one it derived, in whichever record the method takes its options.
+    if (args.some((arg) => isRecord(arg) && isJobContext(arg.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: read the rows through the repository's reads, or join its joinSource({ alias }, options), which " +
+          "carries the visible columns only."
+      ));
+    }
+    const named = [...new Set(args.flatMap((arg) => (isRecord(arg) ? fieldNames(arg.fields) : [])))]
+      .filter((field) => hidden.has(field));
+    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: it passes as it is.
+    if (work) {
+      return answer;
+    }
+    // A Knex value (raw(), a joinSource()'s builder) carries no rows: it passes as it is, unawaited, so a builder
+    // never runs here.
+    if (isKnexValue(answer)) {
+      return withoutFullBuilder(answer, label);
+    }
+    // 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, label))
+      : withoutHiddenValues(answer, hidden, label);
+  };
+}
+
+export { createHiddenFieldReads, createJoinSource, markHandleFunctions, withoutHiddenFields };

package/src/server/handleLocks.js

@@ -0,0 +1,135 @@
+import { missingOf, requireDefinedFilters } from "./handleGuards.js";
+import { handleRecords, sparseFieldset, textList } from "./handleRecords.js";
+
+// The row lock a locking read takes. "update" (the default) is FOR UPDATE. "noKeyUpdate" is PostgreSQL's FOR NO KEY
+// UPDATE, which still keeps every other lock and write of the row out but lets other transactions insert rows that
+// reference it (a foreign key's check takes FOR KEY SHARE); MySQL, MariaDB and SQLite have no weaker exclusive lock and
+// lock as for "update".
+const LOCK_MODES = Object.freeze(["update", "noKeyUpdate"]);
+
+/**
+ * json-rest-api's lock mode for a locking read: none when the call names none, so json-rest-api takes its default.
+ * Another value is a TypeError naming the handle method, before anything runs.
+ * @param {string} name The resource's name.
+ * @param {string} caller The handle method, for the message.
+ * @param {unknown} lockMode
+ */
+function lockModeOf(name, caller, lockMode) {
+  if (lockMode === undefined) {
+    return {};
+  }
+  if (!LOCK_MODES.includes(/** @type {string} */ (lockMode))) {
+    throw new TypeError(`${name}.${caller}() lockMode is "update" (the default) or "noKeyUpdate". Received: ${JSON.stringify(lockMode)}`);
+  }
+  return { lockMode };
+}
+
+/**
+ * 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, in the
+  // lock mode options.lockMode names. `caller` is the handle method, for the messages.
+  async function lockRead(caller, method, read, options) {
+    const mode = lockModeOf(name, caller, options.lockMode);
+    const hidden = hiddenFields.named(options.fields, "plain");
+    const fields = readFields({ fields: options.fields }, "view");
+    const { data } = await jsonRest()[method]({
+      ...read,
+      ...mode,
+      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. `lockMode: "noKeyUpdate"` takes PostgreSQL's FOR NO KEY
+   * UPDATE, so other transactions may still insert rows that reference the locked ones (see LOCK_MODES).
+   * @param {unknown[]} ids
+   * @param {{ context?: object | null, trx: object, missing?: "throw" | "skip", fields?: string[], lockMode?: "update" | "noKeyUpdate" }} options
+   */
+  async function lockMany(ids, options) {
+    return lockRead("lockMany", "lockByIds", { ids, ...(options.missing ? { missing: options.missing } : {}) }, options);
+  }
+
+  // lockMany for lock(): its messages name lock().
+  function lockOne(id, options) {
+    return lockRead("lock", "lockByIds", { ids: [id], ...(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, and `lockMode` picks the lock (see lockMany).
+   * @param {unknown} id
+   * @param {{ context?: object | null, trx: object, missing?: "throw" | "skip", fields?: string[], lockMode?: "update" | "noKeyUpdate" }} options
+   */
+  async function lock(id, options) {
+    missingOf(name, "lock", options.missing);
+    const [record] = await lockOne(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, and `lockMode` picks the lock (see lockMany).
+   * @param {object} filters
+   * @param {{ context?: object | null, trx: object, fields?: string[], lockMode?: "update" | "noKeyUpdate" }} options
+   */
+  async function lockWhere(filters, options) {
+    requireDefinedFilters(name, "lockWhere", filters);
+    return lockRead("lockWhere", "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, and `lockMode` picks the lock (see lockMany).
+   * @param {{ filters: object, sort?: string | string[], take?: number }} params
+   * @param {{ context?: object | null, trx: object, fields?: string[], lockMode?: "update" | "noKeyUpdate" }} 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", "claim", {
+      filters,
+      ...(take === undefined ? {} : { limit: take }),
+      ...(sort === undefined ? {} : { sort: textList(sort) })
+    }, options);
+  }
+
+  return Object.freeze({
+    lock,
+    lockMany,
+    lockWhere,
+    claim
+  });
+}
+
+export { createLockReads, lockModeOf };