silgi 0.51.7 → 0.52.0

package/README.md

@@ -10,6 +10,53 @@
 
 End-to-end type-safe RPC framework for TypeScript. Single package — server, client, 15 plugins, 14 adapters. Full docs at [silgi.dev](https://silgi.dev).
 
+## Install
+
+```bash
+pnpm add silgi
+# or: npm install silgi / yarn add silgi / bun add silgi
+```
+
+Requires Node.js `>=24`.
+
+## Minimal example
+
+```ts
+import { silgi } from 'silgi'
+
+const k = silgi({
+  context: (req) => ({ now: Date.now() }),
+})
+
+const hello = k.$resolve(({ ctx }) => ({ message: 'hi', at: ctx.now }))
+
+const router = k.router({ hello })
+
+export default k.handler(router)
+```
+
+Export `handler` from any Fetch-compatible runtime (Next.js App Router,
+SvelteKit, Remix, Astro, SolidStart, Hono, srvx, Bun, Deno, Cloudflare
+Workers, AWS Lambda via the hono adapter, …). Dedicated adapters for
+Express, Nitro, NestJS, and Node's raw `http` live under
+`silgi/express`, `silgi/nextjs`, `silgi/sveltekit`, etc.
+
+Run a standalone server:
+
+```ts
+await k.serve(router, { port: 3000 })
+```
+
+## Documentation
+
+- **[silgi.dev](https://silgi.dev)** — user guide, recipes, API reference.
+- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — dev setup, commands, PR checklist.
+- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — request pipeline, module layout, performance invariants.
+- [`SECURITY.md`](./SECURITY.md) — threat model, reporting policy, security features.
+- [`docs/rfcs/0001-de-magic.md`](./docs/rfcs/0001-de-magic.md) — the
+  refactor that removed module-global mutable state, explicit schema
+  converter injection, and per-instance context bridges.
+
 ## Credits
 
 - [oRPC](https://github.com/unnoq/orpc) — Pipeline architecture, client proxy, error handling, contract-first workflow

package/dist/adapters/_fetch-adapter.d.mts

@@ -1,4 +1,6 @@
+import { SilgiHooks } from "../silgi.mjs";
 import { WrapHandlerOptions } from "../core/handler.mjs";
+import { Hookable } from "hookable";
 
 //#region src/adapters/_fetch-adapter.d.ts
 interface FetchAdapterConfig<TCtx extends Record<string, unknown>> extends WrapHandlerOptions {
@@ -6,6 +8,8 @@ interface FetchAdapterConfig<TCtx extends Record<string, unknown>> extends WrapH
   prefix?: string;
   /** Context factory — receives the Request (or framework event via eventMap). */
   context?: (req: Request) => TCtx | Promise<TCtx>;
+  /** Lifecycle hooks (request, response, error). */
+  hooks?: Hookable<SilgiHooks>;
 }
 /**
  * For adapters where the context factory needs access to a framework event
@@ -16,6 +20,8 @@ interface FetchAdapterConfigWithEvent<TCtx extends Record<string, unknown>, TEve
   prefix?: string;
   /** Context factory — receives the framework event, not raw Request. */
   context?: (event: TEvent) => TCtx | Promise<TCtx>;
+  /** Lifecycle hooks (request, response, error). */
+  hooks?: Hookable<SilgiHooks>;
 }
 //#endregion
 export { FetchAdapterConfig, FetchAdapterConfigWithEvent };

package/dist/adapters/_fetch-adapter.mjs

@@ -1,4 +1,5 @@
 import { createFetchHandler, wrapHandler } from "../core/handler.mjs";
+import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/adapters/_fetch-adapter.ts
 /**
 * Shared factory for fetch-passthrough adapters.
@@ -15,25 +16,30 @@ import { createFetchHandler, wrapHandler } from "../core/handler.mjs";
 */
 function createFetchAdapter(router, options, defaultPrefix) {
 	const prefix = options.prefix ?? defaultPrefix;
-	return wrapHandler(createFetchHandler(router, options.context ?? (() => ({})), void 0, prefix), router, options, prefix);
+	return wrapHandler(createFetchHandler(router, options.context ?? (() => ({})), options.hooks, prefix), router, options, prefix);
 }
 /**
 * Create a fetch-passthrough adapter for frameworks that pass an event object
 * with a `.request` property (SvelteKit, SolidStart).
-* Uses a WeakMap to safely pass the event into the context factory per-request.
+*
+* Propagates the framework event to the context factory via a per-adapter
+* AsyncLocalStorage scope, so the lookup rides the async call chain instead
+* of Request object identity. Middleware that clones or replaces the Request
+* (body reads, URL rewrites, polyfills) no longer breaks context resolution.
+*
+* Resolves: https://github.com/productdevbook/silgi/issues/4
 */
 function createEventFetchAdapter(router, options, defaultPrefix, extractRequest) {
 	const prefix = options.prefix ?? defaultPrefix;
-	const requestEventMap = /* @__PURE__ */ new WeakMap();
+	const eventStore = new AsyncLocalStorage();
 	const handler = wrapHandler(createFetchHandler(router, (_req) => {
-		const eventRef = requestEventMap.get(_req);
-		if (options.context && eventRef) return options.context(eventRef);
+		const eventRef = eventStore.getStore();
+		if (options.context && eventRef !== void 0) return options.context(eventRef);
 		return {};
-	}, void 0, prefix), router, options, prefix);
+	}, options.hooks, prefix), router, options, prefix);
 	return (event) => {
 		const request = extractRequest(event);
-		requestEventMap.set(request, event);
-		return handler(request);
+		return eventStore.run(event, () => handler(request));
 	};
 }
 //#endregion

