@solidjs/router 0.10.1 → 0.10.3

package/README.md

@@ -350,8 +350,53 @@ You can nest indefinitely - just remember that only leaf nodes will become their
 </Route>
 ```
 
+## Load Functions
+
+Even with smart caches it is possible that we have waterfalls both with view logic and with lazy loaded code. With load functions, we can instead start fetching the data parallel to loading the route, so we can use the data as soon as possible. The load function is called when the Route is loaded or eagerly when links are hovered.
+
+As its only argument, the load function is passed an object that you can use to access route information:
+
+```js
+import { lazy } from "solid-js";
+import { Route } from "@solidjs/router";
+
+const User = lazy(() => import("./pages/users/[id].js"));
+
+// load function
+function loadUser({params, location}) {
+  // do loading
+}
+
+// Pass it in the route definition
+<Route path="/users/:id" component={User} load={loadUser} />;
+```
+
+| key      | type                                              | description                                                                                                                   |
+| -------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| params   | object                                            | The route parameters (same value as calling `useParams()` inside the route component)                                         |
+| location | `{ pathname, search, hash, query, state, key}`    | An object that you can use to get more information about the path (corresponds to [`useLocation()`](#uselocation))        |
+| intent | `"initial", "navigate", "native", "preload"` | Indicates why this function is being called. <ul><li>"initial" - the route is being initially shown (ie page load)</li><li>"native" - navigate originated from the browser (eg back/forward)</li><li>"navigate" - navigate originated from the router (eg call to navigate or anchor clicked)</li><li>"preload" - not navigating, just preloading (eg link hover)</li></ul> |
+
+
+A common pattern is to export the load function and data wrappers that corresponds to a route in a dedicated `route.data.js` file. This way, the data function can be imported without loading anything else.
+
+```js
+import { lazy } from "solid-js";
+import { Route } from "@solidjs/router";
+import loadUser from "./pages/users/[id].data.js";
+const User = lazy(() => import("/pages/users/[id].js"));
+
+// In the Route definition
+<Route path="/users/:id" component={User} load={loadUser} />;
+```
+
+The return value of the `load` function is passed to the page component when called at anytime other than `"preload"`, so you can initialize things in there, or alternatively use our new Data APIs:
+
+
 ## Data APIs
 
+Keep in mind these are completely optional. To use but showcase the power of our load mechanism.
+
 ### `cache`
 
 To prevent duplicate fetching and to trigger handle refetching we provide a cache api. That takes a function and returns the same function.
@@ -370,6 +415,36 @@ This cache accomplishes the following:
 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.
 
+Using it with load function might look like:
+
+```js
+import { lazy } from "solid-js";
+import { Route } from "@solidjs/router";
+import { getUser } from ... // the cache function
+
+const User = lazy(() => import("./pages/users/[id].js"));
+
+// load function
+function loadUser({params, location}) {
+  void getUser(params.id)
+}
+
+// Pass it in the route definition
+<Route path="/users/:id" component={User} load={loadUser} />;
+```
+
+Inside your page component you:
+
+```jsx
+// pages/users/[id].js
+import { getUser } from ... // the cache function
+
+export default function User(props) {
+  const user = createAsync(() => getUser(props.params.id));
+  return <h1>{user().name}</h1>;
+}
+```
+
 Cached function has a few useful methods for getting the key that are useful for invalidation.
 ```ts
 let id = 5;
@@ -423,16 +498,16 @@ const deleteTodo = action(async (formData: FormData) => {
   await api.deleteTodo(id)
 })
 
-<form action={deleteUser} method="post">
+<form action={deleteTodo} method="post">
   <input type="hidden" name="id" value={todo.id} />
   <button type="submit">Delete</button>
 </form>
 ```
 Instead with `with` you can write this:
 ```js
-const deleteUser = action(api.deleteUser)
+const deleteUser = action(api.deleteTodo)
 
-<form action={deleteUser.with(todo.id)} method="post">
+<form action={deleteTodo.with(todo.id)} method="post">
   <button type="submit">Delete</button>
 </form>
 ```
@@ -504,59 +579,6 @@ const updateTodo = action(async (todo: Todo) => {
 })
 ```
 
