@bquery/bquery 1.10.0 → 1.11.1

package/src/ssr/adapters.ts

@@ -0,0 +1,330 @@
+/**
+ * Runtime adapters for SSR.
+ *
+ * Provide thin glue functions that turn a bQuery render handler into a
+ * runtime-native server callback. They share a common signature so the same
+ * application can be served by Bun, Deno, Node and any Web-`fetch` host.
+ *
+ * @module bquery/ssr
+ */
+
+import type { SSRContext } from './context';
+import { detectRuntime } from './runtime';
+
+/** A handler that turns a request into a Response (Web-fetch style). */
+export type SSRRequestHandler = (
+  request: Request,
+  context?: SSRContext
+) => Promise<Response> | Response;
+
+/* ---------------------------------------------------------------------------
+ * Web (generic fetch) adapter
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Identity adapter for Web-`fetch` style hosts (Hono, Elysia, Workerd, edge
+ * runtimes). Exists for symmetry and future logging hooks.
+ */
+export const createWebHandler = (handler: SSRRequestHandler): SSRRequestHandler => handler;
+
+/* ---------------------------------------------------------------------------
+ * Bun adapter
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Wraps a handler for `Bun.serve()`. Returns a function with Bun's expected
+ * signature `(request, server) => Response | Promise<Response>`.
+ */
+export const createBunHandler = (
+  handler: SSRRequestHandler
+): ((request: Request) => Promise<Response>) => {
+  return async (request) => Promise.resolve(handler(request));
+};
+
+/* ---------------------------------------------------------------------------
+ * Deno adapter
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Wraps a handler for `Deno.serve()`. Returns a function with Deno's expected
+ * signature `(request, info?) => Response | Promise<Response>`.
+ */
+export const createDenoHandler = (
+  handler: SSRRequestHandler
+): ((request: Request) => Promise<Response>) => {
+  return async (request) => Promise.resolve(handler(request));
+};
+
+/* ---------------------------------------------------------------------------
+ * Node adapter (`node:http`)
+ * ------------------------------------------------------------------------- */
+
+/** Minimal subset of `node:http` IncomingMessage we rely on. */
+export interface NodeIncomingMessage {
+  url?: string;
+  method?: string;
+  headers: Record<string, string | string[] | undefined>;
+  on(event: 'data', listener: (chunk: Uint8Array | string) => void): void;
+  on(event: 'end', listener: () => void): void;
+  on(event: 'error', listener: (err: unknown) => void): void;
+  destroy?(error?: Error): void;
+}
+
+/** Minimal subset of `node:http` ServerResponse we rely on. */
+export interface NodeServerResponse {
+  statusCode: number;
+  setHeader(name: string, value: string | number | readonly string[]): void;
+  write(chunk: Uint8Array | string): boolean;
+  end(chunk?: Uint8Array | string): void;
+  once?(event: 'drain' | 'error', listener: (error?: unknown) => void): void;
+  on?(event: 'drain' | 'error', listener: (error?: unknown) => void): void;
+}
+
+/** Optional hardening settings for the `node:http` adapter. */
+export interface NodeHandlerOptions {
+  /** Reject request bodies that exceed this many bytes. Default: unlimited. */
+  maxBodyBytes?: number;
+}
+
+const shouldReadNodeBody = (method: string): boolean => method !== 'GET' && method !== 'HEAD';
+
+class NodeRequestLimitError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'NodeRequestLimitError';
+  }
+}
+
+const getSingleHeader = (
+  headers: NodeIncomingMessage['headers'],
+  name: string
+): string | undefined => {
+  const value = headers[name];
+  if (Array.isArray(value)) return value[0];
+  return value;
+};
+
+const getContentLength = (req: NodeIncomingMessage): number | null => {
+  const header = getSingleHeader(req.headers, 'content-length');
+  if (!header) return null;
+  const value = Number.parseInt(header, 10);
+  return Number.isSafeInteger(value) && value >= 0 ? value : null;
+};
+
+const readNodeBody = (req: NodeIncomingMessage, maxBodyBytes?: number): Promise<ArrayBuffer> =>
+  new Promise((resolve, reject) => {
+    const chunks: Uint8Array[] = [];
+    let total = 0;
+    let done = false;
+    const fail = (error: unknown): void => {
+      if (done) return;
+      done = true;
+      chunks.length = 0;
+      total = 0;
+      req.destroy?.(error instanceof Error ? error : undefined);
+      reject(error);
+    };
+
+    const declaredLength = getContentLength(req);
+    if (maxBodyBytes !== undefined && declaredLength !== null && declaredLength > maxBodyBytes) {
+      fail(new NodeRequestLimitError(`Request body exceeds ${maxBodyBytes} bytes.`));
+      return;
+    }
+
+    req.on('data', (chunk) => {
+      if (done) return;
+      const bytes = typeof chunk === 'string' ? new TextEncoder().encode(chunk) : chunk;
+      total += bytes.byteLength;
+      if (maxBodyBytes !== undefined && total > maxBodyBytes) {
+        fail(new NodeRequestLimitError(`Request body exceeds ${maxBodyBytes} bytes.`));
+        return;
+      }
+      chunks.push(bytes);
+    });
+    req.on('end', () => {
+      if (done) return;
+      done = true;
+      const buffer = new ArrayBuffer(total);
+      const body = new Uint8Array(buffer);
+      let offset = 0;
+      for (const chunk of chunks) {
+        body.set(chunk, offset);
+        offset += chunk.byteLength;
+      }
+      resolve(buffer);
+    });
+    req.on('error', fail);
+  });
+
+const buildNodeUrl = (req: NodeIncomingMessage, protocol: string): URL => {
+  const fallbackOrigin = `${protocol}://localhost`;
+  const host = getSingleHeader(req.headers, 'host') || 'localhost';
+  try {
+    return new URL(req.url ?? '/', `${protocol}://${host}`);
+  } catch {
+    try {
+      return new URL(req.url ?? '/', fallbackOrigin);
+    } catch {
+      return new URL('/', fallbackOrigin);
+    }
+  }
+};
+
+const buildRequestFromNode = async (
+  req: NodeIncomingMessage,
+  options: NodeHandlerOptions = {}
+): Promise<Request> => {
+  // Only honour `x-forwarded-proto` when it advertises a known protocol.
+  // This adapter assumes deployment behind a trusted reverse proxy; callers
+  // exposing `node:http` directly to the public internet should strip
+  // `x-forwarded-*` headers in their proxy layer.
+  const forwardedProto =
+    typeof getSingleHeader(req.headers, 'x-forwarded-proto') === 'string'
+      ? (getSingleHeader(req.headers, 'x-forwarded-proto') as string)
+          .split(',')[0]
+          .trim()
+          .toLowerCase()
+      : '';
+  const protocol =
+    forwardedProto === 'http' || forwardedProto === 'https' ? forwardedProto : 'http';
+  const url = buildNodeUrl(req, protocol);
+
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(req.headers)) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) {
+      for (const v of value) headers.append(name, v);
+    } else {
+      headers.append(name, value);
+    }
+  }
+
+  const upperMethod = (req.method ?? 'GET').toUpperCase();
+  const init: RequestInit = {
+    method: upperMethod,
+    headers,
+  };
+
+  if (shouldReadNodeBody(upperMethod)) {
+    init.body = await readNodeBody(req, options.maxBodyBytes);
+  }
+
+  return new Request(url.toString(), init);
+};
+
+type HeadersWithSetCookie = Headers & {
+  getSetCookie?: () => string[];
+};
+
+const getSetCookieHeaderValues = (headers: Headers): string[] => {
+  const setCookies = (headers as HeadersWithSetCookie).getSetCookie?.();
+  if (Array.isArray(setCookies) && setCookies.length > 0) {
+    return setCookies;
+  }
+  const fallback = headers.get('set-cookie');
+  return fallback ? [fallback] : [];
+};
+
+const waitForNodeDrain = (res: NodeServerResponse): Promise<void> =>
+  new Promise((resolve, reject) => {
+    const once = typeof res.once === 'function' ? res.once.bind(res) : undefined;
+    const on = typeof res.on === 'function' ? res.on.bind(res) : undefined;
+    const subscribe = once ?? on;
+    if (!subscribe) {
+      resolve();
+      return;
+    }
+    subscribe('drain', () => resolve());
+    subscribe('error', (error?: unknown) => {
+      reject(
+        error instanceof Error ? error : new Error('Node response stream errored while draining.')
+      );
+    });
+  });
+
+const writeResponseToNode = async (response: Response, res: NodeServerResponse): Promise<void> => {
+  res.statusCode = response.status;
+  const setCookies = getSetCookieHeaderValues(response.headers);
+  if (setCookies.length > 0) {
+    res.setHeader('set-cookie', setCookies.length === 1 ? setCookies[0] : setCookies);
+  }
+  response.headers.forEach((value, name) => {
+    if (name.toLowerCase() === 'set-cookie') return;
+    res.setHeader(name, value);
+  });
+
+  if (!response.body) {
+    res.end();
+    return;
+  }
+
+  const reader = response.body.getReader();
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    if (value && !res.write(value)) {
+      await waitForNodeDrain(res);
+    }
+  }
+  res.end();
+};
+
+/**
+ * Wraps a handler so it can be passed directly to a `node:http` server.
+ *
+ * @example
+ * ```ts
+ * import { createServer } from 'node:http';
+ * import { createNodeHandler, renderToResponse } from '@bquery/bquery/ssr';
+ *
+ * const handler = createNodeHandler(async (request) => {
+ *   return renderToResponse('<div bq-text="msg"></div>', { msg: 'Hello' });
+ * });
+ *
+ * createServer(handler).listen(3000);
+ * ```
+ */
+export const createNodeHandler = (
+  handler: SSRRequestHandler,
+  options: NodeHandlerOptions = {}
+): ((req: NodeIncomingMessage, res: NodeServerResponse) => Promise<void>) => {
+  return async (req, res) => {
+    let request: Request;
+    try {
+      request = await buildRequestFromNode(req, options);
+    } catch (error) {
+      if (error instanceof NodeRequestLimitError) {
+        await writeResponseToNode(new Response(error.message, { status: 413 }), res);
+        return;
+      }
+      throw error;
+    }
+    const response = await Promise.resolve(handler(request));
+    await writeResponseToNode(response, res);
+  };
+};
+
+/* ---------------------------------------------------------------------------
+ * Auto-detection
+ * ------------------------------------------------------------------------- */
+
+/**
+ * Convenience helper that picks the right adapter based on the current
+ * runtime. Returns the same handler unchanged for Web/Bun/Deno (they share a
+ * fetch-style signature). On Node it returns the `node:http` adapter.
+ */
+export const createSSRHandler = (
+  handler: SSRRequestHandler
+): SSRRequestHandler | ((req: NodeIncomingMessage, res: NodeServerResponse) => Promise<void>) => {
+  const runtime = detectRuntime();
+  switch (runtime) {
+    case 'node':
+      return createNodeHandler(handler);
+    case 'bun':
+      return createBunHandler(handler);
+    case 'deno':
+      return createDenoHandler(handler);
+    default:
+      return createWebHandler(handler);
+  }
+};

