silgi 0.53.0 → 0.53.1

package/dist/builder.mjs

@@ -12,6 +12,25 @@ import { createTaskFromProcedure } from "./core/task.mjs";
 *   // ← autocomplete suggests id, title, body
 * ```
 */
+/**
+* A `ProcBuilder` plays two roles in its lifetime:
+*
+*   1. While the user is chaining methods it is a *builder* — each `$x()`
+*      mutates a slot and returns `this`.
+*   2. Once `$resolve()` is called, the *same instance* is returned typed
+*      as `ProcedureDef`. This works because `isProcedureDef` (see
+*      `core/router-utils.ts`) only checks for `type` and a callable
+*      `resolve`, both of which we now have.
+*
+* Using one object for both roles avoids copying the slots into a fresh
+* frozen record at the end — callers hold the object directly, so the
+* shape they see is the same object we wrote into.
+*
+* All slots default to `null` rather than an empty array / object so
+* that downstream code can branch on presence without caring about
+* length, and so that we do not allocate sentinels the user never ends
+* up needing.
+*/
 var ProcBuilder = class {
 	type;
 	input = null;
@@ -21,14 +40,21 @@ var ProcBuilder = class {
 	resolve = null;
 	route = null;
 	meta = null;
+	/**
+	* Underscore-prefixed slots are framework-internal. They are set by
+	* `createProcedureBuilder` when the builder is constructed through a
+	* `silgi({...})` instance and are threaded through to `$task()` so
+	* that background tasks share the instance's context factory and
+	* root wraps.
+	*/
 	_contextFactory = null;
 	_rootWrapsGetter = null;
 	constructor(type) {
 		this.type = type;
 	}
 	$use(...middleware) {
-		if (this.use) this.use.push(...middleware);
-		else this.use = [...middleware];
+		this.use ??= [];
+		this.use.push(...middleware);
 		return this;
 	}
 	$input(schema) {
@@ -63,10 +89,10 @@ var ProcBuilder = class {
 	}
 };
 function createProcedureBuilder(type, contextFactory, rootWrapsGetter) {
-	const b = new ProcBuilder(type);
-	if (contextFactory) b._contextFactory = contextFactory;
-	if (rootWrapsGetter) b._rootWrapsGetter = rootWrapsGetter;
-	return b;
+	const builder = new ProcBuilder(type);
+	if (contextFactory) builder._contextFactory = contextFactory;
+	if (rootWrapsGetter) builder._rootWrapsGetter = rootWrapsGetter;
+	return builder;
 }
 //#endregion
 export { createProcedureBuilder };

package/dist/caller.mjs

@@ -1,96 +1,106 @@
 import { routerCache } from "./core/router-utils.mjs";
-import { compileRouter, createContext, releaseContext } from "./compile.mjs";
+import { compileRouter } from "./compile.mjs";
 import { applyContext } from "./core/dispatch.mjs";
 //#region src/caller.ts
 /**
-* createCaller — call procedures directly without HTTP.
+* Direct caller
+* --------------
 *
-* Compiles the router, creates context, and runs the pipeline
-* for each procedure call. Perfect for testing and server-side usage.
+* `createCaller` returns a proxy that mirrors the router's nested shape.
+* Calling a leaf procedure invokes the compiled pipeline directly — no
+* HTTP, no body serialization, no response encoding. This is what tests
+* and server-side orchestration code use.
 *
 * @example
-* ```ts
-* const caller = s.createCaller(appRouter)
+*   const caller = s.createCaller(appRouter)
+*   const users = await caller.users.list({ limit: 10 })
+*   const user  = await caller.users.get({ id: 1 })
 *
