silgi 0.0.14 → 0.1.0-beta.10

package/dist/silgi.d.mts

@@ -0,0 +1,144 @@
+import { AnySchema, InferSchemaInput, InferSchemaOutput } from "./core/schema.mjs";
+import { ErrorDef, GuardDef, GuardFn, InferClient, ProcedureDef, ResolveContext, RouterDef, WrapDef, WrapFn } from "./types.mjs";
+import { ProcedureBuilder } from "./builder.mjs";
+import { AnalyticsOptions } from "./plugins/analytics.mjs";
+import { ScalarOptions } from "./scalar.mjs";
+import { ServeOptions, SilgiServer } from "./core/serve.mjs";
+import { StorageConfig, useStorage } from "./core/storage.mjs";
+import { Hookable } from "hookable";
+
+//#region src/silgi.d.ts
+interface SilgiHooks {
+  /** Called before a request is processed */
+  request: (event: {
+    path: string;
+    input: unknown;
+  }) => void;
+  /** Called after a successful response */
+  response: (event: {
+    path: string;
+    output: unknown;
+    durationMs: number;
+  }) => void;
+  /** Called when an error occurs */
+  error: (event: {
+    path: string;
+    error: unknown;
+  }) => void;
+  /** Called when the server starts */
+  'serve:start': (event: {
+    url: string;
+    port: number;
+    hostname: string;
+  }) => void;
+  /** Called when the server is shutting down */
+  'serve:stop': (event: {
+    url: string;
+    port: number;
+    hostname: string;
+  }) => void;
+}
+interface SilgiConfig<TCtx extends Record<string, unknown>> {
+  context: (req: Request) => TCtx | Promise<TCtx>;
+  /** Register lifecycle hooks */
+  hooks?: Partial<{ [K in keyof SilgiHooks]: SilgiHooks[K] | SilgiHooks[K][] }>;
+  /**
+   * Storage configuration — mount drivers by path prefix.
+   *
+   * ```ts
+   * import redisDriver from 'unstorage/drivers/redis'
+   * import memoryDriver from 'unstorage/drivers/memory'
+   *
+   * storage: {
+   *   cache: redisDriver({ url: 'redis://localhost' }),
+   *   sessions: memoryDriver(),
+   * }
+   * ```
+   *
+   * Or pass a pre-built unstorage instance:
+   * ```ts
+   * storage: myStorageInstance
+   * ```
+   */
+  storage?: StorageConfig;
+}
+interface SilgiInstance<TBaseCtx extends Record<string, unknown>> {
+  /** Register a lifecycle hook */
+  hook: Hookable<SilgiHooks>['hook'];
+  /** Remove a lifecycle hook */
+  removeHook: Hookable<SilgiHooks>['removeHook'];
+  /** Access storage with optional prefix — uses configured mounts */
+  useStorage: typeof useStorage;
+  /** Create a guard middleware (flat, zero-closure) */
+  guard: GuardFactory<TBaseCtx>;
+  /** Create a wrap middleware (onion, before+after) */
+  wrap: (fn: WrapFn<TBaseCtx>) => WrapDef<TBaseCtx>;
+  /** Start a builder — resolve only */
+  $resolve: ProcedureBuilder<'query', TBaseCtx>['$resolve'];
+  /** Start a builder — set input schema */
+  $input: ProcedureBuilder<'query', TBaseCtx>['$input'];
+  /** Start a builder — add middleware */
+  $use: ProcedureBuilder<'query', TBaseCtx>['$use'];
+  /** Start a builder — set output schema */
+  $output: ProcedureBuilder<'query', TBaseCtx>['$output'];
+  /** Start a builder — set errors */
+  $errors: ProcedureBuilder<'query', TBaseCtx>['$errors'];
+  /** Start a builder — set route metadata */
+  $route: ProcedureBuilder<'query', TBaseCtx>['$route'];
+  /** Start a builder — set custom metadata */
+  $meta: ProcedureBuilder<'query', TBaseCtx>['$meta'];
+  /** Define a subscription (SSE stream) */
+  subscription: SubscriptionFactory<TBaseCtx>;
+  /** Start a builder — create a background task */
+  $task: ProcedureBuilder<'query', TBaseCtx>['$task'];
+  /** Assemble router and compile pipelines */
+  router: <T extends RouterDef>(def: T) => T;
+  /** Create a Fetch API handler: (Request) => Response */
+  handler: (router: RouterDef, options?: {
+    /** Enable Scalar API Reference UI at /reference and /openapi.json */scalar?: boolean | ScalarOptions; /** Enable analytics dashboard at /analytics */
+    analytics?: boolean | AnalyticsOptions;
+  }) => (request: Request) => Response | Promise<Response>;
+  /** Create a direct caller — call procedures without HTTP. For testing and server-side usage. */
+  createCaller: <T extends RouterDef>(router: T, options?: {
+    /** Override or extend the base context */contextOverride?: Record<string, unknown>; /** Mock request headers */
+    headers?: Record<string, string>; /** Default timeout in ms (default: 30000, null = no timeout) */
+    timeout?: number | null;
+  }) => InferClient<T>;
+  /** Create & start a Node.js HTTP server. Returns a handle to gracefully shut down. */
+  serve: (router: RouterDef, options?: ServeOptions) => Promise<SilgiServer>;
+}
+interface GuardConfig<TBaseCtx, TReturn extends Record<string, unknown> | void, TErrors extends ErrorDef> {
+  errors?: TErrors;
+  fn: GuardFn<TBaseCtx, TReturn>;
+}
+interface GuardFactory<TBaseCtx> {
+  /** Simple guard: guard(fn) */
+  <TReturn extends Record<string, unknown> | void>(fn: GuardFn<TBaseCtx, TReturn>): GuardDef<TBaseCtx, TReturn, {}>;
+  /** Guard with typed errors: guard({ errors, fn }) */
+  <TReturn extends Record<string, unknown> | void, TErrors extends ErrorDef>(config: GuardConfig<TBaseCtx, TReturn, TErrors>): GuardDef<TBaseCtx, TReturn, TErrors>;
+}
+interface SubscriptionFactory<TBaseCtx extends Record<string, unknown>> {
+  /** Builder: `subscription()` — returns chainable builder */
+  (): ProcedureBuilder<'subscription', TBaseCtx>;
+  /** Short: `subscription(resolve)` */
+  <TOutput>(resolve: (opts: ResolveContext<TBaseCtx, undefined, {}>) => AsyncIterableIterator<TOutput>): ProcedureDef<'subscription', undefined, TOutput, {}>;
+  /** Short: `subscription(input, resolve)` */
+  <TSchema extends AnySchema, TOutput>(input: TSchema, resolve: (opts: ResolveContext<TBaseCtx, InferSchemaOutput<TSchema>, {}>) => AsyncIterableIterator<TOutput>): ProcedureDef<'subscription', InferSchemaInput<TSchema>, TOutput, {}>;
+}
+/**
+ * Create a Silgi RPC instance with typed context.
+ *
+ * @example
+ * ```ts
+ * const k = silgi({
+ *   context: (req) => ({ db: getDB(), user: getUser(req) }),
+ *   hooks: {
+ *     request: ({ path }) => console.log(`-> ${path}`),
+ *   },
+ * })
+ * const { query, mutation, guard, wrap, router, serve } = k
+ * ```
+ */
+declare function silgi<TBaseCtx extends Record<string, unknown>>(config: SilgiConfig<TBaseCtx>): SilgiInstance<TBaseCtx>;
+//#endregion
+export { SilgiConfig, SilgiInstance, silgi };

