Skip to content

A catalogue people can browse

The ebitex team
Part 8 of 20 of the series “Building Northwind Coffee”: a coffee cup, steaming, beside the part’s number.

Every page so far has been content somebody wrote. /coffees is the first one that is mostly a question: show me the coffees, cheapest first, and let me narrow them.

The Contract behind it holds almost nothing — a heading and an introduction, which really are written by a person. The grid is not content at all. It is a query, correct the moment a coffee is published, and authored nowhere.

Why not just fetch them all

There are eight coffees. Fetching all eight and filtering in the browser would work perfectly, today, in about twenty lines.

It would also stop working at a size nobody notices until a customer does. Eighty coffees is a slow page. Eight hundred is a broken one, and the code that broke it will look exactly as reasonable as it does now. Worse, the failure is gradual — there is no moment where it announces itself, just a page that is a bit slower every quarter.

So the query runs on the server from the start, and the page fetches a page of results.

A list that a person maintains is a list that will one day be wrong. The only question is whether anyone notices before a customer does.

A stream is a saved query with a public surface

A stream is a named, server-side query addressed by external id. Northwind’s is called coffees: it matches published Components of the coffee Contract, ordered by price. The order is part of the stream’s definition rather than something a caller asks for — which is worth knowing, because wanting the same set in a second order is a second stream.

The important part is declaredFilters. That list is the stream’s entire public surface — callers may filter by those keys and by nothing else. Northwind declares three:

FilterKindFrom
roastcategorythe taxonomy in part 6
originreferencethe reference in part 5
qfull textevery string in the document

That is a deliberate boundary rather than a limitation. A query whose shape is decided by the caller is a query you cannot index for, cannot cache, and cannot reason about when it gets slow. Declaring the filters means the server knows the whole space of questions in advance.

And because it knows them, it can answer a second question about each one.

Facets, and the rule that makes them usable

Every declared filter is also facetable: ask for a facet on roast and you get each value with a count, computed against everything currently published.

The rule that makes this feel right is small and easy to get wrong: the facets endpoint excludes a facet’s own dimension while respecting every other active filter.

Concretely. Select Ethiopia, and the roast counts narrow to what Ethiopia actually offers — Light 2, Medium-dark 1 — because roast is a different dimension and Ethiopia constrains it. But the origin chips do not narrow to Ethiopia alone. They still show every origin, with counts.

That is what lets somebody switch from Ethiopia to Kenya in one click. Narrow the origin facet by the origin filter and every other option would drop to zero or disappear, and the only way out of a selection would be to clear it first. Anyone who has used a shop with that behaviour remembers it.

The whole grid is three calls, and they all carry the same active filters:

Promise.all([
  content.delivery.queryStream(STREAM, { filters, limit: PAGE_SIZE, signal }),
  content.delivery.getStreamFacet(STREAM, 'roast', { filters, signal }),
  content.delivery.getStreamFacet(STREAM, 'origin', { filters, signal }),
])

Passing the same filters to each is not redundancy. A facet endpoint excludes its own dimension server-side, so the roast facet answers "given everything else you have selected, what roasts are still available" — which is what makes selecting one never lead to an empty page.

Filter state lives in the URL

?roast=light&origin=… — so a filtered view is a link. Somebody can send "the light Ethiopians" to a colleague, bookmark it, or open it in a second tab to compare.

This costs nothing and is skipped constantly. Filter state in React state alone is filter state that cannot be shared, cannot be returned to, and is lost by the back button.

The link from part 5, at last

Part 5 ended with a card that could not link to its own page, because nothing in the app knew that page’s URL and building one from the origin’s name would have been a guess.

The query answers it. Asking a listing for include=paths returns, per item, the published path of the node that binds it — looked up rather than constructed. So the origin card gets a real link, and an origin with no published page simply gets no link, which is the honest outcome rather than a URL that 404s.

There is a companion setting worth knowing about: titleFieldPath on a Contract tells a listing which field is the human-readable name. With it, a list of coffees hands back real names without resolving each whole document to go looking for one.

One thing to know if you filter on two taxonomies

A detail you will meet only if a Contract carries two category fields, as coffee does with roast and process.

Filtering works as you would expect on either, with one thing to declare. A stored category value is just a category, so nothing about a filter called roast tells the server you meant the roast group rather than the process one — and a facet asked that way answers with both.

So say which. groupExternalId on the declared filter is the whole of it:

declaredFilters: [
  { key: 'q', type: 'fullText' },
  { key: 'roast', type: 'category', groupExternalId: 'roast' },
  { key: 'origin', type: 'reference', fieldPath: 'origin', labelFieldPath: 'name' },
]

That narrows the facet list to the group it names, and it narrows the filter’s own input the other way: filter.roast=process/washed is refused outright rather than quietly filtering by a dimension nobody asked about. Both halves come from the same declaration, which is the point of declaring filters at all.

Where this leaves us

A catalogue that browses, filters, searches and shares — and eight product pages that are, so far, a paragraph each.

Next: long-form content. Brew guides, with pictures inside the prose rather than beside it, and the mirror image of part 5’s decision.