Skip to content

RFC 05: JS contexts: export context, uses(c), provides(c) #6

Open

Description

@yumemi-thomas

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/router 2.0: useParams() and useNavigate() need the router made by createRouter.
  • @tanstack/solid-query 6: useQuery needs <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 c names a context the module's JavaScript owns. Only that same file's uses(…) and provides(…) can name it. It can't be imported, and .rx code can't use or provide it. 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 is NOT_EXPORTED.
  • MO-12b (Uses). uses(c) on a fn makes each call a use of c where it is called, checked by RG-7b over the tree of component applications and across modules through signatures. A page module's component carries uses(…/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 provides c to everything it renders: its children and every prop. On a fn that hands back a Component (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 is CONTEXT_NOT_FOUND like 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 uses refuses correct code, and a missing one lets the run-time throw through. The prototype's rx-declare (RFC 26) drafts uses/provides by running the module (it watches which hooks throw outside which provider), and rx-verify (RFC 28) checks them. Both are tooling, outside this RFC.
  • A context can't be shared across declaration files: uses and provides only name contexts declared in the same file. A library split across several .d.rx files needs one file that declares the context.
  • The alternative of letting .rx use a 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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions