Keep record pages within their declared size
A client should not turn a normal record listing into an entire collection download by asking for an enormous page. Wildo applies the operation’s page-size ceiling in its repository adapters.
The response reports the page size actually used. You choose a ceiling suitable for the operation; filters, counts and internal whole-collection work need their own performance decisions.
Example — Keep a listing manageable
A listing allows pages of 50 records. A client asks for 10,000. The paginated listing applies the declared ceiling and returns pagination metadata reflecting that limit, so the client can continue through pages instead of receiving an oversized response.
For engineers
Declare the ceiling on the operation
maxPaginatedResultPerPageLimit belongs to the operation configuration. Both MongoDB and PostgreSQL paginated list adapters read it, with 100 as the fallback ceiling and 20 as the ordinary default page size. The external HTTP API repository also applies a paginated-read clamp.
The user-profile resource supplies a concrete authoring example. This is its default search variant, extracted from the resource’s operations map; the separate administrator variant is omitted. The operation, variant, role and risk enums are public model exports from @wildo-ai/saas-models.
[CoreResourceOperation.SEARCH]: {
variants: [{
variantType: ResourceOperationVariantType.API_CALL,
isDefault: true,
roles: [CORE_APP_ROLES.APP_USER],
riskLevel: ResourceOperationRiskLevel.LOW,
isSearchable: true,
searchableFields: ['firstName', 'lastName', 'displayName'],
searchableOptions: { caseSensitive: false, fullMatchOnly: false },
filterFields: {},
sortFields: ['firstName', 'lastName'],
maxPaginatedResultPerPageLimit: 50,
}],
},
The ceiling sits beside the fields and access rule for the selected variant. This resource separately allows a larger ceiling for its administrator search variant: a different access contract can have a different page budget. The request schema and repository consume the selected variant’s contract.
Follow the declared ceiling into execution
This excerpt shows the list adapter’s effective limit computation. operation is the resolved operation configuration and listOptions contains the caller’s requested pagination.
const maxLimit =
(operation as { maxPaginatedResultPerPageLimit?: number }).maxPaginatedResultPerPageLimit || 100;
limit = Math.min(maxLimit, Math.max(1, listOptions?.limit || 20));
The lower bound is one; the upper bound comes from the operation. The list result’s pagination metadata reports the applied limit rather than echoing an impossible request size. Choose that declaration alongside the columns returned and the expected record size.
Distinguish the read contracts
| Read path | How to reason about the bound |
|---|---|
| Paginated list | The repository clamps the effective page size |
| Search | The request schema applies the configured maximum; repository search also bounds its page |
| Internal MongoDB/PostgreSQL non-paginated enumeration | Preserves its whole-result contract |
| HTTP API read-through, including internal non-paginated reads | Remains capped at the remote adapter’s maximum; one response does not establish complete enumeration |
Search uses its own default maximum when no limit is configured; do not infer its fallback from list behavior. The adapter parity tests pin the list ceiling across MongoDB and PostgreSQL, and the hostile HTTP tests exercise query coercion and response metadata.
For a remote dataset, follow the remote service’s supported pagination contract and verify traversal completion. Do not treat an internal non-paginated call as an instruction to collect every remote record.
Budget work beyond the returned records
A bounded response can still involve expensive filtering and counting. Authorization remains independent from pagination, and an internal export that requires every record must implement appropriate traversal rather than rely on the public page guard. Pair the page ceiling with request policies when the operation also needs a frequency bound.