@nifrajs/web 5.5.1 → 5.7.0

package/src/query.ts

@@ -11,6 +11,7 @@
  * + navigation use the path cache; component-level interactive data (search, infinite scroll, polling)
  * uses this arbitrary-keyed query cache. The two coexist.
  */
+import { adoptClient, type LiveQuery, querySeam } from "./internal/query-seam.ts"
 
 /** A query's lifecycle status. `pending` = no data yet; `success`/`error` once it has settled once. */
 export type QueryStatus = "pending" | "success" | "error"
@@ -43,6 +44,11 @@ export interface QueryOptions {
   /** Data stays fresh this long (ms) after a fetch; older ⇒ refetch on the next `fetch()`. Overrides
    * the client default for this key. */
   readonly staleTime?: number
+  /**
+   * Live keys the data depends on, as the page's loaders declare them with `ctx.live()`. While the
+   * query is mounted, a change to one refetches it. Needs `live({ queryKeys: true })`.
+   */
+  readonly live?: readonly string[]
 }
 
 export interface QueryClientOptions {
@@ -147,6 +153,9 @@ export interface QueryClient {
   dehydrate: () => DehydratedState
   /** Seed the cache from a {@link dehydrate} snapshot (client boot). Existing fresher entries win. */
   hydrate: (state: DehydratedState) => void
+  /** Drop every cached query: mounted ones go back to pending and refetch, the rest are removed. A
+   * live app calls it on every query client in the page when the viewer changes. */
+  clear: () => void
 }
 
 /**
@@ -180,10 +189,33 @@ function keyMatchesPrefix(key: unknown, prefix: unknown): boolean {
   )
 }
 
-interface Entry {
+/** What both kinds of entry carry for a page with live refresh. */
+interface LiveFields {
+  live: readonly string[]
+  subscribers: number
+  readonly lq: LiveQuery
+}
+
+/** The live tick now; 0 on a page without live refresh. */
+const liveTick = (): number => querySeam()?.tick() ?? 0
+
+/** New keys while mounted are tracked again: a change to a new key before now never reached it. */
+function relive(entry: LiveFields, live: readonly string[] | undefined): void {
+  if (live === undefined) return
+  if (live.length === entry.live.length && live.every((key, i) => key === entry.live[i])) return
+  entry.live = [...live]
+  if (entry.subscribers === 0) return
+  querySeam()?.track(entry.lq, false)
+  querySeam()?.track(entry.lq, true)
+}
+
+interface Entry extends LiveFields {
   readonly key: unknown
   fn: () => Promise<unknown>
   staleTime: number
+  /** The {@link liveTick} at the start of the latest fetch, and of the fetch that produced `state`. */
+  startTick: number
+  dataTick: number
   state: QueryState
   promise: Promise<unknown> | undefined
   /** The {@link generation} the in-flight {@link promise} started at - so a fetch begun *before* an
@@ -192,7 +224,6 @@ interface Entry {
   /** Bumped by `invalidateQueries`/`refetch` to supersede any in-flight fetch begun before it. */
   generation: number
   invalidated: boolean
-  subscribers: number
   /** Scheduled eviction time (set when subscribers hit 0; cleared on resubscribe). */
   gcAt: number | undefined
   readonly listeners: Set<() => void>
@@ -248,10 +279,22 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
   // between renders). All the fetch/dedup/generation machinery lives here so query(), prefetchQuery(),
   // setQueryData(), and invalidateQueries() share exactly one implementation.
   const makeEntry = (key: unknown, fn: () => Promise<unknown>, staleTime: number): Entry => {
+    const lq: LiveQuery = {
+      keys: () => entry.live,
+      tick: () =>
+        entry.promise !== undefined && entry.promiseGen === entry.generation
+          ? entry.startTick
+          : entry.dataTick,
+      refresh: () => invalidateEntry(entry),
+    }
     const entry: Entry = {
       key,
       fn,
       staleTime,
+      live: [],
+      lq,
+      startTick: 0,
+      dataTick: 0,
       state: PENDING,
       promise: undefined,
       promiseGen: 0,
@@ -287,6 +330,8 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
       if (!force && entry.state.status === "success" && !isStale())
         return Promise.resolve(entry.state.data) // fresh cache hit - no fn call
       const gen = entry.generation
+      const started = liveTick()
+      entry.startTick = started
       entry.setState({ ...entry.state, isFetching: true }) // show the background/initial fetch
       const promise = (async () => {
         try {
@@ -296,6 +341,7 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
           // that superseded this one publishes the post-mutation data.
           if (gen !== entry.generation) return data
           entry.invalidated = false
+          entry.dataTick = started
           entry.setState(successState(data, now()))
           return data
         } catch (error) {
@@ -320,10 +366,14 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
         entry.subscribers++
         entry.gcAt = undefined // in use again - cancel any pending eviction
         entry.listeners.add(listener)
+        if (entry.subscribers === 1) querySeam()?.track(lq, true)
         return () => {
           entry.listeners.delete(listener)
           entry.subscribers--
-          if (entry.subscribers === 0) entry.gcAt = now() + gcTime
+          if (entry.subscribers === 0) {
+            entry.gcAt = now() + gcTime
+            querySeam()?.track(lq, false)
+          }
         }
       },
       fetch: () => entry.run(false),
@@ -332,35 +382,50 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
     return entry
   }
 
-  // Get an entry by key, or create + insert a fresh one. `fn`/`staleTime` re-bind on an existing entry.
-  const upsert = (key: unknown, fn: () => Promise<unknown>, staleTime: number): Entry => {
+  const invalidateEntry = (entry: Entry): void => {
+    entry.invalidated = true // next fetch refetches even within staleTime
+    // Supersede any in-flight fetch begun before this point - its result is pre-mutation and must
+    // not resolve as "fresh" or clear `invalidated`. The refetch below (or the next `fetch()`)
+    // starts a new generation that publishes the post-mutation data.
+    entry.generation++
+    if (entry.subscribers > 0) void entry.handle.refetch().catch(() => {}) // refresh mounted now (best-effort)
+  }
+
+  // Get an entry by key, or create + insert a fresh one. `fn`/`staleTime`/`live` re-bind on an
+  // existing entry; `live` stays as it is when the call names none (a write, a hydration).
+  const upsert = (
+    key: unknown,
+    fn: () => Promise<unknown>,
+    staleTime: number,
+    live?: readonly string[],
+  ): Entry => {
     const h = hashQueryKey(key)
     const existing = cache.get(h)
     if (existing !== undefined) {
       existing.fn = fn
       existing.staleTime = staleTime
+      relive(existing, live)
       return existing
     }
     const entry = makeEntry(key, fn, staleTime)
+    relive(entry, live)
     cache.set(h, entry)
     return entry
   }
 
   const query = <T>(key: unknown, fn: () => Promise<T>, opts?: QueryOptions): QueryHandle<T> => {
     sweep()
-    return upsert(key, fn as () => Promise<unknown>, opts?.staleTime ?? defaultStaleTime)
-      .handle as QueryHandle<T>
+    return upsert(
+      key,
+      fn as () => Promise<unknown>,
+      opts?.staleTime ?? defaultStaleTime,
+      opts?.live ?? [],
+    ).handle as QueryHandle<T>
   }
 
   const invalidateQueries = (keyOrPrefix: unknown): void => {
     for (const entry of cache.values()) {
-      if (!keyMatchesPrefix(entry.key, keyOrPrefix)) continue
-      entry.invalidated = true // next fetch refetches even within staleTime
-      // Supersede any in-flight fetch begun before this point - its result is pre-mutation and must
-      // not resolve as "fresh" or clear `invalidated`. The refetch below (or the next `fetch()`)
-      // starts a new generation that publishes the post-mutation data.
-      entry.generation++
-      if (entry.subscribers > 0) void entry.handle.refetch().catch(() => {}) // refresh mounted now (best-effort)
+      if (keyMatchesPrefix(entry.key, keyOrPrefix)) invalidateEntry(entry)
     }
     for (const entry of infinite.values()) {
       if (keyMatchesPrefix(entry.key, keyOrPrefix)) entry.invalidate()
@@ -391,6 +456,7 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
     // and clear the invalidated flag (the caller just supplied fresh data).
     entry.generation++
     entry.invalidated = false
+    entry.dataTick = liveTick()
     entry.setState(successState(data, now()))
   }
 
@@ -400,7 +466,12 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
     opts?: QueryOptions,
   ): Promise<void> => {
     sweep()
-    await upsert(key, fn as () => Promise<unknown>, opts?.staleTime ?? defaultStaleTime).run(false)
+    await upsert(
+      key,
+      fn as () => Promise<unknown>,
+      opts?.staleTime ?? defaultStaleTime,
+      opts?.live,
+    ).run(false)
   }
 
   const dehydrate = (): DehydratedState => {
@@ -433,8 +504,11 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
       // Don't clobber a client entry that's already fresher than the server snapshot (the client may
       // have refetched between SSR and hydration). Seed only when we have no successful data or the
       // incoming snapshot is newer.
-      if (entry.state.status !== "success" || q.updatedAt > entry.state.updatedAt)
+      if (entry.state.status !== "success" || q.updatedAt > entry.state.updatedAt) {
+        // Read before any live load took a watermark: the first grant of its keys refetches it.
+        entry.dataTick = 0
         entry.setState(successState(q.data, q.updatedAt))
+      }
     }
     // An infinite entry needs its page options before it can exist, so a snapshot for a key not yet
     // queried waits here until `infiniteQuery` creates it.
@@ -473,15 +547,16 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
   }
 
   // Infinite entries live in their own map (their data shape + fetch model differ from plain queries).
-  interface InfiniteEntry<T, P> {
+  interface InfiniteEntry<T, P> extends LiveFields {
     readonly key: unknown
     handle: InfiniteQueryHandle<T, P>
     rebind: (fn: (p: P) => Promise<T>, opts: InfiniteQueryOptions<T, P>) => void
     /** Mark stale, drop an in-flight fetch's result, and refetch when mounted. */
     invalidate: () => void
+    /** Back to pending, dropping an in-flight fetch's result; refetch the first page when mounted. */
+    reset: () => void
     /** Take a dehydrated snapshot unless the entry already holds fresher data. */
     seed: (data: InfiniteData<unknown, unknown>, updatedAt: number) => void
-    subscribers: number
     gcAt: number | undefined
   }
   const infinite = new Map<string, InfiniteEntry<unknown, unknown>>()
@@ -495,9 +570,12 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
     let fn = fetchPage
     let opts = initialOpts
     let state: QueryState<InfiniteData<T, P>> = PENDING as QueryState<InfiniteData<T, P>>
+    const pending = state
     let generation = 0
     let invalidated = false
     let promise: Promise<InfiniteData<T, P>> | undefined
+    let startTick = 0
+    let dataTick = 0
     const listeners = new Set<() => void>()
     const emit = (): void => {
       for (const l of listeners) l()
@@ -532,12 +610,15 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
     const runPaged = (build: () => Promise<InfiniteData<T, P>>): Promise<InfiniteData<T, P>> => {
       if (promise !== undefined) return promise
       const gen = ++generation
+      const started = liveTick()
+      startTick = started
       setState({ ...state, isFetching: true })
       const p = (async () => {
         try {
           const data = await build()
           if (gen !== generation) return data
           invalidated = false
+          dataTick = started
           setState(successState(data, now()))
           return data
         } catch (error) {
@@ -566,10 +647,14 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
         entry.subscribers++
         entry.gcAt = undefined
         listeners.add(listener)
+        if (entry.subscribers === 1) querySeam()?.track(lq, true)
         return () => {
           listeners.delete(listener)
           entry.subscribers--
-          if (entry.subscribers === 0) entry.gcAt = now() + gcTime
+          if (entry.subscribers === 0) {
+            entry.gcAt = now() + gcTime
+            querySeam()?.track(lq, false)
+          }
         }
       },
       fetch: () => fetchFirst(false),
@@ -614,12 +699,18 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
         return p !== undefined && p !== null
       },
     }
+    const lq: LiveQuery = {
+      keys: () => entry.live,
+      tick: () => (promise !== undefined ? startTick : dataTick),
+      refresh: () => entry.invalidate(),
+    }
     const entry: InfiniteEntry<T, P> = {
       key,
       handle,
       rebind: (nextFn, nextOpts) => {
         fn = nextFn
         opts = nextOpts
+        relive(entry, nextOpts.live ?? [])
       },
       invalidate: () => {
         invalidated = true
@@ -629,18 +720,50 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
         promise = undefined
         if (entry.subscribers > 0) void handle.refetch().catch(() => {})
       },
+      reset: () => {
+        invalidated = true
+        generation++
+        promise = undefined
+        dataTick = 0
+        setState(pending)
+        if (entry.subscribers > 0) void handle.refetch().catch(() => {})
+      },
       seed: (data, updatedAt) => {
         if (state.status === "success" && state.updatedAt >= updatedAt) return
+        dataTick = 0
         // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the snapshot was dehydrated from an entry under this key, whose pages and params are T and P
         setState(successState(data as InfiniteData<T, P>, updatedAt))
       },
       subscribers: 0,
       gcAt: undefined,
+      live: [],
+      lq,
     }
+    relive(entry, initialOpts.live)
     return entry
   }
 
-  return {
+  const clear = (): void => {
+    seeded.clear()
+    for (const [h, entry] of cache) {
+      // An in-flight fetch carried the last viewer's credentials: its result may not publish.
+      entry.generation++
+      entry.invalidated = true
+      entry.dataTick = 0
+      if (entry.subscribers === 0) {
+        cache.delete(h)
+        continue
+      }
+      entry.setState(PENDING)
+      void entry.handle.refetch().catch(() => {})
+    }
+    for (const [h, entry] of infinite) {
+      if (entry.subscribers === 0) infinite.delete(h)
+      entry.reset()
+    }
+  }
+
+  const client: QueryClient = {
     query,
     infiniteQuery,
     invalidateQueries,
@@ -649,7 +772,11 @@ export function createQueryClient(options: QueryClientOptions): QueryClient {
     prefetchQuery,
     dehydrate,
     hydrate,
+    clear,
   }
+  // A page with live refresh clears every client it made when the viewer changes.
+  adoptClient(client)
+  return client
 }
 
 // --- Standalone mutations -----------------------------------------------------------------------

package/src/render-seam.ts

@@ -135,6 +135,13 @@ export interface RenderStreamOptions {
   readonly nonce?: string
   /** Present only for an adapter that sets {@link RenderAdapter.documentParts}. */
   readonly parts?: DocumentParts
+  /**
+   * Chain indices to render inside the two slot wrappers a kept page needs (`keepAlive`), each
+   * `<slot data-nifra-entry><slot data-nifra-page>` around that chain entry (a `<slot>` lays out as
+   * `display: contents`), so the browser's keep-alive view hydrates the same markup. Present only
+   * in an app with a `keepAlive` route; an adapter without keep-alive support ignores it.
+   */
+  readonly slots?: readonly number[]
 }
 
 /**
@@ -167,13 +174,41 @@ export interface RenderAdapter {
   ): string | undefined | Promise<string | undefined>
   /** Per-document bootstrap markup injected into `<head>` for client hydration. */
   hydrationHead(nonce?: string): string
+  /**
+   * Render one piece of UI (a boundary's `render` result or `fallback`) to an HTML string on its own,
+   * outside the route chain. `ui` produces it: call it inside the render, since a framework whose
+   * markup is made as it is evaluated (Solid) needs its render context there. `idPrefix` namespaces
+   * any ids the framework generates, so two fragments rendered separately never collide. `hydrates`
+   * is set when the client hydrates the fragment as a root of its own (an interactive hole). Required
+   * for partial prerendering; optional otherwise.
+   */
+  renderFragment?(
+    ui: () => unknown,
+    options: { readonly idPrefix?: string; readonly hydrates?: boolean },
+  ): string | Promise<string>
   /**
    * Set when a render can produce markup that belongs outside the app root. Every render is then
    * passed `options.parts` to fill; an adapter without it never is, and pays nothing for the seam.
    */
   readonly documentParts?: boolean
+  /**
+   * Render the chain and return only the HTML of the slot named `name`, or `undefined` when the
+   * render has no such slot. Called for an {@link SWAP_HEADER} request; an adapter without it, or a
+   * render without the slot, answers with the whole document, which the client loads normally.
+   */
+  renderSlot?(
+    chain: readonly unknown[],
+    props: RenderProps,
+    name: string,
+  ): string | undefined | Promise<string | undefined>
 }
 
+/**
+ * Request header of a `data-swap` link or form: the name of the slot it refreshes. A response that
+ * carries only that slot echoes it; any other response is a whole document.
+ */
+export const SWAP_HEADER = "x-nifra-swap"
+
 /** Loads a module through the dev server's module graph rather than the runtime's resolver. */
 export type SsrModuleLoader = (id: string) => Promise<unknown>
 
@@ -209,6 +244,8 @@ export const ACTION_GLOBAL = "__NIFRA_ACTION__"
 /** Dynamic-boundary states for hydration; absent when a route declares no boundaries. */
 export const BOUNDARY_GLOBAL = "__NIFRA_BOUNDARIES__"
 export const COMPONENT_GLOBAL = "__NIFRA_COMPONENTS__"
+/** A live app's seed for the page: the client exchanges it for a grant once its socket opens. */
+export const LIVE_GLOBAL = "__NIFRA_LIVE__"
 /** Locale key -> copy chunk URL, in a production build that split copy tables by locale. The name
  * `@nifrajs/i18n/copy` reads. */
 export const COPY_CHUNKS_GLOBAL = "__NIFRA_COPY__"

package/src/route-types.ts

@@ -144,7 +144,7 @@ function routeTypesModule(
   )
   lines.push(
     route.kind === "page"
-      ? 'import type { MetaArgs as WebMetaArgs, RenderProps } from "@nifrajs/web"'
+      ? 'import type { BoundaryLoadersOf, MetaArgs as WebMetaArgs, RenderProps } from "@nifrajs/web"'
       : 'import type { MetaArgs as WebMetaArgs } from "@nifrajs/web"',
   )
   lines.push("")
@@ -181,6 +181,8 @@ function routeTypesModule(
       "    readonly actionData?: ActionData",
       "    readonly params: Params",
       "  }",
+      "  /** The backend half's `boundaryLoaders`. Check it, `export const boundaryLoaders = { ... } satisfies Route.BoundaryLoaders`, and a key must name a boundary the page declares; with a `shellLoader`, every hole needs one. */",
+      `  export type BoundaryLoaders = BoundaryLoadersOf<${frontend === undefined ? "unknown" : "Frontend"}, ${backend === undefined ? "unknown" : "Backend"}>`,
     )
   } else {
     lines.push(