keryx 0.5.0 → 0.7.0

package/api.ts

@@ -40,6 +40,9 @@ if (!globalThis.api) {
   globalThis.config = Config;
 }
 
+/** The global API singleton. All framework state (actions, db, redis, etc.) is accessed through this object. */
 export const api = globalThis.api;
+/** Convenience re-export of `api.logger`. */
 export const logger = globalThis.logger;
+/** The merged configuration object (framework defaults + user overrides + env vars). */
 export const config = globalThis.config;

package/classes/API.ts

@@ -8,6 +8,7 @@ import type { Initializer, InitializerSortKeys } from "./Initializer";
 import { Logger } from "./Logger";
 import { ErrorType, TypedError } from "./TypedError";
 
+/** The mode the API process is running in, which determines which initializers start. */
 export enum RUN_MODE {
   CLI = "cli",
   SERVER = "server",
@@ -15,15 +16,29 @@ export enum RUN_MODE {
 
 let flapPreventer = false;
 
+/**
+ * The global singleton that manages the full framework lifecycle: initialize → start → stop.
+ * All initializers attach their namespaces to this object (e.g., `api.db`, `api.actions`, `api.redis`).
+ * Stored on `globalThis` so every module shares the same instance.
+ */
 export class API {
+  /** The root directory of the user's application. Set this before calling `initialize()`. */
   rootDir: string;
+  /** The root directory of the keryx package itself (auto-resolved from `import.meta.path`). */
   packageDir: string;
+  /** Whether `initialize()` has completed successfully. */
   initialized: boolean;
+  /** Whether `start()` has completed successfully. */
   started: boolean;
+  /** Whether `stop()` has completed successfully. */
   stopped: boolean;
+  /** Epoch timestamp (ms) when the API instance was created. */
   bootTime: number;
+  /** The framework logger instance, configured from `config.logger`. */
   logger: Logger;
+  /** The current run mode (SERVER or CLI), set during `start()`. */
   runMode!: RUN_MODE;
+  /** All discovered initializer instances, sorted by the most-recently-used priority key. */
   initializers: Initializer[];
 
   // allow arbitrary properties to be set on the API, to be added and typed later
@@ -42,6 +57,13 @@ export class API {
     this.initializers = [];
   }
 
+  /**
+   * Load configuration overrides and discover + run all initializers.
+   * Calls each initializer's `initialize()` method in `loadPriority` order.
+   * The return value of each initializer is attached to `api[initializer.name]`.
+   *
+   * @throws {TypedError} With `ErrorType.SERVER_INITIALIZATION` if any initializer fails.
+   */
   async initialize() {
     this.logger.warn("--- 🔄  Initializing process ---");
     this.initialized = false;
@@ -69,6 +91,17 @@ export class API {
     this.logger.warn("--- 🔄  Initializing complete ---");
   }
 
+  /**
+   * Start the framework: connect to external services, bind server ports, start workers.
+   * Calls `initialize()` first if it hasn't been run yet, then calls each initializer's
+   * `start()` method in `startPriority` order. Initializers whose `runModes` do not include
+   * the current `runMode` are skipped.
+   *
+   * @param runMode - Whether to start in SERVER mode (HTTP/WebSocket) or CLI mode.
+   *   Defaults to `RUN_MODE.SERVER`. Initializers can opt out of specific modes via their
+   *   `runModes` property.
+   * @throws {TypedError} With `ErrorType.SERVER_START` if any initializer fails to start.
+   */
   async start(runMode: RUN_MODE = RUN_MODE.SERVER) {
     this.stopped = false;
     this.started = false;
@@ -104,6 +137,12 @@ export class API {
     this.logger.warn("--- 🔼  Starting complete ---");
   }
 
+  /**
+   * Gracefully shut down the framework: disconnect from services, close server ports, stop workers.
+   * Calls each initializer's `stop()` method in `stopPriority` order. No-ops if already stopped.
+   *
+   * @throws {TypedError} With `ErrorType.SERVER_STOP` if any initializer fails to stop.
+   */
   async stop() {
     if (this.stopped) {
       this.logger.warn("API is already stopped");
@@ -133,6 +172,10 @@ export class API {
     this.logger.warn("--- 🔽  Stopping complete ---");
   }
 
+  /**
+   * Stop and then re-start the framework. Includes a flap preventer that ignores
+   * concurrent restart calls to avoid rapid stop/start cycles.
+   */
   async restart() {
     if (flapPreventer) return;
 

package/classes/Action.ts

@@ -67,17 +67,33 @@ export type ActionMiddlewareResponse = {
   updatedResponse?: any;
 };
 
+/**
+ * Middleware hooks that run before and/or after an action's `run()` method.
+ * Middleware can mutate params (via `updatedParams`) or replace the response (via `updatedResponse`).
+ */
 export type ActionMiddleware = {
+  /**
+   * Runs before the action's `run()` method. Can modify params by returning `{ updatedParams }`.
+   * Throw a `TypedError` to abort the action (e.g., for auth checks).
+   */
   runBefore?: (
     params: ActionParams<Action>,
     connection: Connection,
   ) => Promise<ActionMiddlewareResponse | void>;
+  /**
+   * Runs after the action's `run()` method. Can replace the response by returning `{ updatedResponse }`.
+   */
   runAfter?: (
     params: ActionParams<Action>,
     connection: Connection,
   ) => Promise<ActionMiddlewareResponse | void>;
 };
 
+/**
+ * Abstract base class for transport-agnostic controllers. Actions serve simultaneously as
+ * HTTP endpoints, WebSocket handlers, CLI commands, background tasks, and MCP tools.
+ * Subclasses must implement the `run()` method.
+ */
 export abstract class Action {
   name: string;
   description?: string;
@@ -139,10 +155,18 @@ export abstract class Action {
   ): Promise<any>;
 }
 
+/**
+ * Infers the validated input type for an action from its `inputs` Zod schema.
+ * Falls back to `Record<string, unknown>` when no schema is defined.
+ */
 export type ActionParams<A extends Action> =
   A["inputs"] extends z.ZodType<any>
     ? z.infer<A["inputs"]>
     : Record<string, unknown>;
 
+/**
+ * Infers the return type of an action's `run()` method, merged with an optional `error` field.
+ * Useful for typing API responses on the client side.
+ */
 export type ActionResponse<A extends Action> = Awaited<ReturnType<A["run"]>> &
   Partial<{ error?: TypedError }>;

package/classes/Channel.ts

@@ -37,6 +37,11 @@ export type ChannelConstructorInputs = {
   middleware?: ChannelMiddleware[];
 };
 
+/**
+ * Abstract base class for PubSub channels. Channels define a `name` (exact string or RegExp)
+ * and optional middleware for authorization on subscribe and cleanup on unsubscribe.
+ * Subclasses can override `authorize()` and `presenceKey()` for custom behavior.
+ */
 export abstract class Channel {
   name: string | RegExp;
   description?: string;

package/classes/Connection.ts

@@ -9,16 +9,39 @@ import { isSecret } from "../util/zodMixins";
 import type { Action, ActionParams } from "./Action";
 import { ErrorType, TypedError } from "./TypedError";
 
+/**
+ * Represents a client connection to the server — HTTP request, WebSocket, or internal caller.
+ * Each connection tracks its own session, channel subscriptions, and rate-limit state.
+ * The generic `T` allows typing the session data shape for your application.
+ */
 export class Connection<T extends Record<string, any> = Record<string, any>> {
+  /** Transport type identifier (e.g., `"web"`, `"websocket"`). */
   type: string;
+  /** A human-readable identifier for the connection, typically the remote IP or a session key. */
   identifier: string;
+  /** Unique connection ID (UUID by default). Used as the key in `api.connections`. */
   id: string;
+  /** The connection's session data, lazily loaded on first action invocation. */
   session?: SessionData<T>;
+  /** Set of channel names this connection is currently subscribed to. */
   subscriptions: Set<string>;
+  /** Whether the session has been loaded from Redis at least once. */
   sessionLoaded: boolean;
+  /** The underlying transport handle (e.g., Bun `ServerWebSocket`). */
   rawConnection?: any;
+  /** Rate-limit metadata populated by the rate-limit middleware. */
   rateLimitInfo?: RateLimitInfo;
+  /** Request correlation ID for distributed tracing. Propagated from the incoming `X-Request-Id` header when `config.server.web.correlationId.trustProxy` is enabled. */
+  correlationId?: string;
 
+  /**
+   * Create a new connection and register it in `api.connections`.
+   *
+   * @param type - Transport type (e.g., `"web"`, `"websocket"`).
+   * @param identifier - Human-readable identifier, typically the remote IP address.
+   * @param id - Unique connection ID. Defaults to a random UUID.
+   * @param rawConnection - The underlying transport handle (e.g., Bun `ServerWebSocket`).
+   */
   constructor(
     type: string,
     identifier: string,
@@ -36,8 +59,18 @@ export class Connection<T extends Record<string, any> = Record<string, any>> {
   }
 
   /**
-   * Runs an action for this connection, given FormData params.
-   *  Throws errors.
+   * Execute an action in the context of this connection. Handles the full lifecycle:
+   * session loading, param validation via the action's Zod schema, middleware execution
+   * (before/after), timeout enforcement, and structured logging.
+   *
+   * @param actionName - The name of the action to run. If not found, throws
+   *   `ErrorType.CONNECTION_ACTION_NOT_FOUND`.
+   * @param params - Raw `FormData` from the HTTP request or WebSocket message.
+   *   Validated and coerced against the action's `inputs` Zod schema.
+   * @param method - The HTTP method of the incoming request (used for logging).
+   * @param url - The request URL (used for logging).
+   * @returns The action response and optional error.
+   * @throws {TypedError} With the appropriate `ErrorType` for validation, timeout, or runtime failures.
    */
   async act(
     actionName: string | undefined,
@@ -141,13 +174,23 @@ export class Connection<T extends Record<string, any> = Record<string, any>> {
           : "\r\n" + error.stack
         : "";
 
+    const correlationIdTag = this.correlationId
+      ? ` [cor:${this.correlationId}]`
+      : "";
+
     logger.info(
-      `${messagePrefix} ${actionName} (${duration}ms) ${method.length > 0 ? `[${method}]` : ""} ${this.identifier}${url.length > 0 ? `(${url})` : ""} ${error ? error : ""} ${loggingParams} ${errorStack}`,
+      `${messagePrefix} ${actionName} (${duration}ms) ${method.length > 0 ? `[${method}]` : ""} ${this.identifier}${url.length > 0 ? `(${url})` : ""}${correlationIdTag} ${error ? error : ""} ${loggingParams} ${errorStack}`,
     );
 
     return { response, error };
   }
 
+  /**
+   * Merge new data into the connection's session. Loads the session first if not yet loaded.
+   *
+   * @param data - Partial session data to merge into the existing session.
+   * @throws {TypedError} With `ErrorType.CONNECTION_SESSION_NOT_FOUND` if no session exists.
+   */
   async updateSession(data: Partial<T>) {
     await this.loadSession();
 
@@ -161,14 +204,23 @@ export class Connection<T extends Record<string, any> = Record<string, any>> {
     return api.session.update(this.session, data);
   }
 
+  /** Add a channel to this connection's subscription set. */
   subscribe(channel: string) {
     this.subscriptions.add(channel);
   }
 
+  /** Remove a channel from this connection's subscription set. */
   unsubscribe(channel: string) {
     this.subscriptions.delete(channel);
   }
 
+  /**
+   * Publish a message to a PubSub channel. The connection must already be subscribed.
+   *
+   * @param channel - The channel name to broadcast to.
+   * @param message - The message payload to send.
+   * @throws {TypedError} With `ErrorType.CONNECTION_NOT_SUBSCRIBED` if not subscribed.
+   */
   async broadcast(channel: string, message: string) {
     if (!this.subscriptions.has(channel)) {
       throw new TypedError({
@@ -180,16 +232,28 @@ export class Connection<T extends Record<string, any> = Record<string, any>> {
     return api.pubsub.broadcast(channel, message, this.id);
   }
 
+  /**
+   * Called when a PubSub message arrives for a channel this connection is subscribed to.
+   * Must be overridden by transport-specific subclasses (e.g., WebSocket connections).
+   *
+   * @param _payload - The incoming PubSub message.
+   * @throws {Error} Always throws in the base class — subclasses must override.
+   */
   onBroadcastMessageReceived(_payload: PubSubMessage) {
     throw new Error(
       "unimplemented - this should be overwritten by connections that support it",
     );
   }
 
+  /** Remove this connection from the global connections map and clean up resources. */
   destroy() {
     return api.connections.destroy(this.type, this.identifier, this.id);
   }
 
+  /**
+   * Load the session from Redis (or create a new one if none exists).
+   * No-ops if the session is already loaded. Sets `sessionLoaded` to `true`.
+   */
   async loadSession() {
     if (this.session) return;
 

package/classes/ExitCode.ts

@@ -1,3 +1,4 @@
+/** Process exit codes used by the CLI runner and signal handlers. */
 export enum ExitCode {
   success = 0,
   error = 1,

package/classes/Initializer.ts

@@ -1,18 +1,21 @@
 import { RUN_MODE } from "./../api";
 
 /**
- * Create a new Initializer. The required properties of an initializer. These can be defined statically (this.name) or as methods which return a value.
+ * Abstract base class for lifecycle components. Initializers are discovered automatically
+ * and run in priority order during the framework's initialize → start → stop phases.
+ * Each initializer typically extends the `API` interface via module augmentation and
+ * returns its namespace object from `initialize()`.
  */
 export abstract class Initializer {
-  /**The name of the Initializer. */
+  /** The unique name of this initializer (also used as the key on the `api` object). */
   name: string;
-  /**What order should this Initializer load at (Default: 1000, core methods are < 1000) */
+  /** Priority order for `initialize()`. Lower values run first. Default: 1000; core initializers use < 1000. */
   loadPriority: number;
-  /**What order should this Initializer start at (Default: 1000, core methods are < 1000) */
+  /** Priority order for `start()`. Lower values run first. Default: 1000; core initializers use < 1000. */
   startPriority: number;
-  /**What order should this Initializer stop at (Default: 1000, core methods are < 1000) */
+  /** Priority order for `stop()`. Lower values run first. Default: 1000; core initializers use < 1000. */
   stopPriority: number;
-  /** which run modes does this sever start in*/
+  /** Which run modes this initializer participates in. Defaults to both SERVER and CLI. */
   runModes: RUN_MODE[];
 
   constructor(name: string) {
@@ -24,17 +27,18 @@ export abstract class Initializer {
   }
 
   /**
-   * Method run as part of the `initialize` lifecycle of your process.  Usually sets api['YourNamespace']
+   * Called during the `initialize` phase. Return a namespace object to attach to `api[this.name]`.
+   * @returns The namespace object (e.g., `{ actions, enqueue, ... }`) that gets set on `api`.
    */
   async initialize?(): Promise<any>;
 
   /**
-   * Method run as part of the `start` lifecycle of your process.  Usually connects to remote servers or processes.
+   * Called during the `start` phase. Connect to external services, bind ports, start workers.
    */
   async start?(): Promise<any>;
 
   /**
-   * Method run as part of the `initialize` lifecycle of your process.  Usually disconnects from remote servers or processes.
+   * Called during the `stop` phase. Disconnect from services, release resources, stop workers.
    */
   async stop?(): Promise<any>;
 }

package/classes/Logger.ts

@@ -15,11 +15,17 @@ export enum LogLevel {
  * The Logger Class.  I write to stdout or stderr, and can be colorized.
  */
 export class Logger {
+  /** Minimum log level to output. Messages below this level are silently dropped. */
   level: LogLevel;
+  /** Whether to apply ANSI color codes to the output. */
   colorize: boolean;
+  /** Whether to prepend an ISO-8601 timestamp to each log line. */
   includeTimestamps: boolean;
+  /** Indentation spaces used when JSON-stringifying the optional object argument. */
   jSONObjectParsePadding: number;
-  quiet: boolean; // an override to disable all logging (used by CLI)
+  /** When `true`, all logging is suppressed (used by CLI mode). */
+  quiet: boolean;
+  /** The output function — defaults to `console.log`. Override for custom transports. */
   outputStream: typeof console.log;
 
   constructor(config: typeof configLogger) {
@@ -31,6 +37,14 @@ export class Logger {
     this.outputStream = console.log;
   }
 
+  /**
+   * Core logging method. Formats and writes a log line to `outputStream` if the given
+   * level meets the minimum threshold. Optionally includes a timestamp and pretty-printed object.
+   *
+   * @param level - The severity level of this log entry.
+   * @param message - The log message string.
+   * @param object - An optional object to JSON-stringify and append to the log line.
+   */
   log(level: LogLevel, message: string, object?: any) {
     if (this.quiet) return;
 
@@ -82,6 +96,11 @@ export class Logger {
     this.log(LogLevel.debug, message, object);
   }
 
+  /**
+   * Log an info message.
+   * @param message - The message to log.
+   * @param object - The object to log.
+   */
   info(message: string, object?: any) {
     this.log(LogLevel.info, message, object);
   }

package/classes/Server.ts

@@ -1,16 +1,24 @@
+/**
+ * Abstract base class for transport servers (e.g., HTTP, WebSocket).
+ * The generic `T` is the type of the underlying server object (e.g., `Bun.Server`).
+ * Subclasses must implement `initialize()`, `start()`, and `stop()`.
+ */
 export abstract class Server<T> {
   name: string;
 
-  /**A place to store the actually server object you create */
+  /** The underlying server instance created by the subclass (e.g., `Bun.Server`). */
   server?: T;
 
   constructor(name: string) {
     this.name = name;
   }
 
+  /** Set up routes, handlers, and configuration. Called during the framework's initialize phase. */
   abstract initialize(): Promise<void>;
 
+  /** Bind to a port and begin accepting connections. Called during the framework's start phase. */
   abstract start(): Promise<void>;
 
+  /** Close the server and release its port. Called during the framework's stop phase. */
   abstract stop(): Promise<void>;
 }

package/classes/TypedError.ts

@@ -1,3 +1,7 @@
+/**
+ * Categorizes all framework errors. Each type maps to an HTTP status code via `ErrorStatusCodes`.
+ * Actions should always throw `TypedError` with one of these types.
+ */
 export enum ErrorType {
   // general
   "SERVER_INITIALIZATION" = "SERVER_INITIALIZATION",
@@ -33,6 +37,7 @@ export enum ErrorType {
   "CONNECTION_TASK_DEFINITION" = "CONNECTION_TASK_DEFINITION",
 }
 
+/** Maps each `ErrorType` to the HTTP status code returned to the client. */
 export const ErrorStatusCodes: Record<ErrorType, number> = {
   [ErrorType.SERVER_INITIALIZATION]: 500,
   [ErrorType.SERVER_START]: 500,
@@ -64,16 +69,29 @@ export const ErrorStatusCodes: Record<ErrorType, number> = {
 };
 
 export type TypedErrorArgs = {
+  /** Human-readable error message returned to the client. */
   message: string;
+  /** The error category, which determines the HTTP status code. */
   type: ErrorType;
+  /** The original caught error, if wrapping. Its stack trace is preserved on the `TypedError`. */
   originalError?: unknown;
+  /** The param key that caused the error (for validation errors). */
   key?: string;
+  /** The param value that caused the error (for validation errors). */
   value?: any;
 };
 
+/**
+ * Structured error class for action and framework failures. Extends `Error` with an
+ * `ErrorType` that maps to an HTTP status code, and optional `key`/`value` fields for
+ * param validation errors. If `originalError` is provided, its stack trace is preserved.
+ */
 export class TypedError extends Error {
+  /** The error category, used to determine the HTTP status code via `ErrorStatusCodes`. */
   type: ErrorType;
+  /** The param key that caused the error (for validation errors). */
   key?: string;
+  /** The param value that caused the error (for validation errors). */
   value?: any;
 
   constructor(args: TypedErrorArgs) {

package/config/server/web.ts

@@ -44,6 +44,7 @@ export const configServerWeb = {
     "WS_MAX_SUBSCRIPTIONS",
     100,
   ),
+  websocketDrainTimeout: await loadFromEnvIfSet("WS_DRAIN_TIMEOUT", 5000),
   includeStackInErrors: await loadFromEnvIfSet(
     "WEB_SERVER_INCLUDE_STACK_IN_ERRORS",
     (Bun.env.NODE_ENV ?? "development") !== "production",
@@ -70,4 +71,8 @@ export const configServerWeb = {
       "strict-origin-when-cross-origin",
     ),
   } as Record<string, string>,
+  correlationId: {
+    header: await loadFromEnvIfSet("WEB_CORRELATION_ID_HEADER", "X-Request-Id"),
+    trustProxy: await loadFromEnvIfSet("WEB_CORRELATION_ID_TRUST_PROXY", false),
+  },
 };