/** * vapor-chamber/router/revalidate - mutation-driven revalidation. * * A BUS plugin that lives on the ROUTER side. After a command that changed * server state, the data behind the current route is stale; this re-runs the * affected loaders and patches the snapshot. It listens to settled results * (`attach`, one `on` per pattern), and holds no `next`. Where the server * declares what a write made stale (RFC 9875 `Cache-Group-Invalidation`), the * router refreshes those reads itself, with no map (index.ts `refreshGroup`). * * bus.use(revalidateRoutes(router, loaders, { * 'cart*': ['shop.cart'], // command pattern -> record names * 'productSave': 'affected', // or: the whole current load chain * })); * * PLACEMENT, and why it is here rather than with the bus plugins. The plugin * needs `runLoaders` from the router, and there is no public substitute * (`reload()` reloads the TABLE, not data); bus-side, it would have to import * a router module into the root barrel, which is forbidden. What it needs from * the BUS is two shapes, the plugin function and `on`, declared inline below, * so the edge exists in exactly one direction, the cheap one. * * WHY `loaders` IS AN ARGUMENT. `createRouter` closes over its `LoaderHandlers` * and does not expose them, so the plugin cannot recover the preset the router * is using. Passing the same instance is the composition's one wiring cost; a * plugin building its own would be a second HTTP client and a second cache, * silently diverging from the router's. * * WHY THE PLUGIN OWNS ITS `isRevalidating`. `router.isRevalidating` is * `Readonly`, and its only writer is the engine's `trackRevalidation`, which is * on neither the router object nor the `Router` type. Driving it would mean * casting the readonly away and becoming a second writer to another module's * state. Two refresh sources, two flags; a consumer wanting one spinner ORs * them. See tests/revalidate-routes.test.ts for the full argument. * * ZERO new router capability: this composes `runLoaders`, `currentRoute` and * `setRouteData`, all already public. */ import { type LoaderHandlers } from './loaders'; import type { Router } from './router-type'; /** * The bus's plugin and listener shapes, declared here rather than imported. * * Structural on purpose - it is the whole of this module's dependency on the * bus, and importing it would pull the command bus into the router's graph to * borrow a function signature. */ type BusResult = { ok: boolean; value?: unknown; error?: unknown; }; type BusCommand = { action: string; }; type ListeningBus = { on(pattern: string, listener: (cmd: BusCommand, result: BusResult) => void): () => void; }; export type RevalidatePlugin = { readonly id: 'revalidateRoutes'; /** True while at least one plugin-driven refresh is in flight. */ isRevalidating: { readonly value: boolean; }; /** Stop revalidating and abort anything in flight. */ dispose: () => void; /** The map's patterns, each one listener (`attach`). */ readonly actions: string[]; /** `use()` gives the bus: one listener per pattern (PluginParts.attach). */ attach: (bus: ListeningBus) => () => void; }; /** Command pattern -> record names to refresh, or 'affected' for the current * route's whole load chain. Patterns use the bus's glob shape (`cart*`). */ export type RevalidateMap = Record; export type RevalidateOptions = { /** Called when a revalidation fails. Default: reported as * `router:failed:revalidate`, never thrown - a failed refresh must not * take down the command that succeeded. */ onError?: (error: unknown) => void; }; export declare function revalidateRoutes(router: Router, loaders: LoaderHandlers, map: RevalidateMap, options?: RevalidateOptions): RevalidatePlugin; export {}; //# sourceMappingURL=revalidate.d.ts.map