package/dist/silgi.mjs

@@ -0,0 +1,156 @@
+import { createTaskFromProcedure } from "./core/task.mjs";
+import { createProcedureBuilder } from "./builder.mjs";
+import { assignPaths, routerCache } from "./core/router-utils.mjs";
+import { compileRouter } from "./compile.mjs";
+import { createCaller } from "./caller.mjs";
+import { createFetchHandler } from "./core/handler.mjs";
+import { createHooks } from "hookable";
+//#region src/silgi.ts
+/**
+* silgi() — the main entry point.
+*
+* Creates a Silgi instance with typed context.
+* All procedure/middleware factories are methods on this instance,
+* so context type flows automatically.
+*
+* Usage:
+*   const k = silgi({ context: (req) => ({ db, headers }) })
+*   export const { query, mutation, guard, wrap, router, handler } = k
+*/
+function createProcedure(type, ...args) {
+	if (args.length === 0) return createProcedureBuilder(type);
+	if (args.length === 1 && typeof args[0] === "function") return {
+		type,
+		input: null,
+		output: null,
+		errors: null,
+		use: null,
+		resolve: args[0],
+		route: null,
+		meta: null
+	};
+	if (args.length === 2 && typeof args[1] === "function") return {
+		type,
+		input: args[0],
+		output: null,
+		errors: null,
+		use: null,
+		resolve: args[1],
+		route: null,
+		meta: null
+	};
+	throw new TypeError(`Invalid arguments for ${type}()`);
+}
+/**
+* Create a Silgi RPC instance with typed context.
+*
+* @example
+* ```ts
+* const k = silgi({
+*   context: (req) => ({ db: getDB(), user: getUser(req) }),
+*   hooks: {
+*     request: ({ path }) => console.log(`-> ${path}`),
+*   },
+* })
+* const { query, mutation, guard, wrap, router, serve } = k
+* ```
+*/
+function silgi(config) {
+	const contextFactory = config.context;
+	const hooks = createHooks();
+	if (config.hooks) {
+		for (const [name, fn] of Object.entries(config.hooks)) if (Array.isArray(fn)) for (const f of fn) hooks.hook(name, f);
+		else if (fn) hooks.hook(name, fn);
+	}
+	if (config.storage) import("./core/storage.mjs").then((m) => m.initStorage(config.storage)).catch((e) => {
+		console.error(`[silgi] Failed to initialize storage: ${e instanceof Error ? e.message : e}`);
+	});
+	const ctxFactory = () => contextFactory(new Request("http://localhost"));
+	return {
+		hook: hooks.hook.bind(hooks),
+		removeHook: hooks.removeHook.bind(hooks),
+		useStorage: (...args) => {
+			return import("./core/storage.mjs").then((m) => m.useStorage(...args));
+		},
+		guard: (fnOrConfig) => {
+			if (typeof fnOrConfig === "function") return {
+				kind: "guard",
+				fn: fnOrConfig
+			};
+			return {
+				kind: "guard",
+				fn: fnOrConfig.fn,
+				errors: fnOrConfig.errors
+			};
+		},
+		wrap: (fn) => ({
+			kind: "wrap",
+			fn
+		}),
+		$resolve: ((fn) => createProcedure("query", fn)),
+		$input: ((schema) => createProcedureBuilder("query", ctxFactory).$input(schema)),
+		$use: ((...middleware) => {
+			const b = createProcedureBuilder("query", ctxFactory);
+			for (const m of middleware) b.$use(m);
+			return b;
+		}),
+		$output: ((schema) => createProcedureBuilder("query", ctxFactory).$output(schema)),
+		$errors: ((errors) => createProcedureBuilder("query", ctxFactory).$errors(errors)),
+		$route: ((route) => createProcedureBuilder("query", ctxFactory).$route(route)),
+		$meta: ((meta) => createProcedureBuilder("query", ctxFactory).$meta(meta)),
+		subscription: ((...args) => createProcedure("subscription", ...args)),
+		$task: ((config) => {
+			return createTaskFromProcedure(config, config.resolve, null, null, () => contextFactory(new Request("http://localhost")));
+		}),
+		router: (def) => {
+			const assigned = assignPaths(def);
+			const flat = compileRouter(assigned);
+			routerCache.set(def, flat);
+			routerCache.set(assigned, flat);
+			return def;
+		},
+		createCaller: (routerDef, options) => {
+			return createCaller(routerDef, contextFactory, options);
+		},
+		handler: (routerDef, options) => {
+			let fetchHandler;
+			let initPromise;
+			async function init() {
+				let h = createFetchHandler(routerDef, contextFactory, hooks);
+				if (options?.scalar) {
+					const { wrapWithScalar } = await import("./scalar.mjs");
+					const scalarOpts = typeof options.scalar === "object" ? options.scalar : {};
+					h = wrapWithScalar(h, routerDef, scalarOpts);
+				}
+				if (options?.analytics) {
+					const { wrapWithAnalytics } = await import("./plugins/analytics.mjs");
+					const analyticsOpts = typeof options.analytics === "object" ? options.analytics : {};
+					h = wrapWithAnalytics(h, analyticsOpts);
+				}
+				fetchHandler = h;
+			}
+			return (request) => {
+				if (fetchHandler) return fetchHandler(request);
+				if (!options?.scalar && !options?.analytics) {
+					fetchHandler = createFetchHandler(routerDef, contextFactory, hooks);
+					return fetchHandler(request);
+				}
+				initPromise ??= init();
+				return initPromise.then(() => fetchHandler(request));
+			};
+		},
+		serve: async (routerDef, options) => {
+			const { createServeHandler } = await import("./core/serve.mjs");
+			const server = await createServeHandler(routerDef, contextFactory, hooks, options);
+			const { collectCronTasks, startCronJobs } = await import("./core/task.mjs");
+			const cronTasks = collectCronTasks(routerDef);
+			if (cronTasks.length > 0) {
+				await startCronJobs(cronTasks);
+				console.log(`  ${cronTasks.length} cron task(s) scheduled`);
+			}
+			return server;
+		}
+	};
+}
+//#endregion
+export { silgi };

