@solidjs/router 2.0.0-next.26 → 2.0.0-next.28

package/dist/server.js

@@ -24,6 +24,7 @@
 import { provideRequestEvent } from "@solidjs/web/storage";
 import { createBranches, getRouteMatches, mergeParams, peekLazySubtrees, resolveLazySubtree } from "./routing.js";
 import { extractSearchParams } from "./utils.js";
+import { serverRouteArgs, serverRouteOf } from "./serverRouteShared.js";
 // the instance is the provider component, so it (unlike an options object) is a function
 function isRouterInstance(options) {
     return typeof options === "function";
@@ -146,6 +147,11 @@ function runPreloads(event, branches, url, previousUrl, rootPreload) {
         if (!prevMatches[match] || matches[match].route !== prevMatches[match].route)
             event.router.dataOnly = true;
         const { route, params } = matches[match];
+        // A server component route's markup is collected like any query result:
+        // the same call (function id + derived args) the client is showing, so
+        // the response's region addresses what is mounted.
+        const server = serverRouteOf(route.component);
+        server && server.call(serverRouteArgs(route, params, location.query));
         route.preload &&
             route.preload({
                 params,

package/dist/serverRouteComponent.d.ts

@@ -0,0 +1,20 @@
+import type { Component } from "solid-js";
+import type { Params, RouteSectionProps, ServerRouteFunction, ServerRouteParams, TypedRouteConfig } from "./types.js";
+/**
+ * Use a server component as a route (experimental). `source` is a function
+ * of the router-derived {@link ServerRouteArgs} — this route's `params`, and
+ * `search` when the route declares a schema — resolving to a server
+ * component: typically a `"use server"` function wrapped in `query()` or
+ * `liveQuery()`, whose key the app names and revalidates. The router mounts
+ * the result with the outlet as `children` and calls the same source under
+ * preload intent, so link hover and single-flight collection warm it.
+ *
+ * `children` is the only client position the router fills, so the server
+ * component may declare no other. One that takes client handlers, refs, or
+ * slots has a client half — write an ordinary route component for it.
+ *
+ * ```ts
+ * defineRoute({ path: "/stories/:id", component: serverRouteComponent(query(storyView, "story")) });
+ * ```
+ */
+export declare function serverRouteComponent<P extends Params | TypedRouteConfig = Params, S = undefined>(source: ServerRouteFunction<P, S> | ((...args: never[]) => ReturnType<ServerRouteFunction<P, S>>)): Component<RouteSectionProps<unknown, ServerRouteParams<P>>>;

package/dist/serverRouteComponent.js

@@ -0,0 +1,90 @@
+// Server component routes (experimental — rides the experimental server
+// components surface in @solidjs/web; the arg shape may change).
+//
+// `serverRouteComponent(source)` turns a function of route arguments that
+// resolves to a component into a route `component`. It replaces the client
+// wrapper a server-component route used to need:
+//
+//   // before: a client component exists only to make the call
+//   const getStory = query(storyView, "story");
+//   component: props => {
+//     const View = dynamic(() => getStory(props.params.id));
+//     return <View>{props.children}</View>;
+//   }
+//   // after
+//   component: serverRouteComponent(query(storyView, "story"))
+//
+// The source is the app's: `query(fn, key)` for a request/response server
+// component, `liveQuery(fn, key)` for one that streams successive versions,
+// or any function of the args. The router does not choose the cache
+// strategy and does not own the key — `revalidate("story")` is the app's,
+// as it is for any query. What the router adds is the URL → call
+// translation: it derives the call's arguments from the match, mounts the
+// resolved component with the outlet as `children`, and calls the same
+// source under preload intent (link hover, `preloadRoute`, the single-flight
+// collector), so the query or live channel is warm before the navigation
+// renders against it.
+//
+// Arguments are derived, not read from a live location: the call's
+// `(function, arguments)` address keys the frame store and the query cache,
+// so the args must name precisely what the route depends on. They are the
+// params this route's pattern (with its ancestors') declares — never a
+// child's, so a layout does not refetch when a leaf param changes — and, only
+// when the route declares a `search` schema, its validated output.
+//
+// The router fills exactly one client position: `children`, with the outlet.
+// A server component that takes other client positions — handlers, refs,
+// named slots — has a client half, and that half is a client component; the
+// helper does not pretend otherwise. Write the wrapper for that route.
+import { dynamic } from "@solidjs/web";
+import { createComponent, DEV } from "solid-js";
+import { SERVER_ROUTE } from "./serverRouteShared.js";
+/**
+ * Use a server component as a route (experimental). `source` is a function
+ * of the router-derived {@link ServerRouteArgs} — this route's `params`, and
+ * `search` when the route declares a schema — resolving to a server
+ * component: typically a `"use server"` function wrapped in `query()` or
+ * `liveQuery()`, whose key the app names and revalidates. The router mounts
+ * the result with the outlet as `children` and calls the same source under
+ * preload intent, so link hover and single-flight collection warm it.
+ *
+ * `children` is the only client position the router fills, so the server
+ * component may declare no other. One that takes client handlers, refs, or
+ * slots has a client half — write an ordinary route component for it.
+ *
+ * ```ts
+ * defineRoute({ path: "/stories/:id", component: serverRouteComponent(query(storyView, "story")) });
+ * ```
+ */
+export function serverRouteComponent(
+// A source that ignores its args (an app shell) is `(...args: never[])`
+// once `query()` has typed it; that is the same call, so accept it too.
+source) {
+    const call = source;
+    // The value is a component only so it fits the `component` field; the
+    // router core never calls it — it mounts through the brand, with THIS
+    // level's params and the declared search output. A direct mount (a
+    // `lazy()` wrapper around the helper, a hand-written `<Route />`) would
+    // have only the merged params to call with: the same view under a second
+    // address, missing the cache and owning its own frame. Refuse it.
+    const route = () => {
+        throw new Error("serverRouteComponent(): mount it as a route's `component`" +
+            (DEV
+                ? " — the router derives the call from the match. It was rendered directly (through " +
+                    "lazy(), as the <Router> root, or outside a route). For an app shell, make it a " +
+                    "pathless layout route with children."
+                : ""));
+    };
+    function render(args, routeProps) {
+        // The source may answer a component, a promise of one, or (a live query)
+        // successive components; `dynamic`'s memo lands each the same way.
+        const View = dynamic(() => call(args()));
+        return createComponent(View, {
+            get children() {
+                return routeProps.children;
+            }
+        });
+    }
+    route[SERVER_ROUTE] = { call, render };
+    return route;
+}

package/dist/serverRouteShared.d.ts

@@ -0,0 +1,33 @@
+import type { Accessor } from "solid-js";
+import type { JSX } from "@solidjs/web";
+import type { Params, RouteDescription, RouteSectionProps, SearchParams, ServerRouteArgs } from "./types.js";
+export declare const SERVER_ROUTE: unique symbol;
+/**
+ * What `serverRouteComponent()` attaches to the route component it returns, and
+ * what the router core drives it through: `call` is the query-wrapped server
+ * function (preload and single-flight collection warm/collect through it),
+ * `render` mounts the resolved server component for the current args with
+ * the route's props (`children` is the outlet).
+ */
+export interface ServerRouteBrand {
+    call: (args: ServerRouteArgs<Params, unknown>) => unknown;
+    render: (args: Accessor<ServerRouteArgs<Params, unknown>>, route: RouteSectionProps) => JSX.Element;
+}
+export type BrandedRouteComponent = Function & {
+    [SERVER_ROUTE]?: ServerRouteBrand;
+};
+/** The brand carried by a route component built with `serverRouteComponent()`, if any. */
+export declare function serverRouteOf(component: unknown): ServerRouteBrand | undefined;
+/**
+ * Derive a server route's call arguments from a match: the match's params
+ * (this route's pattern and its ancestors' — never a child's) and the route's
+ * `search` schema output when one is declared. Reads `query` only when a
+ * schema exists, so a search-agnostic route never tracks the query string.
+ */
+export declare function serverRouteArgs(route: RouteDescription, params: Params, query: SearchParams): ServerRouteArgs<Params, unknown>;
+/**
+ * Structural equality for the args memo: a navigation produces fresh match
+ * objects even when this level's params are unchanged, and an equal call
+ * must not re-enter the source (and refetch).
+ */
+export declare function serverRouteArgsEqual(a: ServerRouteArgs<Params, unknown>, b: ServerRouteArgs<Params, unknown>): boolean;

package/dist/serverRouteShared.js

@@ -0,0 +1,39 @@
+import { validateSearch } from "./utils.js";
+export const SERVER_ROUTE = Symbol("solid-router.serverRoute");
+/** The brand carried by a route component built with `serverRouteComponent()`, if any. */
+export function serverRouteOf(component) {
+    return component?.[SERVER_ROUTE];
+}
+/**
+ * Derive a server route's call arguments from a match: the match's params
+ * (this route's pattern and its ancestors' — never a child's) and the route's
+ * `search` schema output when one is declared. Reads `query` only when a
+ * schema exists, so a search-agnostic route never tracks the query string.
+ */
+export function serverRouteArgs(route, params, query) {
+    const schema = route.key?.search;
+    let search;
+    if (schema) {
+        const raw = { ...query };
+        const outcome = validateSearch(schema, raw);
+        // Issues leave the raw values in place, matching useSearchParams: search
+        // strings are user input, so defaults belong in the schema itself.
+        search = outcome.issues ? raw : outcome.value;
+    }
+    return { params: { ...params }, search };
+}
+const shallowEqual = (a, b) => a === b ||
+    (!!a &&
+        !!b &&
+        typeof a === "object" &&
+        typeof b === "object" &&
+        Object.keys(a).length === Object.keys(b).length &&
+        Object.keys(a).every(k => a[k] === b[k]));
+/**
+ * Structural equality for the args memo: a navigation produces fresh match
+ * objects even when this level's params are unchanged, and an equal call
+ * must not re-enter the source (and refetch).
+ */
+export function serverRouteArgsEqual(a, b) {
+    return shallowEqual(a.params, b.params) && shallowEqual(a.search, b.search);
+}

package/dist/types.d.ts

@@ -141,6 +141,36 @@ export interface RouteSectionProps<T = unknown, P extends Params = Params> {
     children?: JSX.Element;
 }
 export type RouteSectionComponent<T = unknown, P extends Params = Params> = Component<RouteSectionProps<T, P>> | Component<Omit<RouteSectionProps<T, P>, "children">> | Component<{}>;
+/**
+ * What a server component route is called with (experimental): the params
+ * the route's pattern (and its ancestors') declares, plus — only when the
+ * route declares a `search` schema — that schema's validated output.
+ */
+export interface ServerRouteArgs<P extends Params | TypedRouteConfig = Params, S = undefined> {
+    params: ServerRouteParams<P>;
+    search: P extends TypedRouteConfig ? SearchOutputOf<P> : S;
+}
+/**
+ * `ServerRouteArgs<typeof route>`: a `defineFileRoute` config is a witness —
+ * params from its pattern, search from its schema — the way
+ * `RouteProps<typeof route>` reads it for a client page.
+ */
+export type ServerRouteParams<P> = P extends TypedRouteConfig<infer Pattern> ? RouteParams<Pattern> : Extract<P, Params>;
+type SearchOutputOf<Def> = Def extends {
+    search: infer Sch extends StandardSchemaV1<any, any>;
+} ? NonNullable<Sch["~standard"]["types"]>["output"] : undefined;
+/**
+ * The shape `serverRouteComponent()` accepts (experimental): a function of
+ * the router-derived {@link ServerRouteArgs} answering a server component —
+ * once (a `query`-wrapped `"use server"` function), or as successive
+ * versions (a `liveQuery`). The component's only client position is
+ * `children` — the route outlet, which the router fills.
+ */
+export type ServerRouteFunction<P extends Params | TypedRouteConfig = Params, S = undefined> = (args: ServerRouteArgs<P, S>) => ServerRouteView | Promise<ServerRouteView> | AsyncIterable<ServerRouteView>;
+/** The component a server route resolves to: `children` is its only client position. */
+export type ServerRouteView = Component<{
+    children?: JSX.Element;
+}>;
 declare const ROUTE_PATTERN: unique symbol;
 export interface TypedRouteConfig<S extends string = string> {
     readonly [ROUTE_PATTERN]: S;
@@ -336,12 +366,19 @@ export type Submission<T, U> = {
     readonly error: any;
     readonly url: string;
     clear: () => void;
-    retry: () => void;
+    /** Re-run the action with the same input; resolves to its result, like the original call. */
+    retry: () => Promise<U>;
 };
 export interface MaybePreloadableComponent extends Component {
     preload?: () => void;
 }
-export type CacheEntry = [number, Promise<any>, any, Intent | undefined, Signal<number> & {
-    count: number;
-}];
+export type CacheEntry = [
+    number,
+    Promise<any>,
+    any,
+    Intent | undefined,
+    Signal<number> & {
+        count: number;
+    }
+];
 export type NarrowResponse<T> = T extends ResponseEnvelope<infer U> ? U : Exclude<T, Response>;

package/dist/utils.d.ts

@@ -1,4 +1,4 @@
-import type { MatchFilters, PathMatch, RouteDescription, SearchParams, SetSearchParams } from "./types.js";
+import type { StandardSchemaV1, MatchFilters, PathMatch, RouteDescription, SearchParams, SetSearchParams } from "./types.js";
 export declare const mockBase = "http://sr";
 export declare function normalizePath(path: string, omitSlash?: boolean): string;
 /** Pathname stripped of search/hash and trailing slash, lowercased — the form link matching compares. */
@@ -6,6 +6,8 @@ export declare const comparablePath: (path: string) => string;
 export declare function resolvePath(base: string, path: string, from?: string): string | undefined;
 export declare function invariant<T>(value: T | null | undefined, message: string): T;
 export declare function joinPaths(from: string, to: string): string;
+/** Run a Standard Schema synchronously — the only mode search params support. */
+export declare function validateSearch(schema: StandardSchemaV1<any, any>, raw: Record<string, any>): import("./types.js").StandardSchemaResult<any>;
 export declare function extractSearchParams(url: URL): SearchParams;
 export declare function createMatcher<S extends string>(path: S, partial?: boolean, matchFilters?: MatchFilters<S>): (location: string) => PathMatch | null;
 export declare function scoreRoute(route: RouteDescription): number;

package/dist/utils.js

@@ -35,6 +35,13 @@ export function invariant(value, message) {
 export function joinPaths(from, to) {
     return normalizePath(from).replace(/\/*(\*.*)?$/g, "") + normalizePath(to);
 }
+/** Run a Standard Schema synchronously — the only mode search params support. */
+export function validateSearch(schema, raw) {
+    const outcome = schema["~standard"].validate(raw);
+    if (outcome instanceof Promise)
+        throw new Error("Async Standard Schema validation is not supported for search params");
+    return outcome;
+}
 export function extractSearchParams(url) {
     const params = {};
     url.searchParams.forEach((value, key) => {

package/package.json

@@ -6,7 +6,7 @@
     "Ryan Turnquist"
   ],
   "license": "MIT",
-  "version": "2.0.0-next.26",
+  "version": "2.0.0-next.28",
   "homepage": "https://github.com/solidjs/solid-router#readme",
   "repository": {
     "type": "git",
@@ -52,10 +52,16 @@
   },
   "peerDependencies": {
     "@solidjs/web": "^2.0.0-rc.9",
+    "filesystem-routing": ">=0.4.0",
     "solid-js": "^2.0.0-rc.9"
   },
+  "peerDependenciesMeta": {
+    "filesystem-routing": {
+      "optional": true
+    }
+  },
   "scripts": {
-    "build": "rm -rf dist && tsc && rollup -c",
+    "build": "rm -rf dist && tsc && rollup -c && node scripts/check-fs-gate.mjs",
     "test": "vitest run && vitest run --config vitest.config.server.ts && npm run test:types",
     "test:watch": "vitest",
     "test:server": "vitest run --config vitest.config.server.ts",