json-rest-api 2.4.0 → 3.0.0

package/plugins/core/rest-api-plugin-methods/scoped-reads.js

@@ -0,0 +1,221 @@
+// Reads that keep the resource's scope: the read-only scoped builder, every-row
+// reads in cursor pages, and row locks inside a transaction.
+import { RestApiBulkWriteUnsupportedError, RestApiRecordsNotFoundError, RestApiRowLimitError, RestApiValidationError } from '../../../lib/rest-api-errors.js'
+import { readOnlyQueryBuilder } from '../lib/querying/read-only-query.js'
+import { normalizeRecordAttributes } from '../lib/querying-writing/database-value-normalizers.js'
+import { filterResponseFields, getResourceFieldset } from '../lib/querying-writing/field-utils.js'
+import { getRequestedComputedFields, validateRequestedFieldsets } from '../lib/querying-writing/knex-field-helpers.js'
+import { resolveFormat } from '../lib/querying-writing/response-options.js'
+import { transformJsonApiToSimplified } from '../lib/querying-writing/simplified-helpers.js'
+import { requireExistingResourceId } from '../lib/querying-writing/resource-id-normalization.js'
+import { chunk } from '../lib/storage/many-row-data-helpers.js'
+import { filterToOneResponseLinkage, snapshotReadRecord } from './common.js'
+import { refuseDuplicateIds, requireLockTransaction, resolveMissing, validateFilters } from './many-row-common.js'
+
+export const SCOPED_QUERY_PURPOSES = new Set(['report', 'bulk-write', 'lock', 'claim'])
+const DEFAULT_QUERY_ALL_PAGE = 1000
+const MAX_CLAIM = 1000
+const MAX_LOCK_WHERE = 1000
+
+const invalid = (field, message) => new RestApiValidationError(message, { fields: [field], violations: [{ field, rule: 'scoped_read', message }] })
+
+/**
+ * The resource's table with ownership and row policy applied, as a read-only
+ * Knex builder over a derived table named after the alias (or the table), so
+ * nothing a caller adds, `orWhere` included, can widen the scope. Resolves to
+ * `{ query }`: a builder is thenable, so returning it from an async method would run it.
+ * @param {any} args
+ */
+export async function scopedQueryMethod ({ params, context, vars, helpers, scope, scopes, runHooks, scopeName, api }) {
+  const { transaction, alias, purpose = 'report', filters, ...unknown } = params
+  if (Object.keys(unknown).length) throw invalid(Object.keys(unknown)[0], `Unknown scopedQuery options: ${Object.keys(unknown).join(', ')}`)
+  if (!SCOPED_QUERY_PURPOSES.has(purpose)) throw invalid('purpose', `purpose must be one of ${[...SCOPED_QUERY_PURPOSES].join(', ')}`)
+  if (alias !== undefined && (typeof alias !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(alias))) {
+    throw invalid('alias', 'alias must be an identifier')
+  }
+  if (typeof helpers.dataScopedQuery !== 'function') {
+    throw new RestApiBulkWriteUnsupportedError({ resourceType: scopeName, operation: 'scopedQuery', reason: 'its storage plugin provides no scoped builder' })
+  }
+  context.method = 'scopedQuery'
+  context.scopeName = scopeName
+  context.schemaInfo = scopes[scopeName].vars.schemaInfo
+  context.transaction = transaction
+  context.db = transaction
+  context.queryParams = { filters: validateFilters({ filters, scopeName, schemaInfo: context.schemaInfo, vars }) || {} }
+  // A caller who may not query the resource may not build reports on it either.
+  await scope.checkPermissions({ method: 'query', originalContext: { ...context, method: 'query', scopedQuery: true } })
+  const { query, alias: name } = await helpers.dataScopedQuery({ scopeName, context, runHooks, alias, purpose, filters: context.queryParams.filters })
+  const derived = (transaction || api.knex.instance).from(query.select(`${name}.*`).as(name))
+  return { query: readOnlyQueryBuilder(derived, { resourceType: scopeName }) }
+}
+
+/**
+ * Every row the filters select, read in cursor pages of `pageSize` rows.
+ * @param {any} args
+ */
+export async function queryAllMethod ({ params, context, vars, scopeName, api }) {
+  const { queryParams = {}, transaction, pageSize = DEFAULT_QUERY_ALL_PAGE, rowLimit, format, ...unknown } = params
+  if (Object.keys(unknown).length) throw invalid(Object.keys(unknown)[0], `Unknown queryAll options: ${Object.keys(unknown).join(', ')}`)
+  if (!Number.isSafeInteger(pageSize) || pageSize < 1) throw invalid('pageSize', 'pageSize must be a positive integer')
+  if (rowLimit !== undefined && (!Number.isSafeInteger(rowLimit) || rowLimit < 1)) throw invalid('rowLimit', 'rowLimit must be a positive integer')
+  if (queryParams.page !== undefined) throw invalid('queryParams.page', 'queryAll pages by itself; leave out queryParams.page')
+  const resolvedFormat = resolveFormat(format, vars.format)
+  const sort = queryParams.sort?.length ? queryParams.sort : ['id']
+
+  const data = []
+  const included = new Map()
+  let cursor
+  do {
+    const page = await api.resources[scopeName].query({
+      format: resolvedFormat,
+      transaction,
+      pageSizeLimit: pageSize,
+      queryParams: { ...queryParams, sort, page: cursor ? { size: pageSize, after: cursor } : { size: pageSize } }
+    }, { ...context })
+    data.push(...page.data)
+    for (const resource of page.included || []) included.set(`${resource.type}:${resource.id}`, resource)
+    if (rowLimit !== undefined && data.length > rowLimit) throw new RestApiRowLimitError({ resourceType: scopeName, rowLimit })
+    cursor = page.meta?.pagination?.hasMore ? page.meta.pagination.cursor?.next : undefined
+  } while (cursor)
+  return resolvedFormat === 'jsonapi' && included.size ? { data, included: [...included.values()] } : { data }
+}
+
+// The rows a lock read leave through the read pipeline `query` runs after its
+// data call, so masking and denials apply to them too: checkDataPermissions for
+// each row as `get` runs it, enrichRecord, computed fields, the finish hooks,
+// sparse fieldsets and the plain format. Hooks see method 'query' and lock: true.
+async function finishLockedRead ({ document, context, scope, scopes, scopeName, runHooks, hasHooks }) {
+  context.method = 'query'
+  context.lock = true
+  context.record = normalizeRecordAttributes(document, scopes)
+  if (hasHooks('checkDataPermissions') || hasHooks('checkDataPermissionsGet')) {
+    for (const entry of context.record.data) {
+      const recordContext = { ...context, method: 'get', id: entry.id, record: { data: entry } }
+      await runHooks('checkDataPermissions', recordContext)
+      await runHooks('checkDataPermissionsGet', recordContext)
+    }
+  }
+  snapshotReadRecord(context, scopes, hasHooks, 'query')
+  await runHooks('enrichRecord')
+  const computedFields = scope.vars.schemaInfo?.computed || {}
+  const requestedComputedFields = getRequestedComputedFields(scopeName, getResourceFieldset(context.queryParams.fields, scopeName), computedFields)
+  for (const entry of context.record.data) {
+    entry.attributes = await scope.enrichAttributes({
+      id: entry.id,
+      attributes: entry.attributes,
+      parentContext: context,
+      requestedComputedFields,
+      isMainResource: true,
+      computedDependencies: context.computedDependencies
+    })
+  }
+  await runHooks('finish')
+  await runHooks('finishQuery')
+  await filterToOneResponseLinkage(context, scopes)
+  const record = normalizeRecordAttributes(context.record, scopes, { source: 'response' })
+  filterResponseFields(record, context.queryParams.fields)
+  if (context.format !== 'plain') return { data: record.data }
+  const schemaInfo = scope.vars.schemaInfo
+  return transformJsonApiToSimplified({ record }, {
+    context: { schemaStructure: schemaInfo.schemaInstance.structure, schemaRelationships: schemaInfo.schemaRelationships, scopes }
+  })
+}
+
+async function setupLockRead ({ params, context, vars, helpers, scopes, scopeName }, operation, storageHelper) {
+  requireLockTransaction({ transaction: params.transaction, scopeName, operation })
+  if (typeof helpers[storageHelper] !== 'function') {
+    throw new RestApiBulkWriteUnsupportedError({ resourceType: scopeName, operation, reason: 'its storage plugin has no row locks (AnyAPI storage takes single writes)' })
+  }
+  context.method = operation
+  context.scopeName = scopeName
+  context.schemaInfo = scopes[scopeName].vars.schemaInfo
+  context.transaction = params.transaction
+  context.db = params.transaction
+  context.format = resolveFormat(params.format, vars.format)
+  context.simplified = context.format === 'plain'
+  const fields = params.queryParams?.fields
+  if (params.queryParams !== undefined && Object.keys(params.queryParams).some(key => key !== 'fields')) {
+    throw invalid('queryParams', `${operation} takes only queryParams.fields`)
+  }
+  context.queryParams = { fields: fields ?? {} }
+  await validateRequestedFieldsets(context, scopes)
+}
+
+/**
+ * Locks the visible rows among `ids` until the transaction ends, in id order,
+ * and returns them as the locking read saw them. That read is the first
+ * statement on the rows and decides visibility itself, so the transaction's
+ * snapshot starts after any lock wait. On MySQL it locks every listed row,
+ * hidden ones too, before it checks the scope (see guide 34).
+ * @param {any} args
+ */
+export async function lockByIdsMethod (args) {
+  const { params, context, helpers, scope, scopes, runHooks, hasHooks, scopeName, scopeOptions, vars } = args
+  await setupLockRead(args, 'lockByIds', 'dataLockByIds')
+  if (!Array.isArray(params.ids) || !params.ids.length) throw invalid('ids', 'ids must be a non-empty array')
+  const ids = params.ids.map(id => requireExistingResourceId(id, { scopeOptions, vars, scopeName }))
+  const storageAdapter = helpers.getStorageAdapter(scopeName)
+  refuseDuplicateIds(ids, storageAdapter, 'ids')
+  const missing = resolveMissing(params.missing)
+  await scope.checkPermissions({ method: 'query', originalContext: { ...context, method: 'query', lock: true } })
+  // Sorted before chunking, so lists longer than a chunk still lock in one
+  // order across transactions: a list of integers numerically, any other list
+  // by code unit (the database's order for a binary collation).
+  const keys = ids.map(id => String(storageAdapter.translateFilterValue('id', id)))
+  const numeric = keys.every(key => /^-?\d+$/.test(key))
+  const sorted = ids
+    .map((id, index) => ({ id, key: numeric ? BigInt(keys[index]) : keys[index] }))
+    .sort((left, right) => left.key < right.key ? -1 : left.key > right.key ? 1 : 0)
+    .map(entry => entry.id)
+  const document = { data: [] }
+  for (const part of chunk(sorted, 1000)) {
+    document.data.push(...(await helpers.dataLockByIds({ scopeName, context, runHooks, ids: part })).data)
+  }
+  if (document.data.length < ids.length && missing === 'throw') {
+    throw new RestApiRecordsNotFoundError({ resourceType: scopeName, missing: ids.length - document.data.length })
+  }
+  if (!document.data.length) return { data: [] }
+  return finishLockedRead({ document, context, scope, scopes, scopeName, runHooks, hasHooks })
+}
+
+/**
+ * Locks the visible rows the filters select until the transaction ends, in id
+ * order, waiting for transactions that hold them, so a row that starts to match
+ * while the lock waits is locked and returned too. At most 1,000 rows.
+ * @param {any} args
+ */
+export async function lockWhereMethod (args) {
+  const { params, context, vars, helpers, scope, scopes, runHooks, hasHooks, scopeName } = args
+  await setupLockRead(args, 'lockWhere', 'dataLockWhere')
+  const filters = validateFilters({ filters: params.filters, scopeName, schemaInfo: context.schemaInfo, vars })
+  await scope.checkPermissions({ method: 'query', originalContext: { ...context, method: 'query', lock: true } })
+  const document = await helpers.dataLockWhere({ scopeName, context, runHooks, filters, limit: MAX_LOCK_WHERE + 1 })
+  if (document.data.length > MAX_LOCK_WHERE) throw new RestApiRowLimitError({ resourceType: scopeName, rowLimit: MAX_LOCK_WHERE, operation: 'lockWhere' })
+  return finishLockedRead({ document, context, scope, scopes, scopeName, runHooks, hasHooks })
+}
+
+/**
+ * Takes up to `limit` rows the filters select that no other transaction holds
+ * (SELECT … FOR UPDATE SKIP LOCKED), for job queues.
+ * @param {any} args
+ */
+export async function claimMethod (args) {
+  const { params, context, vars, helpers, scope, scopes, runHooks, hasHooks, scopeName } = args
+  await setupLockRead(args, 'claim', 'dataClaim')
+  const limit = params.limit ?? 1
+  if (!Number.isSafeInteger(limit) || limit < 1 || limit > MAX_CLAIM) throw invalid('limit', `limit must be an integer from 1 to ${MAX_CLAIM}`)
+  const filters = validateFilters({ filters: params.filters, scopeName, schemaInfo: context.schemaInfo, vars })
+  const sortParam = params.sort ?? ['id']
+  if (!Array.isArray(sortParam)) throw invalid('sort', 'sort must be an array of fields')
+  const schema = context.schemaInfo.schemaStructure
+  const sort = sortParam.map((entry, index) => {
+    const field = typeof entry === 'string' ? entry.replace(/^-/, '') : null
+    if (!field || (field !== 'id' && (!schema[field] || schema[field].virtual || schema[field].computed))) {
+      throw invalid(`sort.${index}`, `'${entry}' is not a stored field`)
+    }
+    return { field, direction: entry.startsWith('-') ? 'desc' : 'asc' }
+  })
+  await scope.checkPermissions({ method: 'query', originalContext: { ...context, method: 'query', lock: true } })
+  const document = await helpers.dataClaim({ scopeName, context, runHooks, filters, sort, limit })
+  return finishLockedRead({ document, context, scope, scopes, scopeName, runHooks, hasHooks })
+}

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