package/dist/trpc-interop.d.mts

@@ -0,0 +1,22 @@
+import { RouterDef } from "./types.mjs";
+
+//#region src/trpc-interop.d.ts
+/**
+ * Convert a tRPC router to a Silgi RouterDef.
+ *
+ * Walks the tRPC router's `_def.procedures` and wraps each one as
+ * a Silgi ProcedureDef that calls the tRPC procedure's resolver.
+ *
+ * Supports:
+ * - tRPC v10 and v11 routers
+ * - Queries, mutations, and subscriptions
+ * - Input schemas (passed through as-is)
+ * - Middleware (runs inside tRPC, not Silgi's pipeline)
+ *
+ * Does NOT support:
+ * - Converting tRPC middleware to Silgi guards/wraps
+ * - tRPC context factories (use Silgi's context instead)
+ */
+declare function fromTRPC(trpcRouter: unknown): RouterDef;
+//#endregion
+export { fromTRPC };

package/dist/trpc-interop.mjs

@@ -0,0 +1,68 @@
+//#region src/trpc-interop.ts
+/**
+* Convert a tRPC router to a Silgi RouterDef.
+*
+* Walks the tRPC router's `_def.procedures` and wraps each one as
+* a Silgi ProcedureDef that calls the tRPC procedure's resolver.
+*
+* Supports:
+* - tRPC v10 and v11 routers
+* - Queries, mutations, and subscriptions
+* - Input schemas (passed through as-is)
+* - Middleware (runs inside tRPC, not Silgi's pipeline)
+*
+* Does NOT support:
+* - Converting tRPC middleware to Silgi guards/wraps
+* - tRPC context factories (use Silgi's context instead)
+*/
+function fromTRPC(trpcRouter) {
+	if (!trpcRouter || typeof trpcRouter !== "object") throw new Error("fromTRPC: expected a tRPC router object");
+	const router = trpcRouter;
+	return walkTRPCRouter(router._def?.procedures ?? router);
+}
+function walkTRPCRouter(node) {
+	const result = {};
+	for (const [key, value] of Object.entries(node)) {
+		if (!value || typeof value !== "object") continue;
+		const proc = value;
+		if (isTRPCProcedure(proc)) result[key] = convertProcedure(proc);
+		else if (isTRPCRouter(proc)) result[key] = walkTRPCRouter(proc._def?.procedures ?? proc);
+		else result[key] = walkTRPCRouter(proc);
+	}
+	return result;
+}
+function isTRPCProcedure(value) {
+	const def = value._def;
+	if (!def) return false;
+	return def.type === "query" || def.type === "mutation" || def.type === "subscription";
+}
+function isTRPCRouter(value) {
+	return !!value._def?.procedures;
+}
+function convertProcedure(trpcProc) {
+	const def = trpcProc._def;
+	const type = def.type === "subscription" ? "subscription" : def.type === "mutation" ? "mutation" : "query";
+	return {
+		type,
+		input: def.inputs?.[0] ?? null,
+		output: null,
+		errors: null,
+		use: null,
+		resolve: async ({ input, ctx }) => {
+			if (typeof def.resolver === "function") return def.resolver({
+				input,
+				ctx,
+				type
+			});
+			if (typeof trpcProc.call === "function") return trpcProc.call({
+				input,
+				ctx
+			});
+			throw new Error(`Cannot resolve tRPC procedure: ${JSON.stringify(Object.keys(def))}`);
+		},
+		route: null,
+		meta: { __trpc: true }
+	};
+}
+//#endregion
+export { fromTRPC };

