@nifrajs/web 2.2.0 → 2.3.0

package/src/search.ts

@@ -0,0 +1,297 @@
+/**
+ * `@nifrajs/web` search-param engine - the agnostic core behind typed, validated search params. It parses
+ * a URL query into a structured object, validates it against a route's Standard Schema (failing CLOSED to
+ * defaults on hostile input), serializes it back, and structural-shares successive values so selector
+ * reads stay referentially stable. Pure: no DOM, no framework, no fs - it runs identically at server match
+ * time and on client navigation, so the two sides cannot drift. See SEARCH-PARAMS-PLAN.md.
+ *
+ * Not yet re-exported from the package entry: this is the engine the route/server/client wiring (later
+ * phases) build on. The public surface (`searchSchema` on a route, `useSearch`, typed `navigate`) lands
+ * with that wiring.
+ */
+import type { InferOutput, StandardSchemaV1 } from "@nifrajs/core/server"
+
+/**
+ * Bounds applied while parsing a query string. A search string is attacker-controlled, so it is capped
+ * BEFORE an object graph is built from it - defense-in-depth alongside the route schema's own validation.
+ */
+export interface SearchLimits {
+  /** Longest raw query (with or without a leading `?`) that will be parsed; longer fails closed to `{}`. */
+  readonly maxLength: number
+  /** Most top-level keys that will be kept; keys beyond the cap are dropped. */
+  readonly maxKeys: number
+  /** Deepest nesting a decoded JSON value may have; deeper values are kept as their raw string instead. */
+  readonly maxDepth: number
+}
+
+/** Conservative defaults: a 4 KB query, 64 keys, 6 levels of nesting. */
+export const DEFAULT_SEARCH_LIMITS: SearchLimits = { maxLength: 4096, maxKeys: 64, maxDepth: 6 }
+
+/**
+ * A pluggable query <-> object codec. The default is JSON-first (numbers/booleans/arrays/nested objects
+ * survive the round-trip); an app can supply its own (compact, base64, comma-arrays) in a later phase.
+ */
+export interface SearchCodec {
+  /** Parse a raw query (`"?a=1&b=x"` or `"a=1&b=x"`) into a structured object, honoring `limits`. */
+  parse(raw: string, limits: SearchLimits): Record<string, unknown>
+  /** Serialize a structured object to a query string, including a leading `?` (or `""` when empty). */
+  serialize(value: Record<string, unknown>): string
+}
+
+// Keys that must never be written from untrusted input: a bracket-assignment to `__proto__` (or the
+// others) can pollute Object.prototype. Dropped at every level of a decoded value.
+const FORBIDDEN_KEYS = new Set<string>(["__proto__", "prototype", "constructor"])
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value)
+}
+
+// True when `value` nests deeper than `remaining` levels (a scalar never does). Used to reject an
+// over-deep decoded JSON value back to its raw string rather than store the graph.
+function exceedsDepth(value: unknown, remaining: number): boolean {
+  if (Array.isArray(value)) {
+    if (remaining <= 0) return true
+    return value.some((item) => exceedsDepth(item, remaining - 1))
+  }
+  if (isPlainObject(value)) {
+    if (remaining <= 0) return true
+    return Object.values(value).some((item) => exceedsDepth(item, remaining - 1))
+  }
+  return false
+}
+
+// Recursively strip forbidden keys from a decoded value. `JSON.parse('{"__proto__":1}')` yields an OWN
+// enumerable `__proto__` property (it does not set the prototype), but a later spread/assign of it would,
+// so it is removed here, at the source.
+function sanitize(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sanitize)
+  if (isPlainObject(value)) {
+    const out: Record<string, unknown> = {}
+    for (const [key, item] of Object.entries(value)) {
+      if (FORBIDDEN_KEYS.has(key)) continue
+      out[key] = sanitize(item)
+    }
+    return out
+  }
+  return value
+}
+
+// One query value: JSON-decode it (so `2` is a number, `true` a boolean, `{...}` an object), falling back
+// to the raw string when it is not JSON or nests past the depth cap.
+function decodeValue(raw: string, limits: SearchLimits): unknown {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(raw)
+  } catch {
+    return raw
+  }
+  if ((isPlainObject(parsed) || Array.isArray(parsed)) && exceedsDepth(parsed, limits.maxDepth)) {
+    return raw
+  }
+  return sanitize(parsed)
+}
+
+function encodeValue(value: unknown): string {
+  if (typeof value !== "string") return JSON.stringify(value)
+  // The codec is JSON-first on decode, so a raw string such as `"2"`, `"true"`, or `"null"`
+  // would otherwise change type on a serialize → parse round-trip. Quote only ambiguous strings;
+  // ordinary text stays readable (`?q=hello`, not `?q=%22hello%22`).
+  try {
+    JSON.parse(value)
+    return JSON.stringify(value)
+  } catch {
+    return value
+  }
+}
+
+/** The default JSON-first codec. Repeated keys (`?t=a&t=b`) decode to an array; single keys to a value. */
+const jsonCodec: SearchCodec = {
+  parse(raw, limits) {
+    const usp = new URLSearchParams(raw.startsWith("?") ? raw.slice(1) : raw)
+    const out: Record<string, unknown> = {}
+    let kept = 0
+    for (const key of new Set(usp.keys())) {
+      if (FORBIDDEN_KEYS.has(key)) continue
+      if (++kept > limits.maxKeys) break
+      const decoded = usp.getAll(key).map((value) => decodeValue(value, limits))
+      out[key] = decoded.length > 1 ? decoded : decoded[0]
+    }
+    return out
+  },
+  serialize(value) {
+    const usp = new URLSearchParams()
+    for (const [key, item] of Object.entries(value)) {
+      if (item === undefined) continue
+      if (Array.isArray(item) && item.length > 1) {
+        for (const element of item) usp.append(key, encodeValue(element))
+      } else {
+        // Repeated query keys naturally preserve arrays of length >= 2. Empty and singleton arrays
+        // need one JSON value or they collapse to a missing key / scalar during decoding.
+        usp.set(key, encodeValue(item))
+      }
+    }
+    const query = usp.toString()
+    return query === "" ? "" : `?${query}`
+  },
+}
+
+/**
+ * Parse a raw URL query into a structured object. Fails closed to `{}` when the raw string exceeds
+ * `limits.maxLength` (before any parsing work is done).
+ */
+export function parseSearch(
+  raw: string,
+  codec: SearchCodec = jsonCodec,
+  limits: SearchLimits = DEFAULT_SEARCH_LIMITS,
+): Record<string, unknown> {
+  if (raw.length > limits.maxLength) return {}
+  return codec.parse(raw, limits)
+}
+
+/** Serialize a structured search object back to a query string (leading `?`, or `""` when empty). */
+export function serializeSearch(
+  value: Record<string, unknown>,
+  codec: SearchCodec = jsonCodec,
+): string {
+  return codec.serialize(value)
+}
+
+/**
+ * The search a route sees for a raw URL query: parsed, then validated against a single `searchSchema`
+ * when the route declares one (failing closed to its defaults), or the raw parsed query otherwise. A
+ * one-link {@link searchOfChain}; use that directly for a layout+page chain. Both the server (`renderPage`,
+ * loader ctx) and the client (the adapter mount) derive search this way, from the same URL + schema, so
+ * they produce the identical value - SSR-correct by construction, no serialization.
+ */
+export function searchOf(
+  searchSchema: StandardSchemaV1 | undefined,
+  rawSearch: string,
+): Record<string, unknown> {
+  return searchOfChain([searchSchema], rawSearch)
+}
+
+/**
+ * The search for a route whose effective schema is a CHAIN - a `_layout` may declare `searchSchema` for
+ * shared keys (`?org`, `?theme`) and each page declares its own. The raw query is validated against every
+ * schema in the chain (outermost layout first, page last) and their outputs are merged, page-wins on a key
+ * conflict (nearest-wins, like `mergeHeads`): validate-each-then-combine, since Standard Schema has no
+ * `.merge()`. `undefined` links (a layout with no `searchSchema`) contribute nothing; when the whole chain
+ * is empty, the raw parsed query is returned. Fails closed per schema, same as {@link searchOf} (which is
+ * this with a one-link chain). The server and the client build the identical chain, so the value matches.
+ */
+export function searchOfChain(
+  schemas: readonly (StandardSchemaV1 | undefined)[],
+  rawSearch: string,
+): Record<string, unknown> {
+  const parsed = parseSearch(rawSearch)
+  const defined = schemas.filter((s): s is StandardSchemaV1 => s !== undefined)
+  if (defined.length === 0) return parsed
+  let out: Record<string, unknown> = {}
+  for (const schema of defined) {
+    const validated = validateSearch(schema, parsed)
+    if (!isPlainObject(validated)) {
+      throw new TypeError("[nifra/web] a search schema must produce an object")
+    }
+    out = { ...out, ...validated }
+  }
+  return out
+}
+
+/**
+ * The search OUTPUT type for a route MODULE - its `searchSchema`'s validated output, or the raw parsed
+ * query (`Record<string, unknown>`) when it declares none. The building block for typed cross-route
+ * navigation: generated route types (`nifra sync-routes`) map each path to
+ * `SearchOf<typeof import("./routes/<file>")>`, populating the augmentable `RouteSearch` interface.
+ */
+export type SearchOf<Module> = Module extends { searchSchema: infer S }
+  ? S extends StandardSchemaV1
+    ? InferOutput<S> extends Record<string, unknown>
+      ? InferOutput<S>
+      : never
+    : Record<string, unknown>
+  : Record<string, unknown>
+
+/**
+ * Validate a parsed search object against a route's Standard Schema, returning the typed output. Fails
+ * CLOSED: on validation issues it retries against an empty object so the schema's per-field defaults apply,
+ * and degrades to `{}` only if even that fails - it never throws on hostile input. An async validator is a
+ * configuration error (search must validate synchronously, in the render/nav path) and throws loudly.
+ */
+export function validateSearch<Schema extends StandardSchemaV1>(
+  schema: Schema,
+  parsed: Record<string, unknown>,
+): InferOutput<Schema> {
+  const result = schema["~standard"].validate(parsed)
+  if (result instanceof Promise) {
+    throw new TypeError("[nifra/web] a search schema must validate synchronously")
+  }
+  if (result.issues === undefined) return result.value as InferOutput<Schema>
+  const fallback = schema["~standard"].validate({})
+  if (fallback instanceof Promise) {
+    throw new TypeError("[nifra/web] a search schema must validate synchronously")
+  }
+  return (fallback.issues === undefined ? fallback.value : {}) as InferOutput<Schema>
+}
+
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (Array.isArray(a) && Array.isArray(b)) {
+    return a.length === b.length && a.every((item, index) => deepEqual(item, b[index]))
+  }
+  if (isPlainObject(a) && isPlainObject(b)) {
+    const aKeys = Object.keys(a)
+    return (
+      aKeys.length === Object.keys(b).length &&
+      aKeys.every((key) => key in b && deepEqual(a[key], b[key]))
+    )
+  }
+  return false
+}
+
+/**
+ * Structural sharing (shallow-first): return `next`, but reuse `prev`'s reference for every top-level key
+ * whose value is deep-equal. When nothing changed, `prev` itself is returned (stable identity), so a
+ * selector like `useSearch(s => s.filters)` does not see a change - and a filters-only component does not
+ * re-render when an unrelated key (`page`) changes.
+ */
+export function shareSearch<T>(prev: T, next: T): T {
+  if (Object.is(prev, next)) return prev
+  if (!isPlainObject(prev) || !isPlainObject(next)) return next
+  const out: Record<string, unknown> = {}
+  let identical = Object.keys(prev).length === Object.keys(next).length
+  for (const [key, after] of Object.entries(next)) {
+    if (key in prev && deepEqual(prev[key], after)) {
+      out[key] = prev[key]
+    } else {
+      out[key] = after
+      identical = false
+    }
+  }
+  return identical ? prev : (out as T)
+}
+
+/**
+ * True when two raw queries differ ONLY in keys a route declared client-only (`searchClientKeys`) - the
+ * signal a client navigation can update search WITHOUT re-running the loader (re-render, not revalidate:
+ * `?tab`, a client-side `?sort` over already-loaded rows, `?modal`). Returns false when a key OUTSIDE the
+ * allow-list changed (that key drives data, so the nav must revalidate) and when nothing changed at all (a
+ * same-URL nav still revalidates). Fail-safe by construction: an empty allow-list can never return true,
+ * so a route that declares no client keys always revalidates - the correct, never-stale default.
+ */
+export function isClientOnlySearchChange(
+  prevRaw: string,
+  nextRaw: string,
+  clientKeys: readonly string[],
+): boolean {
+  if (clientKeys.length === 0) return false
+  const prev = parseSearch(prevRaw)
+  const next = parseSearch(nextRaw)
+  const allow = new Set(clientKeys)
+  let changed = false
+  for (const key of new Set([...Object.keys(prev), ...Object.keys(next)])) {
+    if (deepEqual(prev[key], next[key])) continue
+    if (!allow.has(key)) return false // a loader-affecting key changed - must revalidate
+    changed = true
+  }
+  return changed // only a real change to a client-only key skips the fetch (else revalidate)
+}

