json-rest-api 2.4.0 → 3.0.0

package/plugins/core/rest-api-plugin-methods/delete-many.js

@@ -0,0 +1,132 @@
+// Delete many records by id: one scoped read of the ids the caller may delete
+// per chunk (or, with missing: 'skip', the scope inside the DELETE), then one
+// DELETE per chunk and the pivot rows of the deleted records. deleteWhere
+// deletes the rows its selection finds and answers with those it deleted.
+import { beginWriteTransaction } from '../../../lib/error-context.js'
+import { RestApiRecordsNotFoundError, RestApiValidationError } from '../../../lib/rest-api-errors.js'
+import { rejectRemovedOptions, resolveFormat } from '../lib/querying-writing/response-options.js'
+import { requireExistingResourceId } from '../lib/querying-writing/resource-id-normalization.js'
+import { chunk, databaseFamily } from '../lib/storage/many-row-data-helpers.js'
+import { commitOwnedTransaction, handleWriteMethodError } from './common.js'
+import {
+  keepVisible,
+  refuseDuplicateIds,
+  refuseUnsupportedResource,
+  rejectBulkOptions,
+  requireWhereScope,
+  resolveChunkSize,
+  resolveManyRowReturning,
+  resolveMissing,
+  unsupported,
+  validateFilters
+} from './many-row-common.js'
+import { VISIBLE_READ_CHUNK, visibleIdsByFilters } from './patch-many.js'
+
+function setup ({ params, context, scopes, scopeName }, method) {
+  context.method = method
+  rejectRemovedOptions(params)
+  rejectBulkOptions(params)
+  context.scopeName = scopeName
+  context.schemaInfo = scopes[scopeName].vars.schemaInfo
+  // Deletes return no records; a format is still checked like a single delete's.
+  if (params.format !== undefined) resolveFormat(params.format)
+  context.returning = resolveManyRowReturning(params.returning, { deletes: true })
+  context.params = params
+}
+
+/**
+ * @param {any} args
+ * @param {{ operation: string, ids: unknown[], started?: boolean, selection?: { filters?: Record<string, unknown> } }} batch
+ */
+async function runDeleteMany (args, { operation, ids, started = false, selection }) {
+  const { params, context, helpers, scope, runHooks, hasHooks, perRecordHooks, scopeName, api } = args
+  const storageAdapter = helpers.getStorageAdapter(scopeName)
+  const chunkSize = resolveChunkSize(params.chunkSize)
+  const missing = selection ? 'skip' : resolveMissing(params.missing)
+  refuseUnsupportedResource({ api, helpers, perRecordHooks, scopeName, schemaInfo: context.schemaInfo, operation, kind: 'delete', storageHelper: 'dataDeleteByIds' })
+  refuseDuplicateIds(ids, storageAdapter, 'ids')
+
+  if (!started) await beginWriteTransaction(context, params.transaction, helpers.newTransaction, runHooks)
+  context.db = context.transaction
+
+  // With missing: 'skip' and no hook that needs the rows first, the DELETE
+  // decides which rows the caller may delete, carrying the scope (see patchMany,
+  // also for MySQL and selections).
+  const readFirst = !(missing === 'skip' && !hasHooks('checkPermissions') && !hasHooks('beforeDataCallDeleteMany') &&
+    (selection || databaseFamily(context.db) !== 'mysql'))
+  const scoped = Boolean(selection) || !readFirst
+  let kept = ids
+  if (readFirst) {
+    const visible = new Map()
+    for (const part of chunk(ids, VISIBLE_READ_CHUNK)) {
+      const records = await helpers.dataGetMinimal({ scopeName, context, runHooks, ids: part, filters: {}, queryPurpose: 'bulk-write' })
+      for (const record of records) visible.set(String(storageAdapter.translateFilterValue('id', record.id)), record)
+    }
+    kept = keepVisible({ requested: ids, visible, missing, scopeName, storageAdapter })
+    // bulkIndex is the id's position in the request.
+    const positions = new Map(ids.map((id, index) => [String(storageAdapter.translateFilterValue('id', id)), index]))
+    for (const id of kept) {
+      const key = String(storageAdapter.translateFilterValue('id', id))
+      const minimalRecord = visible.get(key)
+      const bulkIndex = positions.get(key)
+      await scope.checkPermissions({ method: 'delete', originalContext: { ...context, method: 'delete', id, minimalRecord, originalMinimalRecord: minimalRecord, bulkIndex } })
+    }
+  }
+
+  context.ids = kept.map(String)
+  await runHooks('beforeDataCallDeleteMany')
+  const deleted = new Set((kept.length
+    ? await helpers.dataDeleteByIds({ scopeName, context, runHooks, ids: kept, chunkSize, scoped, filters: selection?.filters })
+    : []).map(String))
+  // A row that left the caller's scope after the visibility read is not deleted.
+  if (deleted.size < kept.length && missing === 'throw') throw new RestApiRecordsNotFoundError({ resourceType: scopeName, missing: kept.length - deleted.size })
+  context.ids = kept.map(id => String(storageAdapter.translateFilterValue('id', id))).filter(id => deleted.has(id))
+  await runHooks('afterDataCallDeleteMany')
+
+  await commitOwnedTransaction(context)
+  return deleteResponse(context, scopeName, context.ids)
+}
+
+/** @param {any} context @param {string} scopeName @param {string[]} ids */
+function deleteResponse (context, scopeName, ids) {
+  if (context.returning === 'count') return { meta: { count: ids.length } }
+  return context.returning === 'none' ? undefined : { data: ids.map(id => ({ type: scopeName, id })) }
+}
+
+/** @param {any} args */
+export async function deleteManyMethod (args) {
+  const { params, context, scopeName, scopeOptions, vars, log } = args
+  try {
+    setup(args, 'deleteMany')
+    if (!Array.isArray(params.ids) || !params.ids.length) {
+      throw new RestApiValidationError('ids must be a non-empty array', { fields: ['ids'] })
+    }
+    const ids = params.ids.map(id => requireExistingResourceId(id, { scopeOptions, vars, scopeName }))
+    return await runDeleteMany(args, { operation: 'deleteMany', ids })
+  } catch (error) {
+    await handleWriteMethodError(error, context, 'DELETE_MANY', scopeName, log)
+  }
+}
+
+/** @param {any} args */
+export async function deleteWhereMethod (args) {
+  const { params, context, scopeName, vars, helpers, log } = args
+  try {
+    setup(args, 'deleteWhere')
+    if (typeof helpers.dataVisibleIds !== 'function') {
+      throw unsupported(scopeName, 'deleteWhere', 'its storage plugin has no many-row support (AnyAPI storage takes single writes)')
+    }
+    const filters = validateFilters({ filters: params.filters, scopeName, schemaInfo: context.schemaInfo, vars })
+    requireWhereScope({ filters, all: params.all, missing: params.missing, operation: 'deleteWhere' })
+    await beginWriteTransaction(context, params.transaction, helpers.newTransaction, args.runHooks)
+    context.db = context.transaction
+    const ids = await visibleIdsByFilters(args, filters)
+    if (!ids.length) {
+      await commitOwnedTransaction(context)
+      return deleteResponse(context, scopeName, [])
+    }
+    return await runDeleteMany(args, { operation: 'deleteWhere', ids, started: true, selection: { filters } })
+  } catch (error) {
+    await handleWriteMethodError(error, context, 'DELETE_WHERE', scopeName, log)
+  }
+}

