@nifrajs/web 3.5.0 → 4.0.2

package/src/internal/loading-runtime.ts

@@ -0,0 +1,244 @@
+/**
+ * `_loading` pages. The router is untouched: {@link withLoading} only swaps the leaf of the state the
+ * view is told while a navigation is pending, so no adapter knows a loading page exists.
+ */
+import type { MatchChain } from "../render-seam.ts"
+import { type ClientRouter, type RouterState, redirectOf } from "../router.ts"
+
+/** How long a navigation may run before its `_loading` page shows. Shorter loads swap straight to the
+ * new page: a skeleton that flashes for a few frames reads as a glitch, not as feedback. */
+export const LOADING_DELAY_MS = 120
+
+/**
+ * One route's row: its layout ids (outermost → innermost), and the `_loading` pages above it
+ * (outermost → innermost), each paired with how many of those layouts sit at or above it.
+ */
+export type LoadingRoute = readonly [
+  layoutIds: readonly string[],
+  loadings: ReadonlyArray<readonly [id: string, layouts: number]>,
+]
+
+export interface LoadingOptions {
+  /** Every route id → its {@link LoadingRoute} row. A route id absent here has no layouts. */
+  readonly routes: Readonly<Record<string, LoadingRoute>>
+  /** `_loading` id → a lazy import of its module. */
+  readonly modules: Readonly<
+    Record<string, () => Promise<{ readonly default?: unknown; readonly handle?: unknown }>>
+  >
+  /** The mounted view's route id → component chain table. The wrapper adds a chain per loading view. */
+  readonly chains: Record<string, readonly unknown[]>
+  /** Route id → search-schema chain, kept in step with {@link chains}. */
+  readonly searchSchemas: Record<string, readonly unknown[]>
+  /** Route id → what `useMatches` reports, kept in step with {@link chains}. */
+  readonly matchChains?: Record<string, MatchChain>
+  /** Override {@link LOADING_DELAY_MS}. */
+  readonly delayMs?: number
+  /** Where a navigation goes when it fails after its loading page was shown. Defaults to a document
+   * load of the path. */
+  readonly fallback?: (path: string) => void
+}
+
+const pathnameOf = (path: string): string => {
+  const q = path.indexOf("?")
+  return q === -1 ? path : path.slice(0, q)
+}
+
+/**
+ * Shows the innermost `_loading` within the layouts both pages share once a navigation outlasts
+ * `delayMs`. `navigate` settles when it shows, so a view transition does not hold across the wait; a
+ * later failure goes to `fallback`, or replaces the entry for a redirect out of the app.
+ */
+export function withLoading(router: ClientRouter, options: LoadingOptions): ClientRouter {
+  const { routes, modules, chains, searchSchemas, matchChains } = options
+  const delayMs = options.delayMs ?? LOADING_DELAY_MS
+  const fallback = options.fallback ?? ((path: string) => location.assign(path))
+
+  const listeners = new Set<() => void>()
+  const components = new Map<string, unknown>()
+  const handles = new Map<string, unknown>()
+  const inflight = new Map<string, Promise<void>>()
+  /** Bumped per navigation through this wrapper - the latest one owns the page slot. */
+  let seq = 0
+  /** The loading view on screen (its chain id), and the navigation it belongs to. */
+  let shown: string | undefined
+  let owner = 0
+  // One derived state per (router state, loading view) so `snapshot` is referentially stable.
+  let base: RouterState | undefined
+  let derived: RouterState | undefined
+
+  const emit = (): void => {
+    for (const listener of [...listeners]) listener()
+  }
+
+  const load = (id: string): Promise<void> => {
+    if (components.has(id)) return Promise.resolve()
+    const running = inflight.get(id)
+    if (running !== undefined) return running
+    const importer = modules[id]
+    const job = (
+      importer === undefined ? Promise.reject(new Error(`no _loading module "${id}"`)) : importer()
+    )
+      .then((mod) => {
+        if (mod.default !== undefined) components.set(id, mod.default)
+        handles.set(id, mod.handle)
+      })
+      .finally(() => {
+        inflight.delete(id)
+      })
+    inflight.set(id, job)
+    return job
+  }
+
+  const pick = (
+    fromId: string,
+    toId: string,
+  ): { readonly id: string; readonly shared: number } | undefined => {
+    const target = routes[toId]
+    if (target === undefined) return undefined
+    const current = routes[fromId]?.[0] ?? []
+    const [layouts, candidates] = target
+    let shared = 0
+    while (
+      shared < current.length &&
+      shared < layouts.length &&
+      current[shared] === layouts[shared]
+    ) {
+      shared++
+    }
+    for (let i = candidates.length - 1; i >= 0; i--) {
+      const candidate = candidates[i]
+      if (candidate !== undefined && candidate[1] <= shared) return { id: candidate[0], shared }
+    }
+    return undefined
+  }
+
+  const snapshot = (): RouterState => {
+    const state = router.snapshot()
+    if (shown === undefined || !state.pending) return state
+    if (base !== state || derived === undefined || derived.routeId !== shown) {
+      base = state
+      // The layouts keep their data and the URL-derived fields stay the current page's; only the leaf
+      // changes, and it has no loader data of its own.
+      derived = { ...state, routeId: shown, data: null }
+    }
+    return derived
+  }
+
+  const navigate = (path: string): Promise<void> => {
+    const match = router.match(path)
+    // Unmatched: the router ignores it, so whatever is on screen stays as it is.
+    if (match === null) return router.navigate(path)
+    const mine = ++seq
+    const from = router.snapshot()
+    const choice =
+      pathnameOf(from.path) === pathnameOf(path) ? undefined : pick(from.routeId, match.routeId)
+    // NUL-prefixed: a chain id no route file can produce.
+    const view =
+      choice === undefined ? undefined : `\0${choice.id}\0${from.routeId}\0${choice.shared}`
+    const wasShown = shown !== undefined
+    // A newer navigation that would show the same view keeps it, rather than flashing the old page.
+    const carried = wasShown && shown === view
+    if (carried) owner = mine
+    else shown = undefined
+
+    const done = router.navigate(path)
+    if (choice === undefined || view === undefined) {
+      if (wasShown) emit()
+      return done
+    }
+
+    let finished = false
+    let revealed = carried
+    let timer: ReturnType<typeof setTimeout> | undefined
+    const reveal = new Promise<void>((resolve) => {
+      if (carried) {
+        setTimeout(resolve, 0)
+        return
+      }
+      const show = (): void => {
+        if (finished || mine !== seq || !router.snapshot().pending) return
+        const component = components.get(choice.id)
+        if (component === undefined) return
+        chains[view] ??= [...(chains[from.routeId] ?? []).slice(0, choice.shared), component]
+        // The current route's schemas: the URL is still its URL, so its layouts read the same search.
+        searchSchemas[view] ??= searchSchemas[from.routeId] ?? []
+        if (matchChains !== undefined) {
+          const current = matchChains[from.routeId]
+          matchChains[view] ??= {
+            ids: [...(current?.ids ?? []).slice(0, choice.shared), choice.id],
+            handles: [...(current?.handles ?? []).slice(0, choice.shared), handles.get(choice.id)],
+          }
+        }
+        shown = view
+        owner = mine
+        revealed = true
+        emit()
+        // A macrotask later, so the view has committed the loading page before the caller resumes.
+        setTimeout(resolve, 0)
+      }
+      const ready = load(choice.id)
+      // A `_loading` module that fails to load costs only the loading page, never the navigation.
+      ready.catch(() => {})
+      timer = setTimeout(
+        () => {
+          ready.then(show, () => {})
+        },
+        wasShown ? 0 : delayMs,
+      )
+    })
+
+    const finish = (): void => {
+      finished = true
+      clearTimeout(timer)
+      if (owner !== mine || shown === undefined) return
+      shown = undefined
+      // A navigation that ended without publishing (superseded inside the router) leaves the store
+      // pending: tell the view the page slot is the current page's again.
+      if (router.snapshot().pending) emit()
+    }
+    const settled = done.then(finish, (error: unknown) => {
+      finish()
+      // A newer navigation owns the document now; even an aborted older fetch can reject late.
+      if (mine !== seq) return
+      if (!revealed) throw error
+      const to = redirectOf(error)
+      if (to === undefined) fallback(path)
+      else location.replace(to)
+    })
+    return Promise.race([settled, reveal])
+  }
+
+  return {
+    ...router,
+    snapshot,
+    subscribe(listener) {
+      listeners.add(listener)
+      const unsubscribe = router.subscribe(listener)
+      return () => {
+        listeners.delete(listener)
+        unsubscribe()
+      }
+    },
+    navigate,
+    submit(action, body, opts) {
+      ++seq
+      shown = undefined
+      return router.submit(action, body, opts)
+    },
+    invalidate(paths) {
+      if (paths === undefined || paths.includes(router.snapshot().path)) {
+        ++seq
+        shown = undefined
+      }
+      return router.invalidate(paths)
+    },
+    prefetch(path) {
+      // Warm the loading pages a navigation there could show, alongside the route itself.
+      const match = router.match(path)
+      if (match !== null) {
+        for (const [id] of routes[match.routeId]?.[1] ?? []) load(id).catch(() => {})
+      }
+      return router.prefetch(path)
+    },
+  }
+}