package/src/server-only.ts

@@ -1,25 +1,25 @@
 /**
- * `@nifrajs/web/server-only` — the **explicit, opt-in poison-import marker** (Next's `import
- * "server-only"`). A module of PURE server logic that carries no `node:` import — a secret-bearing
- * constant, a server-only API call — can't be caught by nifra's other two client-leak guards: the
+ * `@nifrajs/web/server-only` - the **explicit, opt-in poison-import marker** (Next's `import
+ * "server-only"`). A module of PURE server logic that carries no `node:` import - a secret-bearing
+ * constant, a server-only API call - can't be caught by nifra's other two client-leak guards: the
  * `.server` convention (which empties `*.server` modules in the client build) needs the file to be
  * NAMED `*.server`, and the node-builtin guard only fires when a `node:` import actually reaches a
- * client chunk. This marker closes that gap: drop a side-effect import at the top of the module —
+ * client chunk. This marker closes that gap: drop a side-effect import at the top of the module -
  *
  *     import "@nifrajs/web/server-only"
  *
- * — and the CLIENT build ({@link buildClient}) FAILS LOUD, naming the import chain, if that module
+ * - and the CLIENT build ({@link buildClient}) FAILS LOUD, naming the import chain, if that module
  * ever lands in a browser chunk. On the SERVER build/runtime it's a harmless no-op (this empty
  * module), so the same file runs untouched server-side.
  *
  * Pair it with the type-level {@link ServerOnly} brand (from `@nifrajs/web`) on the module's exports
  * to signal intent to readers + the compiler; this runtime import is what actually fails the build.
  *
- * @see ServerOnly — the type-level intent marker that complements this runtime import.
+ * @see ServerOnly - the type-level intent marker that complements this runtime import.
  */
 
 // Intentionally empty. The marker is the IMPORT itself: `buildClient` detects any module that imports
 // this specifier and lands in a client chunk (via the same Bun metafile graph the node-builtin guard