package/plugins/core/rest-api-plugin-methods/delete-relationship.js

@@ -22,6 +22,27 @@ import { updateReverseRelationship } from '../lib/writing/reverse-relationship-m
 import { invalidateRemovedPivotVersions } from '../lib/writing/many-to-many-manipulations.js'
 import { getStorageColumn } from '../lib/storage/storage-mapping.js'
 import { RELATIONSHIP_WRITE_BATCH_SIZE } from '../lib/querying-writing/knex-constants.js'
+import { filterVisibleIdentifiers } from '../lib/querying/include-query-helpers.js'
+import { isSystemContext } from '../../../lib/system-context.js'
+
+/**
+ * The identifiers a many-to-many removal may unlink. Targets that ownership
+ * filters or a row policy scope are read for visibility (one read per type and
+ * 1,000 ids), and links to targets the caller cannot see stay, as links to
+ * missing ones always did. Other targets, and every target in a system context,
+ * cost no read. (Reverse hasMany removals check each child's visibility themselves.)
+ * @param {WriteRelationshipContext} context
+ * @param {Identifier[]} identifiers
+ * @param {any} api
+ */
+async function removableTargets (context, identifiers, api) {
+  if (isSystemContext(context)) return identifiers
+  const scoped = (/** @type {Identifier} */ { type }) => Boolean(api.resources[type]?.vars?.schemaInfo?.ownershipFields?.length || api.resources[type]?.vars?.rowPolicy)
+  const checked = identifiers.filter(scoped)
+  if (!checked.length) return identifiers
+  const visible = new Set(await filterVisibleIdentifiers({ identifiers: checked, scopes: api.resources, knex: context.db, context }))
+  return identifiers.filter(identifier => !scoped(identifier) || visible.has(identifier))
+}
 
 /**
  * Remove the identifiers in params.relationshipData from a to-many relationship.
@@ -98,6 +119,7 @@ export default async function deleteRelationshipMethod ({ params, context: calle
 
     // Remove relationships
     if (relDef?.through) {
+      params.relationshipData = await removableTargets(context, params.relationshipData, api)
       if (api.anyapi?.links?.removeMany) {
         await api.anyapi.links.removeMany({
           context,

package/plugins/core/rest-api-plugin-methods/get.js

@@ -78,52 +78,58 @@ export default async function getMethod ({
 
   const identityContext = /** @type {IdentityContext} */ (context)
 
