@oakbun/ws 0.1.0 → 0.1.1

package/dist/index.d.ts

@@ -0,0 +1,998 @@
+import * as bun from 'bun';
+import { ZodTypeAny } from 'zod';
+import * as oakbun from 'oakbun';
+import { AuthPayload, VelnWsAdapter, WsRouteShape as WsRouteShape$1, BaseCtx as BaseCtx$1 } from 'oakbun';
+
+type BindingValue = string | number | bigint | boolean | null | Uint8Array;
+interface ExecuteResult {
+    rowsAffected: number;
+    lastInsertId?: number | bigint;
+}
+/** Emitted by the adapter after every query() or execute() call. */
+interface QueryLogEntry {
+    /** The SQL string that was executed. */
+    sql: string;
+    /** The bound parameter values. */
+    params: BindingValue[];
+    /** Wall-clock duration in milliseconds (performance.now() resolution). */
+    durationMs: number;
+    /** Whether the call was query() (returns rows) or execute() (DML/DDL). */
+    type: 'query' | 'execute';
+}
+interface VelnAdapter {
+    query<T = Record<string, unknown>>(sql: string, params?: BindingValue[]): Promise<T[]>;
+    execute(sql: string, params?: BindingValue[]): Promise<ExecuteResult>;
+    transaction<T>(fn: (tx: VelnAdapter) => Promise<T>): Promise<T>;
+    close(): Promise<void>;
+    /**
+     * Optional query observer. When set, the adapter calls this after every
+     * query() and execute() with timing and SQL details.
+     * Set by dbPlugin when query logging is enabled — do not call directly.
+     */
+    onQuery?: (entry: QueryLogEntry) => void;
+}
+
+type SqlType = 'INTEGER' | 'TEXT' | 'REAL' | 'BOOLEAN' | 'TIMESTAMP' | 'JSON' | 'UUID' | 'BLOB';
+interface ColumnDef {
+    type: SqlType;
+    nullable: boolean;
+    primaryKey: boolean;
+    autoIncrement: boolean;
+    unique: boolean;
+    defaultValue?: unknown;
+    defaultFn?: () => unknown;
+}
+declare class Column<T> {
+    readonly def: Readonly<ColumnDef>;
+    readonly _: T;
+    constructor(def: Readonly<ColumnDef>);
+    nullable(): Column<T | null>;
+    primaryKey(): Column<T>;
+    unique(): Column<T>;
+    default(value: NonNullable<T>): Column<T>;
+    defaultFn(fn: () => NonNullable<T>): Column<T>;
+}
+
+type SchemaMap = Record<string, Column<any>>;
+type InferRow<T> = T extends TableDef<infer R, any, any> ? R : T extends SchemaMap ? {
+    [K in keyof T]: T[K] extends Column<infer C> ? C : never;
+} : never;
+type IsOptionalOnInsert<C extends Column<any>> = C['def']['primaryKey'] extends true ? true : C['def']['defaultValue'] extends undefined ? C['def']['defaultFn'] extends undefined ? C['def']['nullable'] extends true ? true : false : true : true;
+type InferInsertFromSchema<S extends SchemaMap> = {
+    [K in keyof S as IsOptionalOnInsert<S[K]> extends true ? never : K]: S[K] extends Column<infer T> ? NonNullable<T> : never;
+} & {
+    [K in keyof S as IsOptionalOnInsert<S[K]> extends true ? K : never]?: S[K] extends Column<infer T> ? T : never;
+};
+type InferInsert<T> = T extends TableDef<any, infer S, any> ? InferInsertFromSchema<S> : T extends SchemaMap ? InferInsertFromSchema<T> : never;
+interface TableHookHandlers<T> {
+    beforeInsert?: (data: Partial<T>) => Partial<T> | void | Promise<Partial<T> | void>;
+    afterInsert?: (result: T, input: Partial<T>) => void | Promise<void>;
+    beforeUpdate?: (current: T, patch: Partial<T>) => Partial<T> | void | Promise<Partial<T> | void>;
+    afterUpdate?: (result: T, before: T) => void | Promise<void>;
+    beforeDelete?: (current: T) => void | Promise<void>;
+    afterDelete?: (deleted: T) => void | Promise<void>;
+}
+interface TableEventMap {
+    afterInsert?: string;
+    afterUpdate?: string;
+    afterDelete?: string;
+}
+type InferTableEvents<T, M extends TableEventMap> = (M['afterInsert'] extends string ? {
+    [_ in M['afterInsert']]: T;
+} : Record<never, never>) & (M['afterUpdate'] extends string ? {
+    [_ in M['afterUpdate']]: {
+        before: T;
+        after: T;
+    };
+} : Record<never, never>) & (M['afterDelete'] extends string ? {
+    [_ in M['afterDelete']]: T;
+} : Record<never, never>);
+interface TableDef<T, S extends SchemaMap = SchemaMap, TEvents extends TableEventMap = TableEventMap> {
+    readonly name: string;
+    readonly schema: S;
+    readonly primaryKey: keyof T & string;
+    readonly hooks: TableHookHandlers<T>[];
+    readonly events: TEvents;
+    readonly _eventMap: InferTableEvents<T, TEvents>;
+}
+
+interface ModuleHookHandlers<T, TCtx = unknown> {
+    beforeInsert?: (ctx: TCtx, data: Partial<T>) => Partial<T> | void | Promise<Partial<T> | void>;
+    afterInsert?: (ctx: TCtx, result: T, input: Partial<T>) => void | Promise<void>;
+    beforeUpdate?: (ctx: TCtx, current: T, patch: Partial<T>) => Partial<T> | void | Promise<Partial<T> | void>;
+    afterUpdate?: (ctx: TCtx, result: T, before: T) => void | Promise<void>;
+    beforeDelete?: (ctx: TCtx, current: T) => void | Promise<void>;
+    afterDelete?: (ctx: TCtx, deleted: T) => void | Promise<void>;
+}
+
+type EventHandler = (payload: unknown, ctx: unknown) => Promise<void> | void;
+declare class RequestEventQueue {
+    private readonly buffer;
+    collect(name: string, payload: unknown): void;
+    flush(ctx: unknown, bus: EventBusAdapter | InMemoryEventBus): Promise<void>;
+    /** Drain — returns collected events and clears the buffer.
+     *  Used by the TX path to hand events off to TransactionResult. */
+    drain(): PendingEvent[];
+    /** Number of buffered events — useful in tests. */
+    get size(): number;
+}
+interface VelnEvents {
+}
+type EventBusErrorHandler = (event: string, error: unknown) => void;
+interface EventBusOptions {
+    /** Called when an event handler throws. Defaults to console.error. */
+    onError?: EventBusErrorHandler;
+}
+/**
+ * EventBusAdapter — minimal interface for event bus implementations.
+ *
+ * Default: InMemoryEventBus (single-process, zero latency)
+ *
+ * For multi-worker deployments: BroadcastChannelAdapter (@oakbun/broadcast, roadmap)
+ * For multi-server deployments: RedisAdapter (@oakbun/redis, roadmap)
+ *
+ * NOTE: EventBus is single-process by default. Events fired on instance A
+ * will NOT reach instance B without a distributed adapter.
+ */
+interface EventBusAdapter {
+    on(event: string, handler: (payload: unknown) => void): void;
+    emit(event: string, payload: unknown): Promise<void>;
+}
+declare class InMemoryEventBus {
+    private readonly handlers;
+    private readonly _onError;
+    constructor(options?: EventBusOptions);
+    on<K extends keyof VelnEvents>(event: K, handler: (payload: VelnEvents[K], ctx: unknown) => Promise<void> | void): this;
+    on(event: string, handler: EventHandler): this;
+    _emit(event: string, payload: unknown, ctx: unknown): void;
+    emit(event: string, payload: unknown): Promise<void>;
+    flush(events: PendingEvent[], ctx: unknown): Promise<void>;
+}
+/** @deprecated Use InMemoryEventBus instead. EventBus will be removed in a future version. */
+declare const EventBus: typeof InMemoryEventBus;
+type EventBus = InMemoryEventBus;
+
+declare class HookExecutor {
+    private readonly registry;
+    private _adapter?;
+    constructor();
+    setAdapter(adapter: VelnAdapter): void;
+    getAdapter(): VelnAdapter | undefined;
+    registerModuleHook<T, TCtx>(tableName: string, handlers: ModuleHookHandlers<T, TCtx>): void;
+    runBeforeInsert<T>(table: TableDef<T>, ctx: unknown, data: Partial<T>): Promise<Partial<T>>;
+    runBeforeUpdate<T>(table: TableDef<T>, ctx: unknown, current: T, patch: Partial<T>): Promise<Partial<T>>;
+    runBeforeDelete<T>(table: TableDef<T>, ctx: unknown, current: T): Promise<void>;
+    runAfterInsert<T>(table: TableDef<T>, ctx: unknown, result: T, input: Partial<T>, queue?: RequestEventQueue): Promise<void>;
+    runAfterUpdate<T>(table: TableDef<T>, ctx: unknown, result: T, before: T, queue?: RequestEventQueue): Promise<void>;
+    runAfterDelete<T>(table: TableDef<T>, ctx: unknown, deleted: T, queue?: RequestEventQueue): Promise<void>;
+    private _moduleHandlers;
+}
+
+interface JoinClause {
+    type: 'INNER' | 'LEFT' | 'RIGHT' | 'FULL';
+    table: string;
+    on: string;
+}
+/** SQL dialect — used for ILIKE fallback on non-Postgres adapters. */
+type SqlDialect = 'sqlite' | 'postgres' | 'mysql';
+/** Explicit operator condition for a single column. */
+type WhereOp<T> = {
+    op: '=';
+    value: T;
+} | {
+    op: '!=';
+    value: T;
+} | {
+    op: '>';
+    value: T;
+} | {
+    op: '>=';
+    value: T;
+} | {
+    op: '<';
+    value: T;
+} | {
+    op: '<=';
+    value: T;
+} | {
+    op: 'IN';
+    value: T[];
+} | {
+    op: 'NOT IN';
+    value: T[];
+} | {
+    op: 'LIKE';
+    value: string;
+} | {
+    op: 'ILIKE';
+    value: string;
+} | {
+    op: 'IS NULL';
+} | {
+    op: 'IS NOT NULL';
+};
+/** Per-field condition — shorthand (plain value = equality) or explicit operator. */
+type FieldCondition<T> = T | WhereOp<T>;
+/** Map of column conditions — each field is optional. */
+type WhereConditions<TRow> = {
+    [K in keyof TRow]?: FieldCondition<TRow[K]>;
+};
+/**
+ * Full WHERE input — either a flat conditions map, OR-group, or AND-group.
+ * OR/AND values are recursively WhereInput allowing nesting.
+ */
+type WhereInput<TRow> = WhereConditions<TRow> | {
+    OR: WhereInput<TRow>[];
+} | {
+    AND: WhereInput<TRow>[];
+};
+/** A single aggregate expression: FN("col") AS alias. */
+interface AggregateClause {
+    alias: string;
+    fn: 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX';
+    col?: string;
+}
+interface SelectOptions {
+    limit?: number;
+    offset?: number;
+    orderBy?: {
+        col: string;
+        dir: 'ASC' | 'DESC';
+    }[];
+    columns?: string[];
+    groupBy?: string[];
+    aggregates?: AggregateClause[];
+    having?: WhereInput<Record<string, unknown>>;
+}
+
+interface QueryLog {
+    /** Total number of queries executed during this request. */
+    queries: number;
+    /** Cumulative wall-clock duration of all queries in ms. */
+    totalMs: number;
+    /** Individual query entries — populated only when logQueries is true. */
+    entries: QueryLogEntry[];
+    /** Warning threshold — exceeded → N+1 warning. */
+    threshold: number;
+    /** Whether individual query entries should be captured (for logQueries). */
+    logQueries: boolean;
+}
+interface PendingEvent {
+    name: string;
+    payload: unknown;
+}
+interface TransactionResult<T> {
+    result: T;
+    events: PendingEvent[];
+}
+declare class BoundVelnDB {
+    private readonly hooks;
+    private readonly ctx;
+    private readonly queue?;
+    /** Per-request query counter — incremented for every query() and execute() call on this instance. */
+    _queryCount: number;
+    private readonly adapter;
+    constructor(adapter: VelnAdapter, hooks: HookExecutor, ctx: unknown, queue?: RequestEventQueue | undefined, queryLog?: QueryLog);
+    from<T, S extends SchemaMap>(table: TableDef<T, S>): SelectBuilder<T, S>;
+    /**
+     * Start a JOIN query from the given table name.
+     * Returns a JoinBuilder — call .join()/.leftJoin() etc. to add clauses,
+     * then .select() to execute and get Record<string, unknown>[] results.
+     *
+     * @example
+     * const rows = await db.join('orders')
+     *   .columns(['orders.id', 'users.name'])
+     *   .join('users', 'orders.user_id = users.id')
+     *   .where('orders.status = ?', ['pending'])
+     *   .select()
+     */
+    join(tableName: string): JoinBuilder;
+    into<T, S extends SchemaMap>(table: TableDef<T, S>): InsertBuilder<T, S>;
+    /**
+     * DataLoader-pattern relation fetch — single IN-query, no N+1.
+     * Returns a Map keyed by the foreign-key value; each entry is an array of
+     * matching child rows (for one-to-many relations).
+     *
+     * @example
+     * const posts = await db.from(postsTable).select()
+     * const authorMap = await db.loadRelation(posts, 'authorId', usersTable, 'id')
+     * // → SELECT * FROM "users" WHERE "id" IN (1, 2, 3)
+     * const withAuthors = posts.map(p => ({ ...p, author: authorMap.get(p.authorId)?.[0] ?? null }))
+     */
+    loadRelation<TParent extends Record<string, unknown>, TChild, TFk extends keyof TParent & string, TPk extends keyof TChild & string>(parents: TParent[], foreignKey: TFk, childTable: TableDef<TChild>, primaryKey: TPk): Promise<Map<TParent[TFk], TChild[]>>;
+    /**
+     * Convenience variant of loadRelation for belongs-to (many-to-one) relations.
+     * Returns Map<fkValue, TChild> — single child per key instead of an array.
+     *
+     * @example
+     * const authorMap = await db.loadRelationOne(posts, 'authorId', usersTable, 'id')
+     * const author = authorMap.get(post.authorId) ?? null
+     */
+    loadRelationOne<TParent extends Record<string, unknown>, TChild, TFk extends keyof TParent & string, TPk extends keyof TChild & string>(parents: TParent[], foreignKey: TFk, childTable: TableDef<TChild>, primaryKey: TPk): Promise<Map<TParent[TFk], TChild>>;
+    transaction<T>(fn: (db: BoundVelnDB) => Promise<T>): Promise<TransactionResult<T>>;
+    /**
+     * Execute raw SQL and return typed rows.
+     *
+     * Without a schema the return type is `Record<string, unknown>[]`.
+     * With a schema (e.g. a Zod object) every row is validated at runtime
+     * and the return type is inferred from the schema.
+     *
+     * @example
+     * // Untyped
+     * const rows = await ctx.db.raw('SELECT * FROM orders WHERE amount > ?', [100])
+     *
+     * // Typed + validated
+     * const schema = z.object({ id: z.number(), amount: z.number() })
+     * const rows = await ctx.db.raw('SELECT id, amount FROM orders WHERE amount > ?', [100], schema)
+     */
+    raw<T = Record<string, unknown>>(sql: string, params?: BindingValue[], schema?: {
+        parse: (row: unknown) => T;
+    }): Promise<T[]>;
+}
+declare class SelectBuilder<T, S extends SchemaMap> {
+    private readonly adapter;
+    private readonly hooks;
+    private readonly ctx;
+    private readonly queue;
+    private readonly table;
+    private readonly conditions;
+    private readonly _options;
+    private readonly _rawWhere;
+    private readonly _dialect;
+    constructor(adapter: VelnAdapter, hooks: HookExecutor, ctx: unknown, queue: RequestEventQueue | undefined, table: TableDef<T, S>, conditions: WhereInput<T>, _options?: SelectOptions, _rawWhere?: {
+        sql: string;
+        params: BindingValue[];
+    }[], _dialect?: SqlDialect);
+    private _cloneWith;
+    private _clone;
+    /**
+     * Add WHERE conditions. Accepts:
+     * - Plain equality map:   `.where({ role: 'admin' })`
+     * - Operator condition:   `.where({ age: { op: '>=', value: 18 } })`
+     * - OR group:             `.where({ OR: [{ role: 'admin' }, { role: 'mod' }] })`
+     * - AND group:            `.where({ AND: [...] })`
+     *
+     * Multiple `.where()` calls are combined with AND.
+     */
+    where(conditions: WhereInput<T>): SelectBuilder<T, S>;
+    /**
+     * Append a raw SQL WHERE fragment, combined with AND.
+     * Use for conditions the builder cannot express.
+     *
+     * @example
+     * .whereRaw('"score" > "threshold"', [])
+     * .whereRaw('"created_at" > ?', ['2024-01-01'])
+     */
+    whereRaw(sql: string, params: BindingValue[]): SelectBuilder<T, S>;
+    /** Limit the number of rows returned. Bound as a parameter — never interpolated. */
+    limit(n: number): SelectBuilder<T, S>;
+    /** Skip the first n rows. Bound as a parameter — never interpolated. */
+    offset(n: number): SelectBuilder<T, S>;
+    /** Add an ORDER BY clause. Multiple calls accumulate in order. */
+    orderBy(col: keyof T & string, dir?: 'ASC' | 'DESC'): SelectBuilder<T, S>;
+    /**
+     * Convenience helper for cursor-based pagination.
+     * page(1, 10) → LIMIT 10 OFFSET 0
+     * page(2, 10) → LIMIT 10 OFFSET 10
+     */
+    page(page: number, size: number): SelectBuilder<T, S>;
+    /**
+     * Restrict which columns are returned.
+     * SELECT "id", "name" FROM "table" — instead of SELECT *
+     *
+     * Return type is narrowed to Pick<T, K> for full type safety.
+     */
+    columns<K extends keyof T & string>(...cols: K[]): SelectBuilder<Pick<T, K>, S>;
+    /**
+     * Add a GROUP BY clause. Multiple columns are comma-separated.
+     * Combine with .aggregate() to get grouped aggregate results.
+     */
+    groupBy(...cols: (keyof T & string)[]): SelectBuilder<T, S>;
+    /**
+     * Add a HAVING clause — filters aggregate groups.
+     * Uses the same WhereInput system as .where() (supports operators, OR/AND).
+     *
+     * @example
+     * .groupBy('role').aggregate({ cnt: { fn: 'COUNT' } }).having({ cnt: { op: '>', value: 1 } })
+     */
+    having(conditions: WhereInput<Record<string, unknown>>): SelectBuilder<T, S>;
+    /**
+     * Execute a GROUP BY + aggregate query.
+     * Returns typed rows with group-by columns + aggregate aliases.
+     *
+     * @example
+     * const rows = await db.from(orders)
+     *   .groupBy('status')
+     *   .aggregate({ total: { fn: 'SUM', col: 'amount' }, cnt: { fn: 'COUNT' } })
+     * // rows: { status: string; total: number; cnt: number }[]
+     */
+    aggregate<TAgg extends Record<string, number | string | null>>(aggregates: {
+        [K in keyof TAgg]: {
+            fn: 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX';
+            col?: keyof T & string;
+        };
+    }): Promise<(Partial<T> & TAgg)[]>;
+    /** COUNT(*) or COUNT("col") — returns the count as a number. */
+    count(col?: keyof T & string): Promise<number>;
+    /** SUM("col") — returns the sum as a number (0 if no rows). */
+    sum(col: keyof T & string): Promise<number>;
+    /** AVG("col") — returns the average as a number (0 if no rows). */
+    avg(col: keyof T & string): Promise<number>;
+    /** MIN("col") — returns the minimum value. */
+    min(col: keyof T & string): Promise<number | string | null>;
+    /** MAX("col") — returns the maximum value. */
+    max(col: keyof T & string): Promise<number | string | null>;
+    private _scalarAggregate;
+    private _scalarAggregateRaw;
+    select(): Promise<T[]>;
+    first(): Promise<T | null>;
+    update(patch: Partial<T>): Promise<T>;
+    delete(): Promise<T>;
+}
+declare class InsertBuilder<T, S extends SchemaMap> {
+    private readonly adapter;
+    private readonly hooks;
+    private readonly ctx;
+    private readonly queue;
+    private readonly table;
+    constructor(adapter: VelnAdapter, hooks: HookExecutor, ctx: unknown, queue: RequestEventQueue | undefined, table: TableDef<T, S>);
+    insert(data: InferInsert<S>): Promise<T>;
+    /** Serialize values for SQLite storage. Date → ISO string. */
+    private _serializeForInsert;
+}
+declare class JoinBuilder {
+    private readonly adapter;
+    private readonly tableName;
+    private readonly _columns;
+    private readonly _joins;
+    private readonly _where;
+    private readonly _params;
+    private readonly _options;
+    constructor(adapter: VelnAdapter, tableName: string, _columns: string[], _joins: JoinClause[], _where: string, _params: BindingValue[], _options?: SelectOptions);
+    private _cloneOpts;
+    /** Restrict the selected columns (e.g. ['orders.id', 'users.name']). */
+    columns(cols: string[]): JoinBuilder;
+    /** Add an INNER JOIN clause. */
+    join(table: string, on: string): JoinBuilder;
+    /** Add a LEFT JOIN clause. */
+    leftJoin(table: string, on: string): JoinBuilder;
+    /** Add a RIGHT JOIN clause. */
+    rightJoin(table: string, on: string): JoinBuilder;
+    /** Add a FULL JOIN clause. */
+    fullJoin(table: string, on: string): JoinBuilder;
+    /**
+     * Set a typed WHERE clause from a conditions object.
+     * Each key becomes "key" = ? — values are bound safely.
+     *
+     * @example
+     * .where({ status: 'pending', userId })
+     */
+    where(conditions: Record<string, BindingValue>): JoinBuilder;
+    /**
+     * Set a raw WHERE clause.
+     * Use ? as placeholder; pass bind values as the second argument.
+     *
+     * @example
+     * .where('orders.status = ? AND orders.user_id = ?', ['pending', userId])
+     */
+    where(sql: string, params: BindingValue[]): JoinBuilder;
+    /** Limit the number of rows returned. Bound as a parameter — never interpolated. */
+    limit(n: number): JoinBuilder;
+    /** Skip the first n rows. Bound as a parameter — never interpolated. */
+    offset(n: number): JoinBuilder;
+    /**
+     * Add an ORDER BY clause. Multiple calls accumulate in order.
+     * @param col Column reference, e.g. 'orders.created_at' or 'name'.
+     */
+    orderBy(col: string, dir?: 'ASC' | 'DESC'): JoinBuilder;
+    /**
+     * Convenience helper for cursor-based pagination.
+     * page(1, 10) → LIMIT 10 OFFSET 0
+     * page(2, 10) → LIMIT 10 OFFSET 10
+     */
+    page(page: number, size: number): JoinBuilder;
+    /**
+     * Execute the query and return raw rows (no deserialization).
+     *
+     * @remarks
+     * Type parameter T is a manual cast — not validated at runtime.
+     * For runtime validation, use db.raw() with a Zod schema instead.
+     */
+    select<T = Record<string, unknown>>(): Promise<T[]>;
+    /**
+     * Execute the query and return the first row, or null.
+     *
+     * @remarks
+     * Type parameter T is a manual cast — not validated at runtime.
+     */
+    first<T = Record<string, unknown>>(): Promise<T | null>;
+    private _addJoin;
+}
+
+interface WsCtx<TData = unknown> {
+    /** Matched path params, e.g. { roomId: '42' } for /rooms/:roomId */
+    params: Record<string, string>;
+    /** Parsed query string from the upgrade request */
+    query: Record<string, string | string[]>;
+    /**
+     * The Bun ServerWebSocket — use ws.send(), ws.close(), ws.subscribe(), etc.
+     * Typed with `data: WsCtxData` so ws.data carries ctx.user etc.
+     */
+    ws: bun.ServerWebSocket<WsCtxData>;
+    /**
+     * Validated & typed message payload.
+     * Only set inside onMessage() when a message schema was defined.
+     * Undefined in open / close / drain.
+     */
+    data: TData;
+    /** Set by jwtPlugin when registered on the app. undefined otherwise. */
+    user?: AuthPayload;
+    /** Set by dbPlugin when registered on the app. undefined otherwise. */
+    db?: BoundVelnDB;
+}
+interface WsCtxData {
+    _wsPath: string;
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    user?: AuthPayload;
+    db?: BoundVelnDB;
+    [key: string]: unknown;
+    _data?: unknown;
+}
+interface WsHandlers<TMsg = unknown> {
+    /** Called when a client opens a connection. ctx.data is undefined here. */
+    open?: (ctx: WsCtx<undefined>) => void | Promise<void>;
+    /**
+     * Called for each incoming message.
+     * If a message schema was provided, ctx.data is the validated & typed payload.
+     */
+    message?: (ctx: WsCtx<TMsg>, raw: string | Uint8Array) => void | Promise<void>;
+    /**
+     * Called when a client disconnects.
+     * code: WebSocket close code; reason: human-readable string.
+     */
+    close?: (ctx: WsCtx<undefined>, code: number, reason: string) => void | Promise<void>;
+    /** Called when the send buffer is drained and more data can be written. */
+    drain?: (ctx: WsCtx<undefined>) => void | Promise<void>;
+}
+/** Stored internally — one entry per registered WS path. */
+interface WsRoute {
+    /** Registered path pattern, e.g. '/chat' or '/rooms/:id' */
+    path: string;
+    /** Optional Zod schema to parse incoming messages */
+    messageSchema?: ZodTypeAny;
+    handlers: WsHandlers<any>;
+    /** Reference to the originating module (null for app-level) */
+    _module: unknown | null;
+    /** Index signature — satisfies WsRouteShape from core */
+    [key: string]: unknown;
+}
+/**
+ * WsRouteHandler — passed to app.ws() / module.ws().
+ *
+ * Usage (no schema):
+ *   app.ws('/chat', { open(ctx) { ... }, message(ctx, raw) { ... } })
+ *
+ * Usage (with Zod schema — message is typed):
+ *   app.ws('/chat', {
+ *     message: z.object({ text: z.string() }),
+ *     handlers: {
+ *       message(ctx, raw) { ctx.data.text  // ← typed }
+ *     }
+ *   })
+ */
+type WsRouteHandler<TMsg = unknown> = WsHandlers<TMsg> | WsRouteHandlerWithSchema<TMsg>;
+interface WsRouteHandlerWithSchema<TMsg = unknown> {
+    /** Zod schema for incoming messages. Parsed before onMessage is called. */
+    message: ZodTypeAny;
+    /** Lifecycle callbacks — message(ctx) receives the validated & typed payload */
+    handlers: WsHandlers<TMsg>;
+}
+
+declare module 'oakbun' {
+    interface ModuleBuilder<TCtx, TPrefix extends string, TRoutes> {
+        ws<TMsg = unknown>(path: string, handler: WsRouteHandler<TMsg>): ModuleBuilder<TCtx, TPrefix, TRoutes>;
+    }
+}
+
+declare const _baseAuditFields: {
+    readonly id: oakbun.Column<number>;
+    readonly tableName: oakbun.Column<string>;
+    readonly operation: oakbun.Column<string>;
+    readonly actor: oakbun.Column<string | null>;
+    readonly before: oakbun.Column<string | null>;
+    readonly after: oakbun.Column<string | null>;
+    readonly changedAt: oakbun.Column<Date>;
+};
+type BaseAuditSchema = typeof _baseAuditFields;
+type AuditTableDef<S extends SchemaMap = BaseAuditSchema> = TableDef<InferRow<BaseAuditSchema & S>, BaseAuditSchema & S>;
+interface AuditConfig<TCtx, TRow, S extends SchemaMap = BaseAuditSchema> {
+    /** The audit table to write into. */
+    storeIn: AuditTableDef<S>;
+    /** Extract actor identifier from request context. Return null for anonymous. */
+    actor: (ctx: TCtx) => string | null | undefined;
+    /** Field names to replace with '[REDACTED]' in before/after snapshots. */
+    redact?: (keyof TRow & string)[];
+    /** Called when an audit write fails. Defaults to console.error. */
+    onError?: (err: unknown) => void;
+}
+
+type ModelInstance<TDef> = TDef & {
+    readonly db: BoundVelnDB;
+};
+interface ModelDef<TName extends string, TDef> {
+    readonly _modelName: TName;
+    readonly _factory: (db: BoundVelnDB) => ModelInstance<TDef>;
+}
+
+type Dep<TKey extends string, TDef> = ModelDef<TKey, TDef> | ServiceDef<TKey, TDef>;
+interface ServiceDef<TKey extends string, TDef> {
+    readonly _serviceKey: TKey;
+    readonly _deps: ReadonlyArray<Dep<string, unknown>>;
+    readonly _options: BaseOptions;
+    readonly _factory: (deps: Record<string, unknown>) => TDef;
+}
+
+type EventCallback = (payload: unknown) => void | Promise<void>;
+type RawHandler = (payload: unknown, ctx: Record<string, unknown>) => void | Promise<void>;
+interface EventHandlerDef {
+    readonly _handlers: Map<string, EventCallback>;
+    readonly _rawHandlers: Map<string, RawHandler>;
+    readonly _logger: Logger;
+    readonly _services: ReadonlyArray<ServiceDef<string, unknown>>;
+}
+
+interface CronCtx {
+    db: BoundVelnDB;
+    [key: string]: unknown;
+}
+
+interface CronDef<TServices extends Record<string, unknown> = Record<never, never>> {
+    readonly _name: string;
+    readonly _expression: string;
+    readonly _timezone: string | undefined;
+    readonly _runOnStart: boolean;
+    readonly _ttlMs: number | undefined;
+    readonly _logger: Logger;
+    readonly _mode: 'process' | 'os';
+    readonly _handler: ((ctx: CronCtx & TServices, logger: Logger) => Promise<void> | void) | undefined;
+    readonly _services: ReadonlyArray<ServiceDef<string, unknown>>;
+    readonly _script: string | undefined;
+    readonly _onError: ((err: unknown) => void) | undefined;
+    use<TKey extends string, TDef>(service: ServiceDef<TKey, TDef>): CronDef<TServices & Record<TKey, TDef>>;
+}
+
+interface HookDeclaration<T, TCtx> {
+    table: TableDef<T, any>;
+    handlers: ModuleHookHandlers<T, TCtx>;
+}
+interface AuditDeclaration<T, TCtx, S extends SchemaMap> {
+    table: TableDef<T, any>;
+    config: AuditConfig<TCtx, T, S>;
+}
+interface ServiceDeclaration<TKey extends string, TDef> {
+    readonly service: ServiceDef<TKey, TDef>;
+}
+interface VelnModule {
+    prefix: string;
+    routes: Route<any>[];
+    wsRoutes: WsRouteShape[];
+    hookDeclarations: HookDeclaration<any, any>[];
+    auditDeclarations: AuditDeclaration<any, any, any>[];
+    serviceDeclarations: ReadonlyArray<ServiceDeclaration<string, unknown>>;
+    plugins: Plugin<any, any>[];
+    guards: Guard<any>[];
+    onRequestHooks: OnRequestHook<any>[];
+    onBeforeHandleHooks: OnBeforeHandleHook<any>[];
+    onResponseHooks: OnResponseHook<any>[];
+    onError?: ErrorHandler<any>;
+    eventHandlerDefs: EventHandlerDef[];
+    cronDefs: CronDef<Record<string, unknown>>[];
+    visibility: 'public' | 'hidden';
+    meta?: {
+        tag?: string;
+        description?: string;
+    };
+    options?: BaseOptions;
+}
+
+interface CookieOptions {
+    httpOnly?: boolean;
+    secure?: boolean;
+    sameSite?: 'Strict' | 'Lax' | 'None';
+    maxAge?: number;
+    path?: string;
+    domain?: string;
+}
+interface CookieJar {
+    get(name: string): string | undefined;
+    set(name: string, value: string, options?: CookieOptions): void;
+    delete(name: string): void;
+    /** Framework-internal: returns all pending Set-Cookie header values */
+    _pending(): string[];
+}
+
+/** Minimal WS route shape that Core knows about. Full type lives in @veln/ws. */
+interface WsRouteShape {
+    path: string;
+    _module: unknown | null;
+    [key: string]: unknown;
+}
+interface RouteSchema {
+    params?: ZodTypeAny;
+    query?: ZodTypeAny;
+    body?: ZodTypeAny;
+    response?: ZodTypeAny;
+}
+/** Additional response code definition for OpenAPI docs (e.g. 401, 404). */
+interface RouteResponseDoc {
+    description: string;
+}
+interface RouteDocs {
+    /** Human-readable route summary shown in Scalar / Swagger UI. Auto-generated if absent. */
+    summary?: string;
+    /** Longer description rendered below the summary. Markdown supported. */
+    description?: string;
+    /** Unique operationId. Auto-generated if absent (e.g. "listUsers", "getUserById"). */
+    operationId?: string;
+    /**
+     * Additional HTTP response codes to document in the OpenAPI spec.
+     * The 200 success response is always generated automatically.
+     * Use this to document error responses like 401, 403, 404, 422, etc.
+     *
+     * @example
+     * docs: {
+     *   responses: {
+     *     401: { description: 'Unauthorized' },
+     *     404: { description: 'Not found' },
+     *   }
+     * }
+     */
+    responses?: Record<number, RouteResponseDoc>;
+}
+/** Controls a streaming response. Passed to the ctx.stream() writer callback. */
+interface StreamController {
+    /** Push a string or binary chunk to the stream. */
+    send(chunk: string | Uint8Array): void;
+    /** Close the stream. Must be called to end the response. */
+    close(): void;
+}
+/** Options for ctx.stream(). */
+interface StreamOptions {
+    /**
+     * Content-Type header for the streaming response.
+     * Defaults to `'text/plain'`.
+     * Use `'text/event-stream'` for SSE, `'application/x-ndjson'` for NDJSON.
+     */
+    contentType?: string;
+    /** Additional headers to include in the response. */
+    headers?: Record<string, string>;
+    /** HTTP status code. Defaults to 200. */
+    status?: number;
+}
+/**
+ * Controls a Server-Sent Events stream.
+ * Passed to the ctx.sse() writer callback.
+ *
+ * SSE wire format:
+ *   event: <name>\ndata: <json>\n\n   — named event
+ *   data: <json>\n\n                  — unnamed event
+ *   : <text>\n\n                      — comment / keepalive
+ *   id: <value>\n                     — event ID for reconnect
+ *   retry: <ms>\n                     — reconnect interval
+ */
+interface SseController {
+    /** Send a named event with a JSON-serializable payload. */
+    event(name: string, data: unknown): Promise<void>;
+    /** Send an unnamed data event. */
+    data(data: unknown): Promise<void>;
+    /** Send an SSE comment (e.g. keepalive ping). */
+    comment(text?: string): Promise<void>;
+    /** Set the last event ID (used by the browser for reconnect). */
+    id(id: string): Promise<void>;
+    /** Tell the browser how long to wait before reconnecting (milliseconds). */
+    retry(ms: number): Promise<void>;
+}
+interface Logger {
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+}
+interface LogOptions {
+    /** Minimum level to emit. Defaults to 'info'. */
+    level?: 'debug' | 'info' | 'warn' | 'error';
+    /** Keys whose values are replaced with '***' in structured data. Case-insensitive. */
+    mask?: string[];
+    /** Suppress all output — useful in tests. */
+    silent?: boolean;
+}
+interface BaseOptions {
+    log?: LogOptions;
+}
+interface BaseCtx {
+    req: Request;
+    params: Record<string, string>;
+    query: Record<string, string | string[]>;
+    body?: unknown;
+    json: <T>(data: T, status?: number) => Response;
+    text: (data: string, status?: number) => Response;
+    html: (data: string, status?: number) => Response;
+    /**
+     * Returns a streaming Response backed by a ReadableStream.
+     *
+     * The callback receives a StreamController — call `send(chunk)` to push data
+     * and `close()` to end the stream. Errors thrown inside are caught automatically.
+     *
+     * Set `contentType` for SSE (`'text/event-stream'`) or NDJSON (`'application/x-ndjson'`).
+     * Compression is automatically skipped for streaming responses.
+     *
+     * @example
+     * return ctx.stream((stream) => {
+     *   stream.send('data: hello\n\n')
+     *   stream.send('data: world\n\n')
+     *   stream.close()
+     * }, { contentType: 'text/event-stream' })
+     */
+    stream: (writer: (controller: StreamController) => void | Promise<void>, options?: StreamOptions) => Response;
+    /**
+     * Returns a Server-Sent Events Response.
+     *
+     * The callback receives an SseController — call `event()`, `data()`,
+     * `comment()`, `id()`, or `retry()` to push SSE frames, then let the
+     * callback return (or the async iterator complete) to close the stream.
+     *
+     * @example
+     * return ctx.sse(async (sse) => {
+     *   await sse.event('connected', { userId: '42' })
+     *   for await (const update of source()) {
+     *     await sse.event('update', update)
+     *     await sse.comment('keepalive')
+     *   }
+     * })
+     */
+    sse: (writer: (controller: SseController) => void | Promise<void>) => Response;
+    events?: EventBus;
+    logger?: Logger;
+    db?: BoundVelnDB;
+    cookie: CookieJar;
+    emit: <K extends keyof VelnEvents>(event: K, payload: VelnEvents[K]) => void;
+    _requestQueue?: RequestEventQueue;
+    _queryLog?: QueryLog;
+    _startTime?: number;
+}
+type Guard<TCtx> = (ctx: TCtx) => Response | null | Promise<Response | null>;
+type ErrorHandler<TCtx = BaseCtx> = (err: unknown, ctx: TCtx) => Response | Promise<Response>;
+interface RouteHandler<TCtx> {
+    handler: (ctx: TCtx) => Response | Promise<Response>;
+}
+type OnRequestFn<TCtx extends BaseCtx = BaseCtx> = (ctx: TCtx) => Response | void | Promise<Response | void>;
+type OnBeforeHandleFn<TCtx extends BaseCtx = BaseCtx> = (ctx: TCtx) => Response | void | Promise<Response | void>;
+type OnResponseFn<TCtx extends BaseCtx = BaseCtx> = (ctx: TCtx, response: Response) => Response | void | Promise<Response | void>;
+interface OnRequestHook<TCtx extends BaseCtx = BaseCtx> {
+    readonly _phase: 'onRequest';
+    readonly _fn: OnRequestFn<TCtx>;
+}
+interface OnBeforeHandleHook<TCtx extends BaseCtx = BaseCtx> {
+    readonly _phase: 'onBeforeHandle';
+    readonly _fn: OnBeforeHandleFn<TCtx>;
+}
+interface OnResponseHook<TCtx extends BaseCtx = BaseCtx> {
+    readonly _phase: 'onResponse';
+    readonly _fn: OnResponseFn<TCtx>;
+}
+interface Route<TCtx = BaseCtx> {
+    method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    summary?: string;
+    description?: string;
+    /** OpenAPI documentation override set via the `docs` option on route registration. */
+    docs?: RouteDocs;
+    handler: RouteHandler<TCtx>;
+    guards: Guard<TCtx>[];
+    onError?: ErrorHandler<TCtx>;
+    schema?: RouteSchema;
+    visibility?: 'public' | 'hidden';
+    moduleGuardOptOut?: true;
+    _module?: VelnModule;
+    _pluginName?: string;
+}
+
+/** A single navigation item contributed by a plugin via .nav(). */
+interface NavItem {
+    label: string;
+    route: string;
+    icon?: string;
+    order?: number;
+    children?: NavItem[];
+}
+interface Plugin<TCtx, TAdd extends object> {
+    name: string;
+    /**
+     * Optional list of plugin names that must be registered before this plugin.
+     * app.plugin() validates this at registration time and throws PLUGIN_MISSING_DEP
+     * if a required plugin is not yet registered.
+     *
+     * Example: eventBusPlugin sets requires: ['db'] to enforce registration order.
+     */
+    requires?: string[];
+    /**
+     * Optional list of modules this plugin contributes.
+     * app.plugin() calls app.register() on each entry automatically.
+     *
+     * Can also be set to a factory function for typed ctx inference (Option A, Spec 04).
+     * The factory is called once with a dummy ctx to extract the module list —
+     * it is NEVER called at request time.
+     */
+    modules?: VelnModule[];
+    /**
+     * Optional permission gate for all routes contributed via .modules().
+     * app.plugin() checks ctx.user before running plugin.request() for those routes.
+     * User must have at least one of the listed permissions — checked via AuthAdapter.hasPermission().
+     * No user → 401. User without any matching permission → 403.
+     */
+    permissions?: string[];
+    /**
+     * Optional nav items contributed by this plugin.
+     * GET /nav returns these filtered by the plugin's permissions for the current user.
+     */
+    nav?: NavItem[];
+    install?: (hooks: HookExecutor) => Promise<void> | void;
+    request: (ctx: TCtx) => Promise<TCtx & TAdd> | (TCtx & TAdd);
+    teardown?: () => Promise<void> | void;
+}
+
+interface WsRateLimitConfig {
+    /** Maximum messages per window per connection. Default: 60 */
+    max?: number;
+    /** Window duration in milliseconds. Default: 1000 (1 second) */
+    windowMs?: number;
+}
+declare class VelnWsAdapterImpl implements VelnWsAdapter {
+    private readonly _routes;
+    private readonly _rateLimitMap;
+    private readonly _rateLimitMax;
+    private readonly _rateLimitWindowMs;
+    constructor(rateLimit?: WsRateLimitConfig);
+    registerRoute(path: string, route: WsRouteShape$1): void;
+    getRoute(path: string): WsRoute | undefined;
+    /**
+     * ws() — register a typed WebSocket route on this adapter.
+     *
+     * Usage:
+     *   const ws = createWsAdapter()
+     *   app.registerWsAdapter(ws)
+     *
+     *   ws.route('/chat', {
+     *     open(ctx)         { ctx.ws.send('welcome') },
+     *     message(ctx, raw) { ctx.ws.send(raw) },
+     *   })
+     *
+     *   // With Zod message schema:
+     *   ws.route('/chat', {
+     *     message: z.object({ text: z.string() }),
+     *     handlers: { message(ctx) { ctx.data.text } },
+     *   })
+     */
+    route<TMsg = unknown>(path: string, handler: WsRouteHandler<TMsg>): this;
+    handleUpgrade(req: Request, server: bun.Server, baseCtx: BaseCtx$1, plugins: ReadonlyArray<Plugin<any, any>>, installedRef: {
+        value: boolean;
+    }, installedModulePlugins: Set<string>): Promise<Response | null>;
+    getWebsocketConfig(): bun.WebSocketHandler<Record<string, unknown>>;
+    private _buildCtx;
+}
+/**
+ * createWsAdapter() — creates a VelnWsAdapter for use with Veln apps.
+ *
+ * Usage:
+ *   import { createWsAdapter } from '@oakbun/ws'
+ *   app.registerWsAdapter(createWsAdapter())
+ *
+ *   app.ws('/chat', {
+ *     open(ctx)         { ctx.ws.send('welcome') },
+ *     message(ctx, raw) { ctx.ws.send(raw) },
+ *   })
+ */
+declare function createWsAdapter(rateLimit?: WsRateLimitConfig): VelnWsAdapterImpl;
+
+export { VelnWsAdapterImpl, type WsCtx, type WsCtxData, type WsHandlers, type WsRateLimitConfig, type WsRoute, type WsRouteHandler, type WsRouteHandlerWithSchema, createWsAdapter };