sevok 0.0.2

package/dist/core-BGp2ZR_k.d.mts

@@ -0,0 +1,665 @@
+import { EventDispatcher } from "@hornjs/evt";
+import nodeHTTP from "node:http";
+import nodeHTTPS from "node:https";
+import nodeHTTP2 from "node:http2";
+import * as NodeNet from "node:net";
+
+//#region src/core.d.ts
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * HTTP methods supported by the route table shorthand.
+ */
+type HTTPMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+/**
+ * Core request handler function.
+ *
+ * Receives an `InvocationContext` containing the request and invocation state.
+ * Runtime adapters, middleware, and higher-level helpers all eventually resolve down to a
+ * `ServerHandler`.
+ */
+type ServerHandler = (context: InvocationContext) => MaybePromise<Response>;
+/**
+ * Error handler for failures raised during request handling.
+ *
+ * This is used by `wrapFetch()` to turn thrown exceptions or rejected promises
+ * into a fallback `Response`.
+ */
+type ErrorHandler = (error: unknown) => MaybePromise<Response>;
+/**
+ * Request middleware.
+ *
+ * `next` keeps the same handler signature so middleware can replace the request
+ * object before passing control downstream.
+ */
+type ServerMiddleware = (context: InvocationContext, next: ServerHandler) => MaybePromise<Response>;
+/**
+ * Object form of a handler.
+ *
+ * This makes it possible to attach middleware at the leaf of a middleware
+ * chain, which is useful for composing route handlers or feature modules.
+ */
+type ServerHandlerObject = {
+  /**
+   * Additional middleware to apply immediately before `handleRequest`.
+   */
+  middleware?: ServerMiddleware[];
+  /**
+   * Final request handler invoked after middleware has run.
+   */
+  handleRequest: ServerHandler;
+};
+/**
+ * Route-table shorthand keyed by pathname.
+ *
+ * Each path can resolve to a single handler, a handler object with per-route
+ * middleware, or a method map when the same path needs different handlers for
+ * different HTTP verbs.
+ */
+type ServerRoutes<TPath extends string = string> = { [Path in TPath]: ServerHandler | ServerHandlerObject | Partial<Record<HTTPMethod, ServerHandler | ServerHandlerObject>> };
+/**
+ * A type-safe key for storing and retrieving values from
+ * {@link InvocationContext}.
+ *
+ * Keys are objects instead of strings so packages can create collision-free
+ * context channels without coordinating global names.
+ */
+interface InvocationContextKey<TValue> {
+  /**
+   * The default value for this key if no value has been set.
+   */
+  defaultValue?: TValue;
+}
+/**
+ * Resolve the runtime value type associated with a context key.
+ *
+ * Keys created with `createContextKey()` resolve to their declared value type,
+ * while constructor keys resolve to the instance type they construct.
+ */
+type InvocationContextValue<TKey> = TKey extends InvocationContextKey<infer Value> ? Value : TKey extends (abstract new (...args: any[]) => infer Instance) ? Instance : never;
+/**
+ * Create an invocation context key with an optional default value.
+ *
+ * When a default value is provided, `InvocationContext#get()` can always
+ * return a value for that key even if nothing has been explicitly written yet.
+ *
+ * @param defaultValue The default value for the context key
+ * @returns The new context key
+ */
+declare function createContextKey<TValue>(defaultValue?: TValue): InvocationContextKey<TValue>;
+/**
+ * Function to register background work that should complete before the server
+ * shuts down. Mirrors the service-worker `waitUntil()` semantics.
+ *
+ * @param promise The background work to track
+ */
+type WaitUntilFunction = (promise: Promise<unknown> | PromiseLike<unknown>) => MaybePromise<void>;
+/**
+ * Initialization options for creating an `InvocationContext`.
+ */
+type InvocationContextInit = {
+  /** The HTTP request being handled. */request: Request; /** Runtime capabilities for file system, compression, etc. */
+  capabilities: RuntimeCapabilities; /** Optional function to register background work for shutdown tracking. */
+  waitUntil?: WaitUntilFunction; /** Route parameters extracted from the matched route pattern. */
+  params?: Readonly<Record<string, string>>;
+};
+/**
+ * A context object that contains information about the current invocation.
+ * Each handler and middleware receives its own context instance, which may be
+ * derived from a parent context via `with()`.
+ *
+ * Context values are immutable - use `with()` to create a modified copy.
+ */
+declare class InvocationContext {
+  #private;
+  /**
+   * The original request that was dispatched to the router.
+   *
+   * Note: The request body may already have been consumed by middleware
+   * (available as `context.get(FormData)`). Use `context.with({ request })`
+   * if you need to pass a modified request downstream.
+   */
+  readonly request: Request;
+  /**
+   * Cached parsed URL for middleware and handlers that need repeated URL access.
+   */
+  url: URL | undefined;
+  /**
+   * Runtime specific invocation context.
+   */
+  readonly capabilities: RuntimeCapabilities;
+  /**
+   * The current route parameters for this request.
+   *
+   * This reflects the active matched route and returns an empty object before
+   * routing has resolved a match.
+   */
+  readonly params: Readonly<Record<string, string>>;
+  /**
+   * Tell the runtime about an ongoing operation that shouldn't close until the
+   * promise resolves.
+   *
+   * This mirrors service-worker-style `waitUntil()` semantics and is wired into
+   * `Server.close()`.
+   */
+  readonly waitUntil: WaitUntilFunction | undefined;
+  constructor(init: InvocationContextInit);
+  /**
+   * Create a derived context with optional overrides.
+   * Copies all context values to the new instance.
+   */
+  with(overrides: Partial<InvocationContextInit>): InvocationContext;
+  /**
+   * Get a value from invocation context.
+   *
+   * @param TKey The key to read
+   * @returns The value for the given key
+   */
+  get<TKey extends object>(key: TKey): InvocationContextValue<TKey>;
+  /**
+   * Check whether a value exists in invocation context.
+   *
+   * @param TKey The key to check
+   * @returns `true` if a value has been set for the key
+   */
+  has<TKey extends object>(key: TKey): boolean;
+  /**
+   * Set a value in invocation context.
+   *
+   * @param key The key to write
+   * @param value The value to write
+   */
+  set<TKey extends object>(key: TKey, value: InvocationContextValue<TKey>): void;
+}
+/**
+ * Reject when the request abort signal fires before the promise settles.
+ *
+ * This keeps long-running async work aligned with fetch semantics: once the
+ * request has been aborted, downstream work should stop surfacing successful
+ * results for it.
+ */
+declare function raceRequestAbort<T>(promise: Promise<T>, request: Request): Promise<T>;
+/**
+ * Internal helper used to track background tasks registered through
+ * `waitUntil()`.
+ */
+interface WaitUntil {
+  waitUntil(promise: Promise<any> | PromiseLike<any>): void;
+  wait(): Promise<any>;
+}
+/**
+ * Create a `waitUntil()` registry that keeps track of pending background work.
+ *
+ * Rejected tasks are logged and removed from the registry so shutdown can
+ * continue cleanly.
+ */
+declare function createWaitUntil(): WaitUntil;
+/**
+ * Normalize handlers so middleware runners can treat function and object forms
+ * uniformly.
+ *
+ * A bare handler becomes `{ handleRequest }`, while object handlers are returned
+ * unchanged.
+ */
+declare function toServerHandlerObject(handler: ServerHandler | ServerHandlerObject): ServerHandlerObject;
+/**
+ * Type guard to check if a value conforms to the `ServerHandlerObject` shape.
+ *
+ * This is used to distinguish between a bare `ServerHandler` function and an
+ * object wrapper that may also carry per-route middleware.
+ */
+declare function isServerHandlerObject(value: unknown): value is ServerHandlerObject;
+/**
+ * Execute middleware in sequence and then hand off to the terminal handler.
+ *
+ * Middleware may:
+ * - return a `Response` to short-circuit downstream execution
+ * - call `next()` and return its result
+ * - call `next()` without returning it, in which case the downstream response
+ *   is still used
+ *
+ * If the terminal handler is a `ServerHandlerObject`, its own `middleware`
+ * array is executed after the outer middleware chain completes.
+ */
+declare function runMiddleware(context: InvocationContext, middleware: ServerMiddleware[], terminal: ServerHandler | ServerHandlerObject): Promise<Response>;
+type RouteInput = Request | URL | string | {
+  url: string | URL;
+  method?: HTTPMethod;
+};
+type RouteValue = ServerHandler | ServerHandlerObject | Partial<Record<HTTPMethod, ServerHandler | ServerHandlerObject>>;
+type CompiledRoute = {
+  path: string;
+  route: RouteValue;
+  regexp: RegExp;
+  keys: string[];
+};
+/**
+ * Compiled route table grouped by precedence buckets.
+ *
+ * Matching order follows Bun-style routing precedence:
+ * exact -> param -> wildcard -> catch-all.
+ */
+type RouteTree = {
+  exact: Map<string, RouteValue>;
+  param: CompiledRoute[];
+  wildcard: CompiledRoute[];
+  catchAll?: CompiledRoute;
+};
+/**
+ * A pathname match before HTTP method filtering has been applied.
+ */
+type RouteCandidate = {
+  path: string;
+  route: RouteValue;
+  params: Record<string, string>;
+};
+/**
+ * A fully resolved route match including the selected handler for the request
+ * method.
+ */
+type UnstableRouteMatch = RouteCandidate & {
+  handler: ServerHandler | ServerHandlerObject;
+  method?: HTTPMethod;
+};
+/**
+ * Route lookup result containing all pathname candidates and the subset that
+ * also match the request method.
+ */
+type UnstableRouteMatchResult = {
+  all: RouteCandidate[];
+  matched: UnstableRouteMatch[];
+};
+/**
+ * Compile a declarative `ServerRoutes` table into precedence buckets for fast
+ * request matching.
+ *
+ * The build step also rejects conflicting route shapes such as duplicate exact
+ * routes or parameter routes that collapse to the same canonical pattern.
+ */
+declare function unstable_buildRouteTree(routes: ServerRoutes): RouteTree;
+/**
+ * Match a request-like input against a compiled route tree.
+ *
+ * `all` contains every pathname candidate in precedence order, while
+ * `matched` further filters that list by HTTP method and resolves the concrete
+ * handler that would run.
+ */
+declare function unstable_match(tree: RouteTree, input: RouteInput): UnstableRouteMatchResult;
+type UnstableConvertRoutesToHandlerOptions = {
+  input: RouteTree;
+  fallback?: ServerHandler;
+  runRouteMiddleware?: (context: InvocationContext, middleware: ServerMiddleware[], terminal: ServerHandlerObject) => Promise<Response>;
+};
+/**
+ * Turn a precompiled route tree into a `ServerHandler`.
+ *
+ * Pathname matches are resolved using Bun-style precedence. When a pathname
+ * matches but the method does not, the returned handler responds with `405`
+ * and an `Allow` header. If no route matches, `fallback` is used when
+ * provided; otherwise a `404` response is returned.
+ */
+declare function unstable_convertRoutesToHandler({
+  input,
+  fallback,
+  runRouteMiddleware
+}: UnstableConvertRoutesToHandlerOptions): ServerHandler;
+/**
+ * Host capabilities required by middleware and helpers that need filesystem or
+ * compression support.
+ */
+interface RuntimeCapabilities {
+  /**
+   * Resolve a path relative to `root`.
+   *
+   * Returns `null` when the resolved path would escape the root directory.
+   */
+  resolve(root: string, ...components: string[]): Promise<string | null>;
+  /**
+   * Open a path for static file serving.
+   *
+   * Returns `null` when the path does not exist.
+   */
+  open(path: string): Promise<{
+    readonly isFile: false;
+  } | {
+    readonly isFile: true;
+    readonly size: number;
+    stream: (start?: number, end?: number) => ReadableStream;
+  } | null>;
+  /**
+   * Create a gzip compression transform.
+   */
+  createGzip(): MaybePromise<TransformStream>;
+  /**
+   * Create a Brotli compression transform.
+   */
+  createBrotliCompress(): MaybePromise<TransformStream>;
+}
+/**
+ * Lifecycle hooks required to host a `Server` in a specific runtime.
+ *
+ * `setup()` prepares runtime-specific state, `serve()` starts listening,
+ * and `close()` shuts the runtime down.
+ */
+interface RuntimeAdapter {
+  /**
+   * Runtime-specific helpers exposed to middleware and request handlers.
+   */
+  readonly capabilities: RuntimeCapabilities;
+  /**
+   * Whether the adapter/runtime should be treated as supporting graceful
+   * process shutdown integration.
+   */
+  readonly graceful?: boolean;
+  /**
+   * Prepare runtime-specific state before the server starts listening.
+   */
+  setup: (server: Server) => void;
+  /**
+   * Start serving requests and resolve once the adapter knows the public URL.
+   */
+  serve: (server: Server) => Promise<{
+    url: string | undefined;
+  } | undefined>;
+  /**
+   * Stop accepting new work and optionally terminate active connections.
+   */
+  close: (closeActiveConnections: boolean) => Promise<void>;
+}
+/**
+ * Bun's native server options, excluding the fetch handler owned by `Server`.
+ */
+type BunServerOptions = Omit<Bun.Serve.Options<any>, "fetch" | "routes" | "unix">;
+/**
+ * Deno's native serve options.
+ */
+type DenoServerOptions = Deno.ServeOptions;
+/**
+ * Node.js server options.
+ */
+type NodeServerOptions = (nodeHTTP.ServerOptions | nodeHTTPS.ServerOptions | nodeHTTP2.ServerOptions) & NodeNet.ListenOptions & {
+  http2?: boolean;
+};
+/**
+ * Resolve the runtime adapter for the current process.
+ *
+ * The adapter is chosen lazily so the package can stay portable across Bun,
+ * Deno, and Node without importing runtime-specific code up front.
+ */
+declare function loadServerAdapter(): Promise<RuntimeAdapter>;
+/**
+ * Emitted after the server starts accepting requests.
+ */
+declare class ServerServeEvent extends Event {
+  constructor();
+}
+/**
+ * Emitted after the server has fully closed.
+ */
+declare class ServerCloseEvent extends Event {
+  constructor();
+}
+/**
+ * Emitted when server startup or runtime handling raises an error.
+ */
+declare class ServerErrorEvent extends Event {
+  readonly error: any;
+  constructor(error?: any);
+}
+/**
+ * Extension point that can mutate a `Server` instance during construction.
+ */
+type ServerPlugin = (server: Server) => void;
+/**
+ * TLS server options.
+ *
+ * These are normalized by individual runtime adapters before being handed to
+ * Bun, Deno, or Node.
+ */
+type TLSOptions = {
+  /**
+   * File path or inlined TLS certificate in PEM format (required).
+   */
+  cert?: string;
+  /**
+   * File path or inlined TLS private key in PEM format (required).
+   */
+  key?: string;
+  /**
+   * Passphrase for the private key (optional).
+   */
+  passphrase?: string;
+};
+/**
+ * Core server configuration shared by all runtime adapters.
+ *
+ * These options describe request handling behavior, listener defaults, and
+ * process-level features such as graceful shutdown.
+ */
+interface ServerOptions {
+  /**
+   * Declarative route table matched before the fallback `fetch` handler.
+   *
+   * If this table does not define `/*`, `fetch` must be provided to handle
+   * unmatched requests.
+   */
+  routes?: ServerRoutes;
+  /**
+   * Fallback request handler.
+   *
+   * When `routes` is provided, this handles requests that do not match the
+   * route table. When `routes` is omitted, this acts as the primary request
+   * handler.
+   */
+  fetch?: ServerHandler;
+  /**
+   * Handle errors raised while processing requests.
+   *
+   * @note This handler will set built-in Bun and Deno error handler.
+   */
+  error?: ErrorHandler;
+  /**
+   * Server middleware handlers to run before the main fetch handler.
+   *
+   * Middleware is executed in the order provided.
+   */
+  middleware: ServerMiddleware[];
+  /**
+   * If set to `true`, server will not start listening automatically.
+   */
+  manual?: boolean;
+  /**
+   * The port server should be listening to.
+   *
+   * Default is read from `PORT` environment variable or will be `3000`.
+   *
+   * **Tip:** You can set the port to `0` to use a random port.
+   */
+  port?: string | number;
+  /**
+   * The hostname (IP or resolvable host) server listener should bound to.
+   *
+   * When not provided, server with listen to all network interfaces by default.
+   *
+   * **Important:** If you are running a server that is not expected to be exposed to the network, use `hostname: "localhost"`.
+   */
+  hostname?: string;
+  /**
+   * Enabling this option allows multiple processes to bind to the same port, which is useful for load balancing.
+   *
+   * **Note:** Despite Node.js built-in behavior that has `exclusive` flag (opposite of `reusePort`) enabled by default, sevok uses non-exclusive mode for consistency.
+   */
+  reusePort?: boolean;
+  /**
+   * The protocol to use for the server.
+   *
+   * Possible values are `http` and `https`.
+   *
+   * If `protocol` is not set, Server will use `http` as the default protocol or `https` if both `tls.cert` and `tls.key` options are provided.
+   */
+  protocol?: "http" | "https";
+  /**
+   * TLS server options.
+   */
+  tls?: TLSOptions;
+  /**
+   * If set to `true`, server will not print the listening address.
+   */
+  silent?: boolean;
+  /**
+   * Graceful shutdown on SIGINT and SIGTERM signals.
+   *
+   * Supported for Node.js, Deno and Bun runtimes.
+   *
+   * @default true (disabled in test and ci environments)
+   */
+  gracefulShutdown?: boolean | {
+    gracefulTimeout?: number;
+    forceTimeout?: number;
+  };
+  /**
+   * Deno-specific adapter options.
+   */
+  deno?: DenoServerOptions;
+  /**
+   * Bun-specific adapter options.
+   */
+  bun?: BunServerOptions;
+  /**
+   * Node.js-specific adapter options.
+   */
+  node?: NodeServerOptions;
+}
+/**
+ * Constructor input for creating a `Server`.
+ *
+ * Extends the base server options with the runtime adapter and optional
+ * plugins that can mutate server behavior before the adapter is set up.
+ */
+interface ServerInit extends Omit<ServerOptions, "middleware"> {
+  /**
+   * Server plugins.
+   *
+   * Plugins run before the runtime adapter is set up, so they can adjust
+   * `server.options` or register server-level behavior.
+   */
+  plugins?: ServerPlugin[];
+  /**
+   * Global middleware applied before route-level or handler-level middleware.
+   */
+  middleware?: ServerMiddleware[];
+  /**
+   * Runtime adapter responsible for integrating with the host environment.
+   */
+  adapter?: RuntimeAdapter;
+}
+/**
+ * Convenience factory for creating a `Server` without `new`.
+ */
+declare function serve(init: ServerInit): Server;
+/**
+ * Augmentation hook for adding application-specific `Server` events.
+ *
+ * Consumers can extend this interface with module augmentation so custom event
+ * names become part of `ServerEventMap`.
+ *
+ * @example
+ * ```ts
+ * declare module "sevok" {
+ *   interface ServerEventMapCustom {
+ *     reload: CustomEvent<{ full: boolean }>;
+ *   }
+ * }
+ * ```
+ */
+interface ServerEventMapCustom {}
+/**
+ * Complete typed event map for `Server`.
+ *
+ * Combines built-in lifecycle events with any consumer-defined events added
+ * through `ServerEventMapCustom` augmentation.
+ */
+interface ServerEventMap extends ServerEventMapCustom {
+  /** Fired after the runtime adapter reports that the server is serving. */
+  serve: ServerServeEvent;
+  /** Fired after shutdown has completed and background work has settled. */
+  close: ServerCloseEvent;
+  /** Fired when adapter initialization fails with a non-abort error. */
+  error: ServerErrorEvent;
+}
+/**
+ * Runtime-agnostic fetch server.
+ *
+ * `Server` owns middleware composition, per-invocation context setup, background
+ * task tracking, and runtime lifecycle coordination. Concrete adapters handle
+ * the host-specific details of listening for requests.
+ */
+declare class Server extends EventDispatcher<ServerEventMap> {
+  #private;
+  /**
+   * Server options.
+   */
+  readonly options: ServerOptions;
+  /**
+   * Register a background task that the server should await before closing.
+   *
+   * Same as `request.waitUntil` but available at the server level for use
+   * outside of request handlers.
+   */
+  readonly waitUntil?: (promise: Promise<unknown>) => void;
+  /**
+   * Create a server, apply plugins, prepare the runtime adapter, and optionally
+   * start listening immediately.
+   */
+  constructor({
+    middleware,
+    plugins,
+    adapter,
+    ...options
+  }: ServerInit);
+  /**
+   * Listener URL reported by the runtime adapter after `serve()` succeeds.
+   */
+  get url(): string | undefined;
+  /**
+   * Create a `InvocationContext` view over an arbitrary `Request`.
+   *
+   * This preserves the upstream request object and pairs it with sevok
+   * invocation state such as runtime capabilities, `waitUntil`, and `params`.
+   */
+  createContext(request: Request, params?: Readonly<Record<string, string>>): InvocationContext;
+  /**
+   * Invoke the composed request pipeline directly.
+   */
+  handle(context: InvocationContext): MaybePromise<Response>;
+  /**
+   * Adapt an arbitrary `Request` into an `InvocationContext` and invoke the handler pipeline.
+   */
+  fetch(request: Request): Promise<Response>;
+  /**
+   * Start the runtime adapter if it has not been started already.
+   *
+   * The returned promise resolves once the adapter reports the final listener
+   * URL. Repeated calls reuse the same in-flight startup.
+   */
+  serve(): Promise<void>;
+  /**
+   * Wait until the server has completed startup and then return the instance.
+   *
+   * This is mainly a convenience for fluent startup code.
+   */
+  ready(): Promise<Server>;
+  /**
+   * Close the runtime adapter and wait for outstanding `waitUntil()` tasks.
+   *
+   * If startup was still in progress, `ready()` is rejected with an
+   * `AbortError`.
+   */
+  close(closeActiveConnections?: boolean): Promise<void>;
+}
+/**
+ * Compose fetch handler, middleware, and optional error handling into the
+ * single request kernel used by `Server`.
+ */
+declare function wrapFetch(server: Server): ServerHandler;
+//#endregion
+export { WaitUntil as A, unstable_buildRouteTree as B, ServerPlugin as C, UnstableConvertRoutesToHandlerOptions as D, TLSOptions as E, loadServerAdapter as F, unstable_match as H, raceRequestAbort as I, runMiddleware as L, createContextKey as M, createWaitUntil as N, UnstableRouteMatch as O, isServerHandlerObject as P, serve as R, ServerOptions as S, ServerServeEvent as T, wrapFetch as U, unstable_convertRoutesToHandler as V, ServerEventMapCustom as _, InvocationContext as a, ServerInit as b, InvocationContextValue as c, RuntimeAdapter as d, RuntimeCapabilities as f, ServerEventMap as g, ServerErrorEvent as h, HTTPMethod as i, WaitUntilFunction as j, UnstableRouteMatchResult as k, MaybePromise as l, ServerCloseEvent as m, DenoServerOptions as n, InvocationContextInit as o, Server as p, ErrorHandler as r, InvocationContextKey as s, BunServerOptions as t, NodeServerOptions as u, ServerHandler as v, ServerRoutes as w, ServerMiddleware as x, ServerHandlerObject as y, toServerHandlerObject as z };