-  // Fetch minimal record for authorization checks
-  const minimalRecord = await helpers.dataGetMinimal({
-    scopeName,
-    context: identityContext,
-    runHooks
+  const notFound = () => new RestApiResourceError('Resource not found', {
+    subtype: 'not_found',
+    resourceType: scopeName,
+    resourceId: context.id
   })
 
-  if (!minimalRecord) {
-    throw new RestApiResourceError(
-      'Resource not found',
-      {
-        subtype: 'not_found',
-        resourceType: scopeName,
-        resourceId: context.id
-      }
-    )
+  // The minimal record serves the permission checks and the hooks before the
+  // data call. A resource without them reads once: the scoped full read also
+  // answers whether the row exists. Any permission hook keeps both reads.
+  const readOnce = ['checkPermissions', 'checkDataPermissions', 'checkDataPermissionsGet', 'beforeData', 'beforeDataGet'].some(event => hasHooks(event))
+    ? undefined
+    : helpers.dataGetScoped
+
+  if (readOnce) {
+    try {
+      await validateRequestedFieldsets(context, scopes)
+      validateRequestedIncludes(context, scopes)
+    } catch (error) {
+      // A missing row answers 404 before a bad fieldset, as with two reads.
+      if (!(await helpers.dataGetMinimal({ scopeName, context: identityContext, runHooks }))) throw notFound()
+      throw error
+    }
+    context.record = await readOnce({ scopeName, context: identityContext, runHooks })
+  } else {
+    // Fetch minimal record for authorization checks
+    const minimalRecord = await helpers.dataGetMinimal({
+      scopeName,
+      context: identityContext,
+      runHooks
+    })
+    if (!minimalRecord) throw notFound()
+
+    context.minimalRecord = minimalRecord
+
+    await scope.checkPermissions({
+      method: 'get',
+      originalContext: context,
+    })
+
+    await validateRequestedFieldsets(context, scopes)
+    validateRequestedIncludes(context, scopes)
+    await runHooks('beforeData')
+    await runHooks('beforeDataGet')
+
+    context.record = await helpers.dataGet({
+      scopeName,
+      context: identityContext,
+      runHooks
+    })
   }
 
-  context.minimalRecord = minimalRecord
-
-  await scope.checkPermissions({
-    method: 'get',
-    originalContext: context,
-  })
-
-  await validateRequestedFieldsets(context, scopes)
-  validateRequestedIncludes(context, scopes)
-  await runHooks('beforeData')
-  await runHooks('beforeDataGet')
-
-  context.record = await helpers.dataGet({
-    scopeName,
-    context: identityContext,
-    runHooks
-  })
-
-  if (!context.record || !context.record.data) {
-    throw new RestApiResourceError(
-      'Resource not found',
-      {
-        subtype: 'not_found',
-        resourceType: scopeName,
-        resourceId: context.id
-      }
-    )
-  }
+  if (!context.record || !context.record.data) throw notFound()
 
   context.record = normalizeRecordAttributes(context.record, scopes)
 

package/plugins/core/rest-api-plugin-methods/many-row-common.js

@@ -0,0 +1,274 @@
+// Shared steps of the many-row operations: input selection, refusals, chunking,
+// the in-memory per-row pipeline and the response shape.
+import {
+  RestApiBulkWriteUnsupportedError,
+  RestApiLockOutsideTransactionError,
+  RestApiRecordsNotFoundError,
+  RestApiValidationError
+} from '../../../lib/rest-api-errors.js'
+import { transformSimplifiedToJsonApi } from '../lib/querying-writing/simplified-helpers.js'
+import { inverseVersionTypes } from '../lib/writing/resource-version.js'
+import { isRawValue } from '../lib/storage/many-row-data-helpers.js'
+import { queryConstraint } from '../lib/querying/query-constraint.js'
+import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
+
+export const DEFAULT_CHUNK_SIZE = 500
+const READ_CHUNK_SIZE = 1000
+
+// Per-record events whose handlers many-row operations would skip. A handler
+// must be registered with { batch: true } (its work done by a batch hook or not
+// applying to batches), or the operation refuses the resource.
+const PER_RECORD_EVENTS = {
+  post: ['beforeProcessing', 'beforeProcessingPost', 'beforeSchemaValidate', 'beforeSchemaValidatePost', 'afterSchemaValidate', 'afterSchemaValidatePost', 'beforeDataCall', 'beforeDataCallPost', 'afterDataCall', 'afterDataCallPost', 'finish', 'finishPost'],
+  patch: ['beforeProcessing', 'beforeProcessingPatch', 'beforeSchemaValidate', 'beforeSchemaValidatePatch', 'afterSchemaValidate', 'afterSchemaValidatePatch', 'beforeDataCall', 'beforeDataCallPatch', 'afterDataCall', 'afterDataCallPatch', 'finish', 'finishPatch'],
+  delete: ['beforeDataCall', 'beforeDataCallDelete', 'afterDataCall', 'afterDataCallDelete', 'finish', 'finishDelete']
+}
+
+export const noHooks = async () => {}
+
+// Options of the 2.x bulk methods that many-row writes do not have.
+const BULK_OPTIONS = {
+  atomic: 'Many-row writes are all-or-nothing; remove atomic.',
+  expectedVersion: 'Many-row writes refuse versioned resources; use a lockVersionField and onlyIf.',
+  expectedVersions: 'Many-row writes refuse versioned resources; use a lockVersionField and onlyIf.',
+  operations: 'Pass the rows as data: [{ id, ...attributes }] or document: { data: [...] }.'
+}
+
+/** @param {Record<string, unknown>} params */
+export function rejectBulkOptions (params) {
+  const fields = Object.keys(BULK_OPTIONS).filter(name => Object.hasOwn(params, name))
+  if (fields.length) {
+    throw new RestApiValidationError(`Unsupported options: ${fields.join(', ')}. ${[...new Set(fields.map(name => BULK_OPTIONS[name]))].join(' ')}`, { fields })
+  }
+}
+
+/** @param {string} resourceType @param {string} operation @param {string} reason */
+export const unsupported = (resourceType, operation, reason) => new RestApiBulkWriteUnsupportedError({ resourceType, operation, reason })
+
+/**
+ * Refuses what a many-row write cannot do in one statement per chunk.
+ * @param {{ api: any, helpers: any, perRecordHooks: Function, scopeName: string, schemaInfo: any, operation: string, kind: 'post' | 'patch' | 'delete', storageHelper: string }} request
+ */
+export function refuseUnsupportedResource ({ api, helpers, perRecordHooks, scopeName, schemaInfo, operation, kind, storageHelper }) {
+  if (typeof helpers[storageHelper] !== 'function') {
+    throw unsupported(scopeName, operation, 'its storage plugin has no many-row support (AnyAPI storage takes single writes)')
+  }
+  if (schemaInfo.versionField) {
+    throw unsupported(scopeName, operation, `the resource is versioned by '${schemaInfo.versionField}'; use single writes with expectedVersion`)
+  }
+  const parents = [...inverseVersionTypes(api, scopeName, schemaInfo)]
+  if (parents.length) {
+    throw unsupported(scopeName, operation, `writes advance the version of '${parents.join("', '")}'`)
+  }
+  if (kind === 'delete') {
+    for (const [ownerType, owner] of Object.entries(api.resources)) {
+      if (!owner.vars.schemaInfo?.versionField) continue
+      const versioned = Object.values(owner.vars.schemaInfo.schemaRelationships || {})
+        .some(relationship => relationship.type === 'manyToMany' && relationship.target === scopeName)
+      if (versioned) throw unsupported(scopeName, operation, `deletes advance the version of '${ownerType}' through a many-to-many relationship`)
+    }
+  }
+  const hooks = perRecordHooks(PER_RECORD_EVENTS[kind])
+  if (hooks.length) {
+    // The hook names stay in the error details, which HTTP responses leave out.
+    throw new RestApiBulkWriteUnsupportedError({
+      resourceType: scopeName,
+      operation,
+      reason: 'per-record hooks without a batch form run for it; register them with { batch: true } and a batch hook',
+      hooks: hooks.map(hook => `${hook.event}:${hook.name}`)
+    })
+  }
+}
+
+/** @param {unknown} value */
+export function resolveChunkSize (value) {
+  if (value === undefined) return DEFAULT_CHUNK_SIZE
+  if (!Number.isSafeInteger(value) || /** @type {number} */ (value) < 1) {
+    throw new RestApiValidationError('chunkSize must be a positive integer', { fields: ['chunkSize'] })
+  }
+  return /** @type {number} */ (value)
+}
+
+/**
+ * What a many-row write returns: nothing (the default), identifiers, the
+ * records (not for deletes) or `{ meta: { count } }`, the number of rows it
+ * wrote.
+ * @param {unknown} value
+ * @param {{ deletes?: boolean }} [options]
+ * @returns {'none' | 'minimal' | 'full' | 'count'}
+ */
+export function resolveManyRowReturning (value, { deletes = false } = {}) {
+  const returning = value === undefined ? 'none' : value
+  if (returning === 'none' || returning === 'minimal' || returning === 'count' || (returning === 'full' && !deletes)) return returning
+  throw new RestApiValidationError(deletes ? "A delete returns 'none', 'minimal' or 'count'" : "returning must be 'none', 'minimal', 'full' or 'count'", { fields: ['returning'] })
+}
+
+/** @param {unknown} value */
+export function resolveMissing (value) {
+  if (value === undefined) return 'throw'
+  if (value !== 'throw' && value !== 'skip') {
+    throw new RestApiValidationError("missing must be 'throw' or 'skip'", { fields: ['missing'] })
+  }
+  return value
+}
+
+/**
+ * The records of a many-row write: `data: [...]` in the plain format, or
+ * `document: { data: [...] }` in JSON:API.
+ * @param {Record<string, any>} params
+ * @returns {{ inputKey: 'data' | 'document', records: any[] }}
+ */
+export function selectManyInput (params) {
+  const hasData = Object.hasOwn(params, 'data')
+  if (hasData === Object.hasOwn(params, 'document')) {
+    throw new RestApiValidationError('Supply exactly one of data or document', { fields: ['data', 'document'] })
+  }
+  const records = hasData ? params.data : params.document?.data
+  if (!Array.isArray(records) || records.length === 0) {
+    const field = hasData ? 'data' : 'document.data'
+    throw new RestApiValidationError(`${field} must be a non-empty array of records`, {
+      fields: [field], violations: [{ field, rule: 'required_array', message: 'Must be a non-empty array' }]
+    })
+  }
+  records.forEach((record, index) => {
+    if (!record || typeof record !== 'object' || Array.isArray(record)) {
+      throw new RestApiValidationError(`Record ${index} must be an object`, { fields: [`data.${index}`] })
+    }
+  })
+  return { inputKey: hasData ? 'data' : 'document', records }
+}
+
+/**
+ * One record as a JSON:API document, with knex.raw values set aside for the
+ * operations that accept them.
+ * @param {{ record: any, inputKey: 'data' | 'document', scopeName: string, schemaInfo: any, allowRaw?: boolean }} request
+ */
+export function toDocument ({ record, inputKey, scopeName, schemaInfo, allowRaw = false }) {
+  const raw = {}
+  let attributes = inputKey === 'data' ? record : record.attributes
+  if (attributes && typeof attributes === 'object') {
+    for (const [field, value] of Object.entries(attributes)) {
+      if (!isRawValue(value)) {
+        // Knex would run any object carrying the flag as SQL; JSON input can carry the flag.
+        if (value && typeof value === 'object' && Object.hasOwn(value, 'isRawInstance')) {
+          throw new RestApiValidationError(`Field '${field}' holds an object that is not a Knex raw value`, { fields: [field] })
+        }
+        continue
+      }
+      if (!allowRaw) throw new RestApiValidationError(`Field '${field}' cannot take a raw SQL value here`, { fields: [field] })
+      raw[field] = value
+    }
+    if (Object.keys(raw).length) attributes = Object.fromEntries(Object.entries(attributes).filter(([field]) => !Object.hasOwn(raw, field)))
+  }
+  const document = inputKey === 'data'
+    ? transformSimplifiedToJsonApi({ inputRecord: attributes }, {
+      context: { scopeName, schemaStructure: schemaInfo.schemaInstance.structure, schemaRelationships: schemaInfo.schemaRelationships }
+    })
+    : { data: { ...record, ...(record.attributes ? { attributes } : {}) } }
+  return { document, raw }
+}
+
+/**
+ * Prefixes a row's validation paths with its position in the batch.
+ * @param {unknown} error @param {number} index
+ */
+export function atIndex (error, index) {
+  if (!(error instanceof RestApiValidationError)) return error
+  const prefix = path => typeof path === 'string' ? path.replace(/^(data\.)?/, `data.${index}.`) : path
+  const details = /** @type {any} */ (error.details || {})
+  if (Array.isArray(details.fields)) details.fields = details.fields.map(prefix)
+  if (Array.isArray(details.violations)) details.violations = details.violations.map(violation => ({ ...violation, field: prefix(violation.field) }))
+  details.index = index
+  error.details = details
+  return error
+}
+
+/**
+ * Throws when a requested identifier is missing or outside the caller's scope.
+ * @param {{ requested: unknown[], visible: Map<string, unknown> | Set<string>, missing: 'throw' | 'skip', scopeName: string, storageAdapter: any }} request
+ * @returns {unknown[]} requested identifiers that are visible
+ */
+export function keepVisible ({ requested, visible, missing, scopeName, storageAdapter }) {
+  const kept = []
+  let absent = 0
+  for (const id of requested) {
+    if (visible.has(String(storageAdapter.translateFilterValue('id', id)))) kept.push(id)
+    else absent++
+  }
+  if (absent && missing === 'throw') throw new RestApiRecordsNotFoundError({ resourceType: scopeName, missing: absent })
+  return kept
+}
+
+/** @param {unknown[]} ids */
+export function refuseDuplicateIds (ids, storageAdapter, field = 'data') {
+  const seen = new Set()
+  for (const id of ids) {
+    const key = String(storageAdapter.translateFilterValue('id', id))
+    if (seen.has(key)) throw new RestApiValidationError(`Identifier ${id} appears twice in the batch`, { fields: [field] })
+    seen.add(key)
+  }
+}
+
+/** @param {{ transaction?: any, scopeName: string, operation: string }} request */
+export function requireLockTransaction ({ transaction, scopeName, operation }) {
+  if (!transaction || typeof transaction !== 'function' || !transaction.isTransaction || transaction.isCompleted?.()) {
+    throw new RestApiLockOutsideTransactionError({ resourceType: scopeName, operation })
+  }
+}
+
+/**
+ * patchWhere and deleteWhere need filters, or `all: true` to act on every row
+ * the caller can see (in a system context, the whole table).
+ * @param {{ filters: Record<string, unknown> | undefined, all: unknown, missing?: unknown, operation: string }} request
+ */
+export function requireWhereScope ({ filters, all, missing, operation }) {
+  // A selection writes the rows it finds and answers with those; no row is missing.
+  if (missing !== undefined) throw new RestApiValidationError(`${operation} writes the rows its selection finds; missing applies to lists of ids`, { fields: ['missing'] })
+  if (all !== undefined && all !== true) throw new RestApiValidationError('all must be true when given', { fields: ['all'] })
+  const filtered = Boolean(filters && Object.keys(filters).length)
+  if (all && filtered) throw new RestApiValidationError(`${operation} takes filters or all: true, not both`, { fields: ['all'] })
+  if (!all && !filtered) {
+    throw new RestApiValidationError(`${operation} needs filters, or all: true to act on every row the caller can see`, { fields: ['filters'] })
+  }
+}
+
+/**
+ * Validates filters as `query` would, so many-row operations accept the same
+ * search fields and values.
+ */
+export function validateFilters ({ filters, scopeName, schemaInfo, vars }) {
+  if (filters === undefined) return undefined
+  const contracts = getRequestContracts({ scopeName, schemaInfo, includeDepthLimit: vars.includeDepthLimit, sortableFields: vars.sortableFields })
+  return validateRequestContractOrThrow(contracts.query, { queryParams: { filters } }, 'Filters are invalid').queryParams?.filters
+}
+
+/**
+ * The response of a many-row write: the count of written rows, identifiers,
+ * full records read through `query` in the write's transaction, or nothing.
+ * @param {{ api: any, scopeName: string, context: any, ids: unknown[], returning: string, format: string, queryParams?: any }} request
+ */
+export async function manyRowResponse ({ api, scopeName, context, ids, returning, format, queryParams = {} }) {
+  if (returning === 'none') return undefined
+  const present = ids.filter(id => id !== undefined && id !== null).map(String)
+  if (returning === 'count') return { meta: { count: present.length } }
+  if (returning === 'minimal') return { data: present.map(id => ({ type: scopeName, id })) }
+
+  const byId = new Map()
+  /** @type {Map<string, any>} */
+  const included = new Map()
+  for (let offset = 0; offset < present.length; offset += READ_CHUNK_SIZE) {
+    const part = present.slice(offset, offset + READ_CHUNK_SIZE)
+    const page = await api.resources[scopeName].query({
+      format,
+      transaction: context.transaction,
+      pageSizeLimit: part.length,
+      queryParams: { fields: queryParams.fields, include: queryParams.include, sort: ['id'], page: { size: part.length } },
+      [queryConstraint]: { scopeName, idsQuery: part }
+    }, { ...context, method: undefined, knexQuery: undefined })
+    for (const record of page.data) byId.set(String(record.id), record)
+    for (const resource of page.included || []) included.set(`${resource.type}:${resource.id}`, resource)
+  }
+  // Rows the caller's read scope hides are left out.
+  const data = present.filter(id => byId.has(id)).map(id => byId.get(id))
+  return format === 'jsonapi' && included.size ? { data, included: [...included.values()] } : { data }
+}