Changelog - 2026-09-05
One list-response contract
New Feature Bug Fix Breaking ChangeIn one line. respond({ context, format, payload, range }) on BaseRestController writes the list headers and the { count, data } envelope for any controller, and the search controller now sends those headers.
What changed
respond,normalizeCountDataandsetListHeaderslive onBaseRestController. The first two moved up from the CRUD factory.respondtakes an optionalrange; with it, the call also writesContent-Range. Nothing changes on the wire for generated controllers.formatis a const class, and the envelope option ispayload.ResponseFormats.ARRAYandResponseFormats.OBJECT(TResponseFormat) replace string literals, andrespondandnormalizeCountDatatakepayloadwhere they tookresponseData.POST /searchsends the list headers.AbstractSearchControllerused to answer without them.startcomes fromfilter.skiporfilter.offset(raw mode: the engine'soffset, orpagewithper_page) andtotalfromfound. The body is unchanged:{ found, isFoundExact, hits }.POST /multi-searchis unchanged. It returns one result per collection, which oneContent-Rangecannot describe.
| Header or body | Value |
|---|---|
Content-Range | records <start>-<end>/<total>, or records */<total> for an empty page. total is the exact count of the scope, never * |
X-Response-Count | rows in this response, never the total |
X-Response-Format | array |
| Body | { count, data }, or the bare array when the client sends x-request-count: false |
A list never depends on a /count route. The CRUD factory keeps its count verb as an opt-in.
typescript
async listOrders(opts: { context: TRouteContext }) {
const { context } = opts;
const { filter = {} } = context.req.valid<{ filter?: TFilter<TOrder> }>('query');
const { data, range } = await this.repository.find({
filter,
options: { shouldQueryRange: true },
});
return context.json(
this.respond({
context,
format: ResponseFormats.ARRAY,
payload: { count: data.length, data },
range,
}),
HTTP.ResultCodes.RS_2.Ok,
);
}Who is affected
- Hand-written list routes that set the headers themselves. Replace your own
normalizeCountableData(rs)andapplyListResponseHeaders(...)copies:context.json(normalizeCountableData(rs), Ok)becomescontext.json(this.respond({ context, format: ResponseFormats.ARRAY, payload: { count: rs.data.length, data: rs.data }, range: rs.range }), Ok). A body that is not{ count, data }callsthis.setListHeaders(...)instead. No wire change. - Callers of
respond({ ..., responseData })ornormalizeCountData({ context, responseData }). Rename the option topayload. The compiler points at each one. - Clients of
POST /search. New headers only. ReadContent-Rangefor paging; when the body saysisFoundExact: false, the engine stopped counting early and more may exist. - Generated CRUD controllers. No action needed.
Breaking changes
WARNING
The responseData option is renamed payload on respond and normalizeCountData. See the replacement example under Who is affected.
Details
- Reference: Controllers. Style: Route definitions.