package/dist/adapters/astro.mjs

@@ -11,7 +11,7 @@ import { createFetchAdapter } from "./_fetch-adapter.mjs";
 *
 * const handler = createHandler(appRouter, {
 *   context: (req) => ({ db: getDB() }),
-*   analytics: true,
+*   analytics: { auth: "your-secret-token" },
 * })
 *
 * export const GET = handler

package/dist/adapters/nextjs.mjs

@@ -11,7 +11,7 @@ import { createFetchAdapter } from "./_fetch-adapter.mjs";
 *
 * const handler = createHandler(appRouter, {
 *   context: (req) => ({ db: getDB() }),
-*   analytics: true,
+*   analytics: { auth: "your-secret-token" },
 * })
 *
 * export { handler as GET, handler as POST }

package/dist/adapters/remix.mjs

@@ -11,7 +11,7 @@ import { createFetchAdapter } from "./_fetch-adapter.mjs";
 *
 * const handler = createHandler(appRouter, {
 *   context: (req) => ({ db: getDB() }),
-*   analytics: true,
+*   analytics: { auth: "your-secret-token" },
 * })
 *
 * export const action = handler

package/dist/adapters/solidstart.mjs

@@ -11,7 +11,7 @@ import { createEventFetchAdapter } from "./_fetch-adapter.mjs";
 *
 * const handler = createHandler(appRouter, {
 *   context: (event) => ({ db: getDB() }),
-*   analytics: true,
+*   analytics: { auth: "your-secret-token" },
 * })
 *
 * export const GET = handler

package/dist/adapters/sveltekit.mjs

@@ -11,7 +11,7 @@ import { createEventFetchAdapter } from "./_fetch-adapter.mjs";
 *
 * const handler = createHandler(appRouter, {
 *   context: (event) => ({ db: getDB(), user: event.locals.user }),
-*   analytics: true,
+*   analytics: { auth: "your-secret-token" },
 * })
 *
 * export const GET = handler

package/dist/client/client.d.mts