package/src/internal/matches-runtime.ts

@@ -0,0 +1,62 @@
+/**
+ * `useMatches` for every adapter. It reads only {@link RenderProps}, which SSR and the mounted router
+ * both build, so server and browser agree. Layout prefixes follow the `filePathToRoutes` grammar.
+ */
+import type { RenderProps, UIMatch } from "../render-seam.ts"
+
+const GROUP = /^\(.+\)$/
+const OPTIONAL = /^\[\[([A-Za-z_][A-Za-z0-9_]*)\]\]$/
+const CATCH_ALL = /^\[\.\.\.([A-Za-z_][A-Za-z0-9_]*)\]$/
+const MARKER = /\[([A-Za-z_][A-Za-z0-9_]*)\]/g
+
+/** The matches of one render, outermost layout first. Empty when the render carries no chain. */
+export function chainMatches(props: RenderProps): readonly UIMatch[] {
+  const chain = props.matchChain
+  if (chain === undefined) return []
+  const path = props.path ?? ""
+  const query = path.indexOf("?")
+  const pathname = query === -1 ? path : path.slice(0, query)
+  const segments = pathname.split("/").filter((segment) => segment !== "")
+  const params = props.params ?? {}
+  const last = chain.ids.length - 1
+  return chain.ids.map((id, index): UIMatch => {
+    const handle = chain.handles[index]
+    if (index === last) return { id, pathname, params, data: props.data, handle }
+    const owned: Record<string, string> = {}
+    let depth = 0
+    let rest = false
+    const slash = id.lastIndexOf("/")
+    for (const part of slash === -1 ? [] : id.slice(0, slash).split("/")) {
+      if (part === "index" || GROUP.test(part)) continue
+      const optional = OPTIONAL.exec(part)?.[1]
+      if (optional !== undefined) {
+        const value = params[optional]
+        if (value !== undefined) {
+          owned[optional] = value
+          depth += 1
+        }
+        continue
+      }
+      const catchAll = CATCH_ALL.exec(part)?.[1]
+      if (catchAll !== undefined) {
+        const value = params[catchAll]
+        if (value !== undefined) owned[catchAll] = value
+        rest = true
+        break
+      }
+      for (const marker of part.matchAll(MARKER)) {
+        const name = marker[1] as string
+        const value = params[name]
+        if (value !== undefined) owned[name] = value
+      }
+      depth += 1
+    }
+    return {
+      id,
+      pathname: rest ? pathname : `/${segments.slice(0, depth).join("/")}`,
+      params: owned,
+      data: props.layoutData?.[index] ?? null,
+      handle,
+    }
+  })
+}

