@nifrajs/web 5.5.1 → 5.7.0

package/src/internal/island-signals.ts

@@ -0,0 +1,249 @@
+/**
+ * Fine-grained signals - the reactive core of `@nifrajs/web/islands`. Pull-based auto-tracking with
+ * per-run re-tracking (a branch switch drops the stale branch's subscriptions), `Object.is`
+ * equality skips, and an explicit synchronous {@link batch} that coalesces effect re-runs.
+ *
+ * Deliberately tiny and synchronous: a write recomputes the computeds it feeds at once and runs its
+ * effects before `set` returns, each once, after every computed has settled - predictable for
+ * island-scale code (a counter, a filter drawer), and the whole core stays well under a kilobyte.
+ * This is NOT a general app framework - just island-scale reactivity.
+ */
+
+import { adopt } from "./island-owner.ts"
+
+interface EffectNode {
+  run: () => void
+  /** Each source's reader set, mapped to the run (`v`) that last read it. */
+  readonly deps: Map<Set<EffectNode>, number>
+  v: number
+  /** Sources read so far in this run. */
+  n: number
+  /** Running now: a write during the run requeues it only for a source this run already read. */
+  r?: boolean
+  /** Set on a computed's node: it recomputes on the write instead of queueing. */
+  readonly c?: boolean | undefined
+  /** Queued for the current flush. */
+  q?: boolean
+}
+
+let currentEffect: EffectNode | undefined
+
+/** Run `fn` without subscribing the running effect or computed to the signals it reads. */
+export function untrack<T>(fn: () => T): T {
+  const prev = currentEffect
+  currentEffect = undefined
+  try {
+    return fn()
+  } finally {
+    currentEffect = prev
+  }
+}
+
+let batchDepth = 0
+const queue: EffectNode[] = []
+
+/** A readable/writable reactive value: call it to read (tracking), `.set` to write. */
+export type Signal<T> = {
+  (): T
+  set(next: T | ((prev: T) => T)): void
+}
+
+/**
+ * Batch writes: effects triggered inside `fn` run ONCE after it returns, deduplicated - so
+ * `setA(); setB()` updates the DOM once, not twice. Re-entrant; an effect re-queued during the
+ * flush runs in the same flush.
+ */
+export function batch<T>(fn: () => T): T {
+  batchDepth++
+  try {
+    return fn()
+  } finally {
+    flush()
+  }
+}
+
+// Closes one batch level; the outermost runs the queue.
+function flush(): void {
+  let i = 0
+  try {
+    // The flush still counts as a batch: a write an effect makes here queues, so none runs twice.
+    while (batchDepth === 1 && i < queue.length) {
+      const next = queue[i++]
+      if (next?.q) {
+        next.q = false
+        next.run()
+      }
+    }
+  } finally {
+    // A throwing effect leaves the rest queued for the next flush.
+    if (i === queue.length) queue.length = 0
+    else queue.splice(0, i)
+    batchDepth--
+  }
+}
+
+// Each plain signal's reader set, so `watch` can subscribe without tracking.
+const readers = new WeakMap<object, Set<EffectNode>>()
+
+/** Create a signal. Reads inside an {@link effect} (or {@link computed}) subscribe automatically. */
+export function signal<T>(initial: T): Signal<T> {
+  const subs = new Set<EffectNode>()
+  const s = readable(initial, subs)
+  readers.set(s, subs)
+  return s
+}
+
+/**
+ * Call `fn` with `source`'s value now and after each change, queued and batched like an effect but
+ * subscribed once instead of tracking reads. Any other getter (a computed, a derived function) is
+ * tracked as an effect. Either way `fn` runs untracked. Internal to the binding walker, whose bindings each read one named signal,
+ * and to `bindList`; not exported from `@nifrajs/web/islands`.
+ */
+export function watch<T>(source: () => T, fn: (value: T) => void): () => void {
+  const subs = readers.get(source)
+  if (!subs)
+    return effect(() => {
+      const value = source()
+      untrack(() => fn(value))
+    })
+  const e: EffectNode = {
+    deps: new Map([[subs, 0]]),
+    v: 0,
+    n: 1,
+    run: () => {
+      const prev = currentEffect
+      currentEffect = undefined
+      try {
+        fn(source())
+      } finally {
+        currentEffect = prev
+      }
+    },
+  }
+  const stop = (): void => {
+    subs.delete(e)
+    e.q = false
+  }
+  subs.add(e)
+  adopt(stop)
+  batch(e.run)
+  return stop
+}
+
+// A signal whose readers are `subs`, so a computed can see whether anything still reads it.
+function readable<T>(initial: T, subs: Set<EffectNode>): Signal<T> {
+  let value = initial
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: `set` is assigned below, before the signal is returned
+  const read = (() => {
+    const e = currentEffect
+    if (e) {
+      const seen = e.deps.get(subs)
+      if (seen !== e.v) {
+        if (seen === undefined) subs.add(e)
+        e.deps.set(subs, e.v)
+        e.n++
+      }
+    }
+    return value
+  }) as Signal<T>
+  read.set = (next) => {
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: a function passed to `set` is always the updater form
+    const resolved = typeof next === "function" ? (next as (prev: T) => T)(value) : next
+    if (Object.is(resolved, value)) return
+    value = resolved
+    // Snapshot: an effect created while this write flushes must not run in it.
+    batchDepth++
+    try {
+      for (const e of [...subs]) {
+        // A running effect is requeued only by a source its current run has already read.
+        if (e.r && e.deps.get(subs) !== e.v) continue
+        if (e.c) e.run()
+        else if (!e.q) {
+          e.q = true
+          queue.push(e)
+        }
+      }
+    } finally {
+      flush()
+    }
+  }
+  return read
+}
+
+/** A derived value: call it to read (tracking), `.dispose()` to stop recomputing it. */
+export type Computed<T> = {
+  (): T
+  dispose(): void
+}
+
+/**
+ * Derived value, cached into a signal and computed on first read. While an effect (or another
+ * computed) reads it, it recomputes when its tracked inputs change. Once nothing reads it, the next
+ * input change stops it instead of recomputing, so a dropped computed costs nothing; reading it
+ * again starts it afresh. `dispose()` stops it at once.
+ */
+export function computed<T>(fn: () => T): Computed<T> {
+  const subs = new Set<EffectNode>()
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the first read computes it before returning
+  const out = readable<T>(undefined as T, subs)
+  let stop: (() => void) | undefined
+  // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: `dispose` is assigned below
+  const read = (() => {
+    // biome-ignore lint/plugin/requireSafetyCommentForTypeAssertion: the implementation takes the computed flag its public overload hides
+    stop ??= (effect as (fn: () => void, c: boolean) => () => void)(() => {
+      if (!stop || subs.size) out.set(fn())
+      else read.dispose()
+    }, true)
+    return out()
+  }) as Computed<T>
+  read.dispose = () => {
+    stop?.()
+    stop = undefined
+  }
+  return read
+}
+
+/**
+ * Run `fn` now and again whenever any signal it read changes. Returns a disposer. Dependencies
+ * re-track on every run, so conditional reads subscribe to exactly the live branch. Every run,
+ * the first included, finishes before the effects its writes trigger run, itself among them.
+ */
+export function effect(fn: () => void): () => void
+export function effect(fn: () => void, c?: boolean): () => void {
+  const stop = (): void => {
+    for (const subs of e.deps.keys()) subs.delete(e)
+    e.deps.clear()
+    e.q = false
+  }
+  const e: EffectNode = {
+    c,
+    deps: new Map(),
+    v: 0,
+    n: 0,
+    // Subscriptions persist across runs; a source this run did not read is dropped afterwards.
+    run: () => {
+      ++e.v
+      e.n = 0
+      e.q = false
+      e.r = true
+      const prev = currentEffect
+      currentEffect = e
+      try {
+        fn()
+      } finally {
+        currentEffect = prev
+        e.r = false
+        if (e.n < e.deps.size)
+          for (const [subs, seen] of e.deps)
+            if (seen !== e.v) {
+              subs.delete(e)
+              e.deps.delete(subs)
+            }
+      }
+    },
+  }
+  adopt(stop)
+  // Batched, so a write in the first run cannot re-enter it before it finishes.
+  batch(e.run)
+  return stop
+}