@@ -16,6 +16,10 @@ import postMethod from './rest-api-plugin-methods/post.js'
 import putMethod from './rest-api-plugin-methods/put.js'
 import patchMethod from './rest-api-plugin-methods/patch.js'
 import deleteMethod from './rest-api-plugin-methods/delete.js'
+import postManyMethod from './rest-api-plugin-methods/post-many.js'
+import { patchManyMethod, patchWhereIdsMethod, patchWhereMethod } from './rest-api-plugin-methods/patch-many.js'
+import { deleteManyMethod, deleteWhereMethod } from './rest-api-plugin-methods/delete-many.js'
+import { claimMethod, lockByIdsMethod, lockWhereMethod, queryAllMethod, scopedQueryMethod } from './rest-api-plugin-methods/scoped-reads.js'
 import enrichAttributesMethod from './rest-api-plugin-methods/enrich-attributes.js'
 import checkPermissionsMethod from './rest-api-plugin-methods/check-permissions.js'
 import applyQueryFiltersMethod from './rest-api-plugin-methods/apply-query-filters.js'
@@ -98,6 +102,19 @@ export const RestApiPlugin = {
     addResourceMethod('patch', withWriteOutcome(patchMethod))
     addResourceMethod('delete', withWriteOutcome(deleteMethod))
 
+    // Many-row writes, every-row reads, the scoped builder and row locks
+    addResourceMethod('postMany', withWriteOutcome(postManyMethod))
+    addResourceMethod('patchMany', withWriteOutcome(patchManyMethod))
+    addResourceMethod('patchWhereIds', withWriteOutcome(patchWhereIdsMethod))
+    addResourceMethod('patchWhere', withWriteOutcome(patchWhereMethod))
+    addResourceMethod('deleteMany', withWriteOutcome(deleteManyMethod))
+    addResourceMethod('deleteWhere', withWriteOutcome(deleteWhereMethod))
+    addResourceMethod('queryAll', withAvailableContext(queryAllMethod))
+    addResourceMethod('scopedQuery', withAvailableContext(scopedQueryMethod))
+    addResourceMethod('lockByIds', withAvailableContext(lockByIdsMethod))
+    addResourceMethod('lockWhere', withAvailableContext(lockWhereMethod))
+    addResourceMethod('claim', withAvailableContext(claimMethod))
+
     // Relationship methods
     addResourceMethod('getRelationship', withAvailableContext(getRelationshipMethod))
     addResourceMethod('getRelated', withAvailableContext(getRelatedMethod))

package/plugins/core/rest-api-positioning-plugin.js

@@ -3,7 +3,7 @@ import { calculatePosition, getInitialPosition, isValidPosition } from './lib/fr
 import { createStorageAdapter } from './lib/storage/storage-adapter.js'
 import { hasKnexTableIndex } from './lib/dbIntrospection.js'
 import { applyDatabaseReadOptions, databaseIdentityExpression } from './lib/querying-writing/database-value-normalizers.js'
-import { RestApiValidationError } from '../../lib/rest-api-errors.js'
+import { RestApiBulkWriteUnsupportedError, RestApiValidationError } from '../../lib/rest-api-errors.js'
 import { errorMessage, getOperationDiagnosticContext, isRestApiError } from '../../lib/error-context.js'
 import { createEnhancedLogger } from '../../lib/enhanced-logger.js'
 
@@ -104,7 +104,7 @@ export const PositioningPlugin = {
       }
     })
 