package/src/internal/mount-shadow.ts

@@ -0,0 +1,88 @@
+/**
+ * Page routes a mount makes unreachable.
+ *
+ * A pre-route mount (the auto-mounted backend at `apiPrefix`, a `mounts` entry, an `app.mount()` in
+ * `use`) answers every request under its path before page routing, and its 404 is final -
+ * `fallbackOn: 404` only tries the next mount. A page file whose URL sits under one therefore never
+ * renders, and nothing says so: the request gets the mount's 404. This finds those pages so the app
+ * fails at startup, at build, and in `nifra check` instead.
+ *
+ * Pure and fs-free: it takes the manifest and the mount paths, so the runtime, the build and the static
+ * check all run the same comparison.
+ */
+import type { Manifest } from "../manifest.ts"
+
+/** A page file whose URL pattern sits under a mount. */
+export interface ShadowedPage {
+  /** The route file, as the manifest names it (relative to `routes/`). */
+  readonly file: string
+  /** The URL pattern the file serves. */
+  readonly pattern: string
+  /** The mount path, normalized as the server matches it. */
+  readonly mount: string
+}
+
+/**
+ * Normalize a mount path the way the server's mount table does: drop a trailing `/*` and a trailing
+ * `/`, keep `/` for a root mount. `undefined` for a path the server would refuse (not absolute, a
+ * query or hash, a param or an inner wildcard) - the mount itself reports that.
+ */
+export function normalizeMountPath(path: string): string | undefined {
+  if (!path.startsWith("/") || path.includes("?") || path.includes("#")) return undefined
+  const bare = path.endsWith("/*") ? path.slice(0, -2) : path
+  if (bare.includes("*") || bare.includes(":")) return undefined
+  if (bare.length === 0) return "/"
+  return bare.length > 1 && bare.endsWith("/") ? bare.slice(0, -1) : bare
+}
+
+/** Whether every request a pattern serves lands under `mount`: its leading segments equal the mount's
+ * segments literally. A param or wildcard segment is not the mount's literal text, so `/:lang/x` is
+ * reachable for every other value and is not reported. */
+function patternUnderMount(pattern: string, mount: string): boolean {
+  if (mount === "/") return true
+  return pattern === mount || pattern.startsWith(`${mount}/`)
+}
+
+/**
+ * The page routes and nested `_404` scopes that sit under one of `mountPaths`, in manifest order. Paths
+ * are normalized here; one the server would refuse is skipped.
+ */
+export function shadowedPages(
+  manifest: Pick<Manifest, "routes" | "notFounds">,
+  mountPaths: readonly string[],
+): readonly ShadowedPage[] {
+  const mounts: string[] = []
+  for (const path of mountPaths) {
+    const normalized = normalizeMountPath(path)
+    if (normalized !== undefined && !mounts.includes(normalized)) mounts.push(normalized)
+  }
+  if (mounts.length === 0) return []
+  const found: ShadowedPage[] = []
+  const under = (pattern: string): string | undefined => {
+    for (const mount of mounts) if (patternUnderMount(pattern, mount)) return mount
+    return undefined
+  }
+  for (const route of manifest.routes) {
+    const mount = under(route.pattern)
+    if (mount !== undefined) found.push({ file: route.file, pattern: route.pattern, mount })
+  }
+  for (const entry of Object.values(manifest.notFounds ?? {})) {
+    for (const scope of entry.scopes) {
+      const mount = under(scope.pattern)
+      if (mount !== undefined) found.push({ file: entry.file, pattern: scope.pattern, mount })
+    }
+  }
+  return found
+}
+
+/** The message every surface reports shadowed pages with. */
+export function formatShadowedPages(pages: readonly ShadowedPage[]): string {
+  const lines = pages.map(
+    (page) => `  ${page.file} serves ${page.pattern}, under the mount at ${page.mount}`,
+  )
+  return (
+    `${pages.length === 1 ? "1 page route" : `${pages.length} page routes`} can never render: a mount answers every request under its path before page routing, and its 404 is final.\n` +
+    `${lines.join("\n")}\n` +
+    'Move each file out of the mounted path, or serve that URL from the mounted app. The backend\'s mount path is `apiPrefix` (default "/api"; export it from framework.ts, or set it to "" to turn the mount off).'
+  )
+}

