Page Source with Courier
Problem
Your remote API uses zero-based page numbers, while Sourcerer starts at page 1. You need Courier transport and errors while Sourcerer owns page state and request succession.
Solution
Convert page numbers only at the HTTP boundary. Map the server's total count into PageResult.totalItems and forward Sourcerer's cancellation signal.
import { createCourier } from '@vielzeug/courier';
import { createPageSource } from '@vielzeug/sourcerer';
type Issue = { id: number; title: string };
type RemotePage<T> = {
content: T[];
page: { totalElements: number };
};
const courier = createCourier({ baseUrl: 'https://api.example.test' });
const source = createPageSource<Issue, string>({
load: async ({ page, pageSize, params: search, signal }) => {
const response = await courier.get<RemotePage<Issue>>('/issues', {
query: { page: page - 1, size: pageSize, search },
signal,
});
return { items: response.content, totalItems: response.page.totalElements };
},
params: '',
});
try {
await source.reload();
console.log(source.state.items);
} finally {
source.dispose();
courier.dispose();
}Source page 1 requests remote page 0; source page 3 requests remote page 2. With a page size of 20 and a server total of 51, Sourcerer reports three pages, regardless of how many items the current response contains.
The example uses a subset of Spring Data's simplified PagedModel/VIA_DTO response shape. Other APIs and Spring serialization modes may put the total elsewhere; adapt the envelope to your endpoint's actual contract.
Replacing a load aborts the previous loader signal, which Courier forwards to fetch. Superseded work settles without committing stale results. A current load failure populates source.state.error and rejects the loading command; handle that error at your application boundary.
This example owns both resources, so it disposes the source before Courier. When a loader receives a shared application Courier, dispose only the source; the application's client owner handles Courier disposal.
Keep authentication, middleware, timeouts and transport errors on Courier. Keep router/URL state outside Sourcerer: a route's page convention is separate from the remote API's page convention. Use a dedicated query cache when reads must be shared by key.
Pitfalls
- Subtract one only in the HTTP query. Keep source navigation and state one-based.
- Use the server total, not
response.content.length, fortotalItems. - Pass the loader signal to Courier; do not replace it with an unrelated controller.
- A generic response type does not validate JSON at runtime. Use Courier's
schemaoption if your endpoint needs validation.