RFC: Refinement to make Router Data APIs more Intuitive

[ryansolid]

Summary

This proposal looks at naming and type changes to the router that can aid in users learning journey and set the right expectations up front about the behavior of the routers Data APIs.

I'm very interested in people's feedback especially around the potential renaming of the cache function. Please leave comments below.

Background

While I've been content with the direction of the router we've definitely seen a lot of confusion around the APIs. Gathering the feedback has lead to a few realizations where I believe we can make small adjustments that might make the purpose and capabilities of certain router features more obvious.

Proposal

This proposal involves a few small changes but the overall result I hope achieves the goal.

1. Rename load function to preload

We only renamed it from data recently, but I chose load at the time because this function runs during preload, during route navigation, during single flight.. basically any time we potentially wanted to load things. I felt that preload didn't capture the work it was doing.

However, load has meaning from other routers that seems to put a lot more expectation there. Solid Router's load functions are completely optional. All the real work happens in the components. It is just a tool to lift things up for optimization reasons. Some of those optimization reasons don't even matter if the code is preloaded on hover (or if you are server rendering).

We've seen people trying to build blocking/guarding patterns here to limited success and it is because these methods are designed (and have always been even when they were data) to be non-blocking pre-emptive aids. If these blocked they'd sort of defeat the purpose. That is to get things launching ahead of time. We know that the async data isn't available at the time they launch which is why we designed APIs that let you save the work later initially passing signals down or now with our cache functions.

In so load doesn't seem to carry the right connotations. This is a pre-emptive optimization, its a preload rather than where the actual work happens. It can fire it off, it can help with places you hover but might never navigate to, but it is not an opportunity to add yet another waterfall into the pipeline.

2. Rename cache function

I admit I don't have a good name here yet but it is clear that developers don't understand this API. They avoid it even because it says cache. While we have some vision that more cache-like functionality could be extended into this primitive in the future it isn't really that currently (like maybe add a cache option). It and action form a duo that handles our Responses and it isn't obvious to people that you need cache to handle router concerns.

The responsibility of cache is:

1. Dedupe requests on the server/client navigation by key
2. Trigger reactive revalidations on the client by key
3. Handle back-navigation if things have not mutated

These are a cache of sorts but they are non-persistent on reload. It is basically like Tanstack Query.

In so we probably should rename this primitive in a way that is more obvious to its purpose. Suggestions I've seen are data, ie (Server?) Data and Action functions similar to early SolidStart. query similar to Tanstack.

Neither of these suggest that there is Router tie in mind you. I'm definitely open to suggestions. Please leave yours in the comments.

3. Have Response Helper's return Response Types

So trying to solve types in cache and action lead to some pretty funny types. Mostly these functions can return Responses via things like json or redirect where we don't want the response types to impact the output. The way we did this was have the helpers return never which excludes them from the types. But it causes other confusion related to code the runs after them in functions, people not realizing they returned values etc..

So what I'm proposing now is that we have a special typed generic Response type that is returned from these helpers and it is the cache and action functions that filter out the Response instead. This is more accurate description of what is going on here should let TS aid in understanding the functionality rather than just be a fancy trick.

Impact

Hopefully these changes will make the intent of portions of the router much more obvious to people learning the APIs while still retaining their powerful behavior.

Adoption

The first 2 changes can be supported in a minor release with a phase out plan that the old names still work but are deprecated until a later minor release. The 3rd change would also happen in a minor release and hopefully won't impact the types of projects negatively since they are part of a closed cycle. Whether the filtering happens in the helper or in the cache or action function shouldn't matter since in neither cases they escape.

The renaming will require some docs changes, but they can roll out as available since that part will remain backwards compatible.

[Brendonovich]

1. Love it
2. data makes the most sense to me, but that's not saying much. All the name ideas seem to be almost but not quite correct.
3. Love it

[atilafassina]

1. Absolutely!! preload would save us a lot of explaining to newcomers.

2. How about keyed(), since its functionality is rooted in keying the action per flight, then It kinda borrows a bit of the concept from <Show>. Or perhaps dedupe() to make its main functionality very clear.

3. Love this!

[bigmistqke]

I like dedupe() a lot. It is what a cache does, but it doesn't have that long lasting connotation.

[MAST1999]

I like dedupe() a lot as well.

It was the first thing I thought of, knowing what it does.

[brenelz]

1. Yeah i agree with the others that preload makes more sense.
2. Yeah I'm unsure of what a good name for the cache function would be
3. This makes sense to me

[brenelz]

I think i'm learning towards query

const user = query(async () {

}, "user")

[davedbase]

1 and 3 seem pretty reasonable. For 2, this is really tricky.

This is kind of adapted from TanStack query and sticking with query seems to be pretty reasonable. Here's a bunch of ideas and variations of that direction:

1. useQuery
2. withQuery
3. fromQuery
4. makeQuery (this pattern worked nicely for Solid Primitives)
5. bindQuery
6. createQuery

My preference personally is makeQuery or createQuery. Deviating from query here are some different options:

