refactor(atoms)!: 789 — name every route atom *RouteAtom, and only route atoms - #101
Open
randomdevpete wants to merge 1 commit into
Open
Conversation
Owner
Author
|
If anything, ending with "atom" is the pattern supported by jotai core for "factory function that returns an atom instance. I think it is therefore more consistent to rename rootRouteAtom (the singleton) to just rootRoute, and createRootRouteAtom (a create prefix being otherwise never seen) renamed to the slightly more palatable rootRouteAtom. |
…route atoms The suffix now names the return type. An export whose value is a `RouteAtom` — one you can read for a `RouteReturn`, write param values to in order to navigate, or pass as another route's `parent` — ends in `RouteAtom`; any other atom ends in `Atom` alone. Five exports sat on the wrong side of that line, all of them routes. The pairs that read alike were the misleading ones: `rootAtom` and `locationAtom` are both ambient singletons but only one is a route, and `queryAtom` and `queryParamAtom` sound like two flavours of query state when only the second takes part in matching. The rule already held among the types — `RouteAtom` and `AsyncRouteAtom` against `NavigationGuardAtom` — so this brings the values into line with the types rather than inventing a convention, and records it in DESIGN-NOTES.md so later atoms land on the right side. Review feedback on the root pair inverted the initial landing: `rootRouteAtom`, the singleton instance, is not a factory, so per jotai core's own convention — a `...Atom`-suffixed export is a factory that returns an atom instance, not the instance itself — the bare instance drops the suffix (`rootRoute`) and the factory takes it (`createRootRouteAtom` becomes `rootRouteAtom`). This is the one place in the surface where a default instance and its own factory share a root word; every other `*RouteAtom` is a pure factory with no competing instance, so the return-type rule above still decides their names outright. DESIGN-NOTES.md records both the return-type rule and this narrower exception. Old names are not kept as deprecated aliases: two names per export would leave the surface less consistent than it started, which is the opposite of the point. BREAKING CHANGE: `rootAtom` is renamed `rootRoute`, `createRootAtom` to `rootRouteAtom`, `redirectAtom` to `redirectRouteAtom`, `queryParamAtom` to `queryParamRouteAtom`, and `validateAtom` to `validateRouteAtom`. Their options types follow: `RootOptions` becomes `RootRouteOptions` and `QueryParamOptions` becomes `QueryParamRouteOptions`. `locationAtom`, `queryAtom`, `notAtom`, `navigationGuardAtom` and every name already ending in `RouteAtom` are unchanged. Ticket: 789
randomdevpete
force-pushed
the
task-789-converge-core-atom-naming
branch
from
August 21, 2026 13:18
20f7896 to
0694402
Compare
Owner
Author
|
Done in 0694402 |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #100 (
task-685-investigate-required-route-typing) — base this PR against that branch, notmaster.The rule
The suffix names the return type: an export whose value is a
RouteAtom— readable for aRouteReturn, writable to navigate, usable as another route'sparent— ends inRouteAtom;any other atom ends in
Atomalone.The rule was already half-present, not invented from scratch: it held across every type
(
RouteAtom/AsyncRouteAtomcarryRoute,NavigationGuardAtomcorrectly doesn't), and for 6of 11 atom-valued exports plus all 4 correctly-bare non-routes. Five were on the wrong side of the
line, and all five were routes — one-directional drift, not a real second category:
rootAtomrootRouteAtomcreateRootAtomcreateRootRouteAtomredirectAtomredirectRouteAtomqueryParamAtomqueryParamRouteAtomvalidateAtomvalidateRouteAtomRootOptionsRootRouteOptionsQueryParamOptionsQueryParamRouteOptionsUnchanged:
locationAtom,queryAtom,notAtom,navigationGuardAtom(none of these return aRouteAtom), and every export that already ended inRouteAtom(
routeAtom,staticRouteAtom,paramRouteAtom,numericRouteAtom,transformRouteAtom,asyncRouteAtom).Two rejected rules
Both rival rules that could have justified the status quo fail worse than "drift":
queryParamRouteAtomexplicitly doesn't ("Doesn't consume anypath segments, so path matching continues unaffected"), yet it's a route.
rootRouteAtomconsumes zero segments.
redirectRouteAtomswallows whatever's left rather than consuming one.Three of the five renamed exports break this rule.
rootRouteAtomis a plain value (not a function) and still carriesRoute;notAtomis a factory function and correctly doesn't. Contradicts itself on bothnamed-export shapes it's supposed to distinguish.
The pairs that read alike were exactly the misleading ones:
rootAtom/locationAtomare bothambient singletons but only one is a route, and
queryAtom/queryParamAtomsound like twoflavours of the same thing when only the second takes part in matching.
Converging the other way (dropping
Routefrom every route atom instead) is fatal:routeAtom→atomcollides with jotai's ownatom.No deprecated aliases
Old names are not kept side-by-side with the new ones. Two names per export would leave the
surface less consistent than it started — the opposite of this ticket's goal — and the alias
would need its own removal ticket later.
CODING-STYLE.mdalso bans speculative pre-productioncompat hedging; this repo has no stable major yet (major bumps are suppressed, see below), so
there's nothing to be compatible with.
Release shape
Breaking, but ships as 2.7.0, not 3.0.0:
.releaserc.jsonmapsbreaking: trueto a minorrelease, and major bumps are deliberately suppressed in this repo. This lands in the same release
train as #98's (675) own
BREAKING CHANGE— two breaking renames in one minor release, which isconsistent with how this repo has already chosen to version, not a new precedent.
Known gap — not fixed here
e2e/registry-smoke/still referencesresolvedAtom(removed by #98/675) and isn't touched bythis stack either — it installs from the npm registry at
latestand its CI job only runs onmanual dispatch, never on PRs, so nothing here regresses it further. It already breaks on the
first release after this stack lands, tracked as ticket 823.
Verification
npm run build(including the docs SSG prerender of all 130 routes),npm test(114 + 42 = 156tests),
npm run typecheckandnpm run lintall clean. Confirmeddist/index.d.tsexports onlythe five new names and none of the old.
No style-guide exceptions in this diff.