package/src/internal/keep-alive-table.ts

@@ -0,0 +1,72 @@
+/**
+ * Where the slot wrappers of kept pages go, decided once from the route table so that the server's
+ * markup and every client render agree: a wrapper that appeared or vanished with what is kept would
+ * remount the page inside it, and one the server did not render fails hydration.
+ */
+import type { Manifest } from "../manifest.ts"
+
+/** What the server and the browser both read to place the slot wrappers. */
+export interface KeepAliveTable {
+  /** Routes whose page renders inside the slot wrappers: the build found a `keepAlive` export. */
+  readonly routes: readonly string[]
+  /** Layouts rendered inside the slot wrappers, because another chain the browser can render shares
+   * the layouts above one of them and not that one: a kept page then sits there beside the page on
+   * screen. A layout every chain shares is never wrapped. */
+  readonly layouts: readonly string[]
+}
+
+const sharesAbove = (a: readonly string[], b: readonly string[], depth: number): boolean => {
+  for (let i = 0; i < depth; i++) if (a[i] !== b[i]) return false
+  return true
+}
+
+/** The table for `manifest`, or `undefined` when no route keeps its page alive. */
+export function keepAliveTable(manifest: Manifest): KeepAliveTable | undefined {
+  const kept = manifest.routes.filter((route) => route.keepAlive === true)
+  if (kept.length === 0) return undefined
+  // Every layout chain the browser renders: each route's, a root status page's (inside the root
+  // layout unless the page opts out, which only its module says), and a `_loading` page's, which takes
+  // the layouts the two pages of a navigation share, so any prefix of a route under it.
+  const chains: (readonly string[])[] = manifest.routes.map((route) => route.layoutIds)
+  if (manifest.notFound !== undefined || Object.keys(manifest.statusPages ?? {}).length > 0) {
+    chains.push(manifest.layouts._layout === undefined ? [] : ["_layout"])
+  }
+  for (const [id, loading] of Object.entries(manifest.loadings ?? {})) {
+    for (const route of manifest.routes) {
+      if (!route.loadingIds?.includes(id)) continue
+      for (let n = loading.layoutIds.length; n <= route.layoutIds.length; n++) {
+        chains.push(route.layoutIds.slice(0, n))
+      }
+    }
+  }
+  const layouts = new Set<string>()
+  for (const route of kept) {
+    route.layoutIds.forEach((layout, depth) => {
+      if (layouts.has(layout)) return
+      if (
+        chains.some(
+          (chain) => chain[depth] !== layout && sharesAbove(chain, route.layoutIds, depth),
+        )
+      )
+        layouts.add(layout)
+    })
+  }
+  return { routes: [...new Set(kept.map((route) => route.id))], layouts: [...layouts] }
+}
+
+/**
+ * The chain indices to render inside slot wrappers for a chain of `layoutIds` and then the page of
+ * `routeId`: each wrapped layout, and the page when its route keeps alive.
+ */
+export function slotDepths(
+  table: KeepAliveTable,
+  layoutIds: readonly string[],
+  routeId: string | undefined,
+): readonly number[] {
+  const depths: number[] = []
+  layoutIds.forEach((layout, depth) => {
+    if (table.layouts.includes(layout)) depths.push(depth)
+  })
+  if (routeId !== undefined && table.routes.includes(routeId)) depths.push(layoutIds.length)
+  return depths
+}