package/dist/types.d.mts

@@ -0,0 +1,108 @@
+import { AnySchema, InferSchemaInput } from "./core/schema.mjs";
+import { TaskDef } from "./core/task.mjs";
+
+//#region src/types.d.ts
+/** HTTP route metadata + OpenAPI operation metadata */
+interface Route {
+  method?: string;
+  path?: string;
+  /** Short summary of the operation (OpenAPI `summary`) */
+  summary?: string;
+  /** Detailed description of the operation (OpenAPI `description`, supports markdown) */
+  description?: string;
+  /** Tags for grouping operations in API docs */
+  tags?: string[];
+  /** Mark operation as deprecated in API docs */
+  deprecated?: boolean;
+  /** Custom operationId (default: router path joined with `_`) */
+  operationId?: string;
+  /** HTTP status code for successful responses (default: 200) */
+  successStatus?: number;
+  /** Description for the success response in API docs */
+  successDescription?: string;
+  /**
+   * Per-procedure security override.
+   * - `false` — public endpoint (no auth), overrides global security
+   * - `string[]` — named security scheme(s) required
+   */
+  security?: false | string[];
+  /**
+   * Override or extend the auto-generated OpenAPI operation object.
+   * - Object: merged over the generated operation
+   * - Function: receives the generated operation, returns the final one
+   *
+   * Use this for any OpenAPI metadata not covered by other Route fields
+   * (e.g. `externalDocs`, `x-` extensions, custom `parameters`).
+   */
+  spec?: Record<string, unknown> | ((operation: Record<string, unknown>) => Record<string, unknown>);
+  /**
+   * Cache-Control header for query responses.
+   *
+   * - `number` — shorthand for `max-age=N` (seconds)
+   * - `string` — full Cache-Control value (e.g. `'public, max-age=60, stale-while-revalidate=30'`)
+   * - Only applies to query procedures (mutations and subscriptions are never cached)
+   */
+  cache?: number | string;
+  /** Enable WebSocket RPC for this procedure */
+  ws?: boolean;
+}
+/** Procedure metadata */
+type Meta = Record<string, unknown>;
+type ProcedureType = 'query' | 'mutation' | 'subscription';
+/** Internal procedure representation — fixed shape for V8 optimization */
+interface ProcedureDef<TType extends ProcedureType = ProcedureType, _TInput = unknown, _TOutput = unknown, TErrors extends ErrorDef = ErrorDef> {
+  readonly type: TType;
+  readonly input: AnySchema | null;
+  readonly output: AnySchema | null;
+  readonly errors: TErrors | null;
+  readonly use: readonly MiddlewareDef[] | null;
+  readonly resolve: Function;
+  readonly route: Route | null;
+  readonly meta: Meta | null;
+}
+/** Error definition: number shorthand or full config */
+type ErrorDefItem = number | {
+  status: number;
+  message?: string;
+  data?: AnySchema;
+};
+type ErrorDef = Record<string, ErrorDefItem>;
+/** Extract data schema from error def item */
+type ErrorData<T extends ErrorDefItem> = T extends {
+  data: infer S extends AnySchema;
+} ? InferSchemaInput<S> : undefined;
+/** Typed fail() function — inferred from errors definition */
+type FailFn<TErrors extends ErrorDef> = <K extends keyof TErrors & string>(code: K, ...args: ErrorData<TErrors[K]> extends undefined ? [data?: unknown] : [data: ErrorData<TErrors[K]>]) => never;
+type GuardFn<TCtxIn, TReturn> = (ctx: TCtxIn) => TReturn | Promise<TReturn> | void | Promise<void>;
+type WrapFn<TCtx> = (ctx: TCtx, next: () => Promise<unknown>) => Promise<unknown>;
+interface GuardDef<TCtxIn = unknown, TReturn = unknown, TErrors extends ErrorDef = {}> {
+  readonly kind: 'guard';
+  readonly fn: GuardFn<TCtxIn, TReturn>;
+  readonly errors?: TErrors;
+}
+interface WrapDef<TCtx = unknown> {
+  readonly kind: 'wrap';
+  readonly fn: WrapFn<TCtx>;
+}
+type MiddlewareDef = GuardDef<any, any> | WrapDef<any>;
+/** Extract the context additions from a single guard */
+type InferGuardOutput<T> = T extends GuardDef<any, infer O> ? (O extends void | undefined ? {} : O extends Record<string, unknown> ? O : {}) : {};
+/** Walk a middleware tuple, accumulate guard outputs into context */
+type InferContextFromUse<T extends readonly MiddlewareDef[], TBase> = T extends readonly [infer Head, ...infer Tail extends readonly MiddlewareDef[]] ? InferContextFromUse<Tail, TBase & InferGuardOutput<Head>> : TBase;
+interface ResolveContext<TCtx, TInput, TErrors extends ErrorDef> {
+  ctx: TCtx;
+  input: TInput;
+  fail: FailFn<TErrors>;
+  signal: AbortSignal;
+  /** URL params extracted from the route pattern (e.g. `/users/:id` → `{ id: '123' }`) */
+  params: Record<string, string>;
+}
+type RouterDef = {
+  [key: string]: ProcedureDef<any, any, any, any> | TaskDef<any, any> | RouterDef;
+};
+/** Return type wrapper — subscription yields, query/mutation returns Promise */
+type ProcedureResult<TType extends ProcedureType, TOutput> = TType extends 'subscription' ? AsyncIterableIterator<TOutput> : Promise<TOutput>;
+/** Infer client type from router */
+type InferClient<T> = T extends ProcedureDef<infer TType, infer TInput, infer TOutput> ? undefined extends TInput ? () => ProcedureResult<TType, TOutput> : (input: TInput) => ProcedureResult<TType, TOutput> : T extends Record<string, unknown> ? { [K in keyof T]: InferClient<T[K]> } : never;
+//#endregion
+export { ErrorDef, ErrorDefItem, FailFn, GuardDef, GuardFn, InferClient, InferContextFromUse, InferGuardOutput, Meta, MiddlewareDef, ProcedureDef, ProcedureType, ResolveContext, Route, RouterDef, WrapDef, WrapFn };