-// walks) and fails the build. There is no value to export and nothing to run — on the server it's a
+// walks) and fails the build. There is no value to export and nothing to run - on the server it's a
 // no-op so the marked module behaves normally; on the client the build never completes.
 export {}

package/src/service-worker.ts

@@ -0,0 +1,165 @@
+/**
+ * `@nifrajs/web/service-worker` - generate a service worker from a build manifest.
+ *
+ * A service worker is the one piece of an app that outlives a deploy, keeps serving after you have
+ * stopped, and can hand one user a response produced for another. So the generated worker is
+ * deliberately narrow, and every rule below exists because the permissive version of it is a bug:
+ *
+ *   - **Only content-hashed assets are precached.** A hashed URL names its bytes, so serving it from
+ *     cache forever is correct by construction. Anything unhashed is left to the network.
+ *   - **Documents are never cached.** Only navigations that FAIL are answered, and only with the
+ *     offline page you nominate. A cached HTML document is how a service worker serves one signed-in
+ *     user the page rendered for another; there is no per-user story here worth that risk.
+ *   - **GET, same-origin, `ok`, and not `no-store`.** Anything else goes straight to the network.
+ *   - **The cache name carries the build id.** A deploy that changed the assets gets a new cache, and
+ *     activation deletes every older one, so a stale worker cannot pin an old build indefinitely.
+ *
+ * It is opt-in and generated at build time; an app that does not call this ships nothing.
+ */
+
+/** The parts of a `BuildManifest` a worker needs. Structural, so a caller can pass extra fields. */
+export interface ServiceWorkerManifest {
+  readonly entry: string
+  readonly assets: readonly string[]
+  readonly css?: readonly string[]
+}
+
+export interface ServiceWorkerOptions {
+  /**
+   * Distinguishes this build's cache from the last one. Use something that changes exactly when the
+   * assets do - a content hash, a commit sha, a release version.
+   */
+  readonly buildId: string
+  /**
+   * URL of a page to serve when a navigation fails and the network is unreachable. It must be a
+   * static, user-independent document (a prerendered `/offline`), because every visitor gets the same
+   * bytes. Omit it and failed navigations simply fail, which is the honest default.
+   */
+  readonly offlineUrl?: string
+  /** Cache name prefix. Default `nifra`. */
+  readonly cacheName?: string
+  /** Extra same-origin URLs to precache. Only pass immutable ones. */
+  readonly additionalPrecache?: readonly string[]
+}
+
+const SW_URL = /^\/[\w\-./@%]*$/
+
+/** A precache URL has to be same-origin, rooted, and free of anything that could break out of a list. */
+function assertPrecachable(url: string, label: string): void {
+  if (typeof url !== "string" || url === "") {
+    throw new Error(`[nifra/service-worker] ${label} must be a non-empty string`)
+  }
+  if (!url.startsWith("/") || url.startsWith("//")) {
+    throw new Error(
+      `[nifra/service-worker] ${label} must be a root-relative same-origin path, got ${JSON.stringify(url)}`,
+    )
+  }
+  if (!SW_URL.test(url)) {
+    throw new Error(
+      `[nifra/service-worker] ${label} contains characters that are not valid in an asset path: ${JSON.stringify(url)}`,
+    )
+  }
+}
+
+/**
+ * Generate the service worker source for a build.
+ *
+ * Write the result to a file served from the ORIGIN ROOT (`/sw.js`): a worker's default scope is its
+ * own directory, so one served from `/assets/` could never control the pages it exists for.
+ */
+export function generateServiceWorker(
+  manifest: ServiceWorkerManifest,
+  options: ServiceWorkerOptions,
+): string {
+  if (typeof options.buildId !== "string" || options.buildId.trim() === "") {
+    throw new Error("[nifra/service-worker] buildId is required and must be non-empty")
+  }
+  if (/[^\w.-]/.test(options.buildId)) {
+    throw new Error(
+      `[nifra/service-worker] buildId must be word characters, dots or hyphens, got ${JSON.stringify(options.buildId)}`,
+    )
+  }
+  const prefix = options.cacheName ?? "nifra"
+  if (/[^\w.-]/.test(prefix)) {
+    throw new Error(`[nifra/service-worker] cacheName must be word characters, dots or hyphens`)
+  }
+
+  const precache = [
+    manifest.entry,
+    ...manifest.assets,
+    ...(manifest.css ?? []),
+    ...(options.additionalPrecache ?? []),
+  ]
+  for (const url of precache) assertPrecachable(url, "precache url")
+  const offline = options.offlineUrl
+  if (offline !== undefined) assertPrecachable(offline, "offlineUrl")
+
+  // De-duped and sorted so an unchanged build produces an unchanged worker - a byte-identical file
+  // means the browser does not treat it as an update.
+  const urls = [...new Set(offline === undefined ? precache : [...precache, offline])].sort()
+
+  return `// Generated by @nifrajs/web/service-worker. Do not edit.
+const CACHE = ${JSON.stringify(`${prefix}-${options.buildId}`)}
+const PRECACHE = ${JSON.stringify(urls)}
+const OFFLINE = ${offline === undefined ? "null" : JSON.stringify(offline)}
+
+self.addEventListener("install", (event) => {
+  // Take over as soon as the new assets are stored; the activate handler drops the old cache, so
+  // waiting would only serve stale bytes for longer.
+  event.waitUntil(caches.open(CACHE).then((c) => c.addAll(PRECACHE)).then(() => self.skipWaiting()))
+})
+
+self.addEventListener("activate", (event) => {
+  event.waitUntil(
+    caches
+      .keys()
+      .then((keys) => Promise.all(keys.filter((k) => k !== CACHE).map((k) => caches.delete(k))))
+      .then(() => self.clients.claim()),
+  )
+})
+
+self.addEventListener("fetch", (event) => {
+  const request = event.request
+  if (request.method !== "GET") return
+  const url = new URL(request.url)
+  if (url.origin !== self.location.origin) return
+
+  // Navigations: network only, with the offline document as a last resort. A cached HTML response is
+  // how one user gets served the page rendered for another, so nothing is stored here.
+  if (request.mode === "navigate") {
+    if (OFFLINE === null) return
+    event.respondWith(fetch(request).catch(() => caches.match(OFFLINE).then((r) => r ?? Response.error())))
+    return
+  }
+
+  // Assets: cache first, because every precached URL is content-hashed and therefore immutable.
+  event.respondWith(
+    caches.match(request).then((hit) => {
+      if (hit !== undefined) return hit
+      return fetch(request).then((response) => {
+        const cacheable =
+          response.ok &&
+          response.type === "basic" &&
+          !(response.headers.get("cache-control") ?? "").includes("no-store")
+        if (cacheable && PRECACHE.includes(url.pathname)) {
+          const copy = response.clone()
+          void caches.open(CACHE).then((c) => c.put(request, copy))
+        }
+        return response
+      })
+    }),
+  )
+})
+`
+}
+
+/**
+ * The registration snippet, for a `<script>` in your document shell.
+ *
+ * Registration is deliberately deferred to `load`: a worker installing during first paint competes
+ * with the page it is meant to speed up.
+ */
+export function serviceWorkerRegistration(scriptUrl = "/sw.js"): string {
+  assertPrecachable(scriptUrl, "scriptUrl")
+  return `if("serviceWorker"in navigator){addEventListener("load",function(){navigator.serviceWorker.register(${JSON.stringify(scriptUrl)}).catch(function(){})})}`
+}