package/src/internal/live-contract.ts

@@ -0,0 +1,111 @@
+/**
+ * The seam between page execution and a configured live runtime (`@nifrajs/web/live`): types and one
+ * symbol. An app without `live` imports nothing from the live module itself.
+ */
+import type { IdentityPlugin, WebSocketHandler } from "@nifrajs/core/server"
+import type { LoaderContext } from "../manifest.ts"
+import type { LiveClientEntry } from "./codegen.ts"
+
+/** What `createWebApp` tells the runtime about its routes. */
+export interface LiveRouteMatch {
+  readonly routeId: string
+  readonly layoutIds: readonly string[]
+}
+
+/** The app the live socket registers on. */
+export interface LiveHostApp {
+  use(plugin: IdentityPlugin): unknown
+  ws<Data>(path: string, handler: WebSocketHandler<Data>): unknown
+  publish(topic: string, data: string): void
+}
+
+export interface LiveAttachInput {
+  /** The route a canonical `pathname + search` renders, or `null`. */
+  readonly matchRoute: (path: string) => LiveRouteMatch | null
+  readonly app: LiveHostApp
+}
+
+export interface LiveAttachment {
+  /** Admission and dispatch for the live load endpoint; `undefined` for every other request. */
+  readonly onRequest: (req: Request) => Promise<Request | Response> | undefined
+  /** The live load a page request belongs to, or `undefined` for every request that is not one. */
+  readonly loadOf: (req: Request) => LiveLoad | undefined
+  /**
+   * The seed a server-rendered page of `routeId` collects its keys into, or `undefined` when none can
+   * be issued now (the runtime not started, the bus down, Workers). Never admitted: it is no live load.
+   */
+  readonly seedOf: (req: Request, routeId: string) => LiveLoad | undefined
+}
+
+/** One live load, from the page handler's side. */
+export interface LiveLoad {
+  /** The route the endpoint mapped the retain list against. */
+  readonly routeId: string
+  /** `undefined` when admitted; else the 503 to answer with. An admitted load is released once. */
+  admit(): Response | undefined
+  /** Release the admission slot once the response is complete: at once, or when its stream ends. */
+  settle(response: Response): Response
+  release(): void
+  /**
+   * After middleware: resolve the viewer's subject. `false` when the presented grant's retention no
+   * longer applies (another subject), so every owner loads fresh.
+   */
+  bind(ctx: LoaderContext): Promise<boolean>
+  /** Skip the page loader: the page owner is retained. Read after {@link bind}. */
+  readonly retainPage: boolean
+  /** `ctx.live` for one owner. */
+  collector(owner: string): (...keys: string[]) => void
+  /** Close an owner's collector once its loader has settled. */
+  seal(owner: string): void
+  /** The envelope's `live` member, built after every loader settled without a throw or status. */
+  finish(input: LiveFinish): Promise<LiveEnvelope>
+}
+
+export interface LiveFinish {
+  /** Owners whose loaders ran and resolved. */
+  readonly fresh: readonly string[]
+  /** Owners whose loaders were skipped: their keys come from the presented grant. */
+  readonly retained: readonly string[]
+  readonly ctx: LoaderContext
+}
+
+export interface LiveEnvelope {
+  /**
+   * Opaque and stable per viewer, one per listed secret, newest first. A load sharing none with the
+   * last one is another user, so client caches are cleared; a rotation always leaves one in common.
+   */
+  readonly subjects: readonly string[]
+  /** Absent when no grant could be issued; the client then polls. */
+  readonly grant?: string
+  /** Wire tag to the frame's owners that watch its key. */
+  readonly tags?: Readonly<Record<string, readonly string[]>>
+  /** The page loader did not run: the client keeps its page data. */
+  readonly page?: "retained"
+  /** Seconds the grant stays valid from now; the client renews a minute before. */
+  readonly ttl?: number
+  /** For query hooks: with `queryKeys`, and in development so the page can warn. */
+  readonly query?: LiveQueryKeys
+}
+
+export interface LiveQueryKeys {
+  /** Fresh per load; absent when `queryKeys` is off. */
+  readonly salt?: string
+  /** Wire tag to its key's digest under `salt`. */
+  readonly keys?: Readonly<Record<string, string>>
+  /** The app runs in development: the page warns about query keys no grant holds. */
+  readonly dev?: true
+}
+
+/** The owner a hole of a partially prerendered page is in its page's live frame. */
+export const holeOwner = (hole: string, routeId: string): string => `B:${hole}:${routeId}`
+
+/** `createWebApp` reads the runtime through this symbol, so it is not public API on the object. */
+export const LIVE_ATTACH: unique symbol = Symbol.for("nifra.web.live.attach")
+
+export interface LiveRuntimeHandle {
+  readonly [LIVE_ATTACH]: (input: LiveAttachInput) => LiveAttachment
+  /** The client entry's `live` option for this runtime: the endpoints it serves, where not the default. */
+  readonly clientEntry: LiveClientEntry
+  /** Announce changed keys; resolves once this process applied the change. */
+  publish(...keys: string[]): Promise<void>
+}