package/src/internal/node-builtins.ts

@@ -0,0 +1,79 @@
+/**
+ * Node's built-in module names without the `node:` prefix (`fs`, `fs/promises`, ...), for the client
+ * build guards. A fixed list rather than `module.builtinModules`, which differs between Node and Bun
+ * (Bun adds `bun:*`), so a leak reads the same whichever runtime runs the build. Names that exist only
+ * with the prefix (`node:test`, `node:sqlite`) are covered by the prefix itself.
+ */
+const NODE_BUILTIN_MODULES: ReadonlySet<string> = new Set([
+  "_http_agent",
+  "_http_client",
+  "_http_common",
+  "_http_incoming",
+  "_http_outgoing",
+  "_http_server",
+  "_stream_duplex",
+  "_stream_passthrough",
+  "_stream_readable",
+  "_stream_transform",
+  "_stream_wrap",
+  "_stream_writable",
+  "_tls_common",
+  "_tls_wrap",
+  "assert",
+  "assert/strict",
+  "async_hooks",
+  "buffer",
+  "child_process",
+  "cluster",
+  "console",
+  "constants",
+  "crypto",
+  "dgram",
+  "diagnostics_channel",
+  "dns",
+  "dns/promises",
+  "domain",
+  "events",
+  "fs",
+  "fs/promises",
+  "http",
+  "http2",
+  "https",
+  "inspector",
+  "inspector/promises",
+  "module",
+  "net",
+  "os",
+  "path",
+  "path/posix",
+  "path/win32",
+  "perf_hooks",
+  "process",
+  "punycode",
+  "querystring",
+  "readline",
+  "readline/promises",
+  "repl",
+  "stream",
+  "stream/consumers",
+  "stream/promises",
+  "stream/web",
+  "string_decoder",
+  "sys",
+  "timers",
+  "timers/promises",
+  "tls",
+  "trace_events",
+  "tty",
+  "url",
+  "util",
+  "util/types",
+  "v8",
+  "vm",
+  "wasi",
+  "worker_threads",
+  "zlib",
+])
+
+/** Whether `specifier` names a Node built-in without the `node:` prefix (`fs/promises`). */
+export const isBareNodeBuiltin = (specifier: string): boolean => NODE_BUILTIN_MODULES.has(specifier)