RFC: Cache/Preload Architecture

[ryansolid]

Summary

In hopes of aligning with a future where cache centric approach is to routing this RFC outlines a change in Router architecture to enable optimal data fetching patterns for CSR & SSR SPAs, MPAs, and future Hybrid solutions.

Basic Example

// app.tsx
import { lazy } from "solid-js";
import { render } from "solid-js/web";
import { Router, Route } from "@solidjs/router";
import preloadUsers from "./pages/Users.data";

const Users = lazy(() => import("./pages/Users"));
const Home = lazy(() => import("./pages/Home"));

const AppLayout = props => {
  return <>
    <h1>Welcome</h1>
    {props.children}
  </>
}

render(() => (
  <Router>
     <Route component={AppLayout}>
        <Route path="/users/:id" component={User} preload={preloadUser} />
        <Route path="/" component={Home} />
      </Route>
  </Router>
), document.getElementById("app"));

// Users.data.ts
import { cache } from "@solidjs/router/data";

export const fetchUsers = cache(async (id) => {
  return (await fetch(`/api/users/${id}`).json()
}, "users")

export default function({ params }) {
  void fetchUsers(params.id);
}

// Users.tsx
import { createAsync } from "@solidjs/router/data";
import { fetchUsers } from "Users.data";

export default Users(props) {
  const users = createAsync(() => fetchUsers(props.params.id));
  
  // use it in your component
}

Motivation

Solid Router aims to be the universal router for all web applications for Solid. There are few really important evolutions that are taking us in this direction, that this RFC seeks to solve.

1. Link Preloading with Reactive data doesn't really work

One of the longest asked for features is having hover preloading and we've never delivered on it because it is messy at best. Mostly that without caching solution it has no benefit unless we persist the reactivity for period of time. This makes disposal complicated. It makes it hard to call the function more than once. We've mostly resolved that to do this the developer would need a cache solution anyway (like Tanstack Query) but the Router not offering that yet offering preloading is a bit at odds.

2. Data Functions Confuse Developers expecting Blocking Middleware

The best thing about our Data functions are they are not blocking by default. This really lets you leverage things like Suspense and Transitions in your application code. You should never really think of them like a single Loader but a mechanism to set up multiple loaders. We've had many requests over time to make them blocking or access Context that they could never have access to because they are hoisted. We've encouraged people to pull more work into them, and that is good, but it sets a false pretext for some. With Preload Functions I think this expectation can't exist. These are just optional functions that warm the cache. They aren't blocking. If the component beats you to fetching something that you have in preload so be it.

3. People like Fetching in Components

Now I'm not going to say people are right. No matter what if you fetch in your component without doing hoisted preloading you risk waterfalls for the unaware. Moreover hoisting all data fetching to the top-most component in a nested section is also not guaranteed to not waterfall given that the parent needs to render before child first for Context to work. So having a dedicated place to preload like we do for loaders today is essential. Of course with techniques like "hover" preloading, avoiding wrapping nested sections in conditionals, and extreme vigilance, you could author an optimal app without preloading. And the naive approach is at least better than the naive approach today.

However, giving people a place to preload and playing into these sort of patterns is much friendly to other 3rd party libraries. This aligns with things like Tanstack Query better.

4. Enforce better patterns for TypeScript/Data Layer

Things like useRouteData never really sat great with TypeScript. Moving towards a direct import approach with cache and actions will allow completions.

These are also designed to work with our Server Functions both on the fetching and mutation side. There is an added benefit that pushing these references to be global so they can be referenced will discourage people defining server functions inline in components. This will remove need for ambiguous closure abstraction to prevent accidental leakage.

import db from "./sql-connection";
import { cache } from "@solidjs/router/data";

export const fetchUsers = cache(async (id) => {
  "use server";
  return await db.getUser(id);
}, "users")

Simply by API design we should be able to avoid common footguns.

5. Hybrid Islands Routing/Server Components don't support Context

They can't. Once you navigate to the next page with HTML partials there is a chance for the server to render components that read from Context (or Global State) that has been updated in the client since the initial render. The server being unaware could not render the right thing and cause Hydration Mismatch errors. It is fundamental that these solutions always render components that use persistent client state on the client only after initial SSR. Also to support nested partials we can't assume that the parent will have executed, so each Route section must be responsible for its own data and dedupe via a cache.

6. A breaking change sooner is better than later with SolidStart in mind

Knowing what is coming for both Solid 2.0 and these new areas of Routing it probably makes sense to do the bigger changes sooner than later. SolidStart aims to not wrap other libraries(including the router) anymore so these APIs being proposed for Data are those you would choose to use in SolidStart if you choose to use this Router with it.

Detailed Design

I've written a mock ReadMe with all the updates if you prefer to see the proposal more from a consumer standpoint. You can see it here: https://hackmd.io/@0u1u3zEAQAO0iYWVAStEvw/Hk4vO2Az6

Breaking Changes

Data Functions -> Preload Functions

We will replace the data prop on the router with preload. It will fire at the same time that data did and when preload is triggered by other means but there is no return value. The router doesn't store the data, but the cache solution of your choice can.

Return to lower case navigation elements <a> & <form>

Besides reducing the noise of imports these elements + delegation means they can work even in sections that aren't hydrated. Capital <A> will still exist (for the time being) with its ability to handle active class, but it is innately an Island/Client component and this way this works for all.

Removal of <Outlet>, <Routes>, useRoutes

<Outlet> is no longer used and instead will use props.children passed from into the page components. This preseves that the chain is connected for future features like Server Components. Nested <Routes> inherently cause waterfalls and are Outlets in a sense themselves. We do not want to encourage the pattern. Upon observation of solutions concerned with data fetching these are not common to see. The feature isn't available in Tanstack or Next App Router, and discouraged in use with Remix.

These changes mean the <Router> directly receives the routes now (JSX or config) as children. Remember you can always add top level layout by wrapping your <Route>s with another without a path.

element prop removed from Route

Related without <Outlet> component children need to be passed in manually. At which point the element prop has less value. Removing the second way to define route components to reduce confusion and edge cases.

New Data APIs

I made a simple prototype without the router to test these APIs (it doesn't have the preload/cache life): https://codesandbox.io/s/route-cache-store-action-draft-dpf3f3?file=/src/index.tsx

cache

To prevent duplicate fetching and to trigger handle refetching we provide a cache api. That takes a function and returns the same function.

const getUser = cache((id) => {
  return (await fetch(`/api/users${id}`)).json()
}, "users") // used as cache key + serialized arguments

It is expected that the arguments to the cache function are serializable.

This cache accomplishes the following:

1. It does just deduping on the server for the lifetime of the request.
2. It does preload cache in the browser which lasts 10 seconds. When a route is preloaded on hover or when preload is called when entering a route it will make sure to dedupe calls.
3. We have a reactive refetch mechanism based on key. So we can tell routes that aren't new to retrigger on action revalidation.
4. It will serve as a back/forward cache for browser navigation up to 5 mins. Any user based navigation or link click bypasses it. Revalidation or new fetch updates the cache.

This cache can be defined anywhere and then used inside your components with:

createAsync

This is light wrapper over createResource. It is a simpler async primitive where the function tracks like createMemo and it expects a promise back that it turns into a Signal. Reading it before it ready causes Suspense/Transitions to trigger.

const user = createAsync(() => getUser(params.id))

cache API can be used with createResource but it must be passed into the tracking argument not the fetcher which means that you can't only pass a single argument as createResource defaults to just the fetcher. So to use a cache function with createResource you would need to:

const [user] = createResource(
  () => getUser(params.id),
  v => v // pass the return promise through
);

action

Actions are data mutations that can trigger invalidations and further routing. A list of prebuilt response builders can be found below.

// anywhere
const myAction = action(async (data) => {
  await doMutation(data);
  return redirect("/", {
    invalidate: [[getUser, data.id]] // keys to invalidate 
  }) // returns a response
});

// in component
<form action={myAction} />

//or
<button type="submit" formaction={myAction}></button>

Notes of <form> implementation and SSR

This requires stable references as you can only serialize a string as an attribute, and across SSR they'd need to match. The solution is providing a unique name.

const myAction = action(async (args) => {}, "my-action");

useAction

Instead of forms you can use actions directly by wrapping them in a useAction primitive. This is how we get the router context.

// in component
const submit = useAction(myAction)
submit(...args)

The outside of a form context you can use custom data instead of formData, and these helpers preserve types.

useSubmission/useSubmissions

Are used to injecting the optimistic updates while actions are in flight. They either return a single Submission(latest) or all that match with an optional filter function.

type Submission<T, U> = {
  input: T;
  result: U;
  error: any;
  pending: boolean
  clear: () => {}
  retry: () => {}
}

const submissions = useSubmissions(action, (input) => filter(input));
const submission = useSubmission(action, (input) => filter(input));

Response helpers

redirect(path, status || options)

Returns a redirect response with ability to optionally set headers, or indicate invalidations

Unresolved Questions

1. How much control do developers need over cache keys/invalidation?

The idea of providing a name and creating it ourselves is easy, but we could ask for a function that takes the same arguments as the async function and use that to generate the key on each execution.

2. Is there a way to have a reload revalidate without using redirect API

Since actions don't have an URL and generally aren't the same as where you fetched from you typically have to redirect back to the same page to have it reload when dealing with server functions. It would be nice if we could find a way to avoid this that can work when JS is disabled (ie we can't just set custom headers from the client).

Alternatives

From a technical standpoint there aren't much in the way of alternatives. I've spent the last year or so working through the options and finally feel confident to propose this. That being said how we roll it out might be up to debate. Perhaps we can introduce a new router instead of changing the existing. But realistically maintenance would be a concern here.

Adoption Strategy

This change would be a breaking one and it would come in a specific minor version of Solid Router (as it isn't 1.0 yet). The previous versions would be available in NPM but this would replace what we have currently, forcing migration over time across the ecosystem.

[Brendan-csel]

Cache code example is perhaps meant to return fetch result?

const getUser = cache((id) => {
  return await fetch(`/api/users/${id}`)
}, "users") // used as cache key + serialized arguments

[ryansolid]

Yeah good call I will fix that

[Brendan-csel]

What is the API to access a route's preload function if we want to call it?

Experience shows that can be a route-specific assembly of multiple data preloads so it would be nice to keep it right there with the route.

[ryansolid]

Yeah good feedback. Yeah we should have a programmatic way to get it and call it. So we could do so on other JS based criteria not just navigation.

Maybe like usePreload(() => path).. And then you call it void, and it just calls the preload with the right arguments

[Brendan-csel]

Request not to assume all a and form elements on the page are related to the Solid app. Example, we have mini-forms for things like logging out that post back to our (non-JS) backend.

[ryansolid]

I was always thinking of making it able to be disabled. But making it overrideable does have a consideration. It means that the events are always registered. I'm fine with that. But with a true global disabled the code won't run on every link hover etc.. whereas doing it per link means its always there overridable or not.

I think handling preloads this way is probably pretty sane. Mostly that if you don't preload well it is what it is. The impact either way is pretty whatever. I suppose handing whether the client routes this way is possible as well but I'm a bit more concerned with that. I don't like global with local overrides from the perspective it is significant like a mode change. Having a named attribute I suppose is still doable.. like client false or something if it makes things more clear.

Listening to the feedback it isn't even about HTML regions here.. Like if I could contain things to where the Router lived, but rather the same domain has endpoints that aren't expected to be handled (as we already check if isn't).

Lowercase anchor is a big benefit for hybrid partial hydrated solutions still being able to trigger the router without being hydrated. I'm very much of the same thinking as @caseybaggz (which is how this already would work and how it worked in older versions of the router).

[Brendan-csel]

But with a true global disabled the code won't run on every link hover etc

I see the next branch code adds document level listeners for, among others, mouseover and mouseout - so moving the mouse fires router code for every element (and then checks to see if it is an a, etc).

There still may be a case for an option to avoid that work and disable the listeners altogether.

[Brendan-csel]

Having a named attribute I suppose is still doable.. like client false or something if it makes things more clear

Could there be anchors on the page that the dev doesn't control the rendering for (ie rendered by something within their (non-Solid) backend platform)? For those cases Solid's handling of a needs to be opt-in (like the link attribute in the current router).

[ryansolid]

We use the same rules for client routing for preload, so the attributes on it should be sufficient to discount it I think.

I am leaning towards true disable for preloads with no override. Then we don't attach the events etc...

As for the client routing behavior in general. I mean it is tricky. When I was saying a named I meant for opting out. Opting in, like using mode could be done I suppose. I just really dislike all the toggles where same code in different projects acts differently at a per link level. But I guess this is like a global opt out in a sense. Ok.. I can look at this. I dislike it existing but it wouldn't take much code.

[ryansolid]

Yeah I've implemented both a turn off globally for preloading and automatic link interception. And updated the readme appropriately. I think I'm pretty much ready for release. Just testing the last beta build.

[brenelz]

So in your example you show invalidating a specific data.id key from getUser:

const myAction = action(async (data) => {
  await doMutation(data);
  return redirect("/", {
    invalidate: [[getUser, data.id]] // keys to invalidate 
  }) // returns a response
});

I guess the id is automatically part of the key because of the parameters? Guessing you could also pass "users" instead of the getUser function directly?

const getUser = cache((id) => {
  return (await fetch(`/api/users${id}`)).json()
}, "users") // used as cache key + serialized arguments

[ryansolid]

Yep exactly. I had previous iterations where the invalidate was passed in as an option on the action (and that is how SolidStart works today) but this can communicate the intent without the action itself ever getting to the client in some cases.

[brenelz]

But It looks good!

[edygar]

The current specification conflicts with standard form[method=get]. The omission of method imply in a get form, but as of now form[method=get] isn’t even touched by the router, thought it should, as it’s as much a navigation method as a link.

I think the router shouldn’t be the one taking care of the form[action=server] transformation, it doesn’t seem a routing concern. If it provided a way for the targeted routes from a form post to deal with the request, it would be enough.

[edygar]

Basic Example

So my suggestion would be to change a few bits here and there:

// app.tsx
// ...
render(
  () => (
    <Router>
      <Route component={AppLayout}>
        <Route path="/users/:id" component={User} preload={preloadUser} />
        <Route
          path="/users"
          component={UsersList}
          // 1st called
          onPost={createUser}
          // 2nd called if no redirect
          preload={preloadUsers}
        />
        <Route path="/" component={Home} />
      </Route>
    </Router>
  ),
  document.getElementById("app")
);

Affordance

As much as links (a), forms manipulate the current location. In the case of POST form submissions, the only difference is that location should be compound by submitted FormData. The onPost callback could either return a JSON or redirect. The target location could handle a POST, suspend while handling it and return associated data, through a useSubmission.

As much as the action extraction is very useful it shouldn't overstep into the routing territory, neither change Browser semantics. The first RFC suggests to change form default method to POST whenever a action attribute is defined with an action. Where does the <form method="get"> fit into it? It seems very asymmetrical. As off now, there's not even client a client-side navigation handling.

The action extraction can very well happen but without being constrained with by the routing and vice-versa.

[ryansolid]

The thing is it is going to be asymmetrical. Intentionally so. While this uses browser mechanisms I've found over the years that Query and Mutation have different needs. I think GraphQL was dead on making the Query a connected graph and Mutation a set of named RPC calls more or less. REST sucks for mutations. It is great for fetching and standardizing where to find data, but the second you are like I need to move a resource between 2 resource collections you can't properly represent it in a single verb anymore. And innately compound action has this problem and in so I have no intention of tying mutation to typical route URLs.

So assuming I'm not going to put it on the routes because of my intention to support RPC style with server functions, how should we handle form GET? Right now I have the benefit of if it isn't one of our custom actions it does native browser behavior. We could intercept all Forms and if it is a GET treat it like an Anchor, ie.. don't try to call the action and try to use the same rules, but then we'd need a mechanism to opt out similar to how we do with Anchors. Would using stuff like not same base URL or rel="external" or target="_self" be fine I guess.

I'm just trying to decide how important/intended this is. Mostly in that historically client side routers have never handled this case. It seems fine too, but we could also leave this to a future release. I'm very close on this release now. I just need to add some of the opt out behavior for preload and a couple more cache utilities. People can find it on the next branch and beta tags on npm.

[edygar]

The thing is it is going to be asymmetrical. Intentionally so. […]

Got it now. Maybe the intent would be better communicated if what was provided to the users was not a conflicting spec for the form but something else. Instead of modifying the form semantics, a future proof approach would be to name the entity appropriately with a custom component by the library built upon the form

I didn't want to compromise my argument with bad suggestions but I'm going to try anyways:

• <Server action={myAction}>
• <Remote action={myAction}>
• <RPC action={myAction}>

I'm just trying to decide how important/intended this is […]

About the GET forms, as it's doable in the userland, I think it's ok to postpone until there's more appeal to it. Making a Form component responsible of intercepting and navigating in case of a GET it's not very complicated, albeit it's a routing responsibility.

[ryansolid]

I'm not sure there is a conflict here. We only handle the form event for things that aren't prevented default and that are passed one of our actions specifically. Everything else works as normal. Uppercase <Form> was a consideration but then again with server component future similar to lowercase <a> it is very appealing to support native <form>. What I think I'm going to do is force the developer to post the method="post" on their forms if they want to use actions. I don't have the TS chops to make that happen at the moment. But there will be a runtime error. There already is one for server actions. But I will do so in the client as well so it is clear that if someone tries to submit a form with an action without method post it won't work. This way there is no conflict. Non-action URLs will know no better, and forms that use our action will be semantically correct.

[LexSwed]

@ryansolid is it possible to pause the rendering completely until createAsync resolves? I understand it can create waterfalls, but I want to avoid multiple rendering passes when e.g. loading translation files on the server, for translations to be available across components. So instead of every t('some-string') being undefined on the first pass, and then correct string, have the rendering paused until the files are loaded.

[LexSwed]

Technically, I could extract translation files reading out of the framework, but then it means the localisation files are requested per route, which is error prone, instead of by the components itself.

[ryansolid]

On the server we'd need a different mechanism. I will explore this with future versions of Solid. But generally the way you pause rendering is simply read it at a decision point. Like immediately have a <Show> component. But as you know, on the server we re-render from the nearest Suspense boundary which is the problem I think you are facing. As far as I've figured pause/resuming without compiling to expose like generators or async/await wouldn't be able to resume like that unless we brought the reactive system on the server and kept more of a tree in memory before finally combining it. Part of me wonders if the cache API could help in some way diminish the impact of more expensive calculations.