package/src/internal/live-queries.ts

@@ -0,0 +1,60 @@
+/**
+ * The live client's side of the query seam. A mounted query with live keys registers here, and the
+ * live client matches its keys to the tags each live load grants. Importing this module installs the
+ * seam.
+ */
+import { installQuerySeam, type LiveQuery, queryClients } from "./query-seam.ts"
+
+export type { LiveQuery }
+
+let tick = 0
+
+/** Read by a query as each fetch starts. */
+export const liveTick = (): number => tick
+
+/**
+ * Advanced as each live load's response arrives, and as each query registers. A query whose fetch
+ * started after a load arrived read the server after that load took its watermark.
+ */
+export const advanceLiveTick = (): number => ++tick
+
+// Query to the live tick it registered at: a change before that never reached it.
+const queries = new Map<LiveQuery, number>()
+const watchers = new Set<() => void>()
+
+function changed(): void {
+  for (const watcher of watchers) watcher()
+}
+
+export function liveQueries(): Iterable<LiveQuery> {
+  return queries.keys()
+}
+
+/** The live tick `query` registered at, or `undefined` once it left. */
+export function registeredAt(query: LiveQuery): number | undefined {
+  return queries.get(query)
+}
+
+/** Returns the function that stops watching. */
+export function watchLiveQueries(watcher: () => void): () => void {
+  watchers.add(watcher)
+  return () => {
+    watchers.delete(watcher)
+  }
+}
+
+/** Another viewer: no query client keeps data loaded for the last one. */
+export function clearQueryClients(): void {
+  for (const ref of queryClients()) ref.deref()?.clear()
+}
+
+installQuerySeam({
+  tick: liveTick,
+  track(query, mounted) {
+    if (mounted && query.keys().length > 0) {
+      if (queries.has(query)) return
+      queries.set(query, advanceLiveTick())
+      changed()
+    } else if (queries.delete(query)) changed()
+  },
+})

package/src/internal/page-events.ts

@@ -0,0 +1,27 @@
+/** Dispatched on a kept page's element as the router hides it (`keepAlive`), while it is still in the
+ * document and before the router's subscribers see the state that hides it. */
+export const PAGE_HIDE_EVENT = "nifra:pagehide"
+/** Dispatched on a kept page's element once it is shown again. */
+export const PAGE_SHOW_EVENT = "nifra:pageshow"
+
+const releases = new WeakMap<object, Set<() => void>>()
+
+/** Run `release` once the kept page `page` leaves its view for good; the result cancels it. */
+export function onPageRelease(page: object, release: () => void): () => void {
+  let pending = releases.get(page)
+  if (pending === undefined) {
+    pending = new Set()
+    releases.set(page, pending)
+  }
+  pending.add(release)
+  return () => {
+    pending.delete(release)
+  }
+}
+
+/** The kept page `page` left its view: what its hidden content set aside goes. */
+export function releasePage(page: object): void {
+  const pending = releases.get(page)
+  releases.delete(page)
+  for (const release of pending ?? []) release()
+}