json-rest-api 2.3.0 → 2.4.0

package/docs/API.md

@@ -257,7 +257,8 @@ All parameters are passed within a single `params` object:
     page: Object         // Pagination parameters
   },
   format: String,          // 'plain' (default) or 'jsonapi'
-  transaction: Object    // Database transaction object
+  transaction: Object,   // Database transaction object
+  pageSizeLimit: Number  // Server code only: this call's largest page size
 }
 ```
 
@@ -275,6 +276,7 @@ All parameters are passed within a single `params` object:
 | `queryParams.page.before` | String | No | Cursor for backward pagination |
 | `format` | String | No | `'plain'` or `'jsonapi'`; uses the configured default when omitted |
 | `transaction` | Object | No | Database transaction object |
+| `pageSizeLimit` | Number | No | A positive integer replacing the resource's `queryMaxLimit` for this call, so server code reading every row can use larger pages. HTTP and Socket.IO never pass it, so their page sizes stay capped |
 
 #### Return Value
 

package/docs/GUIDE/09-pagination-and-sorting.md

@@ -68,6 +68,13 @@ Page 10 returns an empty array. `enablePaginationCounts: false` suppresses the
 count query and count-derived metadata; do not assume every collection response
 contains totals. Every mode respects `queryMaxLimit`.
 
+Server code that reads every row, for example an export or a nightly job, can
+raise the cap for one call with `pageSizeLimit`, a parameter beside
+`queryParams`: `query({ queryParams: { page: { size: 1000 } }, pageSizeLimit: 1000 })`
+reads up to 1,000 rows a page, so each page's row policy and linkage checks run
+once per 1,000 rows instead of once per `queryMaxLimit`. The transports never
+pass it, so HTTP and Socket.IO page sizes stay capped by `queryMaxLimit`.
+
 ## Cursor pages
 
 ```javascript

package/docs/GUIDE/13-hooks-and-lifecycle.md

@@ -284,7 +284,7 @@ context or enforce ownership through proxies.
 | `responseRecord` | Selected write output, available at write finish; absent for `returning: 'none'`. | Finish hooks can adjust the response before final normalization and commit. A returned write result is copied before completion hooks; mutating this field in `afterCommit` does not change that result. |
 | `method`, `scopeName`, `id`, `relationshipName`, `isUpdate` | Library-owned operation identity and branch selection. Availability varies by method and stage. | Inspect rather than overwrite. Changing them does not select a different operation or safely retarget a write. POST's ID is available after storage; normalize it with `String(context.id)` when comparing it to public IDs. |
 | `schemaInfo`, `params`, `queryParams`, `format`, `returning`, `simplified` | Library-owned compiled schema, request parameters and selected response behavior. | Set public options in method arguments. Do not overwrite these fields to redirect processing. Use schema declarations, row policies and documented query hooks for customization. |
