@aiquants/route-revalidation

One declarative rule for React Router's shouldRevalidate. A route states when its loader needs to run again as a policy, and createShouldRevalidate(policy) turns the policy into the route's shouldRevalidate, so every route decides in the same order instead of hand-writing its own.

• A policy names what does not need the loader: a destination (the sign-out route), the intents whose result the page applies itself, the submissions, another path of the same route, a change of the query, dropping the hash, a revalidation of the unchanged URL.
• Every case the policy leaves out keeps React Router's own decision (defaultShouldRevalidate).
• A policy that changes no case is refused, so a route with nothing to decide exports no shouldRevalidate at all.

React Router 7 or 8 as a peer; no runtime dependencies.

Contents

• Install
• Usage
• The order of the decision
• Policy
• Recipes
• Errors
• License

Install

pnpm add @aiquants/route-revalidation

Usage

import { createShouldRevalidate } from "@aiquants/route-revalidation"

// a page whose list / tree tab and search term live in the URL: switching them needs no new loader data
export const shouldRevalidate = createShouldRevalidate({ submissions: "url", query: { ignore: ["view", "q"] } })

The returned function is assignable to React Router's ShouldRevalidateFunction and takes its ShouldRevalidateFunctionArgs as they are. Build it once at module level; the policy is checked when it is built, never per transition.

The order of the decision

The function decides in this order, and the first step that applies decides:

1. Destination: a next path matching one of skipDestinations (React Router's matchPath, to the end of the path) never runs the loader.
2. Submission (any of formMethod, formAction, formEncType, formData, json, text, actionResult, actionStatus present): a submission whose skipIntents.field holds one of skipIntents.values never runs the loader. The other submissions follow submissions; with "url", and for a GET submission with "writes", the next steps decide.
3. Another path of the same route (a splat or a parameter): otherPath.
4. The same path with another query: query.
5. The same path and query with another hash: hashChange. React Router runs no loader when the hash is added or changed, so this step only sees a navigation that drops the hash (a link from /doc#part to /doc). With "unchanged" (the default) the next step decides.
6. The unchanged URL (path, query and hash; after an action, a revalidate() call or a link to the current page): unchangedUrl.

Policy

| Key | Values (default first) | Meaning | | --- | --- | --- | | skipDestinations | route patterns starting with / | Arriving at one of them never runs this loader. | | skipIntents | { field, values } | A submission whose form field field holds one of values never runs the loader (the page applies its result itself). It is decided before the URL, so name only intents sent where they stay on the page, such as a fetcher submission. | | submissions | "default", "skip", "writes", "url" | The other submissions: React Router's decision whatever the URL does, never, run for a mutation (any method but GET), or decide like a navigation. | | otherPath | "default", "skip" | Another path of the same route: React Router's decision, or never (a page that fetches each document itself). | | query | "default", "skip", { ignore }, { watch }, { refill }, a function | The same path with another query. { ignore }: a change of these parameters alone never runs the loader, any other change keeps React Router's decision. { watch }: run exactly when one of these parameters changed. { refill }: run exactly when one of these parameters, present before, is missing or empty after (the loader fills it back by redirecting). A function decides from copies of the queries before and after. | | hashChange | "unchanged", "default", "skip" | A navigation that drops the hash: decided like the unchanged URL, React Router's decision, or never. | | unchangedUrl | "default", "skip", a function | The unchanged URL: React Router's decision, never, or a function deciding from a copy of the URL. |

watch and refill decide by themselves: they run the loader even when React Router would not, and skip it otherwise. Functions receive copies, so they cannot change React Router's URL objects.

Recipes

| Page | Policy | | --- | --- | | Its tab or search term lives in the URL | { submissions: "url", query: { ignore: ["view", "q"] } } | | It loads the first paint and fetches the rest itself (a document explorer under a splat) | { submissions: "skip", otherPath: "skip", query: "skip", hashChange: "skip" } | | Its actions apply their own results | { skipIntents: { field: "intent", values: ["save", "delete"] }, hashChange: "default", unchangedUrl: "skip" } | | Its loader fills missing query keys by redirecting | { submissions: "url", query: { refill: ["from", "to"] }, unchangedUrl: "skip" } | | Its loader reads one query key | { submissions: "url", query: { watch: ["month"] }, unchangedUrl: "skip" } | | The root route keeps its data on sign-out | { skipDestinations: ["/auth/logout"] } | | Its submissions and query changes need no loader | { submissions: "skip", query: "skip" } |

Errors

createShouldRevalidate checks the policy when it builds the function. A value of the wrong type (a policy that is not a plain object, a setting that is not a string, an array or a function where one is expected, null included) throws a TypeError. A value of the right type that the setting does not take (an unknown key, an unknown choice, an empty list, a blank string, a pattern without a leading /, a policy that keeps React Router's decision for every case) throws a RangeError. Every message starts with [route-revalidation] and ends with the rejected value.

License

MIT