package/src/ssr/async.ts

@@ -0,0 +1,125 @@
+/**
+ * Async data helpers for SSR.
+ *
+ * These tiny utilities let `renderToStringAsync()`/`renderToStream()` await
+ * `Promise`-shaped values inside the binding context before the templates are
+ * evaluated, without coupling the synchronous renderer to async semantics.
+ *
+ * @module bquery/ssr
+ */
+
+import { isComputed, isSignal, type Signal } from '../reactive/index';
+import type { BindingContext } from '../view/types';
+import { isPrototypePollutionKey } from '../core/utils/object';
+import type { SSRContext } from './context';
+import { DEFER_BRAND } from './defer-brand';
+
+/** A loader function executed before render. */
+export type SSRLoader<T = unknown> = (ctx: SSRContext) => T | Promise<T>;
+
+/**
+ * Wraps a loader so it can be invoked or stored uniformly. The wrapper is
+ * tagged with the internal defer brand so `resolveContext()` recognises it
+ * and calls the loader with the active `SSRContext`.
+ */
+export const defineLoader = <T>(loader: SSRLoader<T>): SSRLoader<T> => {
+  Object.defineProperty(loader, DEFER_BRAND, {
+    value: true,
+    enumerable: false,
+    configurable: true,
+  });
+  return loader;
+};
+
+interface DeferredValue<T> {
+  [DEFER_BRAND]: true;
+  promise: Promise<T>;
+  fallback?: unknown;
+}
+
+/**
+ * Marks a promise as "may resolve in parallel". When `renderToStringAsync()`
+ * sees a deferred value in the context, it awaits the underlying promise.
+ * Streaming renderers can flush a fallback first and patch the resolved value
+ * later (see `renderToStreamSuspense()`).
+ */
+export const defer = <T>(promise: Promise<T> | T, fallback?: unknown): DeferredValue<T> => {
+  const p = promise instanceof Promise ? promise : Promise.resolve(promise);
+  return {
+    [DEFER_BRAND]: true,
+    promise: p,
+    fallback,
+  };
+};
+
+const isDeferred = (value: unknown): value is DeferredValue<unknown> =>
+  typeof value === 'object' &&
+  value !== null &&
+  (value as Record<symbol, unknown>)[DEFER_BRAND] === true;
+
+/**
+ * Walks the binding context, awaits all promises and deferred values, and
+ * returns a new context with the resolved values. Signals/computeds are kept
+ * as-is so the renderer can still unwrap them lazily.
+ *
+ * @internal
+ */
+export const resolveContext = async (
+  context: BindingContext,
+  ctx: SSRContext
+): Promise<BindingContext> => {
+  const out = Object.create(null) as BindingContext;
+  const entries = Object.entries(context);
+  await Promise.all(
+    entries.map(async ([key, value]) => {
+      if (isPrototypePollutionKey(key)) return;
+      if (isSignal(value) || isComputed(value)) {
+        out[key] = value;
+        return;
+      }
+      if (isDeferred(value)) {
+        try {
+          out[key] = await value.promise;
+        } catch (error) {
+          ctx.reportError(error);
+          out[key] = value.fallback;
+        }
+        return;
+      }
+      if (value && typeof (value as Promise<unknown>).then === 'function') {
+        try {
+          out[key] = await (value as Promise<unknown>);
+        } catch (error) {
+          ctx.reportError(error);
+          out[key] = undefined;
+        }
+        return;
+      }
+      if (
+        typeof value === 'function' &&
+        (value as unknown as { [DEFER_BRAND]?: unknown })[DEFER_BRAND]
+      ) {
+        // Allow loader-style functions tagged via defineLoader to opt in.
+        try {
+          out[key] = await Promise.resolve((value as SSRLoader)(ctx));
+        } catch (error) {
+          ctx.reportError(error);
+          out[key] = undefined;
+        }
+        return;
+      }
+      out[key] = value;
+    })
+  );
+  // Carry forward signals untouched so unwrap() in the evaluator still works.
+  for (const [key, value] of Object.entries(context)) {
+    if (
+      !isPrototypePollutionKey(key) &&
+      !Object.prototype.hasOwnProperty.call(out, key) &&
+      (isSignal(value) || isComputed(value))
+    ) {
+      out[key] = value as Signal<unknown>;
+    }
+  }
+  return out;
+};

