API/buildListRequest

buildListRequest

src/lists/build-list-request.tsfunction

buildListRequest()

buildListRequest(list: TList, state: ParamsState<TList['params']>, ...input: conditional): ListRequest

Turn list state into the request for its page.

Each call builds on a fresh createQubee() instance: it sets the resource, runs the list’s apply with the state and the input, and applies the page last. addFilter(), addFilterOperator(), addSort(), setLimit(), setSearch(), setParam() and setResource() all reset the page to 1, so the page must come after them to survive.

A page the store would reject — zero, negative or fractional, as a hand-edited URL can carry when the page param sets no min — falls back to the list’s default page.

Errors from apply or generateUri() — a capability the driver lacks, a param collision, an empty resource — are programmer errors and propagate.

const request = buildListRequest(articleList, readListState(articleList, '?page=3'));
const response = await fetch(request.uri, { headers: request.headers ?? {} });
const page = request.paginate<Article>(await response.json(), response.headers);

A list that declares an input takes it as a third argument; one that declares none refuses it:

buildListRequest(taskList, readListState(taskList, search), { projectId: '42' });

The input is read from apply’s parameters with ListInput<TList>, so it does not depend on how the list’s type is written: through an alias such as type LooseList = ListDefinition<ListParams>, a list declares none.

Parameter	Type	Description
`list`	`TList`	The list, as `defineList()` returned it
`state`	`ParamsState<TList['params']>`	The list state, as `readListState()` returned it
`input`	`conditional`	What the list’s request needs besides URL state, for a list that declares an input. The input never reaches the URL; `[uri, headers]` stays a complete cache key

Returns — The URI, the headers, and a parser bound to the same instance