silgi 0.51.7 → 0.52.0

package/dist/silgi.d.mts

@@ -1,6 +1,7 @@
 import { AnySchema, InferSchemaInput, InferSchemaOutput } from "./core/schema.mjs";
 import { ErrorDef, GuardDef, GuardFn, InferClient, ProcedureDef, ResolveContext, RouterDef, WrapDef, WrapFn } from "./types.mjs";
 import { AnalyticsOptions } from "./plugins/analytics/types.mjs";
+import { SchemaConverter } from "./core/schema-converter.mjs";
 import { ScalarOptions } from "./scalar.mjs";
 import { ProcedureBuilder } from "./builder.mjs";
 import { ServeOptions, SilgiServer } from "./core/serve.mjs";
@@ -37,11 +38,53 @@ interface SilgiHooks {
     port: number;
     hostname: string;
   }) => void;
+  /**
+   * Fires after base context is applied and params are merged, before input parsing.
+   * Framework plugins (e.g. analytics) use this to inject fields into `ctx`
+   * before any user code runs.
+   *
+   * @internal
+   */
+  'request:prepare': (event: {
+    request: Request;
+    ctx: Record<string, unknown>;
+  }) => void;
+  /**
+   * Fires after the pipeline produces output, before the `Response` is built.
+   * Framework plugins use this to capture output for trace recording.
+   *
+   * @internal
+   */
+  'response:finalize': (event: {
+    request: Request;
+    ctx: Record<string, unknown>;
+    output: unknown;
+  }) => 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][] }>;
+  /**
+   * Schema converters for OpenAPI spec generation and analytics schema extraction.
+   *
+   * @remarks
+   * Pass a converter for each schema library you use. Schemas with a native
+   * `jsonSchema.input()` implementation (Valibot, ArkType, Zod v4) work
+   * without registering anything. Converters are required for libraries
+   * that do not implement the Standard JSON Schema extension.
+   *
+   * @example
+   * ```ts
+   * import { zodConverter } from 'silgi/zod'
+   *
+   * const k = silgi({
+   *   context: (req) => ({ db: getDB() }),
+   *   schemaConverters: [zodConverter],
+   * })
+   * ```
+   */
+  schemaConverters?: SchemaConverter[];
   /**
    * Storage configuration — mount drivers by path prefix.
    *
@@ -69,35 +112,106 @@ interface SilgiInstance<TBaseCtx extends Record<string, unknown>> {
   removeHook: Hookable<SilgiHooks>['removeHook'];
   /** Access storage with optional prefix — uses configured mounts */
   useStorage: typeof useStorage;
-  /** Create a guard middleware (flat, zero-closure) */
+  /**
+   * Run `fn` inside this instance's per-request `AsyncLocalStorage` scope.
+   *
+   * @remarks
+   * Instrumented integrations (Drizzle, Better Auth) read the installed
+   * context via {@link SilgiInstance.currentContext}. Because each silgi
+   * instance owns its own bridge, calls across instances do not collide.
+   *
+   * @param ctx - Context to install for the duration of `fn`.
+   * @param fn - Function executed with `ctx` as the ambient context.
+   * @returns Whatever `fn` returns.
+   */
+  runInContext: <T>(ctx: TBaseCtx, fn: () => T) => T;
+  /**
+   * Read the context installed by the nearest enclosing
+   * {@link SilgiInstance.runInContext}, or `undefined` if none.
+   */
+  currentContext: () => TBaseCtx | undefined;
+  /**
+   * Await storage initialization.
+   *
+   * @remarks
+   * When `storage` is configured, resolves after `initStorage` completes.
+   * When storage is not configured, resolves immediately (no dynamic
+   * import). Errors during storage init reject this promise — no silent
+   * `console.error` fallback.
+   *
+   * `useStorage()` awaits this promise internally, so calling `ready()`
+   * is optional unless you need an explicit ordering guarantee before
+   * your first `useStorage()` call.
+   *
+   * @example
+   * ```ts
+   * const k = silgi({ context: () => ({}), storage: { cache: redisDriver() } })
+   * await k.ready() // storage driver connected
+   * ```
+   */
+  ready: () => Promise<void>;
+  /**
+   * Create a guard middleware — a flat, zero-closure helper that runs
+   * before the resolver and can throw or return partial context.
+   *
+   * @remarks
+   * Prefer `guard` over `wrap` when you only need a pre-step. The
+   * returned object is passed to `$use(guard)` on any builder.
+   */
   guard: GuardFactory<TBaseCtx>;