@@ -4,11 +4,35 @@ import { ClientContext, ClientLink } from "./types.mjs";
 
 //#region src/client/client.d.ts
 /**
- * Create a type-safe client from a link.
+ * Create a type-safe client from a transport-level {@link ClientLink}.
  *
+ * @remarks
+ * The returned value is a `Proxy` that mirrors the shape of your server
+ * router at the type level. Nested property access builds a dotted
+ * procedure path; calling the terminal proxy invokes the link with
+ * `(path, input, options)`.
+ *
+ * Sub-proxies are cached in a `Map` on first access so repeated lookups
+ * on the same branch do not re-allocate a new proxy tree.
+ *
+ * @typeParam T - The inferred server router type (usually
+ *   `typeof appRouter`).
+ * @typeParam TClientContext - Extra per-call context carried through
+ *   `ClientOptions` (e.g. an abort signal, a request id).
+ * @param link - A transport link (fetch, ofetch, websocket, custom).
+ * @returns A typed client whose shape matches `T`.
+ *
+ * @example
  * ```ts
- * const client = createClient<typeof appRouter>(link)
+ * import { createClient, createFetchLink } from 'silgi/client'
+ *
+ * const client = createClient<typeof appRouter>(
+ *   createFetchLink({ url: 'https://api.example.com' }),
+ * )
+ * const users = await client.users.list({ limit: 10 })
  * ```
+ *
+ * @see {@link createSafeClient} for a `[error, data]` variant.
  */
 declare function createClient<T, TClientContext extends ClientContext = Record<never, never>>(link: ClientLink<TClientContext>): InferClient<T>;
 /**
@@ -22,12 +46,26 @@ interface SafeResult<TOutput, TError> {
 }
 declare function safe<TOutput, TError = unknown>(promise: Promise<TOutput>): Promise<SafeResult<TOutput, TError>>;
 /**
- * Create a safe client — every procedure call returns { error, data } instead of throwing.
+ * Create a safe client — every procedure call returns a {@link SafeResult}
+ * tuple instead of throwing.
+ *
+ * @remarks
+ * Useful when the caller prefers discriminated-union error handling over
+ * `try`/`catch`. The underlying transport is unchanged; errors are
+ * caught by {@link safe} and surfaced as `{ error, data, isError,
+ * isSuccess }`.
+ *
+ * @typeParam T - The inferred server router type.
+ * @typeParam TClientContext - Extra per-call context.
+ * @param link - A transport link.
+ * @returns A client whose every procedure yields a
+ *   `Promise<SafeResult<Output, SilgiError>>`.
  *
+ * @example
  * ```ts
  * const safeClient = createSafeClient<typeof appRouter>(link)
  * const { error, data } = await safeClient.users.list()
- * if (error) console.error(error)
+ * if (error) console.error(error.code, error.status)
  * ```
  */
 declare function createSafeClient<T, TClientContext extends ClientContext = Record<never, never>>(link: ClientLink<TClientContext>): InferSafeClient<T>;

package/dist/client/client.mjs

