Skip to content

Reuse without rebuilding

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

Northwind wants a "you might also like" rail at the bottom of a guide. Three coffees, as cards: a picture, a name, a line of copy, a link.

There is already a card Contract — the front page uses it — and a card.tsx renderer that draws one nicely. The rail should use both.

The two obvious ways to connect them are both worse than they look.

Two bad answers, again

Add card fields to coffee. A card-heading, a card-blurb. Now every coffee carries fields that exist because of one rail on one page, the Contract is about presentation again — which part 2 spent a whole section arguing against — and the second place that wants a card starts the process over.

Copy the content into cards. Three real Card Components, duplicating a name and a blurb that already exist. They are wrong the first time a coffee is renamed, and nothing will tell anyone.

What is actually wanted is neither. The content exists and is correct; it is only the shape that is wrong for this one use.

Change the shape on the way out

An Adapter is a named mapping from one Contract to another, applied when content is delivered. coffee in, card out: name becomes the heading, the first line of the description becomes the blurb, the image passes through.

The binding still points at the coffee. Nothing is copied and no field is added anywhere.

And card.tsx never learns that the thing behind it is a coffee. It renders a Card, because a Card is what arrives. That is the property worth having: the renderer is reusable because it is ignorant, and it stays ignorant because the mapping happened before it was called.

An Adapter changes the shape delivered. It never changes what the content is.

Here is the whole thing. Three rules, and none of them is a formula:

{
  externalId: 'coffee-as-card',
  name: 'Coffee as card',
  input: 'coffee',
  output: 'card',
  rules: [
    { kind: 'direct', target: 'heading', source: 'name' },
    { kind: 'direct', target: 'standfirst', source: 'producer' },
    { kind: 'direct', target: 'image', source: 'image' },
  ],
}

direct copies a field, and the two fields have to line up. Noticing where they do not is part of designing a mapping rather than an obstacle to it — if standfirst wanted something coffee genuinely does not have, that is a question about the model, not about the Adapter.

Three rules, and every other field of the coffee left deliberately unwired. The card gets what a card needs and nothing else.

The link the mapping does not supply

One field the Adapter deliberately does not map: the card’s link.

It could not, honestly. A coffee has no URL field — because a URL is a fact the CMS owns, as part 5 spent a whole section establishing, and part 8 finally answered by asking rather than constructing.

So the link is resolved the same way it was then. The binding names the coffee, an Adapter does not change identity, and the coffee’s own published path is looked up. Rename the slug and the rail follows.

That is a small thing that says something about the design. A mapping that had invented a URL would have been more convenient and would have produced links that rot silently — the exact failure this series has been avoiding since part 3.

One last lesson, from our own script

This one is not about a feature. It is about how a mistake in your own tooling can sit in plain sight, and what finds it.

While building this step it turned out that the card Contract’s image field had been storing an empty list of allowed Contracts since the day it was written. Not a wrong constraint — no constraint at all. The field accepted anything.

The cause was ordering, in our script rather than anywhere in the CMS. It walks the Contracts in the order they are written, resolving names to ids as it goes, and card sat above image. So when card asked for the id of image, there was not one yet — and our own helper drops a name it cannot resolve, deliberately, so that re-running a partial model stays convergent. Here that same helpfulness quietly wrote an empty list.

Nothing anywhere had reason to complain: an empty constraint is completely legal and simply means "any". It was only found because a change elsewhere was expected to affect this field and produced no change at all — which is the actual lesson:

A fix that produces no diff against real data is a finding, not a success. Read the stored data before concluding that anything works.

A unit test on a fixture that declares its constraint properly could never have seen this. It needed real content, and somebody being surprised.

The final bundle

This is the last step, so the bundle is the whole site: import it and you have Northwind entire — catalogue, guides, shops, contact, chrome, both languages, the workflow, the Adapter.

It is also the fastest way to look around a finished content model without building one, which is a reasonable thing to want before deciding whether to.

Where this leaves us

Finished. Next: a short one about what all of this was actually arguing, and where to go from here.