-* // Call procedures directly
-* const users = await caller.users.list({ limit: 10 })
-* const user = await caller.users.get({ id: 1 })
-*
-* // With custom context override
-* const adminCaller = s.createCaller(appRouter, {
-*   contextOverride: { user: { id: 1, role: 'admin' } },
-* })
-* ```
+*   // Override the context for this caller (e.g. for admin tests):
+*   const admin = s.createCaller(appRouter, {
+*     contextOverride: { user: { id: 1, role: 'admin' } },
+*   })
 */
 /**
-* Never-aborting signal used when `timeout: null` is opted into and the
-* caller passes no per-call signal. Allocated once at module load; compiled
-* handlers can still `.addEventListener('abort', …)` safely — the listener
-* simply never fires.
+* Placeholder signal for callers that opt out of timeouts (`timeout: null`)
+* and do not pass their own signal. We still hand the pipeline a real
+* `AbortSignal` so that user code doing `signal.addEventListener('abort', …)`
+* does not crash on `undefined` — this signal just never fires.
 */
-const NEVER = new AbortController().signal;
+const NEVER_ABORTS = new AbortController().signal;
 /**
-* Create a direct caller for a router — no HTTP, no serialization.
+* Build a direct caller for a router.
 *
-* Returns a proxy that mirrors the router's nested structure.
-* Calling a leaf procedure invokes the compiled pipeline directly.
+* The returned value is a proxy that mirrors the router tree: accessing
+* `caller.users.list` returns another proxy; calling it at the leaf
+* dispatches to the compiled pipeline for that procedure.
 */
 function createCaller(routerDef, contextFactory, options) {
-	let compiledRouter = routerCache.get(routerDef);
-	if (!compiledRouter) {
-		compiledRouter = compileRouter(routerDef);
-		routerCache.set(routerDef, compiledRouter);
+	let compiled = routerCache.get(routerDef);
+	if (!compiled) {
+		compiled = compileRouter(routerDef);
+		routerCache.set(routerDef, compiled);
 	}
-	const router = compiledRouter;
-	const defaultTimeout = options?.timeout !== void 0 ? options.timeout : 3e4;
-	function createMockRequest(extraHeaders) {
+	const defaultTimeoutMs = options?.timeout !== void 0 ? options.timeout : 3e4;
+	/**
+	* Construct a mock `Request` to feed into the user's context factory.
+	* Tests rarely care about the URL — only the headers matter, because
+	* that is the surface most factories actually read.
+	*/
+	const mockRequest = (extraHeaders) => {
 		const headers = new Headers(options?.headers);
-		if (extraHeaders) for (const [k, v] of Object.entries(extraHeaders)) headers.set(k, v);
+		if (extraHeaders) for (const [key, value] of Object.entries(extraHeaders)) headers.set(key, value);
 		return new Request("http://localhost/__caller", { headers });
-	}
-	async function resolveContext(perCallContext) {
-		const ctx = createContext();
-		if (contextFactory) {
-			const result = contextFactory(createMockRequest());
-			applyContext(ctx, result instanceof Promise ? await result : result);
-		}
+	};
+	/**
+	* Build a fresh context for a single call. Layers are applied in the
+	* order they would be on the HTTP path: context factory → caller-level
+	* `contextOverride` → per-call override.
+	*/
+	const buildContext = async (perCallContext) => {
+		const ctx = Object.create(null);
+		if (contextFactory) applyContext(ctx, await contextFactory(mockRequest()));
 		if (options?.contextOverride) applyContext(ctx, options.contextOverride);
 		if (perCallContext) applyContext(ctx, perCallContext);
 		return ctx;
-	}
-	function createProxy(segments) {
+	};
+	/**
+	* Build a proxy node for the current `segments` path. Each property
+	* access descends one level; each function call dispatches to the
+	* compiled pipeline.
+	*
+	* The `cache` map ensures repeated property access (e.g.
+	* `caller.users.list`) returns the same proxy object so equality
+	* checks and `.bind` in user tests stay stable.
+	*/
+	const createProxy = (segments) => {
 		const cache = /* @__PURE__ */ new Map();
 		return new Proxy(() => {}, {
 			get(_target, prop) {
 				if (typeof prop === "symbol") return void 0;
 				if (prop === "then" || prop === "toJSON" || prop === "toString" || prop === "$$typeof") return;
-				let sub = cache.get(prop);
-				if (!sub) {
-					sub = createProxy([...segments, prop]);
-					cache.set(prop, sub);
+				let child = cache.get(prop);
+				if (!child) {
+					child = createProxy([...segments, prop]);
+					cache.set(prop, child);
 				}
-				return sub;
+				return child;
 			},
 			apply(_target, _thisArg, args) {
 				const path = "/" + segments.join("/");
 				const input = args[0];
 				const callOptions = args[1];
 				return (async () => {
-					const match = router("", path);
+					const match = compiled("", path);
 					if (!match) throw new Error(`Procedure not found: ${path}`);
-					const ctx = await resolveContext(callOptions?.context);
+					const ctx = await buildContext(callOptions?.context);
 					if (match.params) ctx.params = match.params;
-					const signal = callOptions?.signal ?? (defaultTimeout !== null ? AbortSignal.timeout(defaultTimeout) : NEVER);
-					try {
-						const result = match.data.handler(ctx, input, signal);
-						return result instanceof Promise ? await result : result;
-					} finally {
-						releaseContext(ctx);
-					}
+					const signal = callOptions?.signal ?? (defaultTimeoutMs !== null ? AbortSignal.timeout(defaultTimeoutMs) : NEVER_ABORTS);
+					return await match.data.handler(ctx, input, signal);
 				})();
 			}
 		});
-	}
+	};
 	return createProxy([]);
 }
 //#endregion

package/dist/compile.d.mts

@@ -2,8 +2,9 @@ import { ProcedureDef, WrapDef } from "./types.mjs";
 
 //#region src/compile.d.ts
 /**
- * Compiled pipeline — called per request.
- * May return sync value OR Promise — caller uses instanceof check.
+ * Compiled request handler. May return a sync value or a `Promise` —
+ * adapters branch on `instanceof Promise` for the fast path when the
+ * resolver and guards were all synchronous.
  */
 type CompiledHandler = (ctx: Record<string, unknown>, rawInput: unknown, signal: AbortSignal) => unknown | Promise<unknown>;
 /**
@@ -39,15 +40,21 @@ type CompiledRouterFn = (method: string, path: string) => MatchedRoute<CompiledR
  */
 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.
+ * Disposable wrapper around the pipeline context.
  *
- * Transfer ownership by calling `detachContext(ctx)` before returning.
+ * Adapters use `using ctx = createContext()` so the context is released
+ * automatically at scope exit — unless ownership has been transferred
+ * elsewhere (e.g. to a streaming `Response` that keeps reading from
+ * `ctx` after the handler returns). In that case the handler calls
+ * `detachContext(ctx)` and the new owner is responsible for cleanup.
  */
 type PooledContext = Record<string, unknown> & Disposable;
-/** 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.
+ */
 declare function createContext(): PooledContext;
 //#endregion
 export { compileProcedure, compileRouter, createContext };