-    addHook('beforeProcessing', 'lock-position-resource', {}, async ({ context, scopeName }) => {
+    addHook('beforeProcessing', 'lock-position-resource', { batch: true }, async ({ context, scopeName }) => {
       if (!enabled(scopeName)) return
       const adapter = adapterFor(scopeName)
       const descriptor = context.schemaInfo.descriptor
@@ -124,7 +124,7 @@ export const PositioningPlugin = {
       }
     })
 
-    addHook('beforeSchemaValidate', 'process-beforeid', {}, ({ context, scopeName }) => {
+    addHook('beforeSchemaValidate', 'process-beforeid', { batch: true }, ({ context, scopeName }) => {
       if (!enabled(scopeName)) return
       const attributes = context.inputRecord.data.attributes || {}
       context.positioningBeforeId = attributes[config.beforeIdField]
@@ -207,8 +207,26 @@ export const PositioningPlugin = {
     }
 
     for (const method of ['Post', 'Put', 'Patch']) {
-      addHook(`beforeDataCall${method}`, `calculate-position-${method.toLowerCase()}`, {}, calculateAndSetPosition)
+      addHook(`beforeDataCall${method}`, `calculate-position-${method.toLowerCase()}`, { batch: true }, calculateAndSetPosition)
     }
+
+    // Positions are computed per row against their neighbours: many-row writes
+    // create no positioned rows and change no positions.
+    const refusePositions = ({ context, scopeName }) => {
+      if (!enabled(scopeName)) return
+      const moves = [config.field, config.beforeIdField].some(field => context.rawFields?.includes(field)) || context.inputRecords.some(record => {
+        const attributes = record?.data?.attributes || {}
+        return attributes[config.field] !== undefined || attributes[config.beforeIdField] !== undefined
+      })
+      if (context.method !== 'postMany' && !moves) return
+      throw new RestApiBulkWriteUnsupportedError({
+        resourceType: scopeName,
+        operation: context.method,
+        reason: 'it is positioned; create and move positioned rows with single writes'
+      })
+    }
+    addHook('beforeProcessingPostMany', 'refuse-positions-post-many', {}, refusePositions)
+    addHook('beforeProcessingPatchMany', 'refuse-positions-patch-many', {}, refusePositions)
     addHook('beforeDataQuery', 'apply-position-sort', {}, ({ context, scopeName }) => {
       if (enabled(scopeName) && !context.queryParams.sort?.length) context.queryParams.sort = [config.field]
     })

package/plugins/core/rest-api-query-projections-plugin.js

@@ -42,6 +42,14 @@ export const QueryProjectionsPlugin = {
       context.queryFields = fields && typeof fields === 'object' && !Array.isArray(fields) ? { ...fields } : fields
     })
 
-    addHook('beforeSchemaValidate', 'strip-query-field-input', {}, stripQueryFieldInput)
+    addHook('beforeSchemaValidate', 'strip-query-field-input', { batch: true }, stripQueryFieldInput)
+    // Batch form: strip query fields from every row of a many-row write.
+    const stripEveryRow = async ({ context, scopeName, scopes }) => {
+      for (const inputRecord of context.inputRecords) {
+        await stripQueryFieldInput({ context: { method: context.method, inputRecord }, scopeName, scopes })
+      }
+    }
+    addHook('beforeProcessingPostMany', 'strip-query-field-input-post-many', {}, stripEveryRow)
+    addHook('beforeProcessingPatchMany', 'strip-query-field-input-patch-many', {}, stripEveryRow)
   }
 }

package/plugins/core/rest-api-row-policy-plugin.js

@@ -1,4 +1,5 @@
 import { createStorageAdapterUtilities } from './lib/querying/storage-adapter-utils.js'
+import { assertGenuineSystemFlag, isSystemContext } from '../../lib/system-context.js'
 
 const INLINE_POLICY_NAME = '<inline>'
 
@@ -92,6 +93,7 @@ export const RowPolicyPlugin = {
 
       const compiledPolicy = scopes[scopeName]?.vars?.rowPolicy
       if (!compiledPolicy) return
+      assertGenuineSystemFlag(context)
 
       const adapterUtils = createStorageAdapterUtilities(hookParams, {
         getStorageAdapter: helpers.getStorageAdapter
@@ -117,6 +119,8 @@ export const RowPolicyPlugin = {
         scopeName,
         tableName,
         queryPurpose,
+        // True only for a context from createSystemContext; policies decide what it may see.
+        system: isSystemContext(context),
         db,
         isAnyApi,
         storageAdapter,

package/plugins/core/socketio-plugin.js

@@ -5,6 +5,8 @@ import { errorMessage, getOperationDiagnosticContext } from '../../lib/error-con
 import { queryConstraint } from './lib/querying/query-constraint.js'
 
 const pendingRoomChanges = new WeakMap()
+// Ids a many-row write matches against one subscription per query.
+const MANY_ROW_MATCH_CHUNK = 1000
 
 // Preserve room mutation order when an adapter completes joins/leaves asynchronously.
 async function changeRoom (socket, method, room) {
@@ -567,7 +569,7 @@ export const SocketIOPlugin = {
       return io
     }
 
-    addHook('beforeDataCall', 'socketio-capture-before', {}, async ({ context }) => {
+    addHook('beforeDataCall', 'socketio-capture-before', { batch: true }, async ({ context }) => {
       pendingChanges.delete(context)
       if (!io || !['post', 'put', 'patch', 'delete', 'postRelationship', 'deleteRelationship'].includes(context.method)) return
       const { scopeName, id, transaction } = context
@@ -584,7 +586,7 @@ export const SocketIOPlugin = {
       pendingChanges.set(context, candidates)
     })
 
-    addHook('finish', 'socketio-broadcast', {}, async ({ context }) => {
+    addHook('finish', 'socketio-broadcast', { batch: true }, async ({ context }) => {
       const candidates = pendingChanges.get(context)
       if (!candidates) return
       pendingChanges.delete(context)
@@ -607,6 +609,82 @@ export const SocketIOPlugin = {
       }
     })
 
+    // Batch form: one subscription query per subscription and chunk of ids, before
+    // and after the write, then one notification per changed record after commit.
+    const subscriptionsOf = async scopeName => {
+      const subscriptions = []
+      for (const socket of await io.in(`${scopeName}:updates`).fetchSockets()) {
+        for (const subscription of socket.data.subscriptions || []) {
+          if (subscription.resource === scopeName) subscriptions.push({ socketId: socket.id, subscription })
+        }
+      }
+      return subscriptions
+    }
+    const matchingIds = async ({ subscription, scopeName, ids, transaction }) => {
+      const matched = new Set()
+      for (let offset = 0; offset < ids.length; offset += MANY_ROW_MATCH_CHUNK) {
+        const part = ids.slice(offset, offset + MANY_ROW_MATCH_CHUNK)
+        try {
+          const result = await api.resources[scopeName].query({
+            format: 'jsonapi',
+            transaction,
+            pageSizeLimit: part.length,
+            queryParams: { filters: subscription.filters, include: [], page: { size: part.length } },
+            [queryConstraint]: { scopeName, idsQuery: part }
+          }, { ...subscription.context, auth: subscription.auth })
+          for (const record of result.data) matched.add(String(record.id))
+        } catch (error) {
+          try {
+            await createEnhancedLogger(log, { schemaInfo: scopes[scopeName]?.vars?.schemaInfo }).warn('Socket.IO subscription query failed', {
+              ...getOperationDiagnosticContext({ transaction }, { phase: 'subscriptionMatch', method: 'query', scopeName, backend: api.knex?.instance?.client?.config?.client }),
+              subscriptionId: subscription.id,
+              error
+            })
+          } catch { /* Warning failure must preserve the existing non-match result. */ }
+        }
+      }
+      return matched
+    }
+    const captureBeforeMany = async ({ context }) => {
+      pendingChanges.delete(context)
+      if (!io) return
+      const candidates = []
+      for (const { socketId, subscription } of await subscriptionsOf(context.scopeName)) {
+        const before = context.method === 'postMany'
+          ? new Set()
+          : await matchingIds({ subscription, scopeName: context.scopeName, ids: context.ids, transaction: context.transaction })
+        candidates.push({ socketId, subscription, before })
+      }
+      pendingChanges.set(context, candidates)
+    }
+    const broadcastMany = async ({ context }) => {
+      const candidates = pendingChanges.get(context)
+      if (!candidates) return
+      pendingChanges.delete(context)
+      const ids = (context.ids || []).filter(id => id !== undefined)
+      if (!io || !ids.length) return
+      const { scopeName, transaction } = context
+      const method = { postMany: 'post', deleteMany: 'delete', deleteWhere: 'delete' }[context.method] || 'patch'
+      const recipientsById = new Map(ids.map(id => [id, []]))
+      for (const { socketId, subscription, before } of candidates) {
+        const after = method === 'delete' ? new Set() : await matchingIds({ subscription, scopeName, ids, transaction })
+        for (const id of ids) {
+          if (before.has(id) || after.has(id)) recipientsById.get(id).push({ socketId, subscriptionId: subscription.id, generation: subscription.generation })
+        }
+      }
+      const changes = [...recipientsById].filter(([, recipients]) => recipients.length)
+        .map(([id, recipients]) => ({ method, scopeName, id, isCreate: method === 'post', recipients }))
+      if (!changes.length) return
+      if (!pendingBroadcasts.has(transaction)) pendingBroadcasts.set(transaction, [])
+      pendingBroadcasts.get(transaction).push(...changes)
+    }
+    addHook('beforeDataCallPostMany', 'socketio-capture-before-post-many', {}, captureBeforeMany)
+    addHook('beforeDataCallPatchMany', 'socketio-capture-before-patch-many', {}, captureBeforeMany)
+    addHook('beforeDataCallDeleteMany', 'socketio-capture-before-delete-many', {}, captureBeforeMany)
+    addHook('afterDataCallPostMany', 'socketio-broadcast-post-many', {}, broadcastMany)
+    addHook('afterDataCallPatchMany', 'socketio-broadcast-patch-many', {}, broadcastMany)
+    addHook('afterDataCallDeleteMany', 'socketio-broadcast-delete-many', {}, broadcastMany)
+
     addHook('afterCommit', 'socketio-broadcast-deferred', {}, async ({ context }) => {
       if (!context?.transaction) return
       const broadcasts = pendingBroadcasts.get(context.transaction)

package/types/autofilter.d.ts

@@ -22,6 +22,8 @@ export interface CompiledAutoFilter<Context extends object = Record<string, unkn
   resolve: AutoFilterResolver<Context, Api>
   resolverName: string
   required: boolean
+  // NULL marks a row every owner reads; writes, locks and claims see only the owner's rows.
+  shared: boolean
   relationshipName: string | null
   relationshipType: string | null
   inputPath: string
@@ -30,6 +32,8 @@ export interface CompiledAutoFilter<Context extends object = Record<string, unkn
 export type AutoFilterDefinition<Context extends object = Record<string, unknown>, Api extends object = object> = {
   field: string
   required?: boolean
+  // The field must be nullable: NULL rows are shared reference rows.
+  shared?: boolean
 } & (
   { resolve: string | AutoFilterResolver<Context, Api>; resolver?: string | AutoFilterResolver<Context, Api> }
   | { resolve?: undefined | null; resolver: string | AutoFilterResolver<Context, Api> }
@@ -52,6 +56,6 @@ export interface AutoFilterRegistry {
   getConfig(): { presets: string[]; resolvers: string[] }
   getScopeConfig(scopeName: string): {
     preset: string | null
-    filters: Array<{ field: string; resolver: string; required: boolean }>
+    filters: Array<{ field: string; resolver: string; required: boolean; shared: boolean }>
   } | null
 }

package/types/data-access-methods.d.ts

@@ -0,0 +1,141 @@
+import type { Knex } from 'knex'
+import type { ManagedTransaction } from './transactions.js'
+import type { DirectResourceId, InputResourceId, JsonApiResource, PlainResource, ResourceFormat, ResourceIdentifier } from './representations.js'
+import type { JsonApiWriteDocument, QueryParams, RemovedResourceOptions, SelectionParams } from './resource-methods.js'
+
+// Many-row writes return nothing by default; 'minimal' returns identifiers, 'full' the records,
+// 'count' the number of rows written.
+export type ManyRowReturning = 'none' | 'minimal' | 'full' | 'count'
+export type ManyRowCount = { meta: { count: number } }
+export type ManyRowResult<Format extends ResourceFormat, Returning extends ManyRowReturning, Fields extends object, Type extends string> =
+  Returning extends 'none' ? void
+    : Returning extends 'count' ? ManyRowCount
+    : { data: Array<Returning extends 'minimal' ? ResourceIdentifier<Type> : Format extends 'plain' ? PlainResource<Fields> : JsonApiResource<Fields, Type>> }
+type DeleteResult<Returning extends 'none' | 'minimal' | 'count', Type extends string> =
+  Returning extends 'none' ? void : Returning extends 'count' ? ManyRowCount : { data: ResourceIdentifier<Type>[] }
+export type RecordsResult<Format extends ResourceFormat, Fields extends object, Type extends string> =
+  { data: Array<Format extends 'plain' ? PlainResource<Fields> : JsonApiResource<Fields, Type>>; included?: JsonApiResource[] }
+// knex.raw values: accepted by many-row patches for stored, non-relationship fields.
+export type RawValue = Knex.Raw
+// Ids outside the caller's scope (or missing) throw RestApiRecordsNotFoundError, or are skipped.
+export type MissingRows = 'throw' | 'skip'
+
+export interface ManyRowWriteOptions<Format extends ResourceFormat, Returning extends ManyRowReturning> extends RemovedResourceOptions {
+  transaction?: ManagedTransaction
+  format?: Format
+  returning?: Returning
+  // Rows per statement (default 500), lowered further to the dialect's parameter limit.
+  chunkSize?: number
+  queryParams?: SelectionParams
+}
+export type ManyRowCreateInput<Input extends object, Type extends string> =
+  { data: Array<Partial<Input> & { id?: InputResourceId }>; document?: never } |
+  { data?: never; document: { data: Array<JsonApiWriteDocument<Input, Type>['data']> } }
+export interface UpsertOptions<Input extends object> {
+  // Must include every ownership (autofilter) field. Rows may not carry an id or repeat a key.
+  // ['id'] (or the idProperty) alone is allowed on a resource without ownership fields or a
+  // row policy; every row then carries its id.
+  keys: Array<keyof Input & string> | ['id']
+  // merge also runs the patch permission checks on every row it updates.
+  action: 'ignore' | 'merge'
+  // merge only: fields to update; default every stored field the rows supply but the keys.
+  merge?: Array<keyof Input & string>
+}
+// patchWhere and deleteWhere need filters, or all: true to act on every visible row.
+export type WhereScope = { filters: Record<string, unknown>; all?: never } | { filters?: never; all: true }
+type Patchable<Input extends object> = { [Field in keyof Input]?: Input[Field] | RawValue }
+export type ManyRowPatchInput<Input extends object, Type extends string> =
+  { data: Array<Patchable<Input> & { id: DirectResourceId }>; document?: never } |
+  { data?: never; document: { data: Array<JsonApiWriteDocument<Input, Type>['data'] & { id: DirectResourceId }> } }
+export type SharedPatchInput<Input extends object, Type extends string> =
+  { data: Patchable<Input> & { id?: never }; document?: never } |
+  { data?: never; document: { data: Omit<JsonApiWriteDocument<Input, Type>['data'], 'id'> } }
+export interface PatchConditionOptions<Input extends object> {
+  // Compare-and-set: only rows whose stored values equal these are changed; the result lists them.
+  onlyIf?: { [Field in keyof Input]?: Input[Field] | null }
+  missing?: MissingRows
+}
+
+export interface ScopedQueryParams {
+  transaction?: Knex.Transaction
+  // Table alias for column references; default the table name.
+  alias?: string
+  // report (default) sees shared rows; bulk-write, lock and claim see only the owner's.
+  purpose?: 'report' | 'bulk-write' | 'lock' | 'claim'
+  filters?: Record<string, unknown>
+}
+// A Knex builder over a derived table of the scoped rows. It refuses writes, locks,
+// table changes, set operations, common table expressions and access to the client.
+export type ReadOnlyQueryBuilder = Knex.QueryBuilder
+
+export interface DataAccessMethods<
+  Fields extends object = Record<string, unknown>,
+  Input extends object = Fields,
+  Type extends string = string,
+  DefaultFormat extends ResourceFormat = 'plain',
+  Context extends object = object
+> {
+  // Resolves to { query }: a builder is thenable, so it cannot be the promise's value.
+  scopedQuery(params?: ScopedQueryParams, context?: Context): Promise<{ query: ReadOnlyQueryBuilder }>
+  queryAll<Format extends ResourceFormat = DefaultFormat>(params?: {
+    transaction?: Knex.Transaction
+    format?: Format
+    queryParams?: Omit<QueryParams, 'page'>
+    // Rows per page (default 1000).
+    pageSize?: number
+    // Throws RestApiRowLimitError past this many rows.
+    rowLimit?: number
+  }, context?: Context): Promise<RecordsResult<Format, Fields, Type>>
+  postMany<Format extends ResourceFormat = DefaultFormat, Returning extends ManyRowReturning = 'none'>(
+    params: ManyRowWriteOptions<Format, Returning> & ManyRowCreateInput<Input, Type> & { onConflict?: UpsertOptions<Input> },
+    context?: Context
+  ): Promise<ManyRowResult<Format, Returning, Fields, Type>>
+  patchMany<Format extends ResourceFormat = DefaultFormat, Returning extends ManyRowReturning = 'none'>(
+    params: ManyRowWriteOptions<Format, Returning> & ManyRowPatchInput<Input, Type> & PatchConditionOptions<Input>,
+    context?: Context
+  ): Promise<ManyRowResult<Format, Returning, Fields, Type>>
+  patchWhereIds<Format extends ResourceFormat = DefaultFormat, Returning extends ManyRowReturning = 'none'>(
+    params: ManyRowWriteOptions<Format, Returning> & SharedPatchInput<Input, Type> & PatchConditionOptions<Input> & { ids: DirectResourceId[] },
+    context?: Context
+  ): Promise<ManyRowResult<Format, Returning, Fields, Type>>
+  patchWhere<Format extends ResourceFormat = DefaultFormat, Returning extends ManyRowReturning = 'none'>(
+    params: ManyRowWriteOptions<Format, Returning> & SharedPatchInput<Input, Type> & Omit<PatchConditionOptions<Input>, 'missing'> & WhereScope,
+    context?: Context
+  ): Promise<ManyRowResult<Format, Returning, Fields, Type>>
+  deleteMany<Returning extends 'none' | 'minimal' | 'count' = 'none'>(
+    params: RemovedResourceOptions & { ids: DirectResourceId[]; transaction?: ManagedTransaction; returning?: Returning; chunkSize?: number; missing?: MissingRows },
+    context?: Context
+  ): Promise<DeleteResult<Returning, Type>>
+  // Deletes the rows its selection finds and answers with those it deleted; it never throws for missing rows.
+  deleteWhere<Returning extends 'none' | 'minimal' | 'count' = 'none'>(
+    params: RemovedResourceOptions & WhereScope & { transaction?: ManagedTransaction; returning?: Returning; chunkSize?: number },
+    context?: Context
+  ): Promise<DeleteResult<Returning, Type>>
+  // Locks the visible rows among ids (FOR UPDATE, id order) until the transaction ends.
+  lockByIds<Format extends ResourceFormat = DefaultFormat>(params: {
+    ids: DirectResourceId[]
+    transaction: ManagedTransaction | Knex.Transaction
+    missing?: MissingRows
+    format?: Format
+    queryParams?: { fields?: Record<string, string> }
+  }, context?: Context): Promise<RecordsResult<Format, Fields, Type>>
+  // Locks the visible rows the filters select (FOR UPDATE; id order, on MySQL the
+  // order of the forced index, which starts with the ownership or a filtered column),
+  // waiting for other transactions; throws RestApiRowLimitError past 1000 rows.
+  lockWhere<Format extends ResourceFormat = DefaultFormat>(params: {
+    transaction: ManagedTransaction | Knex.Transaction
+    filters?: Record<string, unknown>
+    format?: Format
+    queryParams?: { fields?: Record<string, string> }
+  }, context?: Context): Promise<RecordsResult<Format, Fields, Type>>
+  // Takes up to limit (default 1, at most 1000) matching rows no other transaction holds.
+  claim<Format extends ResourceFormat = DefaultFormat>(params: {
+    transaction: ManagedTransaction | Knex.Transaction
+    filters?: Record<string, unknown>
+    // Stored fields, '-' for descending; default ['id'].
+    sort?: string[]
+    limit?: number
+    format?: Format
+    queryParams?: { fields?: Record<string, string> }
+  }, context?: Context): Promise<RecordsResult<Format, Fields, Type>>
+}