@@ -1,10 +1,34 @@
 //#region src/client/client.ts
 /**
-* Create a type-safe client from a link.
+* Create a type-safe client from a transport-level {@link ClientLink}.
 *
+* @remarks
+* The returned value is a `Proxy` that mirrors the shape of your server
+* router at the type level. Nested property access builds a dotted
+* procedure path; calling the terminal proxy invokes the link with
+* `(path, input, options)`.
+*
+* Sub-proxies are cached in a `Map` on first access so repeated lookups
+* on the same branch do not re-allocate a new proxy tree.
+*
+* @typeParam T - The inferred server router type (usually
+*   `typeof appRouter`).
+* @typeParam TClientContext - Extra per-call context carried through
+*   `ClientOptions` (e.g. an abort signal, a request id).
+* @param link - A transport link (fetch, ofetch, websocket, custom).
+* @returns A typed client whose shape matches `T`.
+*
+* @example
 * ```ts
-* const client = createClient<typeof appRouter>(link)
+* import { createClient, createFetchLink } from 'silgi/client'
+*
+* const client = createClient<typeof appRouter>(
+*   createFetchLink({ url: 'https://api.example.com' }),
+* )
+* const users = await client.users.list({ limit: 10 })
 * ```
+*
+* @see {@link createSafeClient} for a `[error, data]` variant.
 */
 function createClient(link) {
 	return createClientProxy(link, []);
@@ -46,12 +70,26 @@ async function safe(promise) {
 	}
 }
 /**
-* Create a safe client — every procedure call returns { error, data } instead of throwing.
+* Create a safe client — every procedure call returns a {@link SafeResult}
+* tuple instead of throwing.
+*
+* @remarks
+* Useful when the caller prefers discriminated-union error handling over
+* `try`/`catch`. The underlying transport is unchanged; errors are
+* caught by {@link safe} and surfaced as `{ error, data, isError,
+* isSuccess }`.
+*
+* @typeParam T - The inferred server router type.
+* @typeParam TClientContext - Extra per-call context.
+* @param link - A transport link.
+* @returns A client whose every procedure yields a
+*   `Promise<SafeResult<Output, SilgiError>>`.
 *
+* @example
 * ```ts
 * const safeClient = createSafeClient<typeof appRouter>(link)
 * const { error, data } = await safeClient.users.list()
-* if (error) console.error(error)
+* if (error) console.error(error.code, error.status)
 * ```
 */
 function createSafeClient(link) {

package/dist/client/server.d.mts

@@ -8,8 +8,33 @@ interface ServerClientOptions<TCtx extends Record<string, unknown>> {
 /**
  * Create a type-safe client that calls procedures directly in-process.
  *
- * No HTTP, no serialization, no network — just compiled pipeline execution.
- * Uses the same compiled handlers as serve() and handler().
+ * @remarks
+ * No HTTP, no serialization, no network — the client resolves
+ * procedures through the same compiled pipeline as `handler()` and
+ * `serve()`. Intended for SSR, server components, and tests where the
+ * typed client interface is convenient but a network round-trip is not.
+ *
+ * Note that this helper is a thin proxy over `compileRouter`; it does
+ * not run through `silgi.runInContext`, so integrations that read
+ * `silgi.currentContext()` should call `silgi.runInContext` around the
+ * invocation or use `silgi.createCaller()` instead.
+ *
+ * @typeParam TRouter - The router type (usually `typeof appRouter`).
+ * @typeParam TCtx - The context shape returned by `options.context`.
+ * @param router - The router definition to call into.
+ * @param options - Server-client configuration; must include a
+ *   `context` factory.
+ * @returns A typed client mirroring `TRouter`.
+ *
+ * @example
+ * ```ts
+ * import { createServerClient } from 'silgi/client/server'
+ *
+ * const client = createServerClient(appRouter, {
+ *   context: () => ({ db: getDB() }),
+ * })
+ * const users = await client.users.list({ limit: 10 })
+ * ```
  */
 declare function createServerClient<TRouter extends RouterDef, TCtx extends Record<string, unknown>>(router: TRouter, options: ServerClientOptions<TCtx>): InferClient<TRouter>;
 //#endregion

package/dist/client/server.mjs

@@ -21,8 +21,33 @@ import { compileRouter } from "../compile.mjs";
 /**
 * Create a type-safe client that calls procedures directly in-process.
 *
-* No HTTP, no serialization, no network — just compiled pipeline execution.
-* Uses the same compiled handlers as serve() and handler().
+* @remarks
+* No HTTP, no serialization, no network — the client resolves
+* procedures through the same compiled pipeline as `handler()` and
+* `serve()`. Intended for SSR, server components, and tests where the
+* typed client interface is convenient but a network round-trip is not.
+*
+* Note that this helper is a thin proxy over `compileRouter`; it does
+* not run through `silgi.runInContext`, so integrations that read
+* `silgi.currentContext()` should call `silgi.runInContext` around the
+* invocation or use `silgi.createCaller()` instead.
+*
+* @typeParam TRouter - The router type (usually `typeof appRouter`).
+* @typeParam TCtx - The context shape returned by `options.context`.
+* @param router - The router definition to call into.
+* @param options - Server-client configuration; must include a
+*   `context` factory.
+* @returns A typed client mirroring `TRouter`.
+*
+* @example
+* ```ts
+* import { createServerClient } from 'silgi/client/server'
+*
+* const client = createServerClient(appRouter, {
+*   context: () => ({ db: getDB() }),
+* })
+* const users = await client.users.list({ limit: 10 })
+* ```
 */
 function createServerClient(router, options) {
 	return createServerProxy(compileRouter(router), options.context, []);

package/dist/compile.d.mts

@@ -38,7 +38,16 @@ type CompiledRouterFn = (method: string, path: string) => MatchedRoute<CompiledR
  * Powered by rou3 (unjs) — battle-tested, fast, minimal.
  */
 declare function compileRouter(def: Record<string, unknown>): CompiledRouterFn;
+/**
+ * Pooled context with built-in `using` support. `Symbol.dispose` calls
+ * `releaseContext` unless ownership has been transferred elsewhere
+ * (e.g. to a streaming Response) — in that case the new owner is
+ * expected to call `releaseContext` when the stream ends.
+ *
+ * Transfer ownership by calling `detachContext(ctx)` before returning.
+ */
+type PooledContext = Record<string, unknown> & Disposable;
 /** Acquire a context object from the pool (or create one). */
-declare function createContext(): Record<string, unknown>;
+declare function createContext(): PooledContext;
 //#endregion
 export { compileProcedure, compileRouter, createContext };

package/dist/compile.mjs

@@ -1,6 +1,7 @@
 import { validateSchema } from "./core/schema.mjs";
 import { SilgiError } from "./core/error.mjs";
 import { isProcedureDef } from "./core/router-utils.mjs";
+import { RAW_INPUT } from "./core/ctx-symbols.mjs";
 import { addRoute, createRouter, findRoute } from "rou3";
 //#region src/compile.ts
 /**
@@ -10,8 +11,6 @@ import { addRoute, createRouter, findRoute } from "rou3";
 * 2. ZERO-ALLOC CONTEXT — Object.create(null) + pool reuse
 * 3. ROU3 ROUTER — unjs radix tree (same as h3/nitro)
 */
-/** Internal symbol for pipeline raw input — prevents collision with user context keys */
-const RAW_INPUT = Symbol.for("silgi.rawInput");
 function isThenable(value) {
 	return value !== null && typeof value === "object" && typeof value.then === "function";
 }
@@ -319,8 +318,18 @@ const CTX_POOL = [];
 const CTX_POOL_MAX = 128;
 /** Acquire a context object from the pool (or create one). */
 function createContext() {
-	return CTX_POOL.length > 0 ? CTX_POOL.pop() : Object.create(null);
+	const ctx = CTX_POOL.length > 0 ? CTX_POOL.pop() : Object.create(null);
+	ctx[Symbol.dispose] = disposeContext;
+	return ctx;
 }
+/** Mark the context as owned elsewhere so `using` won't release it. */
+function detachContext(ctx) {
+	ctx[Symbol.dispose] = noopDispose;
+}
+function disposeContext() {
+	releaseContext(this);
+}
+function noopDispose() {}
 /** Return a context object to the pool after request completes. */
 function releaseContext(ctx) {
 	for (const key of Object.keys(ctx)) delete ctx[key];
@@ -328,4 +337,4 @@ function releaseContext(ctx) {
 	if (CTX_POOL.length < CTX_POOL_MAX) CTX_POOL.push(ctx);
 }
 //#endregion
-export { RAW_INPUT, compileProcedure, compileRouter, createContext, releaseContext };
+export { compileProcedure, compileRouter, createContext, detachContext, releaseContext };

package/dist/core/context-bridge.d.mts

@@ -0,0 +1,49 @@
+//#region src/core/context-bridge.d.ts
+/**
+ * Per-instance context bridge built on `AsyncLocalStorage`.
+ *
+ * @remarks
+ * Each silgi instance owns its own bridge, preventing context bleed
+ * between multiple `silgi()` instances in the same process. The bridge
+ * is created lazily in `silgi()` and exposed on the instance as
+ * {@link SilgiInstance.runInContext} / {@link SilgiInstance.currentContext}.
+ *
+ * The top-level `getCtx` / `runWithCtx` free functions that previously
+ * lived in this module have been removed — they were module-global and
+ * silently shared state across instances.
+ *
+ * @category Context
+ */
+/**
+ * Wraps an `AsyncLocalStorage` with a small typed surface. Call
+ * {@link createContextBridge} to construct one.
+ *
+ * @typeParam TCtx - Context shape stored in the bridge.
+ * @category Context
+ */
+interface ContextBridge<TCtx extends Record<string, unknown> = Record<string, unknown>> {
+  /** Execute `fn` with `ctx` installed on the current async scope. */
+  run<T>(ctx: TCtx, fn: () => T): T;
+  /** Read the context installed by the nearest enclosing `run()` call, or `undefined`. */
+  current(): TCtx | undefined;
+}
+/**
+ * Create a fresh {@link ContextBridge}. Each silgi instance calls this
+ * once internally; integrations that need their own ambient scope (e.g.
+ * for programmatic `withCtx()` helpers) can also call it.
+ *
+ * @typeParam TCtx - Context shape to store.
+ *
+ * @example
+ * ```ts
+ * const bridge = createContextBridge<{ userId: string }>()
+ * bridge.run({ userId: 'u_1' }, () => {
+ *   bridge.current()?.userId // 'u_1'
+ * })
+ * ```
+ *
+ * @category Context
+ */
+declare function createContextBridge<TCtx extends Record<string, unknown> = Record<string, unknown>>(): ContextBridge<TCtx>;
+//#endregion
+export { ContextBridge, createContextBridge };

package/dist/core/context-bridge.mjs

@@ -1,11 +1,47 @@
 import { AsyncLocalStorage } from "node:async_hooks";
 //#region src/core/context-bridge.ts
-const ctxStorage = new AsyncLocalStorage();
-function runWithCtx(ctx, fn) {
-	return ctxStorage.run(ctx, fn);
-}
-function getCtx() {
-	return ctxStorage.getStore();
+/**
+* Per-instance context bridge built on `AsyncLocalStorage`.
+*
+* @remarks
+* Each silgi instance owns its own bridge, preventing context bleed
+* between multiple `silgi()` instances in the same process. The bridge
+* is created lazily in `silgi()` and exposed on the instance as
+* {@link SilgiInstance.runInContext} / {@link SilgiInstance.currentContext}.
+*
+* The top-level `getCtx` / `runWithCtx` free functions that previously
+* lived in this module have been removed — they were module-global and
+* silently shared state across instances.
+*
+* @category Context
+*/
+/**
+* Create a fresh {@link ContextBridge}. Each silgi instance calls this
+* once internally; integrations that need their own ambient scope (e.g.
+* for programmatic `withCtx()` helpers) can also call it.
+*
+* @typeParam TCtx - Context shape to store.
+*
+* @example
+* ```ts
+* const bridge = createContextBridge<{ userId: string }>()
+* bridge.run({ userId: 'u_1' }, () => {
+*   bridge.current()?.userId // 'u_1'
+* })
+* ```
+*
+* @category Context
+*/
+function createContextBridge() {
+	const storage = new AsyncLocalStorage();
+	return {
+		run(ctx, fn) {
+			return storage.run(ctx, fn);
+		},
+		current() {
+			return storage.getStore();
+		}
+	};
 }
 //#endregion
-export { getCtx, runWithCtx };
+export { createContextBridge };

package/dist/core/context.d.mts

@@ -0,0 +1,26 @@
+import { RequestTrace } from "../plugins/analytics/trace.mjs";
+//#region src/core/context.d.ts
+/**
+ * Fields that Silgi internals may place on every request's `ctx`.
+ *
+ * @remarks
+ * All fields are optional — they appear only when the relevant framework
+ * feature is active (e.g. `trace` only when analytics is enabled;
+ * `params` only when the matched route has URL parameters). Users extend
+ * their own context via the `context` factory passed to `silgi()`.
+ *
+ * At runtime the pipeline still treats `ctx` as a loose
+ * `Record<string, unknown>`; this interface exists so contributors and
+ * TypeScript users can see which keys are framework-reserved without
+ * grepping the codebase.
+ *
+ * @category Context
+ */
+interface BaseContext {
+  /** URL path parameters from the matched route, when present. */
+  params?: Record<string, string>;
+  /** Per-request analytics trace, attached by the analytics plugin. */
+  trace?: RequestTrace;
+}
+//#endregion
+export { BaseContext };

package/dist/core/ctx-symbols.mjs

@@ -0,0 +1,21 @@
+//#region src/core/ctx-symbols.ts
+/**
+* Framework-internal symbol keys for the shared pipeline context.
+*
+* @internal
+*
+* @remarks
+* These keys are reserved by Silgi internals and MUST NOT be used as
+* ordinary fields in user context objects. Centralizing them in one
+* module makes the reserved surface trivial to audit — there is nowhere
+* else in the codebase where silgi stamps a symbol key onto `ctx`.
+*/
+/**
+* Pipeline raw-input slot. The wrap onion reads the input off this slot
+* so middleware (e.g. `mapInput`) can rewrite it before the resolver runs.
+*
+* @internal
+*/
+const RAW_INPUT = Symbol.for("silgi.rawInput");
+//#endregion
+export { RAW_INPUT };