package/src/ssr/config.ts

@@ -0,0 +1,86 @@
+/**
+ * Global SSR configuration.
+ *
+ * Lets users opt into a custom DOM implementation (`linkedom`, `happy-dom`,
+ * `jsdom`, …) for the legacy `DOMParser`-based renderer, or force the
+ * DOM-free renderer everywhere. Defaults are runtime-aware: if a global
+ * `DOMParser` exists, it is used (preserves legacy behaviour); otherwise the
+ * DOM-free renderer kicks in automatically.
+ *
+ * @module bquery/ssr
+ */
+
+/**
+ * Backend used by `renderToString()` and `renderToStringAsync()`.
+ */
+export type SSRRendererBackend = 'auto' | 'pure' | 'dom';
+
+/**
+ * DOM implementation injected by `configureSSR()` for the `'dom'` backend.
+ */
+export interface SSRDocumentImpl {
+  /** A `DOMParser` constructor compatible with the WHATWG spec. */
+  DOMParser: typeof globalThis.DOMParser;
+}
+
+interface SSRConfig {
+  backend: SSRRendererBackend;
+  documentImpl: SSRDocumentImpl | null;
+}
+
+const config: SSRConfig = {
+  backend: 'auto',
+  documentImpl: null,
+};
+
+/**
+ * Updates the global SSR configuration. All options are optional and merged
+ * shallowly with the existing configuration.
+ *
+ * @example
+ * ```ts
+ * import { configureSSR } from '@bquery/bquery/ssr';
+ * import { DOMParser } from 'linkedom';
+ *
+ * configureSSR({ backend: 'dom', documentImpl: { DOMParser } });
+ * ```
+ */
+export const configureSSR = (
+  options: Partial<{ backend: SSRRendererBackend; documentImpl: SSRDocumentImpl | null }>
+): void => {
+  if (options.backend !== undefined) config.backend = options.backend;
+  if (options.documentImpl !== undefined) config.documentImpl = options.documentImpl;
+};
+
+/**
+ * Returns a snapshot of the current SSR configuration.
+ */
+export const getSSRConfig = (): Readonly<SSRConfig> => ({
+  backend: config.backend,
+  documentImpl: config.documentImpl,
+});
+
+/**
+ * Resolves the renderer backend that should actually be used right now.
+ * Honours `configureSSR()` and falls back to runtime feature detection.
+ *
+ * @internal
+ */
+export const resolveBackend = (): 'pure' | 'dom' => {
+  if (config.backend === 'pure') return 'pure';
+  if (config.backend === 'dom') return 'dom';
+
+  if (config.documentImpl) return 'dom';
+  if (typeof globalThis.DOMParser === 'function') return 'dom';
+  return 'pure';
+};
+
+/**
+ * Returns the configured `DOMParser` constructor or the global one.
+ * @internal
+ */
+export const getDOMParserImpl = (): typeof globalThis.DOMParser | null => {
+  if (config.documentImpl) return config.documentImpl.DOMParser;
+  if (typeof globalThis.DOMParser === 'function') return globalThis.DOMParser;
+  return null;
+};