package/dist/ws.d.mts

@@ -0,0 +1,88 @@
+import { RouterDef } from "./types.mjs";
+import { Hooks, Peer } from "crossws";
+import { Server } from "node:http";
+
+//#region src/ws.d.ts
+interface WSAdapterOptions<TCtx extends Record<string, unknown> = Record<string, unknown>> {
+  /**
+   * Wire protocol for WebSocket message encoding.
+   *
+   * - `'json'` — default, text frames with JSON
+   * - `'messagepack'` — binary frames with MessagePack
+   *
+   * @default 'json'
+   */
+  protocol?: 'json' | 'messagepack';
+  /**
+   * @deprecated Use `protocol: 'messagepack'` instead.
+   */
+  binary?: boolean;
+  /** Context factory — receives the peer on each message */
+  context?: (peer: Peer) => TCtx | Promise<TCtx>;
+  /**
+   * Enable per-message-deflate compression.
+   *
+   * - `true`: enable with defaults
+   * - `object`: fine-tune zlib options (passed to ws `perMessageDeflate`)
+   *
+   * @default false
+   */
+  compress?: boolean | {
+    threshold?: number;
+    serverNoContextTakeover?: boolean;
+    clientNoContextTakeover?: boolean;
+    serverMaxWindowBits?: number;
+    clientMaxWindowBits?: number;
+  };
+  /**
+   * Maximum allowed message size in bytes.
+   * Messages exceeding this limit will cause the connection to be closed.
+   *
+   * @default 1_048_576 (1 MB)
+   */
+  maxPayload?: number;
+  /**
+   * Keepalive ping interval in milliseconds.
+   * Server sends a ping frame at this interval; if the client
+   * does not respond with a pong before the next ping, the connection is terminated.
+   *
+   * Set to `0` or `false` to disable.
+   *
+   * @default 30_000 (30 seconds)
+   */
+  keepalive?: number | false;
+}
+/**
+ * Create crossws-compatible hooks for Silgi RPC over WebSocket.
+ *
+ * Works with any crossws integration — Nitro, Deno, Bun, Cloudflare, etc.
+ *
+ * @example
+ * ```ts
+ * // Nitro / Nuxt
+ * import { createWSHooks } from "silgi/ws";
+ * export default defineWebSocketHandler(createWSHooks(appRouter));
+ *
+ * // With context
+ * export default defineWebSocketHandler(createWSHooks(appRouter, {
+ *   context: (peer) => ({ userId: peer.request?.headers.get('x-user-id') }),
+ * }));
+ * ```
+ */
+declare function createWSHooks<TCtx extends Record<string, unknown>>(routerDef: RouterDef, options?: WSAdapterOptions<TCtx>): Partial<Hooks>;
+/**
+ * Attach WebSocket RPC handler to an existing Node.js HTTP server.
+ *
+ * @example
+ * ```ts
+ * import { createServer } from "node:http";
+ * import { attachWebSocket } from "silgi/ws";
+ *
+ * const server = createServer(httpHandler);
+ * attachWebSocket(server, appRouter);
+ * server.listen(3000);
+ * ```
+ */
+declare function attachWebSocket<TCtx extends Record<string, unknown>>(server: Server, routerDef: RouterDef, options?: WSAdapterOptions<TCtx>): Promise<void>;
+//#endregion
+export { WSAdapterOptions, attachWebSocket, createWSHooks };