json-rest-api 2.3.1 → 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.
 

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

@@ -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.1",
+  "version": "2.4.0",
   "main": "index.js",
   "types": "index.d.ts",
   "type": "module",

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/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

@@ -35,6 +35,7 @@ export default async function patchMethod ({
   scope,
   scopes,
   runHooks,
+  hasHooks,
   scopeOptions,
   scopeName,
   api,
@@ -170,6 +171,7 @@ export default async function patchMethod ({
       api,
       scopes,
       runHooks,
+      hasHooks,
       helpers
     })
 

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

@@ -33,6 +33,7 @@ export default async function postMethod ({
   scope,
   scopes,
   runHooks,
+  hasHooks,
   scopeOptions,
   scopeName,
   api,
@@ -169,6 +170,7 @@ export default async function postMethod ({
       api,
       scopes,
       runHooks,
+      hasHooks,
       helpers
     })
 

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

@@ -37,6 +37,7 @@ export default async function putMethod ({
   scope,
   scopes,
   runHooks,
+  hasHooks,
   scopeOptions,
   scopeName,
   api,
@@ -214,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 }