@bquery/bquery 1.10.0 → 1.11.0

package/src/server/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Lightweight backend helpers for bQuery.js.
+ *
+ * Provides an Express-inspired middleware and routing layer that stays
+ * dependency-free, tree-shakeable, and SSR-aware.
+ *
+ * @module bquery/server
+ */
+
+export { createServer, isServerWebSocketSession, isWebSocketRequest } from './create-server';
+export type {
+  CreateServerOptions,
+  ServerApp,
+  ServerContext,
+  ServerHandler,
+  ServerResult,
+  ServerHtmlResponseInit,
+  ServerMiddleware,
+  ServerNext,
+  ServerQuery,
+  ServerRenderResponseOptions,
+  ServerRequestInit,
+  ServerResponseInit,
+  ServerRoute,
+  ServerWebSocketConnection,
+  ServerWebSocketData,
+  ServerWebSocketHandlerSet,
+  ServerWebSocketMiddleware,
+  ServerWebSocketNext,
+  ServerWebSocketPeer,
+  ServerWebSocketRouteHandler,
+  ServerWebSocketSession,
+} from './types';

package/src/server/types.ts

@@ -0,0 +1,490 @@
+import type { RenderOptions } from '../ssr/index';
+import type { BindingContext } from '../view/index';
+
+/**
+ * Repeated query parameters are represented as arrays.
+ */
+export interface ServerQuery {
+  [key: string]: string | string[] | undefined;
+}
+
+/**
+ * Lightweight request input accepted by `handle()`.
+ */
+export interface ServerRequestInit {
+  /**
+   * Request URL or path.
+   *
+   * Relative paths are resolved against `CreateServerOptions.baseUrl`.
+   */
+  url: string | URL;
+
+  /**
+   * HTTP method.
+   * @default 'GET'
+   */
+  method?: string;
+
+  /**
+   * Request headers.
+   */
+  headers?: HeadersInit;
+
+  /**
+   * Optional request body.
+   */
+  body?: BodyInit | null;
+}
+
+/**
+ * Shared response options used by server helpers.
+ */
+export interface ServerResponseInit extends ResponseInit {
+  headers?: HeadersInit;
+}
+
+/**
+ * HTML response options.
+ */
+export interface ServerHtmlResponseInit extends ServerResponseInit {
+  /**
+   * When `true`, the HTML string is assumed to be already safe and is returned
+   * without additional sanitization.
+   * @default false
+   */
+  trusted?: boolean;
+}
+
+/**
+ * SSR response options.
+ */
+export interface ServerRenderResponseOptions extends RenderOptions {
+  /**
+   * HTTP status to use for the response.
+   * @default 200
+   */
+  status?: number;
+
+  /**
+   * Additional response headers.
+   */
+  headers?: HeadersInit;
+}
+
+/**
+ * Binary/text payloads accepted by server-side WebSocket peers and sessions.
+ *
+ * Use this for raw frames sent through `socket.send(...)`.
+ */
+export type ServerWebSocketData = string | Blob | ArrayBufferLike | ArrayBufferView;
+
+/**
+ * Minimal runtime WebSocket peer shape consumed by server-side WebSocket sessions.
+ */
+export interface ServerWebSocketPeer {
+  /**
+   * Negotiated sub-protocol, when available.
+   */
+  protocol?: string;
+
+  /**
+   * Current readyState, when the runtime exposes it.
+   */
+  readyState?: number;
+
+  /**
+   * Remote URL, when the runtime exposes it.
+   */
+  url?: string;
+
+  /**
+   * Send a raw payload to the connected peer.
+   */
+  send(data: ServerWebSocketData): void;
+
+  /**
+   * Close the connection.
+   */
+  close(code?: number, reason?: string): void;
+}
+
+/**
+ * Wrapped WebSocket connection exposed to route handlers.
+ */
+export interface ServerWebSocketConnection extends ServerWebSocketPeer {
+  /**
+   * Serialize a value with `JSON.stringify()` and send it to the peer.
+   */
+  sendJson(data: unknown): void;
+}
+
+/**
+ * Request/response context passed through the server pipeline.
+ */
+export interface ServerContext {
+  /**
+   * Normalized `Request` instance.
+   */
+  request: Request;
+
+  /**
+   * Parsed URL for the current request.
+   */
+  url: URL;
+
+  /**
+   * Uppercase HTTP method.
+   */
+  method: string;
+
+  /**
+   * Pathname without query string.
+   */
+  path: string;
+
+  /**
+   * Route params captured from `:param` path segments.
+   */
+  params: Record<string, string>;
+
+  /**
+   * Parsed query object. Repeated keys become arrays.
+   */
+  query: ServerQuery;
+
+  /**
+   * Per-request mutable state bag for middleware communication.
+   */
+  state: Record<string, unknown>;
+
+  /**
+   * Create a raw `Response`.
+   *
+   * @example
+   * ```ts
+   * return ctx.response('Created', { status: 201 });
+   * ```
+   */
+  response(body?: BodyInit | null, init?: ServerResponseInit): Response;
+
+  /**
+   * Create a plain-text response.
+   *
+   * @example
+   * ```ts
+   * return ctx.text('ok');
+   * ```
+   */
+  text(body: string, init?: ServerResponseInit): Response;
+
+  /**
+   * Create a sanitized HTML response by default.
+   *
+   * @example
+   * ```ts
+   * return ctx.html('<h1>Hello</h1>');
+   * ```
+   */
+  html(body: string, init?: ServerHtmlResponseInit): Response;
+
+  /**
+   * Create a JSON response.
+   *
+   * @example
+   * ```ts
+   * return ctx.json({ ok: true });
+   * ```
+   */
+  json(data: unknown, init?: ServerResponseInit): Response;
+
+  /**
+   * Create a redirect response.
+   *
+   * @example
+   * ```ts
+   * return ctx.redirect('/login', 302);
+   * ```
+   */
+  redirect(location: string | URL, status?: number): Response;
+
+  /**
+   * Render a bQuery SSR template into an HTML response.
+   *
+   * @example
+   * ```ts
+   * return ctx.render('<h1 bq-text="title"></h1>', { title: 'Dashboard' });
+   * ```
+   */
+  render(
+    template: string,
+    data: BindingContext,
+    options?: ServerRenderResponseOptions
+  ): Response;
+
+  /**
+   * `true` when the incoming request is a WebSocket upgrade handshake.
+   */
+  isWebSocketRequest: boolean;
+}
+
+/**
+ * Final request handler.
+ */
+export interface ServerHandler {
+  (context: ServerContext): Response | Promise<Response>;
+}
+
+/**
+ * WebSocket route lifecycle callbacks.
+ */
+export interface ServerWebSocketHandlerSet<TReceive = unknown> {
+  /**
+   * Requested sub-protocols for the handshake.
+   */
+  protocols?: string | string[];
+
+  /**
+   * Additional handshake headers used by compatible runtimes.
+   */
+  headers?: HeadersInit;
+
+  /**
+   * Deserialize incoming WebSocket messages.
+   *
+   * Defaults to JSON.parse for string payloads with a raw-string fallback.
+   */
+  deserialize?: (event: MessageEvent) => TReceive;
+
+  /**
+   * Called after the runtime accepts the upgrade.
+   */
+  onOpen?: (socket: ServerWebSocketConnection, context: ServerContext) => void | Promise<void>;
+
+  /**
+   * Called for each incoming message after deserialization.
+   */
+  onMessage?: (
+    data: TReceive,
+    socket: ServerWebSocketConnection,
+    context: ServerContext,
+    event: MessageEvent
+  ) => void | Promise<void>;
+
+  /**
+   * Called when the connection closes.
+   */
+  onClose?: (
+    event: CloseEvent,
+    socket: ServerWebSocketConnection,
+    context: ServerContext
+  ) => void | Promise<void>;
+
+  /**
+   * Called when the runtime reports a socket error.
+   */
+  onError?: (
+    event: Event,
+    socket: ServerWebSocketConnection,
+    context: ServerContext
+  ) => void | Promise<void>;
+}
+
+/**
+ * WebSocket route definition or per-request factory.
+ */
+export type ServerWebSocketRouteHandler<TReceive = unknown> =
+  | ServerWebSocketHandlerSet<TReceive>
+  | ((
+      context: ServerContext
+    ) => ServerWebSocketHandlerSet<TReceive> | Promise<ServerWebSocketHandlerSet<TReceive>>);
+
+/**
+ * Runtime-agnostic WebSocket session returned by `handleWebSocket()`.
+ */
+export interface ServerWebSocketSession {
+  /**
+   * Request context captured during route matching and middleware execution.
+   */
+  context: ServerContext;
+
+  /**
+   * Normalized requested sub-protocols.
+   */
+  protocols: string[];
+
+  /**
+   * Additional handshake headers requested by the route.
+   */
+  headers?: HeadersInit;
+
+  /**
+   * Notify the session that the runtime accepted the connection.
+   */
+  open(socket: ServerWebSocketPeer): Promise<void>;
+
+  /**
+   * Deliver an incoming message event to the session.
+   */
+  message(socket: ServerWebSocketPeer, event: MessageEvent): Promise<void>;
+
+  /**
+   * Notify the session about a close event.
+   */
+  close(socket: ServerWebSocketPeer, event: CloseEvent): Promise<void>;
+
+  /**
+   * Notify the session about a socket error.
+   */
+  error(socket: ServerWebSocketPeer, event: Event): Promise<void>;
+}
+
+/**
+ * Result type used by middleware and WebSocket handling.
+ */
+export type ServerResult = Response | ServerWebSocketSession | null;
+
+/**
+ * Middleware continuation callback.
+ */
+export interface ServerNext {
+  (): Promise<Response>;
+}
+
+/**
+ * Express-inspired middleware for request pipelines.
+ */
+export interface ServerMiddleware {
+  (context: ServerContext, next: ServerNext): Response | Promise<Response>;
+}
+
+/**
+ * WebSocket middleware continuation callback.
+ */
+export interface ServerWebSocketNext {
+  (): Promise<ServerResult>;
+}
+
+/**
+ * Middleware used by WebSocket routes.
+ */
+export interface ServerWebSocketMiddleware {
+  (context: ServerContext, next: ServerWebSocketNext): ServerResult | Promise<ServerResult>;
+}
+
+/**
+ * Route definition used by `add()`.
+ */
+export interface ServerRoute {
+  /**
+   * Route path. Supports static segments, `:params`, and terminal `*`.
+   */
+  path: string;
+
+  /**
+   * One or many HTTP methods. Omit for "all methods".
+   */
+  method?: string | string[];
+
+  /**
+   * Optional route-scoped middleware.
+   */
+  middlewares?: ServerMiddleware[];
+
+  /**
+   * Final route handler.
+   */
+  handler: ServerHandler;
+}
+
+/**
+ * Configures a server instance.
+ */
+export interface CreateServerOptions {
+  /**
+   * Base URL used to resolve relative request paths.
+   * @default 'http://localhost'
+   */
+  baseUrl?: string;
+
+  /**
+   * Global middleware applied to every request.
+   */
+  middlewares?: ServerMiddleware[];
+
+  /**
+   * Custom 404 handler.
+   */
+  notFound?: ServerHandler;
+
+  /**
+   * Custom error handler.
+   */
+  onError?: (error: unknown, context: ServerContext) => Response | Promise<Response>;
+}
+
+/**
+ * Express-inspired app-like server handle.
+ */
+export interface ServerApp {
+  /**
+   * Register global middleware.
+   */
+  use(middleware: ServerMiddleware): ServerApp;
+
+  /**
+   * Add a fully specified route.
+   */
+  add(route: ServerRoute): ServerApp;
+
+  /**
+   * Register a GET route.
+   */
+  get(path: string, handler: ServerHandler, middlewares?: ServerMiddleware[]): ServerApp;
+
+  /**
+   * Register a POST route.
+   */
+  post(path: string, handler: ServerHandler, middlewares?: ServerMiddleware[]): ServerApp;
+
+  /**
+   * Register a PUT route.
+   */
+  put(path: string, handler: ServerHandler, middlewares?: ServerMiddleware[]): ServerApp;
+
+  /**
+   * Register a PATCH route.
+   */
+  patch(path: string, handler: ServerHandler, middlewares?: ServerMiddleware[]): ServerApp;
+
+  /**
+   * Register a DELETE route.
+   */
+  delete(path: string, handler: ServerHandler, middlewares?: ServerMiddleware[]): ServerApp;
+
+  /**
+   * Register a route that matches any method.
+   */
+  all(path: string, handler: ServerHandler, middlewares?: ServerMiddleware[]): ServerApp;
+
+  /**
+   * Register a WebSocket route.
+   */
+  ws<TReceive = unknown>(
+    path: string,
+    handler: ServerWebSocketRouteHandler<TReceive>,
+    middlewares?: ServerWebSocketMiddleware[]
+  ): ServerApp;
+
+  /**
+   * Handle a normalized request.
+   */
+  handle(input: Request | string | URL | ServerRequestInit): Promise<Response>;
+
+  /**
+   * Resolve a WebSocket upgrade request into a runtime-agnostic session.
+   *
+   * Returns `null` when the request is not a WebSocket handshake or no matching
+   * WebSocket route exists. Middleware may also short-circuit with a `Response`.
+   */
+  handleWebSocket(input: Request | string | URL | ServerRequestInit): Promise<ServerResult>;
+}