@bquery/bquery 1.10.0 → 1.11.0

package/src/ssr/router-bridge.ts

@@ -0,0 +1,177 @@
+/**
+ * Router ↔ SSR bridge.
+ *
+ * On the server you typically need to:
+ * 1. Match the incoming URL against your router's route table.
+ * 2. Run any data loaders attached to the matched route.
+ * 3. Inject the resolved route + loader data into the SSR binding context.
+ *
+ * `resolveSSRRoute()` and `runRouteLoaders()` perform steps 1 and 2 without
+ * coupling the SSR module to the actual `createRouter()` runtime — only the
+ * pure `matchRoute()` helper from `@bquery/bquery/router` is used. Loaders
+ * live on `RouteDefinition.meta.loader` (additive, no existing field changes).
+ *
+ * @module bquery/ssr
+ */
+
+import { matchRoute } from '../router/match';
+import { parseQuery } from '../router/query';
+import type { Route, RouteDefinition } from '../router/types';
+import type { SSRContext } from './context';
+
+/**
+ * Loader signature for SSR routes. Attach as `meta.loader` on a
+ * `RouteDefinition` and `runRouteLoaders()` will invoke it with the matched
+ * route + the active SSR context.
+ */
+export type SSRRouteLoader<T = unknown> = (args: {
+  route: Route;
+  ctx: SSRContext;
+}) => T | Promise<T>;
+
+const getLoader = (route: RouteDefinition | null): SSRRouteLoader | undefined => {
+  if (!route || !route.meta) return undefined;
+  const loader = (route.meta as { loader?: unknown }).loader;
+  return typeof loader === 'function' ? (loader as SSRRouteLoader) : undefined;
+};
+
+/** Result of `resolveSSRRoute()`. */
+export interface ResolvedSSRRoute {
+  /** Route-like snapshot for the requested URL, with `matched` set when found. */
+  route: Route;
+  /** Whether a route definition was actually matched. */
+  matched: boolean;
+  /** Whether the matched route has a `redirectTo` target. */
+  isRedirect: boolean;
+  /** Redirect target, if any. */
+  redirectTo?: string;
+}
+
+/**
+ * Matches a URL against a route table without instantiating a full router.
+ *
+ * Designed to be called on the server before the SSR render so userland can
+ * branch on `matched`/`isRedirect` (e.g. issue a 302 instead of rendering).
+ *
+ * @example
+ * ```ts
+ * import { resolveSSRRoute } from '@bquery/bquery/ssr';
+ *
+ * const { route, matched, isRedirect, redirectTo } = resolveSSRRoute({
+ *   url: new URL(request.url),
+ *   routes,
+ * });
+ *
+ * if (isRedirect) return Response.redirect(redirectTo!, 302);
+ * if (!matched) return new Response('Not Found', { status: 404 });
+ * ```
+ */
+export const resolveSSRRoute = (options: {
+  url: string | URL;
+  routes: RouteDefinition[];
+  /** Strip a base path before matching. Default: `''`. */
+  base?: string;
+}): ResolvedSSRRoute => {
+  const url =
+    typeof options.url === 'string' ? new URL(options.url, 'http://localhost/') : options.url;
+  const base = options.base ?? '';
+  let pathname = url.pathname;
+  if (base) {
+    if (pathname === base) {
+      pathname = '/';
+    } else if (pathname.startsWith(`${base}/`)) {
+      pathname = pathname.slice(base.length) || '/';
+    }
+  }
+
+  const result = matchRoute(pathname, options.routes);
+  const route: Route = {
+    path: pathname,
+    params: result?.params ?? {},
+    query: parseQuery(url.search),
+    matched: result?.matched ?? null,
+    hash: url.hash.replace(/^#/, ''),
+  };
+  const matched = result !== null;
+  const matchedDef = result?.matched ?? null;
+  const isRedirect =
+    !!matchedDef && 'redirectTo' in matchedDef && typeof matchedDef.redirectTo === 'string';
+  return {
+    route,
+    matched,
+    isRedirect,
+    redirectTo: isRedirect ? (matchedDef as { redirectTo: string }).redirectTo : undefined,
+  };
+};
+
+/**
+ * Runs the loader attached to the matched route (`meta.loader`), if any.
+ * Returns the resolved data, or `undefined` if no loader is configured.
+ */
+export const runRouteLoaders = async <T = unknown>(
+  route: Route,
+  ctx: SSRContext
+): Promise<T | undefined> => {
+  const loader = getLoader(route.matched);
+  if (!loader) return undefined;
+  try {
+    return (await loader({ route, ctx })) as T;
+  } catch (error) {
+    ctx.reportError(error);
+    return undefined;
+  }
+};
+
+/**
+ * Convenience wrapper that resolves a route, runs its loader, and returns a
+ * binding-context fragment ready to be merged into the data passed to
+ * `renderToStringAsync()` / `renderToResponse()`.
+ *
+ * @example
+ * ```ts
+ * import {
+ *   createSSRContext,
+ *   createSSRRouterContext,
+ *   renderToResponse,
+ * } from '@bquery/bquery/ssr';
+ *
+ * const ctx = createSSRContext();
+ * const router = await createSSRRouterContext({ url: request.url, routes, ctx });
+ * if (router.isRedirect) return Response.redirect(router.redirectTo!, 302);
+ *
+ * return renderToResponse(template, { ...router.bindings }, { context: ctx });
+ * ```
+ */
+export const createSSRRouterContext = async (options: {
+  url: string | URL;
+  routes: RouteDefinition[];
+  base?: string;
+  ctx: SSRContext;
+}): Promise<{
+  route: Route;
+  matched: boolean;
+  isRedirect: boolean;
+  redirectTo?: string;
+  data: unknown;
+  bindings: Record<string, unknown>;
+}> => {
+  const resolved = resolveSSRRoute({
+    url: options.url,
+    routes: options.routes,
+    base: options.base,
+  });
+  const data = resolved.matched ? await runRouteLoaders(resolved.route, options.ctx) : undefined;
+  return {
+    route: resolved.route,
+    matched: resolved.matched,
+    isRedirect: resolved.isRedirect,
+    redirectTo: resolved.redirectTo,
+    data,
+    bindings: {
+      route: resolved.route,
+      params: resolved.route.params,
+      query: resolved.route.query,
+      data,
+    },
+  };
+};

package/src/ssr/runtime.ts

@@ -0,0 +1,131 @@
+/**
+ * Runtime detection helpers for the SSR module.
+ *
+ * Detects whether the current runtime is Bun, Deno, Node.js, a browser,
+ * or a Web-Worker / edge runtime (Cloudflare Workers / `workerd`).
+ * Detection is feature-based and never throws; calling these helpers is
+ * safe in any environment that provides `globalThis`.
+ *
+ * @module bquery/ssr
+ */
+
+/**
+ * Identifier for a recognised JavaScript runtime.
+ */
+export type SSRRuntime = 'bun' | 'deno' | 'node' | 'browser' | 'workerd' | 'unknown';
+
+interface BunGlobal {
+  version?: string;
+}
+
+interface DenoGlobal {
+  version?: { deno?: string };
+}
+
+interface NodeProcess {
+  versions?: { node?: string };
+}
+
+const safeGlobal = (): Record<string, unknown> => {
+  return (typeof globalThis !== 'undefined' ? globalThis : {}) as Record<string, unknown>;
+};
+
+/**
+ * Detects the current runtime via feature checks on `globalThis`.
+ * Order matters: Bun and Deno expose Node compatibility shims, so they are
+ * checked first.
+ *
+ * @returns The detected runtime identifier, or `'unknown'` if none match.
+ *
+ * @example
+ * ```ts
+ * import { detectRuntime } from '@bquery/bquery/ssr';
+ *
+ * if (detectRuntime() === 'deno') {
+ *   // Deno-specific behaviour
+ * }
+ * ```
+ */
+export const detectRuntime = (): SSRRuntime => {
+  const g = safeGlobal();
+
+  if (typeof (g.Bun as BunGlobal | undefined)?.version === 'string') {
+    return 'bun';
+  }
+
+  if (typeof (g.Deno as DenoGlobal | undefined)?.version?.deno === 'string') {
+    return 'deno';
+  }
+
+  // workerd / Cloudflare Workers expose `navigator.userAgent === 'Cloudflare-Workers'`
+  // and lack `process.versions.node`.
+  const navigator = g.navigator as { userAgent?: string } | undefined;
+  if (
+    typeof navigator?.userAgent === 'string' &&
+    navigator.userAgent.toLowerCase().includes('cloudflare-workers')
+  ) {
+    return 'workerd';
+  }
+
+  if (typeof (g.process as NodeProcess | undefined)?.versions?.node === 'string') {
+    return 'node';
+  }
+
+  if (typeof g.window !== 'undefined' && typeof g.document !== 'undefined') {
+    return 'browser';
+  }
+
+  return 'unknown';
+};
+
+/**
+ * Returns `true` when called inside a server-side runtime (Bun, Deno, Node,
+ * Cloudflare Workers / `workerd`).
+ */
+export const isServerRuntime = (): boolean => {
+  const rt = detectRuntime();
+  return rt === 'bun' || rt === 'deno' || rt === 'node' || rt === 'workerd';
+};
+
+/**
+ * Returns `true` when called inside a browser-like runtime (full DOM available).
+ */
+export const isBrowserRuntime = (): boolean => detectRuntime() === 'browser';
+
+/**
+ * Lightweight feature-detection report for runtime capabilities relevant to SSR.
+ */
+export interface SSRRuntimeFeatures {
+  /** Whether `Request`/`Response`/`fetch` are available on `globalThis`. */
+  fetchApi: boolean;
+  /** Whether `ReadableStream` is available on `globalThis`. */
+  webStreams: boolean;
+  /** Whether `TextEncoder` is available on `globalThis`. */
+  textEncoder: boolean;
+  /** Whether `crypto.subtle` is available (used for ETag hashing). */
+  subtleCrypto: boolean;
+  /** Whether `crypto.randomUUID()` is available. */
+  randomUuid: boolean;
+  /** Whether the global `DOMParser` is available. */
+  domParser: boolean;
+}
+
+/**
+ * Returns a feature-detection report for the current runtime. All checks are
+ * non-throwing; missing globals yield `false`.
+ */
+export const getSSRRuntimeFeatures = (): SSRRuntimeFeatures => {
+  const g = safeGlobal();
+  const crypto = g.crypto as { subtle?: unknown; randomUUID?: () => string } | undefined;
+  return {
+    fetchApi:
+      typeof g.Request === 'function' &&
+      typeof g.Response === 'function' &&
+      typeof g.fetch === 'function',
+    webStreams: typeof g.ReadableStream === 'function',
+    textEncoder: typeof g.TextEncoder === 'function',
+    subtleCrypto: typeof crypto?.subtle === 'object' && crypto?.subtle !== null,
+    randomUuid: typeof crypto?.randomUUID === 'function',
+    domParser: typeof g.DOMParser === 'function',
+  };
+};

package/src/ssr/serialize.ts

@@ -9,6 +9,7 @@
 
 import { getStore, listStores } from '../store/index';
 import { isPrototypePollutionKey } from '../core/utils/object';
+import { escapeForHtmlAttribute, escapeForScript } from './escape';
 import type { DeserializedStoreState, SerializeOptions } from './types';
 
 const isStoreStateObject = (value: unknown): value is Record<string, unknown> =>
@@ -33,33 +34,6 @@ export type SerializeResult = {
   scriptTag: string;
 };
 
-/**
- * Escapes a string for safe embedding in a `<script>` tag.
- * Prevents XSS via `</script>` injection and HTML entities.
- *
- * @internal
- */
-const escapeForScript = (str: string): string => {
-  return str
-    .replace(/</g, '\\u003c')
-    .replace(/>/g, '\\u003e')
-    .replace(/\//g, '\\u002f')
-    .replace(/\u2028/g, '\\u2028')
-    .replace(/\u2029/g, '\\u2029');
-};
-
-/**
- * Escapes a string for safe embedding in an HTML attribute value.
- * @internal
- */
-const escapeForHtmlAttribute = (str: string): string => {
-  return str
-    .replace(/&/g, '&amp;')
-    .replace(/"/g, '&quot;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;');
-};
-
 /**
  * Serializes the state of registered stores into a JSON string and
  * a `<script>` tag suitable for embedding in server-rendered HTML.

package/src/ssr/store-snapshot.ts

@@ -0,0 +1,209 @@
+/**
+ * Versioned store snapshots and strict drift-checking hydration.
+ *
+ * Sits *on top of* the simple `serializeStoreState()` / `hydrateStore()` pair
+ * to give applications a way to:
+ * - tag the snapshot with a schema version so a stale client can refuse to
+ *   apply server data that no longer matches its store shape;
+ * - opt into strict mode where unknown keys cause a warning;
+ * - selectively serialize / hydrate a subset of stores.
+ *
+ * Backwards compatible: the existing helpers stay untouched and remain the
+ * primary entry-point for simple use cases.
+ *
+ * @module bquery/ssr
+ */
+
+import { getStore, listStores } from '../store/index';
+import { isPrototypePollutionKey } from '../core/utils/object';
+import { escapeForHtmlAttribute, escapeForScript } from './escape';
+
+const isStateObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value);
+
+const sanitize = (value: Record<string, unknown>): Record<string, unknown> => {
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (isPrototypePollutionKey(k)) continue;
+    out[k] = v;
+  }
+  return out;
+};
+
+/** Versioned store snapshot. */
+export interface SSRStoreSnapshot {
+  /** Application-defined version string. Stable per schema. */
+  version: string;
+  /** Map of store ID → sanitized state. */
+  state: Record<string, Record<string, unknown>>;
+}
+
+/** Result of `serializeStoreSnapshot()`. */
+export interface SerializeSnapshotResult {
+  snapshot: SSRStoreSnapshot;
+  /** JSON-serialized snapshot. */
+  json: string;
+  /** `<script>` tag ready to embed (CSP-nonce-aware via `options.nonce`). */
+  scriptTag: string;
+}
+
+/** Options for `serializeStoreSnapshot()`. */
+export interface SerializeSnapshotOptions {
+  /** Schema version. Required: hydration only succeeds when versions match. */
+  version: string;
+  /** Subset of store IDs to serialize. Defaults to all registered stores. */
+  storeIds?: string[];
+  /** Element ID for the generated `<script>` tag. */
+  scriptId?: string;
+  /** Global window key where the snapshot is assigned. */
+  globalKey?: string;
+  /** CSP nonce applied to the generated `<script>`. */
+  nonce?: string;
+}
+
+/**
+ * Captures every registered store's state into a versioned snapshot and
+ * returns both the JSON payload and a ready-to-embed `<script>` tag.
+ */
+export const serializeStoreSnapshot = (
+  options: SerializeSnapshotOptions
+): SerializeSnapshotResult => {
+  const {
+    version,
+    storeIds,
+    scriptId = '__BQUERY_STORE_SNAPSHOT__',
+    globalKey = '__BQUERY_STORE_SNAPSHOT__',
+    nonce,
+  } = options;
+
+  if (typeof version !== 'string' || version.length === 0) {
+    throw new Error(
+      'serializeStoreSnapshot: `version` is required and must be a non-empty string.'
+    );
+  }
+  if (isPrototypePollutionKey(scriptId) || isPrototypePollutionKey(globalKey)) {
+    throw new Error('serializeStoreSnapshot: invalid scriptId/globalKey.');
+  }
+
+  const ids = storeIds ?? listStores();
+  const state = Object.create(null) as Record<string, Record<string, unknown>>;
+  for (const id of ids) {
+    if (isPrototypePollutionKey(id)) continue;
+    const store = getStore<{ $state: Record<string, unknown> }>(id);
+    if (store) state[id] = sanitize(store.$state);
+  }
+  const snapshot: SSRStoreSnapshot = { version, state };
+  const json = JSON.stringify(snapshot);
+
+  const escapedJson = escapeForScript(json);
+  const escapedKey = escapeForScript(JSON.stringify(globalKey));
+  const escapedId = escapeForHtmlAttribute(scriptId);
+  const nonceAttr = nonce ? ` nonce="${escapeForHtmlAttribute(nonce)}"` : '';
+  const scriptTag = `<script id="${escapedId}"${nonceAttr}>window[${escapedKey}]=${escapedJson}</script>`;
+  return { snapshot, json, scriptTag };
+};
+
+/** Options for `hydrateStoreSnapshot()`. */
+export interface HydrateSnapshotOptions {
+  /**
+   * If set, the snapshot's `version` must match this value. Otherwise the
+   * function returns early (and warns when `strict` is true).
+   */
+  expectedVersion?: string;
+  /**
+   * Strict mode: warn on version mismatch + warn on unknown store IDs (i.e.
+   * the snapshot has IDs that aren't currently registered). Default: `false`.
+   */
+  strict?: boolean;
+}
+
+/** Result of `hydrateStoreSnapshot()`. */
+export interface HydrateSnapshotResult {
+  /** Whether the snapshot was applied. */
+  applied: boolean;
+  /** Reason when not applied (`'version-mismatch' | 'invalid-shape'`). */
+  reason?: 'version-mismatch' | 'invalid-shape';
+  /** IDs that were applied. */
+  appliedIds: string[];
+  /** IDs in the snapshot that no store exists for. */
+  unknownIds: string[];
+}
+
+const isStoreSnapshot = (value: unknown): value is SSRStoreSnapshot => {
+  if (!isStateObject(value)) return false;
+  const v = (value as { version: unknown }).version;
+  const s = (value as { state: unknown }).state;
+  return typeof v === 'string' && isStateObject(s);
+};
+
+/**
+ * Applies a previously-serialized `SSRStoreSnapshot` to the registered stores.
+ *
+ * Returns a structured result; never throws on drift unless an explicit error
+ * is thrown by a store's `$patch()` implementation.
+ */
+export const hydrateStoreSnapshot = (
+  snapshot: unknown,
+  options: HydrateSnapshotOptions = {}
+): HydrateSnapshotResult => {
+  if (!isStoreSnapshot(snapshot)) {
+    if (options.strict) {
+      console.warn('[bQuery SSR] hydrateStoreSnapshot: snapshot has invalid shape.');
+    }
+    return { applied: false, reason: 'invalid-shape', appliedIds: [], unknownIds: [] };
+  }
+
+  if (typeof options.expectedVersion === 'string' && options.expectedVersion !== snapshot.version) {
+    if (options.strict) {
+      console.warn(
+        `[bQuery SSR] hydrateStoreSnapshot: version mismatch — server="${snapshot.version}" client="${options.expectedVersion}". Skipping.`
+      );
+    }
+    return { applied: false, reason: 'version-mismatch', appliedIds: [], unknownIds: [] };
+  }
+
+  const appliedIds: string[] = [];
+  const unknownIds: string[] = [];
+  for (const [id, state] of Object.entries(snapshot.state)) {
+    if (isPrototypePollutionKey(id) || !isStateObject(state)) continue;
+    const store = getStore<{ $patch?: (partial: Record<string, unknown>) => void }>(id);
+    if (!store || typeof store.$patch !== 'function') {
+      unknownIds.push(id);
+      if (options.strict) {
+        console.warn(
+          `[bQuery SSR] hydrateStoreSnapshot: store "${id}" is not registered; skipping.`
+        );
+      }
+      continue;
+    }
+    store.$patch(sanitize(state));
+    appliedIds.push(id);
+  }
+  return { applied: appliedIds.length > 0, appliedIds, unknownIds };
+};
+
+/**
+ * Reads the snapshot emitted by `serializeStoreSnapshot()` from `window`,
+ * cleans up the global, and returns the parsed `SSRStoreSnapshot`.
+ *
+ * Returns `null` when no snapshot was found or when it has the wrong shape.
+ */
+export const readStoreSnapshot = (
+  globalKey = '__BQUERY_STORE_SNAPSHOT__',
+  scriptId = '__BQUERY_STORE_SNAPSHOT__'
+): SSRStoreSnapshot | null => {
+  if (isPrototypePollutionKey(globalKey) || isPrototypePollutionKey(scriptId)) return null;
+  if (typeof window === 'undefined') return null;
+  const raw = (window as unknown as Record<string, unknown>)[globalKey];
+  try {
+    delete (window as unknown as Record<string, unknown>)[globalKey];
+  } catch {
+    (window as unknown as Record<string, unknown>)[globalKey] = undefined;
+  }
+  if (typeof document !== 'undefined' && typeof document.getElementById === 'function') {
+    const el = document.getElementById(scriptId);
+    if (el) el.remove();
+  }
+  if (!isStoreSnapshot(raw)) return null;
+  return raw;
+};