-### Load Functions
-
-Even with the cache API it is possible that we have waterfalls both with view logic and with lazy loaded code. With load functions, we can instead start fetching the data parallel to loading the route, so we can use the data as soon as possible.
-
-To do this, we can call our cache function in the load function.
-
-```js
-import { lazy } from "solid-js";
-import { Route } from "@solidjs/router";
-import { getUser } from ... // the cache function
-
-const User = lazy(() => import("./pages/users/[id].js"));
-
-// load function
-function loadUser({params, location}) {
-  void getUser(params.id)
-}
-
-// Pass it in the route definition
-<Route path="/users/:id" component={User} load={loadUser} />;
-```
-
-The load function is called when the Route is loaded or eagerly when links are hovered. Inside your page component you:
-
-```jsx
-// pages/users/[id].js
-import { getUser } from ... // the cache function
-
-export default function User(props) {
-  const user = createAsync(() => getUser(props.params.id));
-  return <h1>{user().name}</h1>;
-}
-```
-
-As its only argument, the load function is passed an object that you can use to access route information:
-
-| key      | type                                              | description                                                                                                                   |
-| -------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
-| params   | object                                            | The route parameters (same value as calling `useParams()` inside the route component)                                         |
-| location | `{ pathname, search, hash, query, state, key}`    | An object that you can use to get more information about the path (corresponds to [`useLocation()`](#uselocation))        |
-
-A common pattern is to export the preload function and data wrappers that corresponds to a route in a dedicated `route.data.js` file. This way, the data function can be imported without loading anything else.
-
-```js
-import { lazy } from "solid-js";
-import { Route } from "@solidjs/router";
-import loadUser from "./pages/users/[id].data.js";
-const User = lazy(() => import("/pages/users/[id].js"));
-
-// In the Route definition
-<Route path="/users/:id" component={User} load={loadUser} />;
-```
-
 ## Config Based Routing
 
 You don't have to use JSX to set up your routes; you can pass an object:
@@ -834,6 +856,41 @@ Related without Outlet component it has to be passed in manually. At which point
 
 These have been replaced by a load mechanism. This  allows link hover preloads (as the load function can be run as much as wanted without worry about reactivity). It support deduping/cache APIs which give more control over how things are cached. It also addresses TS issues with getting the right types in the Component without `typeof` checks.
 
+That being said you can reproduce the old pattern largely by turning off preloads at the router level and then injecting your own Context:
+
+```js
+import { lazy } from "solid-js";
+import { Route } from "@solidjs/router";
+
+const User = lazy(() => import("./pages/users/[id].js"));
+
+// load function
+function loadUser({params, location}) {
+  const [user] = createResource(() => params.id, fetchUser);
+  return user;
+}
+
+// Pass it in the route definition
+<Router preload={false}>
+  <Route path="/users/:id" component={User} load={loadUser} />
+</Router>
+```
+
+And then in your component taking the page props and putting them in a Context.
+```js
+function User(props) {
+  <UserContext.Provider value={props.data}>
+    {/* my component content  */}
+  </UserContext.Provider>
+}
+
+// Somewhere else
+function UserDetails() {
+  const user = useContext(UserContext)
+  // render stuff
+}
+```
+
 ## SPAs in Deployed Environments
 
 When deploying applications that use a client side router that does not rely on Server Side Rendering you need to handle redirects to your index page so that loading from other URLs does not cause your CDN or Hosting to return not found for pages that aren't actually there.

package/dist/index.d.ts

@@ -4,4 +4,4 @@ export * from "./lifecycle";
 export { useHref, useIsRouting, useLocation, useMatch, useNavigate, useParams, useResolvedPath, useSearchParams, useBeforeLeave, } from "./routing";
 export { mergeSearchString as _mergeSearchString } from "./utils";
 export * from "./data";
-export type { Location, LocationChange, NavigateOptions, Navigator, OutputMatch, Params, RouteSectionProps, RouteLoadFunc, RouteLoadFuncArgs, RouteDefinition, RouterIntegration, RouterOutput, RouterUtils, SetParams, BeforeLeaveEventArgs } from "./types";
+export type { Location, LocationChange, NavigateOptions, Navigator, OutputMatch, Params, RouteSectionProps, RouteLoadFunc, RouteLoadFuncArgs, RouteDefinition, RouterIntegration, RouterUtils, SetParams, BeforeLeaveEventArgs } from "./types";

package/dist/index.js

@@ -239,13 +239,15 @@ function createRoutes(routeDef, base = "") {
   const {
     component,
     load,
-    children
+    children,
+    metadata
   } = routeDef;
   const isLeaf = !children || Array.isArray(children) && !children.length;
   const shared = {
     key: routeDef,
     component,
-    load
+    load,
+    metadata
   };
   return asArray(routeDef.path).reduce((acc, path) => {
     for (const originalPath of expandOptionals(path)) {
@@ -559,6 +561,12 @@ function createRouteContext(router, parent, outlet, match, params) {
     load
   } = match().route;
   const path = createMemo(() => match().path);
+  component && component.preload && component.preload();
+  const data = load ? load({
+    params,
+    location,
+    intent: intent || "initial"
+  }) : undefined;
   const route = {
     parent,
     pattern,
@@ -567,6 +575,7 @@ function createRouteContext(router, parent, outlet, match, params) {
     outlet: () => component ? createComponent(component, {
       params,
       location,
+      data,
       get children() {
         return outlet();
       }
@@ -575,12 +584,6 @@ function createRouteContext(router, parent, outlet, match, params) {
       return resolvePath(base.path(), to, path());
     }
   };
-  component && component.preload && component.preload();
-  load && load({
-    params,
-    location,
-    intent: intent || "initial"
-  });
   return route;
 }
 
@@ -611,6 +614,20 @@ const createRouterComponent = router => props => {
 };
 function Routes(props) {
   const matches = createMemo(() => getRouteMatches(props.branches, props.routerState.location.pathname));
+  if (isServer) {
+    const e = getRequestEvent();
+    e && (e.routerMatches || (e.routerMatches = [])).push(matches().map(({
+      route,
+      path,
+      params
+    }) => ({
+      path: route.originalPath,
+      pattern: route.pattern,
+      match: path,
+      params,
+      metadata: route.metadata
+    })));
+  }
   const params = createMemoObject(() => {
     const m = matches();
     const params = {};

package/dist/routers/components.d.ts

@@ -1,9 +1,9 @@
 import type { Component, JSX } from "solid-js";
-import type { MatchFilters, RouteLoadFunc, RouterIntegration, RouteSectionProps } from "../types";
+import type { MatchFilters, RouteLoadFunc, RouteDefinition, RouterIntegration, RouteSectionProps } from "../types";
 export type BaseRouterProps = {
     base?: string;
     root?: Component<RouteSectionProps>;
-    children?: JSX.Element;
+    children?: JSX.Element | RouteDefinition | RouteDefinition[];
 };
 export declare const createRouterComponent: (router: RouterIntegration) => (props: BaseRouterProps) => JSX.Element;
 export type RouteProps<S extends string> = {
@@ -12,5 +12,6 @@ export type RouteProps<S extends string> = {
     load?: RouteLoadFunc;
     matchFilters?: MatchFilters<S>;
     component?: Component;
+    metadata?: Record<string, any>;
 };
 export declare const Route: <S extends string>(props: RouteProps<S>) => JSX.Element;

package/dist/routers/components.jsx

@@ -1,4 +1,5 @@
 /*@refresh skip*/
+import { getRequestEvent, isServer } from "solid-js/web";
 import { children, createMemo, createRoot, mergeProps, on, Show } from "solid-js";
 import { createBranches, createRouteContext, createRouterContext, getRouteMatches, RouteContextObj, RouterContextObj } from "../routing";
 import { createMemoObject } from "../utils";
@@ -14,6 +15,17 @@ export const createRouterComponent = (router) => (props) => {
 };
 function Routes(props) {
     const matches = createMemo(() => getRouteMatches(props.branches, props.routerState.location.pathname));
+    if (isServer) {
+        const e = getRequestEvent();
+        e &&
+            (e.routerMatches || (e.routerMatches = [])).push(matches().map(({ route, path, params }) => ({
+                path: route.originalPath,
+                pattern: route.pattern,
+                match: path,
+                params,
+                metadata: route.metadata
+            })));
+    }
     const params = createMemoObject(() => {
         const m = matches();
         const params = {};

package/dist/routing.js

@@ -56,12 +56,13 @@ export const useBeforeLeave = (listener) => {
     onCleanup(s);
 };
 export function createRoutes(routeDef, base = "") {
-    const { component, load, children } = routeDef;
+    const { component, load, children, metadata } = routeDef;
     const isLeaf = !children || (Array.isArray(children) && !children.length);
     const shared = {
         key: routeDef,
         component,
-        load
+        load,
+        metadata
     };
     return asArray(routeDef.path).reduce((acc, path) => {
         for (const originalPath of expandOptionals(path)) {
@@ -350,6 +351,10 @@ export function createRouteContext(router, parent, outlet, match, params) {
     const { base, location } = router;
     const { pattern, component, load } = match().route;
     const path = createMemo(() => match().path);
+    component &&
+        component.preload &&
+        component.preload();
+    const data = load ? load({ params, location, intent: intent || "initial" }) : undefined;
     const route = {
         parent,
         pattern,
@@ -359,6 +364,7 @@ export function createRouteContext(router, parent, outlet, match, params) {
             ? createComponent(component, {
                 params,
                 location,
+                data,
                 get children() {
                     return outlet();
                 }
@@ -368,9 +374,5 @@ export function createRouteContext(router, parent, outlet, match, params) {
             return resolvePath(base.path(), to, path());
         }
     };
-    component &&
-        component.preload &&
-        component.preload();
-    load && load({ params, location, intent: intent || "initial" });
     return route;
 }

package/dist/types.d.ts

@@ -2,6 +2,7 @@ import type { Component, JSX, Signal } from "solid-js";
 declare module "solid-js/web" {
     interface RequestEvent {
         response?: Response;
+        routerMatches?: OutputMatch[][];
         routerCache?: Map<any, any>;
         initialSubmission?: Submission<any, any>;
         serverOnly?: boolean;
@@ -47,18 +48,20 @@ export interface RouteLoadFuncArgs {
     location: Location;
     intent: Intent;
 }
-export type RouteLoadFunc = (args: RouteLoadFuncArgs) => void;
-export interface RouteSectionProps {
+export type RouteLoadFunc<T = unknown> = (args: RouteLoadFuncArgs) => T;
+export interface RouteSectionProps<T = unknown> {
     params: Params;
     location: Location;
+    data?: T;
     children?: JSX.Element;
 }
-export type RouteDefinition<S extends string | string[] = any> = {
+export type RouteDefinition<S extends string | string[] = any, T = unknown> = {
     path?: S;
     matchFilters?: MatchFilters<S>;
-    load?: RouteLoadFunc;
+    load?: RouteLoadFunc<T>;
     children?: RouteDefinition | RouteDefinition[];
-    component?: Component<RouteSectionProps>;
+    component?: Component<RouteSectionProps<T>>;
+    metadata?: Record<string, any>;
 };
 export type MatchFilter = readonly string[] | RegExp | ((s: string) => boolean);
 export type PathParams<P extends string | readonly string[]> = P extends `${infer Head}/${infer Tail}` ? [...PathParams<Head>, ...PathParams<Tail>] : P extends `:${infer S}?` ? [S] : P extends `:${infer S}` ? [S] : P extends `*${infer S}` ? [S] : [];
@@ -73,10 +76,11 @@ export interface RouteMatch extends PathMatch {
     route: Route;
 }
 export interface OutputMatch {
-    originalPath: string;
-    pattern: string;
     path: string;
+    pattern: string;
+    match: string;
     params: Params;
+    metadata?: Record<string, any>;
 }
 export interface Route {
     key: unknown;
@@ -86,6 +90,7 @@ export interface Route {
     load?: RouteLoadFunc;
     matcher: (location: string) => PathMatch | null;
     matchFilters?: MatchFilters;
+    metadata?: Record<string, any>;
 }
 export interface Branch {
     routes: Route[];
@@ -107,16 +112,6 @@ export interface RouterUtils {
     go(delta: number): void;
     beforeLeave: BeforeLeaveLifecycle;
 }
-export interface OutputMatch {
-    originalPath: string;
-    pattern: string;
-    path: string;
-    params: Params;
-}
-export interface RouterOutput {
-    url?: string;
-    matches: OutputMatch[][];
-}
 export interface RouterContext {
     base: RouteContext;
     location: Location;

package/package.json

@@ -6,7 +6,7 @@
     "Ryan Turnquist"
   ],
   "license": "MIT",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "homepage": "https://github.com/solidjs/solid-router#readme",
   "repository": {
     "type": "git",