@solidjs/router 2.0.0-next.16 → 2.0.0-next.18

package/README.md

@@ -20,7 +20,7 @@ Explore the official [documentation](https://docs.solidjs.com/solid-router) for
 - **Plain Anchors**: no link component — `<a>` elements get `aria-current`, `data-active`, and `data-pending` automatically via compiler-claimed anchors
 - **Universal Rendering**: one factory for browser, hash, memory, and server rendering; history adapters are imports, so unused ones never enter your bundle
 - **Preload Functions**: parallel data fetching following the render-as-you-fetch pattern, triggered eagerly on link hover/focus
-- **Data APIs with Caching**: `query` and `action` with deduplication, revalidation, single-flight mutations, and progressive enhancement
+- **Data APIs with Caching**: `query` and `action` with deduplication, revalidation, single-flight mutations, and progressive enhancement — plus experimental `liveQuery` for keyed queries over live streams
 - **Typed Search Params**: opt-in per-route [Standard Schema](https://github.com/standard-schema/standard-schema) validation — `search.page` is a `number`, not `"2"`
 
 ## Table of Contents
@@ -519,6 +519,38 @@ getUser.keyFor(5); // "users[5]"
 
 Revalidate with the `revalidate` export or by setting `revalidate` keys on action responses — the whole key invalidates every entry for the query, `keyFor` invalidates one.
 
+### `liveQuery` (experimental)
+
+`query`'s live sibling: a keyed query over a value-shaped stream. The function is an async iterable (typically an async generator server function) whose yields are successive **values of one logical query** — each yield is the current state, not an event — with the contract that it re-yields current state on every invocation:
+
+```tsx
+const roomMessages = liveQuery(async function* (room: string) {
+  "use server";
+  yield await db.messages.list(room); // current state, immediately
+  for await (const change of db.messages.watch(room)) {
+    yield await db.messages.list(room); // current state again, on change
+  }
+}, "messages");
+```
+
+Declaring it is what makes it live — no separate wrapper, and server functions are declared GET at creation just like `query`. Consumption is the same story as `query`: Solid primitives, no router-specific async wrapper. The value updates in place as yields arrive:
+
+```tsx
+const messages = createMemo(() => roomMessages(params.room));
+return <For each={messages()}>{msg => <Message {...msg} />}</For>;
+```
+
+One connection per key (name + arguments) is shared by every consumer: late subscribers get the latest value immediately, delivery is latest-wins, and the connection closes when the last consumer leaves. A connected stream that dies transiently (network, 5xx) reconnects with exponential backoff while the latest value keeps serving; a definite rejection (4xx) or a first-connect failure surfaces to the consumer like any thrown error.
+
+Live queries ride the router's existing machinery rather than adding their own:
+
+- **Preload** — calling one in a preload function warms the connection, so navigation renders against an already-delivered value instead of holding the transition on connect.
+- **SSR** — the document face renders the first value; hydration adopts it and reconnects. Server-side, consumers of a key within one request observe the same value.
+- **Revalidation** — explicit `revalidate(key)` reconnects (the producer re-yields current state by contract). The post-mutation sweep leaves healthy connections alone: the stream is its own freshness mechanism.
+- **Single-flight** — a mutation's flight payload pushes straight into open channels, so mutated state lands in the same round trip.
+
+The callable carries the `query` conventions (`key`, `keyFor`) plus a reactive `status(...args)` read (`"idle" | "connecting" | "connected" | "reconnecting" | "closed"`) for surfacing connection state in UI.
+
 ### `action`
 
 A router action is *an action with a URL* — Solid's mutation primitive plus URL addressability, submission tracking, and response handling. Data helpers come from the router; response helpers (`redirect`, `reload`) come from `@solidjs/web` — they're protocol-level and work without the router:

package/dist/data/action.js

@@ -7,7 +7,7 @@ import { decodeFlashCookie } from "@solidjs/web/server-functions/server";
 import { provideFlashDecoder, provideFlightConsumer, useRouter } from "../routing.js";
 import { setRouterFormHandler } from "./events.js";
 import { mockBase, setFunctionName } from "../utils.js";
-import { cacheKeyOp, hashKey, revalidate, query } from "./query.js";
+import { cacheKeyOp, deliverFlightData, hashKey, revalidate, query } from "./query.js";
 const submitHooksSymbol = Symbol("routerActionSubmitHooks");
 const settledHooksSymbol = Symbol("routerActionSettledHooks");
 const invokeSymbol = Symbol("routerActionInvoke");
@@ -328,8 +328,10 @@ function applyResponseMetadata(metadata, navigate, flightData) {
     }
     // invalidate
     cacheKeyOp(keys, entry => (entry[0] = 0));
-    // set cache
+    // set cache — and fan the payload out to other keyed stores (live query
+    // channels adopt delivered values instead of reconnecting)
     flightData && Object.keys(flightData).forEach(k => query.set(k, flightData[k]));
+    flightData && deliverFlightData(flightData);
     // trigger revalidation inside the same transition as the navigation, so
     // the redirect commits atomically with fresh data: surviving consumers
     // (shared layouts) the flight payload didn't seed refetch and hold the

package/dist/data/index.d.ts

@@ -1,2 +1,3 @@
 export { action, useSubmissions, useAction, type Action } from "./action.js";
 export { query, revalidate, type CachedFunction } from "./query.js";
+export { liveQuery, type LiveFunction, type LiveQueryStatus } from "./liveQuery.js";

package/dist/data/index.js

@@ -1,2 +1,3 @@
 export { action, useSubmissions, useAction } from "./action.js";
 export { query, revalidate } from "./query.js";
+export { liveQuery } from "./liveQuery.js";

package/dist/data/liveQuery.d.ts

@@ -0,0 +1,44 @@
+export type LiveQueryStatus = "idle" | "connecting" | "connected" | "reconnecting" | "closed";
+export type LiveFunction<T extends (...args: any) => any> = T extends (...args: infer A) => infer R ? ((...args: A) => AsyncIterable<Awaited<R> extends AsyncIterable<infer V> ? V : Awaited<R>>) & {
+    keyFor: (...args: A) => string;
+    key: string;
+    status: (...args: A) => LiveQueryStatus;
+} : never;
+/**
+ * Declares a keyed live query over a value-shaped stream: an async-iterable
+ * producer whose yields are successive VALUES of one logical query, with the
+ * contract that the producer re-yields current state on every invocation.
+ * liveQuery IS the live layer — no separate declaration needed:
+ *
+ * - One connection per (name + args) key, shared by every consumer. Late
+ *   subscribers receive the latest value immediately, delivery is
+ *   latest-wins, and the connection closes when the last consumer leaves.
+ * - A connected stream that dies transiently (network, 5xx) reconnects with
+ *   exponential backoff — the latest value keeps serving meanwhile. A
+ *   definite rejection (4xx: the transport stamps HTTP statuses onto
+ *   failures) ends the channel and surfaces the error to consumers, as does
+ *   a first-connect failure.
+ * - Server functions are declared GET at creation (like `query`). Live
+ *   queries participate in single-flight on the delivery side: a mutation's
+ *   flight payload pushes straight into open channels (the mutation
+ *   response is the round trip), while the post-mutation sweep leaves the
+ *   healthy connection in place — the live stream stays authoritative.
+ * - Calling under preload intent warms the channel (a temporary hold keeps
+ *   it open through the preload window), so navigation renders against an
+ *   already-connected stream instead of holding the transition on connect
+ *   plus first yield. Outside preload, calling remains free — only a real
+ *   pull connects.
+ * - SSR: the document face renders the first value; hydration adopts it and
+ *   reconnects. Channels are request-scoped on the server, so every
+ *   consumer of a key in one render observes the same value. Explicit
+ *   `revalidate(key)` reconnects (the producer re-yields current state on
+ *   invocation), and `status(...args)` is a reactive read of the channel's
+ *   wire state.
+ *
+ * ```ts
+ * const roomMessages = liveQuery(getMessages, "messages");
+ * // in a component — one connection, however many consumers:
+ * const messages = createMemo(() => roomMessages(props.room));
+ * ```
+ */
+export declare function liveQuery<T extends (...args: any) => any>(fn: T, name: string): LiveFunction<T>;

package/dist/data/liveQuery.js

@@ -0,0 +1,377 @@
+import { createSignal } from "solid-js";
+import { getRequestEvent, getServerFunctionMetadata, getServerFunctionRPC, isServer, isServerFunction } from "@solidjs/web";
+import { getIntent } from "../routing.js";
+import { hashKey, matchKey, registerFlightDataHook, registerRevalidateHook } from "./query.js";
+// Matches query's preload lifetime: a channel warmed by preload intent
+// stays held this long waiting for its navigation.
+const PRELOAD_TIMEOUT = 5000;
+// The live-source brand (registered symbol — no transport import needed):
+// computations meeting a branded iterable apply live SSR policy (document
+// face takes the first value; hydration re-runs the compute after adoption
+// to reconnect). liveQuery writes it on both faces itself — the server-side
+// resolved iterable and the client-side multicast iterable — so a producer
+// needs no separate live() declaration to be live here.
+const LIVE_SOURCE = Symbol.for("solid.LiveSource");
+const channelMap = new Map();
+// Status outlives the channel (an "idle"/"closed" read after teardown is
+// meaningful), so signals live in their own keyed map.
+const statusMap = new Map();
+function statusSignal(key) {
+    let s = statusMap.get(key);
+    // ownedWrite: the first write happens synchronously inside whatever
+    // computation pulled the channel open — this is channel-owned state, not
+    // the computation's own.
+    if (!s)
+        statusMap.set(key, (s = createSignal("idle", { ownedWrite: true })));
+    return s;
+}
+function wake(ch) {
+    const waiters = [...ch.waiters];
+    ch.waiters.clear();
+    for (const w of waiters)
+        w();
+}
+const noStatus = () => { };
+async function connect(ch) {
+    const gen = ch.gen;
+    const setStatus = ch.report ? statusSignal(ch.key)[1] : noStatus;
+    let attempts = 0;
+    setStatus(ch.version ? "reconnecting" : "connecting");
+    while (true) {
+        try {
+            const result = await ch.call();
+            if (gen !== ch.gen || ch.done) {
+                // superseded (reconnect) or torn down while connecting: the arrived
+                // stream must still be ended or its request leaks
+                result?.[Symbol.asyncIterator] && result[Symbol.asyncIterator]().return?.();
+                return;
+            }
+            // A live()-declared producer's own retry loop erases deaths from the
+            // value stream and reports them through onstatus — forward those into
+            // the channel's status so both producer kinds read the same. Its
+            // "closed" is redundant with our own done handling below.
+            if (result !== null && typeof result === "object") {
+                try {
+                    result.onstatus = (state) => {
+                        if (gen === ch.gen && state !== "closed")
+                            setStatus(state);
+                    };
+                }
+                catch { }
+            }
+            const it = result !== null && typeof result === "object" && result[Symbol.asyncIterator]
+                ? result[Symbol.asyncIterator]()
+                : (async function* () {
+                    yield result;
+                })();
+            ch.close = () => {
+                try {
+                    const r = it.return && it.return();
+                    if (r && typeof r.then === "function")
+                        r.then(undefined, () => { });
+                }
+                catch { }
+            };
+            while (true) {
+                const r = await it.next();
+                if (gen !== ch.gen || ch.done)
+                    return;
+                if (r.done)
+                    break;
+                ch.latest = r.value;
+                ch.version++;
+                attempts = 0; // healthy value: backoff resets
+                setStatus("connected");
+                wake(ch);
+            }
+            ch.done = true;
+            setStatus("closed");
+            wake(ch);
+            return;
+        }
+        catch (error) {
+            if (gen !== ch.gen || ch.done)
+                return;
+            const status = error?.status;
+            if (!ch.version || (typeof status === "number" && status >= 400 && status < 500)) {
+                // Terminal: never connected (fail like a normal call), or a
+                // definite rejection — the transport stamps HTTP statuses onto
+                // failures, and a 4xx means the server understood and refused;
+                // retrying cannot change the answer. Consumers rethrow (after
+                // draining the latest value), surfacing to error boundaries.
+                ch.error = error;
+                ch.done = true;
+                setStatus("closed");
+                wake(ch);
+                return;
+            }
+            // A stream that had delivered died transiently (network, 5xx,
+            // severed stream): the channel IS the live layer — reconnect with
+            // backoff, latest value keeps serving meanwhile. (A live()-declared
+            // producer never reaches here; its transport retries.)
+            setStatus("reconnecting");
+            let timer, wakeUp;
+            await new Promise(resolve => {
+                wakeUp = () => resolve();
+                timer = setTimeout(wakeUp, Math.min(500 * 2 ** attempts++, 10000));
+                // connectivity returning wakes the sleep early
+                if (typeof addEventListener === "function")
+                    addEventListener("online", wakeUp, { once: true });
+            });
+            clearTimeout(timer);
+            // a timer-woken sleep leaves its once-listener behind otherwise —
+            // one leaked closure per backoff cycle until an online event fires
+            if (typeof removeEventListener === "function")
+                removeEventListener("online", wakeUp);
+            if (gen !== ch.gen || ch.done)
+                return;
+        }
+    }
+}
+function teardown(ch) {
+    // Deferred so a same-key resubscribe in the same tick (a memo re-running
+    // its compute) reuses the connection instead of thrashing it.
+    queueMicrotask(() => {
+        if (ch.count > 0 || ch.map.get(ch.key) !== ch)
+            return;
+        const ended = ch.done; // completed/failed on its own — "closed" persists
+        ch.done = true;
+        ch.close();
+        wake(ch);
+        if (ch.retain)
+            return; // request-scoped: latest stays replayable
+        ch.map.delete(ch.key);
+        if (ch.report && !ended)
+            statusSignal(ch.key)[1]("idle");
+    });
+}
+function openChannel(map, key, call, report, retain) {
+    let ch = map.get(key);
+    if (!ch) {
+        ch = {
+            key,
+            map,
+            count: 0,
+            version: 0,
+            latest: undefined,
+            error: undefined,
+            done: false,
+            waiters: new Set(),
+            gen: 0,
+            close: () => { },
+            call,
+            report,
+            retain
+        };
+        map.set(key, ch);
+        connect(ch);
+    }
+    return ch;
+}
+// The consumer half: a branded iterable whose iterators subscribe to the
+// channel lazily (first pull connects — a hydration trace or speculative
+// call opens nothing), replay the latest value immediately, then follow
+// with latest-wins delivery.
+function subscriberIterable(open) {
+    return {
+        [LIVE_SOURCE]: true,
+        [Symbol.asyncIterator]() {
+            const ch = open();
+            ch.count++;
+            let seen = 0;
+            let released = false;
+            const release = () => {
+                if (released)
+                    return;
+                released = true;
+                if (--ch.count === 0)
+                    teardown(ch);
+            };
+            const pull = async () => {
+                while (true) {
+                    if (ch.error && seen >= ch.version) {
+                        release();
+                        throw ch.error;
+                    }
+                    if (ch.version > seen) {
+                        seen = ch.version;
+                        return { done: false, value: ch.latest };
+                    }
+                    if (ch.done) {
+                        release();
+                        return { done: true, value: undefined };
+                    }
+                    await new Promise(resolve => ch.waiters.add(resolve));
+                }
+            };
+            return {
+                next: () => (released ? Promise.resolve({ done: true, value: undefined }) : pull()),
+                return(value) {
+                    release();
+                    return Promise.resolve({ done: true, value });
+                }
+            };
+        }
+    };
+}
+function reconnectChannel(ch) {
+    ch.gen++;
+    ch.close();
+    ch.error = undefined;
+    ch.done = false;
+    connect(ch);
+}
+function push(ch, value) {
+    ch.latest = value;
+    ch.version++;
+    wake(ch);
+}
+// Live channels participate in both data protocols. Registered on first
+// liveQuery() call, not at module scope: a side-effectful top level would
+// anchor this module into graphs that never use it.
+//
+// - Explicit revalidate(key) (force) reconnects — the producer re-yields
+//   current state on invocation by contract.
+// - The post-mutation sweep (force=false) does NOT reconnect: the
+//   connection is alive and is itself the freshness mechanism — a
+//   push-driven producer yields the mutated state on its own, and tearing
+//   down healthy connections on every mutation defeats the model.
+// - Single-flight payloads deliver INTO open channels, exactly as they seed
+//   the query cache: the mutation response is the round trip, the channel
+//   adopts the value immediately, and the live stream stays authoritative
+//   for everything after.
+let hooked = false;
+function hookRevalidate() {
+    if (hooked)
+        return;
+    hooked = true;
+    registerRevalidateHook((keys, force) => {
+        if (!force)
+            return;
+        for (const [k, ch] of channelMap) {
+            if (keys === undefined || matchKey(k, keys))
+                reconnectChannel(ch);
+        }
+    });
+    registerFlightDataHook(data => {
+        for (const k in data) {
+            const ch = channelMap.get(k);
+            if (!ch || ch.done)
+                continue;
+            const v = data[k];
+            if (v !== null && typeof v === "object" && v[Symbol.asyncIterator]) {
+                // a live key collected server-side arrives stream-shaped: adopt
+                // its yields for as long as it runs (it ends with the response
+                // body); the channel's own connection remains authoritative
+                (async () => {
+                    try {
+                        for await (const value of v) {
+                            if (ch.done)
+                                return;
+                            push(ch, value);
+                        }
+                    }
+                    catch { }
+                })();
+            }
+            else
+                push(ch, v);
+        }
+    });
+}
+/**
+ * Declares a keyed live query over a value-shaped stream: an async-iterable
+ * producer whose yields are successive VALUES of one logical query, with the
+ * contract that the producer re-yields current state on every invocation.
+ * liveQuery IS the live layer — no separate declaration needed:
+ *
+ * - One connection per (name + args) key, shared by every consumer. Late
+ *   subscribers receive the latest value immediately, delivery is
+ *   latest-wins, and the connection closes when the last consumer leaves.
+ * - A connected stream that dies transiently (network, 5xx) reconnects with
+ *   exponential backoff — the latest value keeps serving meanwhile. A
+ *   definite rejection (4xx: the transport stamps HTTP statuses onto
+ *   failures) ends the channel and surfaces the error to consumers, as does
+ *   a first-connect failure.
+ * - Server functions are declared GET at creation (like `query`). Live
+ *   queries participate in single-flight on the delivery side: a mutation's
+ *   flight payload pushes straight into open channels (the mutation
+ *   response is the round trip), while the post-mutation sweep leaves the
+ *   healthy connection in place — the live stream stays authoritative.
+ * - Calling under preload intent warms the channel (a temporary hold keeps
+ *   it open through the preload window), so navigation renders against an
+ *   already-connected stream instead of holding the transition on connect
+ *   plus first yield. Outside preload, calling remains free — only a real
+ *   pull connects.
+ * - SSR: the document face renders the first value; hydration adopts it and
+ *   reconnects. Channels are request-scoped on the server, so every
+ *   consumer of a key in one render observes the same value. Explicit
+ *   `revalidate(key)` reconnects (the producer re-yields current state on
+ *   invocation), and `status(...args)` is a reactive read of the channel's
+ *   wire state.
+ *
+ * ```ts
+ * const roomMessages = liveQuery(getMessages, "messages");
+ * // in a component — one connection, however many consumers:
+ * const messages = createMemo(() => roomMessages(props.room));
+ * ```
+ */
+export function liveQuery(fn, name) {
+    hookRevalidate();
+    // liveQuery implies GET, exactly as query does: reads belong on the GET
+    // transport (cacheable URLs, no single-flight enveloping). An explicit
+    // GET(fn) or live(GET(fn)) declaration passes through untouched.
+    if (isServerFunction(fn) && !getServerFunctionMetadata(fn)?.method) {
+        const rpc = getServerFunctionRPC();
+        if (rpc)
+            fn = rpc.GET(fn);
+    }
+    const liveFn = ((...args) => {
+        const key = name + hashKey(args);
+        if (isServer) {
+            const e = getRequestEvent();
+            if (!e) {
+                // No request scope (static render, tests): hand the source through
+                // whole, branded, so the signals layer applies live SSR policy
+                // (first value, then client takeover).
+                const result = fn(...args);
+                const brand = (r) => {
+                    if (r !== null && typeof r === "object" && r[Symbol.asyncIterator])
+                        r[LIVE_SOURCE] = true;
+                    return r;
+                };
+                return result !== null && typeof result === "object" && typeof result.then === "function"
+                    ? result.then(brand)
+                    : brand(result);
+            }
+            // Request-scoped channels: two consumers of one key during one render
+            // must observe the SAME first value (query's request cache gives its
+            // reads the same guarantee). Channels live in the event, retained
+            // past teardown so a later consumer replays the settled value instead
+            // of reinvoking; the producer still closes with its last consumer.
+            const router = (e.router || (e.router = {}));
+            const channels = router.liveChannels || (router.liveChannels = new Map());
+            return subscriberIterable(() => openChannel(channels, key, () => fn(...args), false, true));
+        }
+        const open = () => openChannel(channelMap, key, () => fn(...args), true, false);
+        // Preload warms the channel, exactly as calling a query in a preload
+        // function warms its cache: connect now, hold a temporary consumer slot
+        // so refcounting doesn't close it before navigation renders. When the
+        // real consumer arrives it inherits the live connection (first pull
+        // replays the already-arrived value — the transition doesn't hold);
+        // when navigation never comes, the hold lapses and teardown closes it.
+        if (getIntent() === "preload") {
+            const ch = open();
+            ch.count++;
+            setTimeout(() => {
+                if (--ch.count === 0)
+                    teardown(ch);
+            }, PRELOAD_TIMEOUT);
+        }
+        return subscriberIterable(open);
+    });
+    liveFn.keyFor = (...args) => name + hashKey(args);
+    liveFn.key = name;
+    liveFn.status = (...args) => statusSignal(name + hashKey(args))[0]();
+    return liveFn;
+}

package/dist/data/query.d.ts

@@ -1,4 +1,9 @@
 import type { CacheEntry, NarrowResponse } from "../types.js";
+export declare function registerRevalidateHook(hook: (keys: string[] | void, force: boolean) => void): void;
+export declare function registerFlightDataHook(hook: (data: Record<string, any>) => void): void;
+/** Fans a single-flight payload out to registered keyed stores (the query
+ * cache itself is seeded by the caller via query.set). */
+export declare function deliverFlightData(data: Record<string, any>): void;
 /**
  * Revalidates the given cache entry/entries.
  */
@@ -18,4 +23,5 @@ export declare namespace query {
     export var clear: () => void;
     export { _a as delete };
 }
+export declare function matchKey(key: string, keys: string[]): boolean;
 export declare function hashKey<T extends Array<any>>(args: T): string;

package/dist/data/query.js

@@ -38,6 +38,23 @@ function getCache() {
         throw new Error("Cannot find cache context");
     return (req.router || (req.router = {})).cache || (req.router.cache = new Map());
 }
+// Other keyed stores participating in the data protocols (live query
+// channels) register here — revalidate() stays the one invalidation verb,
+// and single-flight payloads reach every keyed store, not just the cache.
+const revalidateHooks = [];
+export function registerRevalidateHook(hook) {
+    revalidateHooks.push(hook);
+}
+const flightHooks = [];
+export function registerFlightDataHook(hook) {
+    flightHooks.push(hook);
+}
+/** Fans a single-flight payload out to registered keyed stores (the query
+ * cache itself is seeded by the caller via query.set). */
+export function deliverFlightData(data) {
+    for (const hook of flightHooks)
+        hook(data);
+}
 /**
  * Revalidates the given cache entry/entries.
  */
@@ -47,6 +64,9 @@ export function revalidate(key, force = true) {
         force && (entry[0] = 0); //force cache miss
         entry[4][1](now); // retrigger live signals
     });
+    const keys = key === undefined ? undefined : Array.isArray(key) ? key : [key];
+    for (const hook of revalidateHooks)
+        hook(keys, force);
 }
 export function cacheKeyOp(key, fn) {
     key && !Array.isArray(key) && (key = [key]);
@@ -291,7 +311,7 @@ query.set = (key, value) => {
 };
 query.delete = (key) => getCache().delete(key);
 query.clear = () => getCache().clear();
-function matchKey(key, keys) {
+export function matchKey(key, keys) {
     for (let k of keys) {
         if (k && key.startsWith(k))
             return true;

package/dist/fs.js

@@ -37,7 +37,9 @@ export function fileRoutes(entries) {
         }
         let component = components.get(ref.src);
         if (!component) {
-            component = lazy(ref.import, ref.src);
+            // moduleUrl is lazy()'s third argument as of solid 2.0.0-rc.1 (options
+            // moved second); route components are default exports, so no { export }.
+            component = lazy(ref.import, undefined, ref.src);
             components.set(ref.src, component);
         }
         return component;