1. bindData
2. retrieve
3. extract
4. useData
5. bind :-/

[sabercoy]

I think I also like createQuery as opposed to just query
just query feels like a "one and done" sort of call for data, where createQuery feels like a longer-living thing that can be retriggered and induce behaviors-through-time, more similar to createEffect or createSignal

[Brendonovich]

I'm not a fan of createQuery as the create prefix implies that the function is connected to the reactive system or has some cleanup internally, like makeEventListener vs createEventListener in solid primitives. makeQuery seems more appropriate of the two and would probably warrant renaming action to makeAction.

[sabercoy]

I'm not a fan of createQuery as the create prefix implies that the function is connected to the reactive system or has some cleanup internally, like makeEventListener vs createEventListener in solid primitives. makeQuery seems more appropriate of the two and would probably warrant renaming action to makeAction.

Ah yeah youre right. I was mixing cache with createAsync in my mind for a second. In that case I wouldnt mind query or makeQuery if thats a convention in solid primitives

[danieljcafonso]

Regarding renaming cache, considering we drew inspiration from TanStack Query, I'm leaning toward query
I've always looked at cache as a query that has a query key, which is a cache identifier. I've taught this to people this way, and considering people are familiar with TanStack Query, it draws the parallel and makes it easier to understand.

[peerreynders]

2. Sticking with the electronics theme established by signals, I could rationalize calling cache a via instead as it acts as a distribution point/staging area for async data to enter the reactive domain.

Is it intuitive? No. But at least it doesn't set unrealistic expectations.

[KookiKodes]

1. Rename load function to preload

I absolutely love the idea of naming this preload, that makes more sense😄 !

2. Rename cache function

Given the way this function works similar to how tanstack queries work, I think this function having query in the name makes the most sense. I've seen it mention to use createQuery. While I like the name, I agree with @Brendonovich here, naming the function createQuery would be too confusing as it sounds like it ties into the reactive system. What about using defineQuery and defineAction?

3. Have Response Helper's return Response Types

I am all in with these changes.

[sparklog]

My Viewpoints

Strongly Support Renaming the Load Function to Preload

From my personal experience, the load function indeed caused some confusion. When I first started using load(), I mistakenly thought that once I used load() in a route, the component for that route would automatically include the data loaded by load(). However, you actually need to create a signal in the component, such as createAsync. While it's a reasonable and clear basic principle to use signals to manage data flow, I made similar mistakes. Therefore, renaming it to preload can more accurately convey its purpose and avoid misunderstandings.

No Strong Opinion on Renaming the Cache Function

My understanding is that functions created with the cache function are loaded as needed, especially to avoid redundant calculations on multiple loads. Because of this feature, once a function is loaded with cache in load(), it doesn't need to be recalculated when retrieved through signals in the component. Therefore, the name cache seems reasonable to me. However, if there's a better name that can more clearly convey its functionality, I would support that too.

Fully Support Returning Response Types

I look forward to the great convenience this will bring. Returning response types will make type definitions more accurate and help understand the functionality, reducing potential confusion.

Thanks to the developers for their hard work. I hope to keep learning and eventually contribute to the community myself.

[katywings]

1. I like the rename to preload
2. As I havent seen it in other suggestions, I wanna bring up buffer. Its short and pretty much summarizes what we are doing with cache.

