silgi 0.52.2 → 0.53.1

package/dist/compile.mjs

@@ -1,15 +1,34 @@
 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 { RAW_INPUT, ROOT_WRAPS } from "./core/ctx-symbols.mjs";
 import { addRoute, createRouter, findRoute } from "rou3";
 //#region src/compile.ts
 /**
-* Pipeline Compiler — guard unrolling, context pooling, rou3 routing.
+* Pipeline Compiler
+* ------------------
 *
-* 1. UNROLLED GUARDS — 0-4 guard specialization (no loop, V8 inlines)
-* 2. ZERO-ALLOC CONTEXT — Object.create(null) + pool reuse
-* 3. ROU3 ROUTER — unjs radix tree (same as h3/nitro)
+* Turns a user-authored procedure (input schema, guards, wraps,
+* resolver, output schema) into a single handler that the adapters
+* call once per request:
+*
+*     (ctx, rawInput, signal) => output | Promise<output>
+*
+* The pipeline order is:
+*
+*   1. Guards — pre-steps that may mutate `ctx` or throw.
+*   2. Input validation — via Standard Schema if `input` is set.
+*   3. Wraps — onion middleware around the resolver (root wraps first).
+*   4. Resolver — user's business logic.
+*   5. Output validation — via Standard Schema if `output` is set.
+*
+* Everything that can be decided up-front (the merged error map, the
+* guard/wrap lists, whether validation exists) is closed over at
+* compile time so the per-request path stays small.
+*
+* Router compilation lives in `compileRouter`. It walks the nested
+* router def, compiles each procedure, and registers it in a rou3
+* radix tree.
 */
 function isThenable(value) {
 	return value !== null && typeof value === "object" && typeof value.then === "function";
@@ -31,14 +50,30 @@ function noopFail(code, data) {
 		defined: false
 	});
 }
+/**
+* Keys forbidden anywhere in a guard's return value. Blocking them at
+* every level keeps `ctx` (a plain object) safe from attacker-supplied
+* payloads that could otherwise reach `Object.prototype`.
+*/
 const UNSAFE_KEYS = /* @__PURE__ */ new Set([
 	"__proto__",
 	"constructor",
 	"prototype"
 ]);
-/** Pre-frozen empty params — avoids per-request {} allocation */
+/** Shared frozen empty params object. Read only, never mutated. */
 const EMPTY_PARAMS = /* @__PURE__ */ Object.freeze(Object.create(null));