-| `minimalRecord`, `originalMinimalRecord`, `originalInputAttributes`, `originalRecord` | Library-owned stored data and snapshots; availability depends on the stage. | Inspect them when available. Do not change snapshots to influence validation, permissions or persistence. |
+| `minimalRecord`, `originalMinimalRecord`, `originalInputAttributes`, `originalRecord` | Library-owned stored data and snapshots; availability depends on the stage. A get or query sets `originalRecord`, a copy of its records before enrichment, only when an `enrichRecord`, `enrichAttributes`, `finish`, `finishGet` or `finishQuery`, `enrichRecordWithRelationships` (get) or `transport:response` hook is registered for the resource or globally, or an `enrichAttributes` hook for an included resource: copying every row is a read's largest CPU cost. | Inspect them when available. Do not change snapshots to influence validation, permissions or persistence. |
 | `transaction`, `db`, `shouldCommit`, `transactionOutcome`, `transactionCommitted`, `error`, `cleanupErrors` | Library-owned transaction and failure state. | Inspect through the documented transaction/error contract. Pass transaction handles through method arguments; do not replace these fields, forge outcomes or erase diagnostics. |
 | `knexQuery`, `storageAdapter` | Temporary state at native query hook boundaries, also visible to nested query permission checks. | `knexQuery` is a filtering envelope; its `query` property holds the native builder. Use the [documented filtering contract](29-writing-plugins.md#knexqueryfiltering), and do not retain a builder for a later operation. |
 
@@ -375,7 +375,9 @@ is `Post`, `Put` or `Patch`, for example `beforeDataCallPatch`.
    method-specific hook.
 5. Acquire required relationship locks, apply setters and write to storage.
 6. Run the method-specific `afterDataCall`, then `afterDataCall`.
-7. Apply relationship changes and refresh the minimal stored record.
+7. Apply relationship changes and refresh the minimal stored record when a
+   `finish`, method-specific finish, `afterCommit`, `afterRollback` or
+   `transport:response` hook is registered to see it.
 8. Prepare the response; run `finish`, then its method-specific hook.
 9. Commit an owned transaction and await its `afterCommit` chain.
 
@@ -422,7 +424,14 @@ its eligibility queries also run the ordinary query lifecycle in the write's
 transaction with the subscriber's trusted context.
 
 Relationship writes acquire database locks after the `beforeDataCall` hooks.
-Belongs-to and polymorphic targets are rechecked while locking them. Collection
+Belongs-to, polymorphic and many-to-many targets are rechecked under a shared
+lock (`FOR SHARE`, or `LOCK IN SHARE MODE` on MySQL): writers that reference the
+same row do not wait for each other, while its deletion waits for them. A target
+the write also changes, such as a versioned parent whose revision it advances or
+a child moved by a reverse relationship, is locked `FOR UPDATE` instead. A hook
+that updates a referenced row upgrades the shared lock and can deadlock with a
+concurrent writer doing the same; lock that row `FOR UPDATE` in `beforeDataCall`
+first. Collection
 mutations also preserve a parent row version so concurrent replacements cannot
 use stale membership; a database UPDATE trigger may run even when the parent's
 attribute values did not change. These internal operations do not invoke another

package/docs/GUIDE/33-migrating-to-v2.md

@@ -734,8 +734,8 @@ Database UPDATE triggers on the parent may therefore run for relationship-only
 writes. Resource hooks still follow their existing operation lifecycle; these
 internal locks do not invoke a second resource PATCH hook.
 If you use per-table database grants, account for parent UPDATEs and target
-`SELECT ... FOR UPDATE` statements when configuring the application's database
-role.
+locking reads (`FOR UPDATE`, or `FOR SHARE` / `LOCK IN SHARE MODE` for
+existence checks) when configuring the application's database role.
 
 Treat native deadlock, lock-timeout and serialization errors as failed transaction
 attempts. Let `api.transaction` roll back, then retry the complete callback in a
@@ -958,7 +958,11 @@ POST, PUT and PATCH also reject an unexpected failure while refreshing
 and ignored, allowing a successful response and completion hooks with stale
 state. The cause chain retains the failure and resource context with phase
 `postWriteRead`; typed errors retain their identity within that chain. This refresh runs for
-`returning: 'full'`, `'minimal'` and `'none'`. It happens before finish hooks and
+`returning: 'full'`, `'minimal'` and `'none'` whenever a hook can see it: a `finish`,
+method-specific finish, `afterCommit`, `afterRollback` or `transport:response` hook
+registered for the resource or globally. Without one, nothing reads the refreshed
+record, so the write skips that query and its row policy run; a `'full'` response is
+read by its own get either way. It happens before finish hooks and
 owned commit, so a failure rolls back owned changes, including relationship
 updates. Borrowed transactions remain active for the caller to complete.
 

package/lib/runtime/json-rest-api.js

@@ -19,6 +19,11 @@ export class Hooks {
     this.#events.set(event, handlers)
   }
 
+  // Whether run(event) for this resource would call any handler.
+  has (event, resource) {
+    return (this.#events.get(event) || []).some(entry => !entry.resource || entry.resource === resource)
+  }
+
   async run (event, args) {
     for (const entry of [...(this.#events.get(event) || [])]) {
       if (entry.resource && entry.resource !== args.scope) continue
@@ -81,7 +86,8 @@ export class JsonRestApi {
       vars: resource?.vars || this.vars,
       helpers: resource?.helpers || this.helpers,
       log: this.log,
-      runHooks: (event, nextContext = context) => this.#hooks.run(event, this.#arguments(resource, {}, nextContext))
+      runHooks: (event, nextContext = context) => this.#hooks.run(event, this.#arguments(resource, {}, nextContext)),
+      hasHooks: (event, scope = resource) => this.#hooks.has(event, scope)
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "json-rest-api",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "main": "index.js",
   "types": "index.d.ts",
   "type": "module",

package/plugins/core/lib/anyapi/canonical-link-store.js

@@ -247,7 +247,9 @@ export function createCanonicalLinkStore ({ api, getDescriptor, getScopeStorageA
     if (relArray.length === 0) return
     assertVersionedRelationshipTransaction(api, relInfo, db)
 
-    await lockRelationshipTargets(api, db, relArray.map(identifier => ({ type: relInfo.target, id: identifier.id })))
+    await lockRelationshipTargets(api, db, relArray.map(identifier => ({ type: relInfo.target, id: identifier.id })), {
+      exclusive: hasVersionedInverse(api, relInfo)
+    })
 
     const ids = [...new Set(relArray.map(identifier => normalizeId(identifier.id)).filter(id => id !== null))]
     const readLinks = batchIds => buildLinkMutationQuery(options, (query, column) => query.whereIn(column, batchIds))
@@ -442,7 +444,7 @@ export function createCanonicalLinkStore ({ api, getDescriptor, getScopeStorageA
     }
     if (!relationships.length) return
     assertVersionedRelationshipTransaction(api, relationships[0].inverse, context.transaction)
-    await lockRelationshipTargets(api, context.transaction, [{ type: scopeName, id: context.id }])
+    await lockRelationshipTargets(api, context.transaction, [{ type: scopeName, id: context.id }], { exclusive: true })
     const id = normalizeId(context.id)
     for (const { inverse, info } of relationships) {
       const query = buildLinkMutationQuery({ ...info, db: context.transaction, allParents: true }, (query, column) => query.where(column, id))

package/plugins/core/lib/querying/include-query-helpers.js

@@ -188,6 +188,10 @@ export const applyScopeFiltersToIncludeQuery = async ({
   }
 }
 
+// Linked ids checked per visibility query: a 1,000-row page costs one query and
+// one row-policy run per linked type, and any number of ids stays bounded SQL.
+const VISIBILITY_BATCH_SIZE = 1000
+
 export const filterVisibleIdentifiers = async ({ identifiers, scopes, knex, context }) => {
   const idsByType = new Map()
   for (const { type, id } of identifiers) {
@@ -204,9 +208,11 @@ export const filterVisibleIdentifiers = async ({ identifiers, scopes, knex, cont
     const column = `${tableName}.${idColumn}`
     const visibleIds = new Set()
     visible.set(type, visibleIds)
-    const loadBatch = async values => {
+    const values = [...ids].map(id => adapter.translateFilterValue('id', id))
+    for (let start = 0; start < values.length; start += VISIBILITY_BATCH_SIZE) {
+      // whereInIdentifiers binds a long id list as one parameter where the database allows it.
       const query = adapter.buildBaseQuery({ transaction: context.transaction })
-        .whereIn(column, values)
+        .modify(whereInIdentifiers, column, values.slice(start, start + VISIBILITY_BATCH_SIZE))
         .distinct({ [idColumn]: adapter.isCanonical() ? column : databaseIdentityExpression(knex, column) })
       const state = await applyScopeFiltersToIncludeQuery({
         query,
@@ -219,15 +225,6 @@ export const filterVisibleIdentifiers = async ({ identifiers, scopes, knex, cont
       })
       for (const row of await state.query) visibleIds.add(String(row[idColumn]))
     }
-    let values = []
-    for (const id of ids) {
-      values.push(adapter.translateFilterValue('id', id))
-      if (values.length === RELATIONSHIP_READ_BATCH_SIZE) {
-        await loadBatch(values)
-        values = []
-      }
-    }
-    if (values.length) await loadBatch(values)
   }
   return identifiers.filter(({ type, id }) => visible.get(type)?.has(String(id)))
 }

package/plugins/core/lib/querying/knex-pagination-helpers.js

@@ -7,8 +7,9 @@ import { RestApiValidationError } from '../../../../lib/rest-api-errors.js'
 
 // Page parameters have passed the shared request contract. Physical sort
 // columns and built-in value conversion remain with descriptors and adapters.
-export const applyPaginationToQuery = ({ query, page = {}, vars, sortDescriptors, storageAdapter }) => {
-  const pageSize = Math.min(page.size ?? (vars.queryDefaultLimit || DEFAULT_QUERY_LIMIT), vars.queryMaxLimit || DEFAULT_MAX_QUERY_LIMIT)
+// pageSizeLimit, a server caller's query param, replaces queryMaxLimit for that call.
+export const applyPaginationToQuery = ({ query, page = {}, vars, pageSizeLimit, sortDescriptors, storageAdapter }) => {
+  const pageSize = Math.min(page.size ?? (vars.queryDefaultLimit || DEFAULT_QUERY_LIMIT), pageSizeLimit || vars.queryMaxLimit || DEFAULT_MAX_QUERY_LIMIT)
   if (!Number.isInteger(pageSize) || pageSize <= 0) {
     throw new RestApiValidationError('Page size must be a positive integer', {
       fields: ['page.size'],

package/plugins/core/lib/storage/canonical-data-helpers.js

@@ -503,6 +503,7 @@ export function createCanonicalDataHelpers ({
       query: queryBuilder,
       page: queryParams.page,
       vars: scope.vars,
+      pageSizeLimit: context.pageSizeLimit,
       sortDescriptors,
       storageAdapter,
     })

package/plugins/core/lib/storage/ordinary-data-helpers.js

@@ -385,6 +385,7 @@ export function createOrdinaryDataHelpers ({ api, scopes, knex, log, getScopeSto
       query,
       page: queryParams.page,
       vars: scope.vars,
+      pageSizeLimit: context.pageSizeLimit,
       sortDescriptors,
       storageAdapter
     })

package/plugins/core/lib/storage/storage-types.d.ts

@@ -265,6 +265,8 @@ export interface DataReadContext extends TransactionContext, StorageContext {
     sort?: string[]
     page?: { size?: number; number?: number; before?: string; after?: string }
   }
+  // Replaces the resource's queryMaxLimit for this query (a server caller's query param).
+  pageSizeLimit?: number
   knexQuery?: QueryFilteringState | null
   computedDependencies?: string[]
   returnMeta?: {

package/plugins/core/lib/writing/many-to-many-manipulations.js

@@ -17,7 +17,7 @@ export async function invalidateDeletedPivotTargets (api, scopeName, context) {
   }
   if (!relationships.length) return
   assertVersionedRelationshipTransaction(api, relationships[0], context.transaction)
-  await lockRelationshipTargets(api, context.transaction, [{ type: scopeName, id: context.id }])
+  await lockRelationshipTargets(api, context.transaction, [{ type: scopeName, id: context.id }], { exclusive: true })
   const id = api.knex.helpers.getStorageAdapter(scopeName).translateFilterValue('id', context.id)
   for (const inverse of relationships) {
     const pivot = getPivotStorage(api, inverse)
@@ -110,7 +110,7 @@ export const updateManyToManyRelationship = async (scope, { api, context }) => {
   assertVersionedRelationshipTransaction(api, relDef, trx)
   const relData = normalizeRelationshipIdentifiers(context.relData || [], { api })
   const pivot = getPivotStorage(api, relDef)
-  const targets = await lockRelationshipTargets(api, trx, relData)
+  const targets = await lockRelationshipTargets(api, trx, relData, { exclusive: hasVersionedInverse(api, relDef) })
   const ids = [...new Set(targets.map(record => String(record.id)))]
   // Negate the complete keep-list once; independent batch deletions lose wanted links.
   const removals = trx(pivot.tableName).where(pivot.foreignKey, resourceId)
@@ -127,7 +127,7 @@ export const createPivotRecords = async (api, resourceId, relDef, relData, trx)
   if (relData.length === 0) return
   assertVersionedRelationshipTransaction(api, relDef, trx)
   const pivot = getPivotStorage(api, relDef)
-  const targets = await lockRelationshipTargets(api, trx, relData)
+  const targets = await lockRelationshipTargets(api, trx, relData, { exclusive: hasVersionedInverse(api, relDef) })
   await insertMissingPivotRecords(trx, pivot, resourceId, targets.map(record => record.id))
   await invalidateManyToManyVersions(api, relDef, targets.map(record => record.id), trx)
 }

package/plugins/core/lib/writing/relationship-processor.js

@@ -17,8 +17,25 @@ export const lockRelationshipParent = async ({ context, helpers, scopeName }) =>
   }
 }
 
-export const lockRelationshipTargets = async (api, transaction, identifiers) => {
+// Not PostgreSQL's FOR KEY SHARE: it would not conflict with lockRelationshipParent's
+// UPDATE, so writes from opposite ends of one many-to-many edge could both insert it.
+const lockTargetRows = (query, exclusive) => exclusive ? query.forUpdate() : query.forShare()
+
+/**
+ * Lock referenced rows and fail when one no longer exists.
+ * Targets are share-locked so writers referencing one row do not queue behind
+ * each other. A caller that later modifies a target must lock it exclusively:
+ * upgrading a shared lock deadlocks against a concurrent writer doing the same.
+ *
+ * @param {any} api
+ * @param {any} transaction
+ * @param {Array<{ type: string, id: string }>} identifiers
+ * @param {{ exclusive?: boolean | Set<string> }} [options] - Lock every target, or targets of these types, for update
+ * @returns {Promise<Array<{ type: string, id: string }>>} Each database identity once, in its first submitted spelling
+ */
+export const lockRelationshipTargets = async (api, transaction, identifiers, { exclusive = false } = {}) => {
   if (!transaction) return identifiers
+  const isExclusive = type => exclusive instanceof Set ? exclusive.has(type) : exclusive
   const targets = []
   const resolved = []
   const resources = new Map()
@@ -41,17 +58,17 @@ export const lockRelationshipTargets = async (api, transaction, identifiers) =>
     for (const [type, group] of byType) {
       const { adapter } = group[0]
       const idColumn = adapter.getIdColumn()
-      const rows = await applyDatabaseReadOptions(adapter.buildBaseQuery({ transaction })
+      const rows = await applyDatabaseReadOptions(lockTargetRows(adapter.buildBaseQuery({ transaction })
         .whereIn(idColumn, group.map(target => target.value))
-        .orderBy(`${adapter.getTableName()}.${idColumn}`).forUpdate().select({ [idColumn]: databaseIdentityExpression(transaction, idColumn) }))
+        .orderBy(`${adapter.getTableName()}.${idColumn}`), isExclusive(type)).select({ [idColumn]: databaseIdentityExpression(transaction, idColumn) }))
       found.set(type, new Set(rows.map(row => String(row[idColumn]))))
     }
     for (const { type, id, value, adapter } of batch) {
       let storedId = String(value)
       // Let the database resolve alternate spellings under its column collation.
       if (!found.get(type).has(storedId)) {
-        const record = await applyDatabaseReadOptions(adapter.buildBaseQuery({ transaction })
-          .where(adapter.getIdColumn(), value).forUpdate().first({ [adapter.getIdColumn()]: databaseIdentityExpression(transaction, adapter.getIdColumn()) }))
+        const record = await applyDatabaseReadOptions(lockTargetRows(adapter.buildBaseQuery({ transaction })
+          .where(adapter.getIdColumn(), value), isExclusive(type)).first({ [adapter.getIdColumn()]: databaseIdentityExpression(transaction, adapter.getIdColumn()) }))
         if (!record) {
           throw new RestApiResourceError(`Related ${type} with id ${id} not found`, {
             subtype: 'not_found', resourceType: type, resourceId: id

package/plugins/core/lib/writing/resource-version.js

@@ -47,8 +47,7 @@ async function readInverseReferences (state, context) {
     .where(adapter.getIdColumn(), adapter.translateFilterValue('id', context.id)).forUpdate().first(selection))
 }
 
-// Capture actual stored references after authorization; hooks/setters may change the input.
-export async function captureInverseVersions ({ api, helpers, context, scopeName, isCreate = false }) {
+function inverseVersionReferences (api, scopeName, scopeSchemaInfo) {
   const references = []
   for (const [parentType, parent] of Object.entries(api.resources)) {
     const schemaInfo = parent.vars.schemaInfo
@@ -60,11 +59,25 @@ export async function captureInverseVersions ({ api, helpers, context, scopeName
       }
       if (!['hasMany', 'hasOne'].includes(relationship.type) || relationship.target !== scopeName) continue
       if (relationship.via) {
-        const inverse = context.schemaInfo.schemaRelationships[relationship.via]?.belongsToPolymorphic
+        const inverse = scopeSchemaInfo.schemaRelationships[relationship.via]?.belongsToPolymorphic
         if (inverse?.types.includes(parentType)) references.push({ parentType, idField: inverse.idField, typeField: inverse.typeField })
       } else if (relationship.foreignKey) references.push({ parentType, idField: relationship.foreignKey })
     }
   }
+  return references
+}
+
+/**
+ * Resource types whose revision a write to scopeName can advance.
+ * @returns {Set<string>}
+ */
+export function inverseVersionTypes (api, scopeName, scopeSchemaInfo) {
+  return new Set(inverseVersionReferences(api, scopeName, scopeSchemaInfo).map(reference => reference.parentType))
+}
+
+// Capture actual stored references after authorization; hooks/setters may change the input.
+export async function captureInverseVersions ({ api, helpers, context, scopeName, isCreate = false }) {
+  const references = inverseVersionReferences(api, scopeName, context.schemaInfo)
   if (!references.length) return undefined
   const fields = new Set()
   for (const { idField, typeField, valueField } of references) {

package/plugins/core/lib/writing/reverse-relationship-manipulations.js

@@ -44,7 +44,7 @@ export async function updateReverseRelationship ({ api, helpers, context, scopeN
   } else if (relData !== null) {
     identifiers = [relData]
   }
-  const targets = operation === 'remove' ? identifiers : await lockRelationshipTargets(api, context.transaction, identifiers)
+  const targets = operation === 'remove' ? identifiers : await lockRelationshipTargets(api, context.transaction, identifiers, { exclusive: true })
   const requested = new Map()
   for (const { id } of targets) {
     const value = adapter.translateFilterValue('id', id)

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

@@ -2,7 +2,7 @@
 /** @import {
  * CompletedWriteContext, Field, Identifier, IdentityContext, InputDocument, LifecycleApi,
  * LifecycleArguments, LifecycleContext, LifecycleHelpers, LifecycleResource, LifecycleSchema,
- * LifecycleVars, ProcessingContext, RelationshipContext, Resource, ResourceContext, RunHooks,
+ * LifecycleVars, ProcessingContext, ReadContext, RelationshipContext, Resource, ResourceContext, RunHooks,
  * Schema, WriteContext
  * } from './lifecycle-types.js' */
 /** @import { StorageRow } from '../lib/storage/storage-types.js' */
@@ -388,6 +388,8 @@ export const validateResourceAttributesBeforeWrite = async ({
 export const validateRelationshipAccess = async (context, inputRecord, helpers, api) => {
   if (!inputRecord?.data?.relationships) return
 
+  // Targets of every relationship, so each type is read once per record.
+  const unique = new Map()
   for (const [relName, relData] of Object.entries(inputRecord.data.relationships)) {
     if (!relData?.data) continue
 
@@ -402,62 +404,61 @@ export const validateRelationshipAccess = async (context, inputRecord, helpers,
       ? normalizedRelationshipData
       : [normalizedRelationshipData]
 
-    const unique = new Map()
     for (const item of relatedItems) unique.set(JSON.stringify([item.type, item.id]), item)
-    const targets = [...unique.values()]
-    for (let offset = 0; offset < targets.length; offset += RELATIONSHIP_READ_BATCH_SIZE) {
-      const batch = targets.slice(offset, offset + RELATIONSHIP_READ_BATCH_SIZE)
-      /** @type {Map<string, Identifier[]>} */
-      const byType = new Map()
-      for (const item of batch) {
-        const items = byType.get(item.type)
-        if (items) items.push(item)
-        else byType.set(item.type, [item])
+  }
+  const targets = [...unique.values()]
+  for (let offset = 0; offset < targets.length; offset += RELATIONSHIP_READ_BATCH_SIZE) {
+    const batch = targets.slice(offset, offset + RELATIONSHIP_READ_BATCH_SIZE)
+    /** @type {Map<string, Identifier[]>} */
+    const byType = new Map()
+    for (const item of batch) {
+      const items = byType.get(item.type)
+      if (items) items.push(item)
+      else byType.set(item.type, [item])
+    }
+    const lookups = new Map()
+    for (const [type, items] of byType) {
+      const relatedScope = api.resources[type]
+      if (!relatedScope) throw new Error(`Unknown resource type: ${type}`)
+      const getContext = {
+        ...context,
+        id: undefined,
+        minimalRecord: undefined,
+        schemaInfo: relatedScope.vars.schemaInfo,
+        scopeName: type,
+        queryParams: {},
+        method: 'get',
+        isUpdate: false
       }
-      const lookups = new Map()
-      for (const [type, items] of byType) {
-        const relatedScope = api.resources[type]
-        if (!relatedScope) throw new Error(`Unknown resource type: ${type}`)
-        const getContext = {
-          ...context,
-          id: undefined,
-          minimalRecord: undefined,
-          schemaInfo: relatedScope.vars.schemaInfo,
-          scopeName: type,
-          queryParams: {},
-          method: 'get',
-          isUpdate: false
-        }
-        const lookup = {
-          scopeName: type,
-          context: getContext,
-          /** @param {import('../lib/storage/storage-types.js').QueryFilteringState} filterParams */
-          applyQueryFilters: filterParams => relatedScope.applyQueryFilters({
-            ...filterParams, schemaInfo: getContext.schemaInfo
-          }, getContext),
-          filters: {},
-          queryPurpose: 'relationship-validation'
-        }
-        const records = await helpers.dataGetMinimal({ ...lookup, ids: items.map(item => item.id) })
-        lookups.set(type, { relatedScope, lookup, records: new Map(records.map(record => [String(record.id), record])) })
+      const lookup = {
+        scopeName: type,
+        context: getContext,
+        /** @param {import('../lib/storage/storage-types.js').QueryFilteringState} filterParams */
+        applyQueryFilters: filterParams => relatedScope.applyQueryFilters({
+          ...filterParams, schemaInfo: getContext.schemaInfo
+        }, getContext),
+        filters: {},
+        queryPurpose: 'relationship-validation'
       }
-      for (const item of batch) {
-        const { relatedScope, lookup, records } = lookups.get(item.type)
-        // A database collation can equate IDs with different spellings.
-        const record = records.get(String(item.id)) || await helpers.dataGetMinimal({
-          ...lookup, context: { ...lookup.context, id: item.id }
-        })
-        if (!record) {
-          throw new RestApiResourceError(
-            `Cannot create relationship to non-existent ${item.type} with id ${item.id}`,
-            { subtype: 'not_found', resourceType: item.type, resourceId: item.id }
-          )
-        }
-        await relatedScope.checkPermissions({
-          method: 'get',
-          originalContext: { ...lookup.context, id: item.id, minimalRecord: record }
-        })
+      const records = await helpers.dataGetMinimal({ ...lookup, ids: items.map(item => item.id) })
+      lookups.set(type, { relatedScope, lookup, records: new Map(records.map(record => [String(record.id), record])) })
+    }
+    for (const item of batch) {
+      const { relatedScope, lookup, records } = lookups.get(item.type)
+      // A database collation can equate IDs with different spellings.
+      const record = records.get(String(item.id)) || await helpers.dataGetMinimal({
+        ...lookup, context: { ...lookup.context, id: item.id }
+      })
+      if (!record) {
+        throw new RestApiResourceError(
+          `Cannot create relationship to non-existent ${item.type} with id ${item.id}`,
+          { subtype: 'not_found', resourceType: item.type, resourceId: item.id }
+        )
       }
+      await relatedScope.checkPermissions({
+        method: 'get',
+        originalContext: { ...lookup.context, id: item.id, minimalRecord: record }
+      })
     }
   }
 }
@@ -537,19 +538,23 @@ export const applyFieldSetters = async (context, api, helpers) => {
 /**
  * Refreshes post-write state and prepares POST/PATCH/PUT responses before commit.
  * Runs finish hooks once and normalizes their result; borrows the write transaction.
- * @param {Pick<LifecycleArguments, 'scopeName' | 'api' | 'scopes' | 'runHooks' | 'helpers'> & { context: CompletedWriteContext }} options
+ * The refreshed minimalRecord is read only when a later hook can see it.
+ * @param {Pick<LifecycleArguments, 'scopeName' | 'api' | 'scopes' | 'runHooks' | 'hasHooks' | 'helpers'> & { context: CompletedWriteContext }} options
  */
-export async function handleRecordReturnAfterWrite ({ context, scopeName, api, scopes, runHooks, helpers }) {
+export async function handleRecordReturnAfterWrite ({ context, scopeName, api, scopes, runHooks, hasHooks, helpers }) {
   const hookSuffix = getMethodHookSuffix(context.method)
   if (context.minimalRecord) context.originalMinimalRecord = context.minimalRecord
 
-  try {
-    context.minimalRecord = await helpers.dataGetMinimal({ scopeName, context, runHooks })
-  } catch (error) {
-    throw wrapUnexpectedError(error, {
-      message: `Failed to refresh record after ${context.method}`,
-      context: { scopeName, phase: 'postWriteRead' }
-    })
+  // A full response reads the record again through get; only hooks see the refresh.
+  if (['finish', `finish${hookSuffix}`, 'afterCommit', 'afterRollback', 'transport:response'].some(event => hasHooks(event))) {
+    try {
+      context.minimalRecord = await helpers.dataGetMinimal({ scopeName, context, runHooks })
+    } catch (error) {
+      throw wrapUnexpectedError(error, {
+        message: `Failed to refresh record after ${context.method}`,
+        context: { scopeName, phase: 'postWriteRead' }
+      })
+    }
   }
 
   const returnMode = context.returning
@@ -590,6 +595,33 @@ export async function handleRecordReturnAfterWrite ({ context, scopeName, api, s
   return structuredClone(context.responseRecord)
 }
 
+// The hooks that run after a read's snapshot is taken and can see it: the read's
+// own context, or the parentContext of an enrichAttributes wrapper.
+const READ_SNAPSHOT_EVENTS = {
+  get: ['enrichRecord', 'enrichAttributes', 'enrichRecordWithRelationships', 'finish', 'finishGet', 'transport:response'],
+  query: ['enrichRecord', 'enrichAttributes', 'finish', 'finishQuery', 'transport:response']
+}
+
+/**
+ * Copies a read's records, as stored, to context.originalRecord before
+ * enrichment. A deep copy of every row is the largest CPU cost of a read
+ * without hooks, so it is taken only when a hook that runs afterwards is
+ * registered for the resource or globally, or an enrichAttributes hook for an
+ * included resource.
+ * @param {ReadContext} context
+ * @param {Record<string, LifecycleResource>} scopes
+ * @param {LifecycleArguments['hasHooks']} hasHooks
+ * @param {'get' | 'query'} method
+ */
+export function snapshotReadRecord (context, scopes, hasHooks, method) {
+  if (!context.record) return
+  const includedScopes = new Set((context.record.included || []).map(entry => scopes[entry.type]))
+  if (READ_SNAPSHOT_EVENTS[method].some(event => hasHooks(event)) ||
+      [...includedScopes].some(scope => hasHooks('enrichAttributes', scope))) {
+    context.originalRecord = structuredClone(context.record)
+  }
+}
+
 /** @param {ResourceContext} context @param {Record<string, LifecycleResource>} scopes */
 export const filterToOneResponseLinkage = async (context, scopes) => {
   const document = context.record

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

@@ -11,7 +11,7 @@ import { getRequestedComputedFields, validateRequestedFieldsets } from '../lib/q
 import { transformJsonApiToSimplified } from '../lib/querying-writing/simplified-helpers.js'
 import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
 import { requireExistingResourceId } from '../lib/querying-writing/resource-id-normalization.js'
-import { validateRequestedIncludes, filterToOneResponseLinkage } from './common.js'
+import { validateRequestedIncludes, filterToOneResponseLinkage, snapshotReadRecord } from './common.js'
 
 /**
  * Read one resource using params.id and params.queryParams. Missing resources
@@ -26,6 +26,7 @@ export default async function getMethod ({
   scope,
   scopes,
   runHooks,
+  hasHooks,
   scopeOptions,
   scopeName,
   api
@@ -129,7 +130,7 @@ export default async function getMethod ({
   await runHooks('checkDataPermissions')
   await runHooks('checkDataPermissionsGet')
 
-  context.originalRecord = structuredClone(context.record)
+  snapshotReadRecord(context, scopes, hasHooks, 'get')
 
   await runHooks('enrichRecord')
 

package/plugins/core/rest-api-plugin-methods/lifecycle-types.d.ts

@@ -112,6 +112,8 @@ export interface LifecycleContext<Data = Resource | Resource[] | null, Input = I
   computedDependencies?: string[]
   returnMeta?: Record<string, unknown>
   sortableFields?: string[]
+  // A server caller's query page cap, replacing queryMaxLimit for that query.
+  pageSizeLimit?: number
   auth?: unknown
   [customProperty: string]: unknown
   knexQuery?: QueryFilteringState | null
@@ -166,6 +168,7 @@ export interface LifecycleArguments<Data = Resource | Resource[] | null> {
   scope: LifecycleResource
   scopes: Record<string, LifecycleResource>
   runHooks: RunHooks
+  hasHooks: (event: string, scope?: LifecycleResource) => boolean
   scopeOptions: RestApiPluginOptions
   scopeName: string
   api: LifecycleApi

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

@@ -2,7 +2,7 @@
 /** @import {
  * CompletedWriteContext, LifecycleArguments
  * } from './lifecycle-types.js' */
-import { applyResourceVersion, captureInverseVersions, invalidateInverseVersions } from '../lib/writing/resource-version.js'
+import { applyResourceVersion, captureInverseVersions, inverseVersionTypes, invalidateInverseVersions } from '../lib/writing/resource-version.js'
 import { RestApiResourceError } from '../../../lib/rest-api-errors.js'
 import { lockRelationshipParent, lockRelationshipTargets, processRelationships } from '../lib/writing/relationship-processor.js'
 import { updateReverseRelationship } from '../lib/writing/reverse-relationship-manipulations.js'
@@ -35,6 +35,7 @@ export default async function patchMethod ({
   scope,
   scopes,
   runHooks,
+  hasHooks,
   scopeOptions,
   scopeName,
   api,
@@ -108,7 +109,10 @@ export default async function patchMethod ({
     await runHooks('beforeDataCall')
     await runHooks('beforeDataCallPatch')
 
-    await lockRelationshipTargets(api, context.transaction, belongsToTargets)
+    // A parent whose revision this write advances is updated, not just referenced.
+    await lockRelationshipTargets(api, context.transaction, belongsToTargets, {
+      exclusive: inverseVersionTypes(api, scopeName, context.schemaInfo)
+    })
 
     if (manyToManyRelationships.length || reverseRelationships.length) {
       await lockRelationshipParent({ context, helpers, scopeName })
@@ -167,6 +171,7 @@ export default async function patchMethod ({
       api,
       scopes,
       runHooks,
+      hasHooks,
       helpers
     })
 

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

@@ -2,7 +2,7 @@
 /** @import {
  * CompletedWriteContext, LifecycleArguments, WriteContext
  * } from './lifecycle-types.js' */
-import { applyResourceVersion, captureInverseVersions, invalidateInverseVersions } from '../lib/writing/resource-version.js'
+import { applyResourceVersion, captureInverseVersions, inverseVersionTypes, invalidateInverseVersions } from '../lib/writing/resource-version.js'
 import { lockRelationshipTargets, processRelationships } from '../lib/writing/relationship-processor.js'
 import { updateReverseRelationship } from '../lib/writing/reverse-relationship-manipulations.js'
 import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
@@ -33,6 +33,7 @@ export default async function postMethod ({
   scope,
   scopes,
   runHooks,
+  hasHooks,
   scopeOptions,
   scopeName,
   api,
@@ -115,7 +116,10 @@ export default async function postMethod ({
     await runHooks('beforeDataCall')
     await runHooks('beforeDataCallPost')
 
-    await lockRelationshipTargets(api, context.transaction, belongsToTargets)
+    // A parent whose revision this write advances is updated, not just referenced.
+    await lockRelationshipTargets(api, context.transaction, belongsToTargets, {
+      exclusive: inverseVersionTypes(api, scopeName, context.schemaInfo)
+    })
 
     await applyFieldSetters(context, api, helpers)
     const inverseVersions = await captureInverseVersions({ api, helpers, context, scopeName, isCreate: true })
@@ -166,6 +170,7 @@ export default async function postMethod ({
       api,
       scopes,
       runHooks,
+      hasHooks,
       helpers
     })
 

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

@@ -2,7 +2,7 @@
 /** @import {
  * CompletedWriteContext, LifecycleArguments, PivotField
  * } from './lifecycle-types.js' */
-import { applyResourceVersion, captureInverseVersions, invalidateInverseVersions } from '../lib/writing/resource-version.js'
+import { applyResourceVersion, captureInverseVersions, inverseVersionTypes, invalidateInverseVersions } from '../lib/writing/resource-version.js'
 import { RestApiResourceError } from '../../../lib/rest-api-errors.js'
 import { lockRelationshipParent, lockRelationshipTargets, processRelationships } from '../lib/writing/relationship-processor.js'
 import { updateReverseRelationship } from '../lib/writing/reverse-relationship-manipulations.js'
@@ -37,6 +37,7 @@ export default async function putMethod ({
   scope,
   scopes,
   runHooks,
+  hasHooks,
   scopeOptions,
   scopeName,
   api,
@@ -148,7 +149,10 @@ export default async function putMethod ({
     await runHooks('beforeDataCall')
     await runHooks('beforeDataCallPut')
 
-    await lockRelationshipTargets(api, context.transaction, belongsToTargets)
+    // A parent whose revision this write advances is updated, not just referenced.
+    await lockRelationshipTargets(api, context.transaction, belongsToTargets, {
+      exclusive: inverseVersionTypes(api, scopeName, context.schemaInfo)
+    })
 
     if (!context.isCreate && (manyToManyRelationships.length || reverseRelationships.length)) {
       await lockRelationshipParent({ context, helpers, scopeName })
@@ -211,6 +215,7 @@ export default async function putMethod ({
       api,
       scopes,
       runHooks,
+      hasHooks,
       helpers
     })
 

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

@@ -10,8 +10,21 @@ import { getRequestedComputedFields, validateRequestedFieldsets } from '../lib/q
 import { getEffectiveSortableFields } from '../lib/querying/query-field-sort-helpers.js'
 import { transformJsonApiToSimplified } from '../lib/querying-writing/simplified-helpers.js'
 import { getRequestContracts, validateRequestContractOrThrow } from '../lib/querying-writing/request-contracts.js'
-import { validateRequestedIncludes, filterToOneResponseLinkage } from './common.js'
+import { validateRequestedIncludes, filterToOneResponseLinkage, snapshotReadRecord } from './common.js'
 import { queryConstraint } from '../lib/querying/query-constraint.js'
+import { RestApiValidationError } from '../../../lib/rest-api-errors.js'
+
+/** @param {unknown} value */
+const validatePageSizeLimit = value => {
+  if (value === undefined) return undefined
+  if (!Number.isSafeInteger(value) || /** @type {number} */ (value) <= 0) {
+    throw new RestApiValidationError('pageSizeLimit must be a positive integer', {
+      fields: ['pageSizeLimit'],
+      violations: [{ field: 'pageSizeLimit', rule: 'min_value', message: 'pageSizeLimit must be a positive integer' }]
+    })
+  }
+  return /** @type {number} */ (value)
+}
 
 /**
  * Read a filtered collection using params.queryParams and the selected format.
@@ -27,12 +40,15 @@ export default async function queryMethod ({
   scope,
   scopes,
   runHooks,
+  hasHooks,
   scopeName,
   api
 }) {
   callerContext.method = 'query'
   // Nested queries only inherit membership when it is explicitly supplied again.
   callerContext[queryConstraint] = params[queryConstraint]
+  // A server caller's page cap for this call; connectors never pass it.
+  callerContext.pageSizeLimit = validatePageSizeLimit(params.pageSizeLimit)
 
   rejectRemovedOptions(params)
   callerContext.format = resolveFormat(params.format, vars.format)
@@ -90,7 +106,7 @@ export default async function queryMethod ({
 
   context.record = normalizeRecordAttributes(context.record, scopes)
 
-  context.originalRecord = structuredClone(context.record)
+  snapshotReadRecord(context, scopes, hasHooks, 'query')
 
   await runHooks('enrichRecord')
 

package/types/resource-methods.d.ts

@@ -94,7 +94,13 @@ export interface ResourceCoreMethods<
     params: ReadOptions<Format> & { id: DirectResourceId }, context?: Context
   ): Promise<SingleResourceResult<Format, Fields, Type>>
   query<Format extends ResourceFormat = DefaultFormat>(
-    params?: RemovedResourceOptions & TransactionParam & { format?: Format; queryParams?: QueryParams }, context?: Context
+    params?: RemovedResourceOptions & TransactionParam & {
+      format?: Format
+      queryParams?: QueryParams
+      // Server code only: the largest page size for this call, replacing the resource's queryMaxLimit.
+      // HTTP and Socket.IO connectors never pass it.
+      pageSizeLimit?: number
+    }, context?: Context
   ): Promise<CollectionResult<Format, Fields, Type>>
   aggregate(params: AggregateParams, context?: Context): Promise<AggregateResult>
   post<Format extends ResourceFormat = DefaultFormat, Returning extends WriteReturning = DefaultReturning>(

package/types/runtime.d.ts

@@ -31,6 +31,8 @@ export interface RuntimeArguments<Context extends object = Record<string, unknow
   helpers: Record<string, unknown>
   log: RuntimeLogger
   runHooks(event: string, context?: Record<string, unknown>): Promise<boolean>
+  /** Whether runHooks(event) for this resource, or for scope when given, would call any handler. */
+  hasHooks(event: string, scope?: RuntimeResource): boolean
 }
 export type RuntimeMethod<Context extends object = Record<string, unknown>> = (args: RuntimeArguments<Context>) => unknown
 export type HookPlacement = { beforeFunction?: string; afterFunction?: never } | { beforeFunction?: never; afterFunction?: string }