The wiki entry about buffer reads: `a data buffer (or just buffer) is a region of memory used to store data temporarily while it is being moved from one place to another.

[alex-crabnebula]

1. The name preload is a lot more intuitive than load, so it's not even a question, just do it already!
2. Even the name cache infers daunting complexity, the name query sounds like just another version of resource with integrated fetcher, buffer sounds like lazy state. What it actually does is to pipe data from different state into the current route, thus I'm for pipe.
3. Please do, it makes a lot more sense than the current types.

[ryansolid]

Thanks everyone for the comments.

1. This seems like a no-brainer from the responses.

2. I'm not sold on a different name. The challenge is that it dedupes and it revalidates. So query might fit as people suggest but we have to be careful that we aren't suggesting it is like createAsync or equivalent to Tanstack Query on its own. My one argument for data is it is so generic no one can have much opinion about what it does outside of it is Router data. Functionally something like key could make sense, but it is a bit overloaded. Not that data isn't but there is more expectation key would mean something. I think a challenge here is this has to carry a concept when discussing, so calling it dedupe is hard. It needs to capture the essence of that it is the GET to action's POST. We have Route ____ and Route Actions. I think the biggest challenge with data is we used to call the load function data so that is in recent memory. And the thing returned from load functions, mostly for backwards compatibility is also called data. So there is a difference between the data prop we send from the load function and this caching/deduping mechanism.

3. This also seems clearly desired.

I will start working on 1 & 3 and hopefully in the next little bit will have more clarity on #2. Love all your feedback so far.

[apatrida]

why one function? why is redirect not available when you don't want revalidate?...

from reply on X:

It is clearer to separate router aware from revalidatable queries. it is useful to redirect also on queries where you never want revalidate or dedupe. THEN pick a name got each of these traits:

• routable result
• deduped
• revalidatable (actionable, reloadable)

therefore compose any or all of these as you want.

actionable(dedupe(routable(myServerFunc)))

routable(myServerFunc)

dedupe(myServerFunc)

dedupe(routable(myServerFunc))
...

[ryansolid]

I started here, but the function wrappers actually are hard with hydration/serialization because of the order things run. I tried to conceive a generic approach to these sort of wrappers and then just was like ok, collapse them because it was too specific. It was easier to just make a new wrapper that didn't have some of the functionality. Deduping/serialization/revalidation is too tied together. If you dedupe on the client you do have a short-lived cache, that cache needs to hydrate beyond the individual resource queries.

Now all action and cache need the routable functionality or if they didn't it would common place enough it that people would mess it up the second they needed that functionality. So having them compose makes little sense. Now the real question is does it make sense to have an additional routable function that isn't one of those.

If people want to have router aware server functions working in their own data caching/serialization solutions. Things like Tanstack Query. I'm open to it. So maybe we are looking for 2 names? I don't think this alleviates the name for our data fetching solution, just suggests that there should be a mechanism to handle redirects from returned responses.

[apatrida]

@ryansolid We have two wrappers we use extensively. One takes the cache function and rips out caching and leaves the code for Response handling which allows redirects from server functions. The other is action that by default sets no revalidation passiveAction is what we call it (for now).

The latter looks like:

import { action, Action, json } from '@solidjs/router';

const IMPOSSIBLE_REVALIDATION = '!!!impossible value!!!';

export function passiveAction<T extends Array<any>, U = void>(
  fn: (...args: T) => Promise<U>,
  name?: string
): Action<T, U> {
  return action(async (...args: T) => {
    return fn(...args).then((response) => {
      if (response instanceof Response) {
        const existingHeader = response.headers.get('X-Revalidate');
        if (!existingHeader) {
          response.headers.set('X-Revalidate', IMPOSSIBLE_REVALIDATION);
        }
        return response;
      } else {
        return json(response, { revalidate: IMPOSSIBLE_REVALIDATION });
      }
    });
  }, name);
}

And we use this 95% of the time, normal action 5% of the time as most of our actions are not about data that we loaded via cache so we don't want the error in favor of reloading data which could cause a lot of load on servers (since we have millions of users). This as a silent failure of causing a mass amount of traffic can't happen, so we want the default the opposite.

the routable function is cache with the fn GET optimization at the top and the handle response portion kept, the append to response promise or not, and the dataonly stuff in there turned into logging only because we aren't sure what it is for and watned to see if it occurs in nature for our use case (does not).

We use this to wrap some core things that are called on page start to catch an auth token error (i.e. token expired) and also on a function that is called every minute, and most the others will just error out and let these other functions catch the logged out / expired condition for us.

[ryansolid]

Passive Action doesn't surprise me. I understand the defaults don't scale at all. The hope is most people would use it like React Query which would mean they'd specify keys, and then for those advanced cases just no use action at all.

The main thinking is while actions uniquely provide Progressive Enhancement with forms, if you aren't buying into the whole cache/action thing I don't know if it'd work properly anyway. In something like Next/SvelteKit/Remix you don't have this flexibility. It's all in built in. If using programmatic APIs there are a lot more options. I guess encoding the response is convenient compared to having the client look at the response and decide if it wants to do a redirect from the client.

What I'm still trying to figure out is in what situation would I ever want to rip out the cache out of the cache function. Which kind of why I wanted to rename it because I thought people maybe were avoiding it for some reason. I understand it is because you don't get routing with naked server functions. But is there something about the cache function that is unsuitable? Like one of its behaviors that doesn't work for you?

[apatrida]

We avoid cache to avoid anything interfering with state and data that we manage more specifically, such as endless paging or cases where we need to be able to update the value like we could with a resource (refetch, mutate). Yet in some of those cases we still need the redirect for invalid token or 2FA events (until we do popups for them). We cache maybe 12 API's that are called in most SSR rendering (including passing ENV values back to client dynamically, user session transfer of part of the cookie from server to client, basic user data, tenant data, and user settings/privs for that tenant) ... the rest is queried in resources via direct fetch calls in the BFF (backend for frontend, or what you call "use server" functions).

[peerreynders]

I think that that familiar names like cache, dedup, query, data, buffer, etc. focus too much on what it does (it is a function after all, so verbs seem natural) and understate what it is.

Borrowing monikers from Ports and Adapters a name like port or asyncPort clarifies that it is the async half of an async-to-reactive data bridge/gateway (createAsync() being the reactive adapter).

I suspect that it would be a valuable reminder that an architecturally significant boundary is being crossed.

[davedbase]

This did trigger the thought about what is inputting and what is outputting. The async produces a promise with a result afterall.

I'm liking a name closer in relevance to unwrapping the async promise. Just spitballing here but this feels right to me...

createAsync/useResult

Input/output...port/adapter...initializing/consuming. The create and use prefixes help compound the verb and noun of what's specifically happening with the primitive.

🤷‍♂️