-/** Sanitize a value to prevent prototype pollution from nested __proto__ keys */
+/**
+* Recursively scrub a value produced by a guard so it cannot reach
+* `Object.prototype` through nested `__proto__` / `constructor` /
+* `prototype` keys.
+*
+* Arrays are scrubbed in place (they cannot be prototype-polluted
+* themselves, but their elements might). Class instances are left
+* alone — they already have a non-literal prototype, so merging them
+* into `ctx` does not mutate `Object.prototype`. Plain objects get a
+* shallow rebuild when they carry a forbidden key, otherwise their
+* values are scrubbed in place.
+*/
 function sanitizeValue(value) {
 	if (typeof value !== "object" || value === null) return value;
 	if (Array.isArray(value)) {
@@ -50,131 +85,71 @@ function sanitizeValue(value) {
 	const obj = value;
 	if (Object.prototype.hasOwnProperty.call(obj, "__proto__")) {
 		const clean = Object.create(null);
-		const keys = Object.keys(obj);
-		for (let i = 0; i < keys.length; i++) {
-			const k = keys[i];
-			if (!UNSAFE_KEYS.has(k)) clean[k] = sanitizeValue(obj[k]);
-		}
+		for (const key of Object.keys(obj)) if (!UNSAFE_KEYS.has(key)) clean[key] = sanitizeValue(obj[key]);
 		return clean;
 	}
-	const keys = Object.keys(obj);
-	for (let i = 0; i < keys.length; i++) {
-		const k = keys[i];
-		obj[k] = sanitizeValue(obj[k]);
-	}
+	for (const key of Object.keys(obj)) obj[key] = sanitizeValue(obj[key]);
 	return value;
 }
-/** Apply a single guard result to context — direct property set */
+/**
+* Merge a single guard's return value into the live context. Guards
+* typically return a partial patch (e.g. `{ user }`); returning
+* nothing is fine and is how guards that only validate are expressed.
+*/
 function applyGuardResult(ctx, result) {
 	if (result === null || result === void 0 || typeof result !== "object") return;
-	const keys = Object.keys(result);
-	for (let i = 0; i < keys.length; i++) {
-		const k = keys[i];
-		if (UNSAFE_KEYS.has(k)) continue;
-		ctx[k] = sanitizeValue(result[k]);
+	for (const key of Object.keys(result)) {
+		if (UNSAFE_KEYS.has(key)) continue;
+		ctx[key] = sanitizeValue(result[key]);
 	}
 }
-/** Apply a single guard (sync fast-path, async fallback) */
-async function applyGuard(ctx, guard) {
-	const result = guard.fn(ctx);
-	applyGuardResult(ctx, isThenable(result) ? await result : result);
-}
-function runGuards0() {}
-function runGuards1(ctx, g0) {
-	const r0 = g0.fn(ctx);
-	if (isThenable(r0)) return r0.then((v) => applyGuardResult(ctx, v));
-	applyGuardResult(ctx, r0);
-}
-function runGuards2(ctx, g0, g1) {
-	const r0 = g0.fn(ctx);
-	if (isThenable(r0)) return r0.then((v) => {
-		applyGuardResult(ctx, v);
-		return applyGuard(ctx, g1);
-	});
-	applyGuardResult(ctx, r0);
-	const r1 = g1.fn(ctx);
-	if (isThenable(r1)) return r1.then((v) => applyGuardResult(ctx, v));
-	applyGuardResult(ctx, r1);
-}
-function runGuards3(ctx, g0, g1, g2) {
-	const r0 = g0.fn(ctx);
-	if (isThenable(r0)) return r0.then(async (v) => {
-		applyGuardResult(ctx, v);
-		await applyGuard(ctx, g1);
-		await applyGuard(ctx, g2);
-	});
-	applyGuardResult(ctx, r0);
-	const r1 = g1.fn(ctx);
-	if (isThenable(r1)) return r1.then(async (v) => {
-		applyGuardResult(ctx, v);
-		await applyGuard(ctx, g2);
-	});
-	applyGuardResult(ctx, r1);
-	const r2 = g2.fn(ctx);
-	if (isThenable(r2)) return r2.then((v) => applyGuardResult(ctx, v));
-	applyGuardResult(ctx, r2);
-}
-function runGuards4(ctx, g0, g1, g2, g3) {
-	const r0 = g0.fn(ctx);
-	if (isThenable(r0)) return r0.then(async (v) => {
-		applyGuardResult(ctx, v);
-		await applyGuard(ctx, g1);
-		await applyGuard(ctx, g2);
-		await applyGuard(ctx, g3);
-	});
-	applyGuardResult(ctx, r0);
-	const r1 = g1.fn(ctx);
-	if (isThenable(r1)) return r1.then(async (v) => {
-		applyGuardResult(ctx, v);
-		await applyGuard(ctx, g2);
-		await applyGuard(ctx, g3);
-	});
-	applyGuardResult(ctx, r1);
-	const r2 = g2.fn(ctx);
-	if (isThenable(r2)) return r2.then(async (v) => {
-		applyGuardResult(ctx, v);
-		await applyGuard(ctx, g3);
-	});
-	applyGuardResult(ctx, r2);
-	const r3 = g3.fn(ctx);
-	if (isThenable(r3)) return r3.then((v) => applyGuardResult(ctx, v));
-	applyGuardResult(ctx, r3);
+/**
+* Run every guard in order, applying each result to `ctx` before the
+* next guard runs.
+*
+* Sync-first: when a guard returns synchronously we stay on the sync
+* path — only the first guard that returns a `Promise` forces us onto
+* the async branch. That keeps the common case of all-sync guards from
+* allocating a Promise at all.
+*
+* Empty-guards path is short-circuited at the call site (the returned
+* runner is `undefined` when `guards.length === 0`).
+*/
+function runGuardsSequential(ctx, guards) {
+	for (let i = 0; i < guards.length; i++) {
+		const result = guards[i].fn(ctx);
+		if (isThenable(result)) return finishGuardsAsync(ctx, guards, i, result);
+		applyGuardResult(ctx, result);
+	}
 }
-/** Fallback for 5+ guards — loop */
-async function runGuardsN(ctx, guards) {
-	for (const guard of guards) {
-		const result = guard.fn(ctx);
+/**
+* Complete the guard chain on the async branch once a guard returned a
+* `Promise`. The remaining guards are awaited in order so their results
+* land on `ctx` in the same order a sync run would have produced.
+*/
+async function finishGuardsAsync(ctx, guards, resumeIndex, firstPromise) {
+	applyGuardResult(ctx, await firstPromise);
+	for (let i = resumeIndex + 1; i < guards.length; i++) {
+		const result = guards[i].fn(ctx);
 		applyGuardResult(ctx, isThenable(result) ? await result : result);
 	}
 }
 /**
-* Select the optimal guard runner based on count.
-* Returns a function that applies all guards to a context.
+* Pre-bind the guard list to a runner. Returning `undefined` for the
+* zero-guard case means the call site can skip the call entirely with
+* a cheap null check.
 */
 function selectGuardRunner(guards) {
-	switch (guards.length) {
-		case 0: return runGuards0;
-		case 1: {
-			const g0 = guards[0];
-			return (ctx) => runGuards1(ctx, g0);
-		}
-		case 2: {
-			const [g0, g1] = guards;
-			return (ctx) => runGuards2(ctx, g0, g1);
-		}
-		case 3: {
-			const [g0, g1, g2] = guards;
-			return (ctx) => runGuards3(ctx, g0, g1, g2);
-		}
-		case 4: {
-			const [g0, g1, g2, g3] = guards;
-			return (ctx) => runGuards4(ctx, g0, g1, g2, g3);
-		}
-		default: return (ctx) => runGuardsN(ctx, guards);
-	}
+	if (guards.length === 0) return void 0;
+	return (ctx) => runGuardsSequential(ctx, guards);
 }
 /** Call resolve, then validate output (sync-first, async fallback) */
-function _resolveWithOutput(resolveFn, input, ctx, failFn, signal, outputSchema) {
+/**
+* Call the resolver, then validate the output. Stays sync when the
+* resolver is sync and there is no output schema; switches to
+* `.then()` chaining only once an async boundary appears.
+*/
+function resolveWithOutput(resolveFn, input, ctx, failFn, signal, outputSchema) {
 	const output = resolveFn({
 		input,
 		ctx,
@@ -186,14 +161,19 @@ function _resolveWithOutput(resolveFn, input, ctx, failFn, signal, outputSchema)
 	if (isThenable(output)) return output.then((o) => validateSchema(outputSchema, o));
 	return validateSchema(outputSchema, output);
 }
-/** Validate input, resolve, validate output — sync-first with rejected Promise fallback.
-*  All sync throws (validation errors, fail() calls, resolver errors) are converted
-*  to rejected Promises for consistent error handling in .then().catch() chains. */
-function _validateAndResolve(inputSchema, outputSchema, resolveFn, rawInput, ctx, failFn, signal) {
+/**
+* Validate input, call the resolver, validate output.
+*
+* Everything that throws synchronously (input validation errors,
+* `fail()` calls inside the resolver, the resolver itself) is turned
+* into a rejected `Promise` so callers can rely on a single
+* `.then().catch()` chain no matter which branch the pipeline took.
+*/
+function validateAndResolve(inputSchema, outputSchema, resolveFn, rawInput, ctx, failFn, signal) {
 	try {
 		const input = inputSchema ? validateSchema(inputSchema, rawInput ?? {}) : rawInput;
-		if (isThenable(input)) return input.then((resolvedInput) => _resolveWithOutput(resolveFn, resolvedInput, ctx, failFn, signal, outputSchema));
-		return _resolveWithOutput(resolveFn, input, ctx, failFn, signal, outputSchema);
+		if (isThenable(input)) return input.then((resolvedInput) => resolveWithOutput(resolveFn, resolvedInput, ctx, failFn, signal, outputSchema));
+		return resolveWithOutput(resolveFn, input, ctx, failFn, signal, outputSchema);
 	} catch (e) {
 		return Promise.reject(e);
 	}
@@ -207,12 +187,14 @@ function _validateAndResolve(inputSchema, outputSchema, resolveFn, rawInput, ctx
 * - Pre-computed fail function (singleton per procedure)
 * - Sync fast path when all guards are sync
 */
-function compileProcedure(procedure) {
+function compileProcedure(procedure, rootWraps) {
 	const middlewares = procedure.use ?? [];
 	const guards = [];
-	const wraps = [];
+	const procedureWraps = [];
 	for (const mw of middlewares) if (mw.kind === "guard") guards.push(mw);
-	else wraps.push(mw);
+	else procedureWraps.push(mw);
+	const rootWrapList = rootWraps && rootWraps.length > 0 ? rootWraps : EMPTY_WRAPS;
+	const hasRootWraps = rootWrapList.length > 0;
 	const inputSchema = procedure.input;
 	const outputSchema = procedure.output;
 	const resolveFn = procedure.resolve;
@@ -223,9 +205,10 @@ function compileProcedure(procedure) {
 	} : guard.errors;
 	const failFn = mergedErrors ? createFail(mergedErrors) : noopFail;
 	const runGuards = selectGuardRunner(guards);
-	if (wraps.length === 0 && !inputSchema && !outputSchema) return (ctx, rawInput, signal) => {
+	let innerHandler;
+	if (procedureWraps.length === 0 && !inputSchema && !outputSchema) innerHandler = (ctx, rawInput, signal) => {
 		try {
-			const guardResult = runGuards(ctx);
+			const guardResult = runGuards?.(ctx);
 			if (guardResult && isThenable(guardResult)) return guardResult.then(() => resolveFn({
 				input: rawInput,
 				ctx,
@@ -244,17 +227,17 @@ function compileProcedure(procedure) {
 			return Promise.reject(e);
 		}
 	};
-	if (wraps.length === 0) return (ctx, rawInput, signal) => {
+	else if (procedureWraps.length === 0) innerHandler = (ctx, rawInput, signal) => {
 		try {
-			const guardResult = runGuards(ctx);
-			if (guardResult && isThenable(guardResult)) return guardResult.then(() => _validateAndResolve(inputSchema, outputSchema, resolveFn, rawInput, ctx, failFn, signal));
-			return _validateAndResolve(inputSchema, outputSchema, resolveFn, rawInput, ctx, failFn, signal);
+			const guardResult = runGuards?.(ctx);
+			if (guardResult && isThenable(guardResult)) return guardResult.then(() => validateAndResolve(inputSchema, outputSchema, resolveFn, rawInput, ctx, failFn, signal));
+			return validateAndResolve(inputSchema, outputSchema, resolveFn, rawInput, ctx, failFn, signal);
 		} catch (e) {
 			return Promise.reject(e);
 		}
 	};
-	return async (ctx, rawInput, signal) => {
-		const guardResult = runGuards(ctx);
+	else innerHandler = async (ctx, rawInput, signal) => {
+		const guardResult = runGuards?.(ctx);
 		if (guardResult && isThenable(guardResult)) await guardResult;
 		let input;
 		if (inputSchema) {
@@ -272,8 +255,8 @@ function compileProcedure(procedure) {
 				params: ctx.params ?? EMPTY_PARAMS
 			}));
 		};
-		for (let i = wraps.length - 1; i >= 0; i--) {
-			const wrapFn = wraps[i].fn;
+		for (let i = procedureWraps.length - 1; i >= 0; i--) {
+			const wrapFn = procedureWraps[i].fn;
 			const next = execute;
 			execute = () => wrapFn(ctx, next);
 		}
@@ -282,7 +265,19 @@ function compileProcedure(procedure) {
 		const validated = validateSchema(outputSchema, output);
 		return isThenable(validated) ? await validated : validated;
 	};
+	if (!hasRootWraps) return innerHandler;
+	return async (ctx, rawInput, signal) => {
+		let execute = async () => innerHandler(ctx, rawInput, signal);
+		for (let i = rootWrapList.length - 1; i >= 0; i--) {
+			const wrapFn = rootWrapList[i].fn;
+			const next = execute;
+			execute = () => Promise.resolve(wrapFn(ctx, next));
+		}
+		return execute();
+	};
 }
+/** Shared empty array for the "no root wraps" case — avoids per-call allocation. */
+const EMPTY_WRAPS = /* @__PURE__ */ Object.freeze([]);
 /**
 * Compile a router tree into a rou3 radix router.
 *
@@ -290,6 +285,7 @@ function compileProcedure(procedure) {
 */
 function compileRouter(def) {
 	const router = createRouter();
+	const rootWraps = def[ROOT_WRAPS];
 	function walk(node, path) {
 		if (isProcedureDef(node)) {
 			const proc = node;
@@ -299,7 +295,7 @@ function compileRouter(def) {
 			let cacheControl;
 			if (route?.cache != null) cacheControl = typeof route.cache === "number" ? `public, max-age=${route.cache}` : route.cache;
 			const compiled = {
-				handler: compileProcedure(proc),
+				handler: compileProcedure(proc, rootWraps),
 				cacheControl,
 				passthrough: routePath.includes("**") || void 0,
 				method
@@ -313,28 +309,49 @@ function compileRouter(def) {
 	walk(def, []);
 	return (method, path) => findRoute(router, method, path);
 }
-/** Pool of pre-allocated null-prototype context objects — eliminates per-request GC pressure. */
+/**
+* Small pool of recyclable context objects.
+*
+* Each request allocates a context; rather than let every one become
+* GC pressure, released contexts with their properties wiped are
+* parked here and re-used on the next `createContext()` call. Capped
+* to prevent unbounded growth under burst traffic.
+*
+* Externally-visible: `test/core/context-release.test.ts` relies on
+* the recycling behaviour to verify that `releaseContext` runs
+* exactly once on every request exit path.
+*/
 const CTX_POOL = [];
 const CTX_POOL_MAX = 128;
-/** Acquire a context object from the pool (or create one). */
+/**
+* Acquire a context object — from the pool when one is available,
+* otherwise a fresh null-prototype object. Null-prototype keeps user
+* keys from colliding with `Object.prototype` members and avoids a
+* prototype-chain walk on every property lookup.
+*/
 function createContext() {
 	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. */
+/**
+* Release a context. Called automatically at `using` scope exit and
+* explicitly by stream handlers when their stream ends.
+*
+* With the pool gone the object itself will be GC'd as soon as its
+* last reference drops, but we still wipe its properties here.
+* Callers (and tests) use "properties were cleared" as the observable
+* signal that release ran exactly once — notably
+* `test/core/context-release.test.ts` tags a context before handing
+* it off and checks the tag is gone once the request completes.
+*/
 function releaseContext(ctx) {
 	for (const key of Object.keys(ctx)) delete ctx[key];
 	for (const sym of Object.getOwnPropertySymbols(ctx)) delete ctx[sym];
 	if (CTX_POOL.length < CTX_POOL_MAX) CTX_POOL.push(ctx);
 }
 //#endregion
-export { compileProcedure, compileRouter, createContext, detachContext, releaseContext };
+export { compileProcedure, compileRouter, createContext };

package/dist/core/ctx-symbols.mjs

@@ -17,5 +17,22 @@
 * @internal
 */
 const RAW_INPUT = Symbol.for("silgi.rawInput");
+/**
+* Brand stamped on a `RouterDef` by `silgi({ wraps }).router(def)` to carry
+* the instance's root wraps along with the def itself.
+*
+* @remarks
+* Every compile site (`silgi.router`, `createCaller`, `createFetchHandler`,
+* WS hooks, adapter `createHandler` variants) calls `compileRouter(def)`.
+* Reading the brand off `def` inside `compileRouter` means root wraps
+* reach every adapter without any per-adapter plumbing, without relying
+* on `routerCache`, and without a second tree walk.
+*
+* The brand is a non-enumerable own property on the user's def (Symbol
+* keys are skipped by `Object.entries`, so router traversal is unaffected).
+*
+* @internal
+*/
+const ROOT_WRAPS = Symbol.for("silgi.rootWraps");
 //#endregion
-export { RAW_INPUT };
+export { RAW_INPUT, ROOT_WRAPS };

package/dist/core/handler.d.mts

@@ -9,7 +9,7 @@ type FetchHandler = (request: Request) => Response | Promise<Response>;
 interface WrapHandlerOptions {
   analytics?: AnalyticsOptions;
   scalar?: boolean | ScalarOptions;
-  /** URL path prefix for the handler (e.g. "/api"). Requests not matching this prefix return 404. */
+  /** URL path prefix for the handler (e.g. `/api`). Requests outside the prefix return 404. */
   basePath?: string;
   /**
    * Schema registry for OpenAPI / analytics schema conversion. Built from
@@ -18,8 +18,8 @@ interface WrapHandlerOptions {
    */
   schemaRegistry?: SchemaRegistry;
   /**
-   * Hookable instance — threaded so `wrapWithAnalytics` can register
-   * lifecycle listeners on `request:prepare` / `response:finalize`.
+   * Hookable instance threaded through so `wrapWithAnalytics` can register
+   * listeners on `request:prepare` / `response:finalize`.
    * @internal
    */
   hooks?: Hookable<SilgiHooks>;