adapter-store: sanctioned single-resource fetch by string key (route-binding keys)

[jasperboerhof]

Problem

adapter-store consumers can only get a single resource into the store via retrieveById(id: number). For Laravel backends using custom route-model binding, the show route often accepts a string key as well — e.g. kendo's Issue::resolveRouteBinding resolves both numeric ids and issue keys, so GET projects/1/issues/KD-0123 and GET projects/1/issues/123 both work.

Because the store has no typed path for string keys, kendo's issue Show/Edit pages currently work around it by calling retrieveAll() and resolving the key client-side — fetching 600+ issues in production to display one, on every page mount (retrieveAll has no caching). We want to fix that, and the fix needs a sanctioned way to fetch one resource by key.

Constraints we want to keep:

• setById stays internal — the public StoreModuleForAdapter surface remains read-only.
• No type-system abuse in consumers (retrieveById(slug as unknown as number) works at runtime since the value is only URL-interpolated, but we don't want to ship that).

Options

Option 1 — first-class retrieveByKey(key: string)

A sibling of retrieveById, identical implementation:

retrieveByKey: async (key: string) => {
    const { data } = await httpService.getRequest(`${domainName}/${key}`);
    setById(data);
},

• Laravel route-model binding with custom keys is a first-class framework concept, so "fetch one resource by string key" arguably belongs in the package's domain rather than being app-specific.
• setById stays internal, numeric call sites keep strict number typing.
• Misuse surface: calling it on a store whose backend only binds ids yields a 404 — the same failure mode as retrieveById(999999) today.
• Narrow: solves exactly this need and nothing else; a future store-level need means another package change.

Option 2 — generic extend config hook

Capability injection in the style of the existing broadcast config: the hook runs once at store creation and receives the same internal module tier the adapter factory already gets.

type AdapterStoreConfig<T, E, N, X extends object = {}> = {
    // ...existing...
    broadcast?: AdapterStoreBroadcast<T>;
    extend?: (storeModule: AdapterStoreModule<T>) => X;
};
// createAdapterStoreModule returns StoreModuleForAdapter<T, E, N> & X

Consumer side:

extend: ({setById}) => ({
    retrieveBySlug: async (slug: string): Promise<void> => {
        const {data} = await httpService.getRequest<IssueResource>(`${url}/${slug}`);
        setById(data);
    },
}),

• Most future-proof: consumers define their own sanctioned store-level methods without further package changes, and nothing app-specific (like "slug") enters the package.
• The trust boundary is unchanged in kind — adapter and broadcast.subscribe already receive the internal tier at creation time; extend is the same pattern generalized.
• It does relax the current discipline that custom writes are adapter methods tied to a resource — store-level custom methods become a thing. Whether that's a direction the package wants is the main question here.

Option 3 — widen retrieveById to number | string

Smallest possible diff. Trade-off is semantic: a method named ById accepting keys blurs what actually binds, and every store starts accepting strings whether or not its backend supports them.

Option 4 — no package change (consumer-side resolve-then-retrieve)

The consumer does a plain getRequest on the show route to learn the numeric id, then calls the typed retrieveById(data.id):

• numeric value → 1 request (straight retrieveById)
• string key → 2 requests, the second re-fetching a payload the consumer already had, because retrieveById is the only sanctioned door into the store

Zero package work, fully typed, mildly wasteful by design. Also viable as an interim while one of the other options is discussed/released, since the consumer-side fix isn't blocked on a package release.

Ask

Which direction fits the package best? Happy to PR whichever option we agree on.

Context: found while fixing kendo's issue Show page perf (600-issue fetch to render one issue).

[Goosterhof]

Decision: Option 2, hardened — extend ships, but receives a response-backed ingest primitive, not raw setById

Option 2 is the right bet: store-level custom methods unlock real use well beyond retrieveBySlug, and "no further package change per consumer need" is genuinely valuable. We're taking it — with one change to the trust surface.

The problem with raw setById in extend

As drafted in #120, extend receives the internal {setById, deleteById} tier. That lets a consumer put the raw mutator straight onto the public store surface:

extend: (sm) => ({ save: sm.setById })   // store.save(item) now writes local state, no HTTP

This isn't fixable with a runtime guard. A reference-identity check catches the line above, but a one-line wrapper defeats it:

extend: (sm) => ({ save: (item) => sm.setById(item) })   // new function — slips through

…and that wrapper is the same operation as a legitimate retrieveBySlug minus the await http.get(...) we can't inspect. "Fetch-then-set" and "expose-raw" are indistinguishable at runtime. A guard is real protection against accidents and theater against intent.

The fix: constrain the capability, don't police the output

extend receives a response-backed ingest primitive instead of the raw mutators — the only way data can enter the store is through an HTTP response:

extend?: (cap: ExtendCapabilities<T>) => X;

type ExtendCapabilities<T extends Item> = {
    // GET endpoint -> upsert the response item(s) into the store
    retrieveInto: (endpoint: string, options?: AxiosRequestConfig) => Promise<void>;
    // generalizes to requestInto({method, url, data}, map?) for write-verb custom actions
};

// consumer — the motivating kendo case:
extend: ({retrieveInto}) => ({
    retrieveBySlug: (slug) => retrieveInto(`${domainName}/${slug}`),
})

setById/deleteById never leave the factory, so { save: sm.setById } and its wrapper variant are unexpressible — not guarded against, structurally impossible.

The only capability this removes versus raw setById is "write store state with no server response behind it" — which is exactly the abuse. Custom endpoints, verbs, cross-store coordination, derived methods all stay expressible (extend still closes over the consumer's whole module scope). The control surface equals the abuse surface; nothing you'd legitimately want is lost. This matters more here than in most packages because consumer territories carry ISO 27001 / NEN 7510 obligations where the HTTP path is where authz/audit live.

Next steps for #120

1. Rework extend to pass ExtendCapabilities<T> (start with retrieveInto; add requestInto when a write-verb use case lands — don't over-build ahead of need). Widen the store's Pick<HttpService, ...> only as far as the shipped primitives require.
2. The collision guard, version cascade, docs, and test structure from feat(adapter-store): add extend config hook for consumer-defined store methods #120 largely carry over.
3. Split the esbuild 0.27.7 → 0.28.1 override into its own PR — it clears the dev-only advisory and un-reds main on its own merit, and shouldn't be coupled to this design.

Nice analysis in the original write-up — the four-option framing is what made this decidable.

[Goosterhof]

Follow-up to the Option-2-hardened decision: #128 hardens broadcast (payload validation + handlers no longer leak the bare mutators). It's the concrete demonstration of why extend and broadcast are not the same trust tier — broadcast's non-HTTP write path is irreducible (it's the feature), so it can only be validated, not designed out; extend's isn't, so it can and should be routed through a server-backed ingest primitive. The asymmetry is the argument for constraining extend, now backed by shipped code.