silgi 0.43.28 → 0.50.0

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 };

package/dist/ws.mjs

@@ -0,0 +1,205 @@
+import { SilgiError, toSilgiError } from "./core/error.mjs";
+import { compileRouter, createContext, releaseContext } from "./compile.mjs";
+import { stringifyJSON } from "./core/utils.mjs";
+import { decode, encode } from "./codec/msgpack.mjs";
+//#region src/ws.ts
+/**
+* WebSocket RPC adapter — powered by crossws.
+*
+* Bidirectional type-safe RPC over WebSocket.
+* Supports subscriptions (server → client streaming) natively.
+*
+* Protocol:
+*   Client → Server: { id: string, path: string, input?: unknown }
+*   Server → Client: { id: string, result?: unknown, error?: unknown }
+*   Server → Client (stream): { id: string, data: unknown, done?: boolean }
+*/
+const peerAbortControllers = /* @__PURE__ */ new WeakMap();
+const peerKeepaliveTimers = /* @__PURE__ */ new WeakMap();
+/**
+* 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') }),
+* }));
+* ```
+*/
+function createWSHooks(routerDef, options = {}) {
+	const flat = compileRouter(routerDef);
+	const useMsgpack = options.protocol === "messagepack" || options.protocol == null && (options.binary ?? false);
+	const contextFactory = options.context;
+	const keepaliveMs = options.keepalive === false ? 0 : options.keepalive ?? 3e4;
+	function send(peer, data) {
+		const compress = !!options.compress;
+		if (useMsgpack) peer.send(encode(data), { compress });
+		else peer.send(stringifyJSON(data), { compress });
+	}
+	function parseMessage(message) {
+		if (useMsgpack) return decode(message.uint8Array());
+		return message.json();
+	}
+	return {
+		open(peer) {
+			peerAbortControllers.set(peer, /* @__PURE__ */ new Set());
+			if (keepaliveMs > 0) {
+				const ws = peer._internal?.ws;
+				if (ws && typeof ws.ping === "function") {
+					let alive = true;
+					ws.on("pong", () => {
+						alive = true;
+					});
+					const timer = setInterval(() => {
+						if (!alive) {
+							clearInterval(timer);
+							ws.terminate();
+							return;
+						}
+						alive = false;
+						ws.ping();
+					}, keepaliveMs);
+					peerKeepaliveTimers.set(peer, timer);
+				}
+			}
+		},
+		async message(peer, message) {
+			let req;
+			try {
+				req = parseMessage(message);
+			} catch {
+				send(peer, {
+					id: "0",
+					error: {
+						code: "BAD_REQUEST",
+						status: 400,
+						message: "Invalid message format"
+					}
+				});
+				return;
+			}
+			const { id, path, input } = req;
+			const route = flat("POST", "/" + path)?.data;
+			if (!route || !route.ws) {
+				send(peer, {
+					id,
+					error: {
+						code: "NOT_FOUND",
+						status: 404,
+						message: `Procedure "${path}" not found`
+					}
+				});
+				return;
+			}
+			const ctx = createContext();
+			if (contextFactory) try {
+				const baseResult = contextFactory(peer);
+				const base = baseResult instanceof Promise ? await baseResult : baseResult;
+				const keys = Object.keys(base);
+				for (let i = 0; i < keys.length; i++) ctx[keys[i]] = base[keys[i]];
+			} catch (err) {
+				releaseContext(ctx);
+				send(peer, {
+					id,
+					error: (err instanceof SilgiError ? err : toSilgiError(err)).toJSON()
+				});
+				return;
+			}
+			const ac = new AbortController();
+			const controllers = peerAbortControllers.get(peer);
+			controllers?.add(ac);
+			try {
+				const result = route.handler(ctx, input ?? {}, ac.signal);
+				const output = result instanceof Promise ? await result : result;
+				if (output && typeof output === "object" && Symbol.asyncIterator in output) {
+					const iter = output;
+					try {
+						for await (const data of iter) {
+							if (ac.signal.aborted) break;
+							send(peer, {
+								id,
+								data
+							});
+						}
+						if (!ac.signal.aborted) send(peer, {
+							id,
+							data: null,
+							done: true
+						});
+					} catch (err) {
+						if (!ac.signal.aborted) send(peer, {
+							id,
+							error: (err instanceof SilgiError ? err : toSilgiError(err)).toJSON()
+						});
+					} finally {
+						await iter.return?.();
+					}
+					return;
+				}
+				send(peer, {
+					id,
+					result: output
+				});
+			} catch (err) {
+				send(peer, {
+					id,
+					error: (err instanceof SilgiError ? err : toSilgiError(err)).toJSON()
+				});
+			} finally {
+				controllers?.delete(ac);
+				releaseContext(ctx);
+			}
+		},
+		close(peer, _details) {
+			const timer = peerKeepaliveTimers.get(peer);
+			if (timer) {
+				clearInterval(timer);
+				peerKeepaliveTimers.delete(peer);
+			}
+			const controllers = peerAbortControllers.get(peer);
+			if (controllers) {
+				for (const ac of controllers) ac.abort();
+				controllers.clear();
+				peerAbortControllers.delete(peer);
+			}
+		},
+		error(_peer, error) {
+			console.error("[silgi:ws] error:", error);
+		}
+	};
+}
+/**
+* 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);
+* ```
+*/
+async function attachWebSocket(server, routerDef, options = {}) {
+	const nodeAdapter = (await import("crossws/adapters/node")).default;
+	const serverOptions = {};
+	if (options.compress) serverOptions.perMessageDeflate = typeof options.compress === "object" ? options.compress : true;
+	if (options.maxPayload !== void 0) serverOptions.maxPayload = options.maxPayload;
+	const ws = nodeAdapter({
+		hooks: createWSHooks(routerDef, options),
+		...Object.keys(serverOptions).length > 0 && { serverOptions }
+	});
+	server.on("upgrade", (req, socket, head) => {
+		ws.handleUpgrade(req, socket, head);
+	});
+}
+//#endregion
+export { attachWebSocket, createWSHooks };