-  /** Create a wrap middleware (onion, before+after) */
+  /**
+   * Create a wrap middleware — onion-style before/after hook that can
+   * short-circuit the pipeline or transform the output.
+   */
   wrap: (fn: WrapFn<TBaseCtx>) => WrapDef<TBaseCtx>;
-  /** Start a builder — resolve only */
+  /** Start a builder chain — set the resolver for a query procedure. */
   $resolve: ProcedureBuilder<'query', TBaseCtx>['$resolve'];
-  /** Start a builder — set input schema */
+  /** Start a builder chain — set the input schema (Standard Schema). */
   $input: ProcedureBuilder<'query', TBaseCtx>['$input'];
-  /** Start a builder — add middleware */
+  /** Start a builder chain — add guard/wrap middleware. */
   $use: ProcedureBuilder<'query', TBaseCtx>['$use'];
-  /** Start a builder — set output schema */
+  /** Start a builder chain — set the output schema. */
   $output: ProcedureBuilder<'query', TBaseCtx>['$output'];
-  /** Start a builder — set errors */
+  /** Start a builder chain — declare typed errors. */
   $errors: ProcedureBuilder<'query', TBaseCtx>['$errors'];
-  /** Start a builder — set route metadata */
+  /** Start a builder chain — set HTTP route metadata (method, path, etc). */
   $route: ProcedureBuilder<'query', TBaseCtx>['$route'];
-  /** Start a builder — set custom metadata */
+  /** Start a builder chain — attach custom metadata for tooling. */
   $meta: ProcedureBuilder<'query', TBaseCtx>['$meta'];
-  /** Define a subscription (SSE stream) */
+  /** Define a subscription — returns an SSE stream of events. */
   subscription: SubscriptionFactory<TBaseCtx>;
-  /** Start a builder — create a background task */
+  /**
+   * Start a builder chain — create a background/cron task.
+   *
+   * @remarks
+   * Tasks are collected from the router on `serve()` and scheduled via
+   * `croner` when a `cron` spec is provided.
+   */
   $task: ProcedureBuilder<'query', TBaseCtx>['$task'];
-  /** Assemble router and compile pipelines */
+  /**
+   * Assemble a router from nested procedures and pre-compile each
+   * pipeline.
+   *
+   * @remarks
+   * The returned value is the same object you passed in — path
+   * assignment and compilation happen off to the side, cached in a
+   * `WeakMap` keyed on the def. Never mutate the router after handing
+   * it to `router()`; build a new one instead.
+   */
   router: <T extends RouterDef>(def: T) => T;
