Repository navigation
Description
One of a series of small proposals, in order; the tracking issue lists them. Depends on: none beyond upstream PR solidjs#69.
Summary
A .d.rx may declare a context that the JS library owns (export context router). A hook can then say it reads that context with uses(router), and a JS component or component factory can say it provides it with provides(router). The .rx checker's existing context check (RG-7b) then refuses a hook called where nothing provides its context. Today that is a throw at run time.
Motivation
Solid libraries keep their state in a context, created with createContext. Their hooks read it, and one of their components provides it:
@solidjs/router2.0:useParams()anduseNavigate()need the router made bycreateRouter.@tanstack/solid-query6:useQueryneeds<QueryClientProvider>.- Kobalte:
<Dialog.Trigger>needs<Dialog>above it.
.rx already checks its own contexts statically (use/provide, RG-7b): a use with no provider above it on some render path is CONTEXT_NOT_FOUND. A JS hook, though, is invisible to that check on upstream. useParams() inside a component rendered outside the router compiles and then throws at run time. That is exactly the error the context check exists to catch.
Proposal
// @solidjs/router's .d.rx
export context router
export pure fn createRouter(config: { routes: RouteDefinition[] }): Component provides(router)
export pure fn useParams(): Params uses(router)
export component RouterProvider(props: { children?: View }) provides(router)
export component Outlet(props: {}) uses(router)
- MO-12a (Declared).
export context cnames a context the module's JavaScript owns. Only that same file'suses(…)andprovides(…)can name it. It can't be imported, and.rxcode can'tuseorprovideit. Its key is the declaration file's (…/router.d.rx#router), so every module that imports the library means the same context. Naming a context the file doesn't declare isNOT_EXPORTED. - MO-12b (Uses).
uses(c)on a fn makes each call auseofcwhere it is called, checked by RG-7b over the tree of component applications and across modules through signatures. A page module's component carriesuses(…/router.d.rx#router)to its importers. A fn that uses a context is an instantiation (called once, where it is bound), because Solid finds a context through the owner the hook runs under. On a declared JS component,uses(c)is what the component itself needs from above. - MO-12c (Provides).
provides(c)on a declared JS component providescto everything it renders: its children and every prop. On a fn that hands back aComponent(a factory, MO-11f), the made component provides it to the components the call was given. On any other fn it is a parse error, because nothing it renders could see the provision. - MO-12d (Provider order). A provider that needs another provider above it says so with
uses(…). Nested in the wrong order, it isCONTEXT_NOT_FOUNDlike any other use. Nothing new is needed.
component Stray() {
params = useParams() // CONTEXT_NOT_FOUND: no router above <Stray /> in App
<p>{params.id}</p>
}
export default component App() { <Stray /> }
Nothing changes at run time: the compiled call is the same JS call.
Drawbacks and alternatives
- The rows are trusted, like every declaration row. A wrong
usesrefuses correct code, and a missing one lets the run-time throw through. The prototype'srx-declare(RFC 26) draftsuses/providesby running the module (it watches which hooks throw outside which provider), andrx-verify(RFC 28) checks them. Both are tooling, outside this RFC. - A context can't be shared across declaration files:
usesandprovidesonly name contexts declared in the same file. A library split across several.d.rxfiles needs one file that declares the context. - The alternative of letting
.rxusea JS context directly would expose the library's internal value, which no library API intends.
Prototype
Branch claude/magical-bell-pfhb1w of yumemi-thomas/reactivescript, commits 452438c (MO-12a–c) and 8e06515 (MO-12d). S-module-7 has the router with a factory, hooks and RouterProvider, and covers: a hook with no router above it, the need crossing a module boundary, a JS component that uses a context, an undeclared context (NOT_EXPORTED), provides on a non-factory (parse error) and wrong provider order. examples/router and examples/query declare their contexts and run in Chromium. Both implementations (ref/ and the Rust crate) agree.
Activity