-  /** Create a Fetch API handler: (Request) => Response */
+  /**
+   * Create a Fetch API handler — `(Request) => Response | Promise<Response>`.
+   *
+   * @remarks
+   * Use this from any Fetch-compatible adapter (Next.js App Router,
+   * SvelteKit, Remix, srvx, Cloudflare Workers, Bun, Deno, hono over
+   * Lambda, etc.). The router has subscriptions mounted automatically
+   * when `hasWsProcedures` is detected.
+   */
   handler: (router: RouterDef, options?: {
     /** URL path prefix (e.g. "/api"). Only requests matching this prefix are handled; others return 404. */basePath?: string; /** Enable Scalar API Reference UI at /api/reference and /api/openapi.json */
-    scalar?: boolean | ScalarOptions; /** Enable analytics dashboard at /api/analytics */
-    analytics?: boolean | AnalyticsOptions;
+    scalar?: boolean | ScalarOptions; /** Enable analytics dashboard at /api/analytics — requires `auth` to be set */
+    analytics?: 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?: {
@@ -105,8 +219,24 @@ interface SilgiInstance<TBaseCtx extends Record<string, unknown>> {
     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>;
+  /**
+   * Create & start a Node.js HTTP server. Returns a handle to gracefully shut down.
+   *
+   * @remarks
+   * When `options.handleSignals` is `true`, registers `process.once('SIGINT')`
+   * and `process.once('SIGTERM')` listeners that invoke `server.close()`.
+   * Default `false` — opt in explicitly. The srvx-level graceful HTTP drain
+   * is controlled by `ServeOptions.gracefulShutdown`; `handleSignals`
+   * governs only the silgi-layer cron-stop wiring on OS signals.
+   */
+  serve: (router: RouterDef, options?: ServeOptions & {
+    /**
+     * Register `process.once('SIGINT')` / `'SIGTERM'` listeners that call
+     * `server.close()`. Default `false` (opt-in). The close wrapper stops
+     * cron jobs regardless of this setting when called explicitly.
+     */
+    handleSignals?: boolean;
+  }) => Promise<SilgiServer>;
 }
 interface GuardConfig<TBaseCtx, TReturn extends Record<string, unknown> | void, TErrors extends ErrorDef> {
   errors?: TErrors;
@@ -129,6 +259,20 @@ interface SubscriptionFactory<TBaseCtx extends Record<string, unknown>> {
 /**
  * Create a Silgi RPC instance with typed context.
  *
+ * @remarks
+ * Every call returns a self-contained instance with its own schema
+ * registry, `AsyncLocalStorage` bridge, hook emitter and storage state.
+ * Two `silgi()` instances in the same process never share mutable state
+ * — see [ARCHITECTURE.md §3](../ARCHITECTURE.md) for the "de-magic"
+ * invariants.
+ *
+ * @typeParam TBaseCtx - Shape of the base context returned by
+ *   `config.context(req)`. Flows into every procedure's `ResolveContext`.
+ * @param config - Instance configuration. `context` is required; all
+ *   other fields are opt-in.
+ * @returns A {@link SilgiInstance} exposing builder, router, handler,
+ *   caller and server helpers.
+ *
  * @example
  * ```ts
  * const k = silgi({
@@ -139,7 +283,10 @@ interface SubscriptionFactory<TBaseCtx extends Record<string, unknown>> {
  * })
  * // k.$input(), k.$resolve(), k.guard(), k.router(), k.serve()
  * ```
+ *
+ * @see {@link SilgiInstance}
+ * @see {@link SilgiConfig}
  */
 declare function silgi<TBaseCtx extends Record<string, unknown>>(config: SilgiConfig<TBaseCtx>): SilgiInstance<TBaseCtx>;
 //#endregion
-export { SilgiConfig, SilgiInstance, silgi };
+export { SilgiConfig, SilgiHooks, SilgiInstance, silgi };

package/dist/silgi.mjs

@@ -3,8 +3,10 @@ import { createProcedureBuilder } from "./builder.mjs";
 import { assignPaths, routerCache } from "./core/router-utils.mjs";
 import { compileRouter } from "./compile.mjs";
 import { createCaller } from "./caller.mjs";
+import { createContextBridge } from "./core/context-bridge.mjs";
 import { normalizePrefix } from "./core/url.mjs";
 import { createFetchHandler, wrapHandler } from "./core/handler.mjs";
+import { createSchemaRegistry } from "./core/schema-converter.mjs";
 import { createHooks } from "hookable";
 //#region src/silgi.ts
 /**
@@ -45,6 +47,20 @@ function createProcedure(type, ...args) {
 /**
 * Create a Silgi RPC instance with typed context.
 *
+* @remarks
+* Every call returns a self-contained instance with its own schema
+* registry, `AsyncLocalStorage` bridge, hook emitter and storage state.
+* Two `silgi()` instances in the same process never share mutable state
+* — see [ARCHITECTURE.md §3](../ARCHITECTURE.md) for the "de-magic"
+* invariants.
+*
+* @typeParam TBaseCtx - Shape of the base context returned by
+*   `config.context(req)`. Flows into every procedure's `ResolveContext`.
+* @param config - Instance configuration. `context` is required; all
+*   other fields are opt-in.
+* @returns A {@link SilgiInstance} exposing builder, router, handler,
+*   caller and server helpers.
+*
 * @example
 * ```ts
 * const k = silgi({
@@ -55,24 +71,32 @@ function createProcedure(type, ...args) {
 * })
 * // k.$input(), k.$resolve(), k.guard(), k.router(), k.serve()
 * ```
+*
+* @see {@link SilgiInstance}
+* @see {@link SilgiConfig}
 */
 function silgi(config) {
 	const contextFactory = config.context;
+	const schemaRegistry = createSchemaRegistry(config.schemaConverters ?? []);
+	const bridge = createContextBridge();
 	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 readyPromise = config.storage ? import("./core/storage.mjs").then((m) => {
+		m.initStorage(config.storage);
+	}) : Promise.resolve();
 	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));
+			return readyPromise.then(() => import("./core/storage.mjs")).then((m) => m.useStorage(...args));
 		},
+		runInContext: (ctx, fn) => bridge.run(ctx, fn),
+		currentContext: () => bridge.current(),
+		ready: () => readyPromise,
 		guard: (fnOrConfig) => {
 			if (typeof fnOrConfig === "function") return {
 				kind: "guard",
@@ -115,7 +139,14 @@ function silgi(config) {
 		},
 		handler: (routerDef, options) => {
 			const prefix = options?.basePath ? normalizePrefix(options.basePath) : void 0;
-			const fetchHandler = wrapHandler(createFetchHandler(routerDef, contextFactory, hooks, prefix), routerDef, options, prefix);
+			const fetchHandler = wrapHandler(createFetchHandler(routerDef, contextFactory, hooks, prefix, bridge), routerDef, options ? {
+				...options,
+				schemaRegistry,
+				hooks
+			} : {
+				schemaRegistry,
+				hooks
+			}, prefix);
 			if (!(function checkWs(def) {
 				if (!def || typeof def !== "object") return false;
 				if (def.type === "subscription") return true;
@@ -146,7 +177,7 @@ function silgi(config) {
 		},
 		serve: async (routerDef, options) => {
 			const { createServeHandler } = await import("./core/serve.mjs");
-			const server = await createServeHandler(routerDef, contextFactory, hooks, options);
+			const server = await createServeHandler(routerDef, contextFactory, hooks, options, schemaRegistry, bridge);
 			const { collectCronTasks, startCronJobs, stopCronJobs } = await import("./core/task.mjs");
 			const cronTasks = collectCronTasks(routerDef);
 			if (cronTasks.length > 0) {
@@ -154,14 +185,19 @@ function silgi(config) {
 				console.log(`  ${cronTasks.length} cron task(s) scheduled`);
 			}
 			const originalClose = server.close.bind(server);
-			server.close = async (force) => {
+			const wrappedClose = async (force) => {
 				stopCronJobs();
 				return originalClose(force);
 			};
-			const onSignal = () => stopCronJobs();
-			process.once("SIGINT", onSignal);
-			process.once("SIGTERM", onSignal);
-			return server;
+			const silgiServer = Object.assign(Object.create(Object.getPrototypeOf(server)), server, { close: wrappedClose });
+			if (options?.handleSignals) {
+				const onSignal = () => {
+					wrappedClose().catch(() => {});
+				};
+				process.once("SIGINT", onSignal);
+				process.once("SIGTERM", onSignal);
+			}
+			return silgiServer;
 		}
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "silgi",
-  "version": "0.51.7",
+  "version": "0.52.0",
   "private": false,
   "description": "The fastest end-to-end type-safe RPC framework for TypeScript — compiled pipelines, single package, every runtime",
   "keywords": [
@@ -41,7 +41,9 @@
     "lib"
   ],
   "type": "module",
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/integrations/zod/index.mjs"
+  ],
   "exports": {
     ".": {
       "import": "./dist/index.mjs",
@@ -286,6 +288,7 @@
     "pinia": "^3.0.4",
     "rou3": "^0.8.1",
     "tsdown": "^0.21.7",
+    "typedoc": "^0.28.19",
     "typescript": "^6.0.2",
     "vitest": "^4.1.2",
     "vue": "^3.5.31",
@@ -337,6 +340,7 @@
     "fix": "oxlint --fix . && oxfmt --ignore-path .oxfmtignore .",
     "test": "vitest run",
     "typecheck": "tsgo --noEmit",
+    "docs:check": "typedoc --options typedoc.json",
     "release": "bumpp"
   }
 }

package/dist/core/trace-map.d.mts

@@ -1,13 +0,0 @@
-//#region src/core/trace-map.d.ts
-/**
- * Shared WeakMap for passing analytics traces between handler and analytics plugin.
- *
- * Lives in core/ so the dependency direction is correct:
- *   core/handler.ts → core/trace-map.ts ← plugins/analytics.ts
- *
- * The WeakMap maps Request → RequestTrace, allowing the handler to inject
- * trace data into context without importing the analytics plugin.
- */
-declare const analyticsTraceMap: WeakMap<Request, unknown>;
-//#endregion
-export { analyticsTraceMap };

package/dist/core/trace-map.mjs

@@ -1,13 +0,0 @@
-//#region src/core/trace-map.ts
-/**
-* Shared WeakMap for passing analytics traces between handler and analytics plugin.
-*
-* Lives in core/ so the dependency direction is correct:
-*   core/handler.ts → core/trace-map.ts ← plugins/analytics.ts
-*
-* The WeakMap maps Request → RequestTrace, allowing the handler to inject
-* trace data into context without importing the analytics plugin.
-*/
-const analyticsTraceMap = /* @__PURE__ */ new WeakMap();
-//#endregion
-export { analyticsTraceMap };