silgi 0.53.0 → 0.53.2

package/dist/silgi.mjs

@@ -21,36 +21,44 @@ import { createHooks } from "hookable";
 *   const k = silgi({ context: (req) => ({ db, headers }) })
 *   // k.$input(), k.$resolve(), k.$use(), k.guard(), k.router(), k.handler()
 */
-function createProcedure(type, ...args) {
-	if (args.length === 0) return createProcedureBuilder(type);
-	if (args.length === 1 && typeof args[0] === "function") return {
-		type,
-		input: null,
-		output: null,
-		errors: null,
-		use: null,
-		resolve: args[0],
-		route: null,
-		meta: null
-	};
-	if (args.length === 2 && typeof args[1] === "function") return {
+/**
+* Build a `ProcedureDef` with all optional slots set to `null`.
+*
+* Procedures carry eight slots — `type`, `input`, `output`, `errors`,
+* `use`, `resolve`, `route`, `meta`. Most call sites set only a couple;
+* funnelling construction through this helper keeps the shape in one
+* place so new slots do not have to be added to every short form.
+*/
+function makeProcedureDef(type, input, resolve) {
+	return {
 		type,
-		input: args[0],
+		input,
 		output: null,
 		errors: null,
 		use: null,
-		resolve: args[1],
+		resolve,
 		route: null,
 		meta: null
 	};
+}
+/**
+* Dispatch on the call shape of `$resolve` / `subscription`.
+*
+*   createProcedure(type)                 → chainable builder
+*   createProcedure(type, resolve)        → single-shot procedure
+*   createProcedure(type, input, resolve) → single-shot with input schema
+*/
+function createProcedure(type, ...args) {
+	if (args.length === 0) return createProcedureBuilder(type);
+	if (args.length === 1 && typeof args[0] === "function") return makeProcedureDef(type, null, args[0]);
+	if (args.length === 2 && typeof args[1] === "function") return makeProcedureDef(type, args[0], args[1]);
 	throw new TypeError(`Invalid arguments for ${type}()`);
 }
 /**
-* Stamp root wraps onto a router def as a non-enumerable Symbol-keyed
-* property. Idempotent — if the def is already branded with the same
-* reference, this is a no-op. Multiple silgi instances registering the
-* same def throws, because a single compiled router cannot serve two
-* context shapes.
+* Stamp root wraps onto a router def via a non-enumerable Symbol-keyed
+* property. Idempotent for the same wrap reference; throws when a
+* different silgi instance has already registered the def, because a
+* single compiled router cannot serve two different context shapes.
 *
 * @internal
 */
@@ -66,6 +74,55 @@ function stampRootWraps(def, wraps) {
 	});
 }
 /**
+* Validate + freeze the `wraps` config array.
+*
+* Guards are rejected at the instance level because a guard's return
+* type must flow into every procedure's context, and the instance-level
+* config cannot express that across an unknown router shape. Guards
+* must be attached via route-level `.$use()` where the context
+* enrichment can be typed.
+*/
+function prepareRootWraps(wraps) {
+	if (!wraps || wraps.length === 0) return null;
+	for (const w of wraps) if (!w || w.kind !== "wrap") throw new TypeError("silgi({ wraps }) only accepts wrap middleware — use route-level .$use() for guards.");
+	return Object.freeze([...wraps]);
+}
+/**
+* Register the user-provided hook listeners on a fresh `Hookable`.
+* Accepts either a single function or an array of functions per hook,
+* matching the shape documented on `SilgiConfig['hooks']`.
+*/
+function registerHooks(hooks, config) {
+	if (!config) return;
+	for (const [name, fn] of Object.entries(config)) {
+		const key = name;
+		if (Array.isArray(fn)) for (const f of fn) hooks.hook(key, f);
+		else if (fn) hooks.hook(key, fn);
+	}
+}
+/**
+* Build the storage-ready promise. Resolves immediately when no storage
+* is configured — and crucially, never triggers the dynamic import in
+* that case, so tree-shakers can drop the driver code entirely.
+*/
+function makeStorageReady(storage) {
+	if (!storage) return Promise.resolve();
+	return import("./core/storage.mjs").then((m) => {
+		m.initStorage(storage);
+	});
+}
+/**
+* Recursively search a router def for any `subscription` procedure.
+* Used to decide whether `handler()` should bother to lazy-load the
+* crossws hooks for the `/_ws` mount.
+*/
+function routerHasSubscriptions(def) {
+	if (!def || typeof def !== "object") return false;
+	if (def.type === "subscription") return true;
+	for (const child of Object.values(def)) if (routerHasSubscriptions(child)) return true;
+	return false;
+}
+/**
 * Create a Silgi RPC instance with typed context.
 *
 * @remarks
@@ -101,20 +158,80 @@ function silgi(config) {
 	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);
-	}
-	const readyPromise = config.storage ? import("./core/storage.mjs").then((m) => {
-		m.initStorage(config.storage);
-	}) : Promise.resolve();
+	registerHooks(hooks, config.hooks);
+	const readyPromise = makeStorageReady(config.storage);
+	const rootWraps = prepareRootWraps(config.wraps);
 	const ctxFactory = () => contextFactory(new Request("http://localhost"));
-	let rootWraps = null;
-	if (config.wraps && config.wraps.length > 0) {
-		for (const w of config.wraps) if (!w || w.kind !== "wrap") throw new TypeError("silgi({ wraps }) only accepts wrap middleware — use route-level .$use() for guards.");
-		rootWraps = Object.freeze([...config.wraps]);
-	}
 	const rootWrapsGetter = rootWraps ? () => rootWraps : null;
+	const startBuilder = () => createProcedureBuilder("query", ctxFactory, rootWrapsGetter);
+	const registerRouter = (def) => {
+		const assigned = assignPaths(def);
+		if (rootWraps) {
+			stampRootWraps(def, rootWraps);
+			stampRootWraps(assigned, rootWraps);
+		}
+		const compiled = compileRouter(assigned);
+		routerCache.set(def, compiled);
+		routerCache.set(assigned, compiled);
+		return def;
+	};
+	const buildHandler = (routerDef, options) => {
+		const prefix = options?.basePath ? normalizePrefix(options.basePath) : void 0;
+		const fetchHandler = wrapHandler(createFetchHandler(routerDef, contextFactory, hooks, prefix, bridge), routerDef, options ? {
+			...options,
+			schemaRegistry,
+			hooks
+		} : {
+			schemaRegistry,
+			hooks
+		}, prefix);
+		if (!routerHasSubscriptions(routerDef)) return fetchHandler;
+		let wsHooks;
+		let wsInitPromise;
+		const initWsHooks = async () => {
+			const { _createWSHooks } = await import("./ws.mjs");
+			wsHooks = _createWSHooks(routerDef, { context: (peer) => {
+				return contextFactory(peer?.request instanceof Request ? peer.request : peer);
+			} });
+		};
+		const wsPath = prefix ? `${prefix}/_ws` : "/_ws";
+		return async (request) => {
+			if (new URL(request.url).pathname === wsPath) {
+				if (!wsHooks) {
+					wsInitPromise ??= initWsHooks();
+					await wsInitPromise;
+				}
+				const response = new Response(null, { status: 200 });
+				response.crossws = wsHooks;
+				return response;
+			}
+			return fetchHandler(request);
+		};
+	};
+	const buildServe = async (routerDef, options) => {
+		const { createServeHandler } = await import("./core/serve.mjs");
+		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) {
+			await startCronJobs(cronTasks);
+			console.log(`  ${cronTasks.length} cron task(s) scheduled`);
+		}
+		const originalClose = server.close.bind(server);
+		const wrappedClose = async (force) => {
+			stopCronJobs();
+			return originalClose(force);
+		};
+		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;
+	};
 	return {
 		hook: hooks.hook.bind(hooks),
 		removeHook: hooks.removeHook.bind(hooks),
@@ -140,96 +257,22 @@ function silgi(config) {
 			fn
 		}),
 		$resolve: ((fn) => createProcedure("query", fn)),
-		$input: ((schema) => createProcedureBuilder("query", ctxFactory, rootWrapsGetter).$input(schema)),
+		$input: ((schema) => startBuilder().$input(schema)),
 		$use: ((...middleware) => {
-			const b = createProcedureBuilder("query", ctxFactory, rootWrapsGetter);
+			const b = startBuilder();
 			for (const m of middleware) b.$use(m);
 			return b;
 		}),
-		$output: ((schema) => createProcedureBuilder("query", ctxFactory, rootWrapsGetter).$output(schema)),
-		$errors: ((errors) => createProcedureBuilder("query", ctxFactory, rootWrapsGetter).$errors(errors)),
-		$route: ((route) => createProcedureBuilder("query", ctxFactory, rootWrapsGetter).$route(route)),
-		$meta: ((meta) => createProcedureBuilder("query", ctxFactory, rootWrapsGetter).$meta(meta)),
+		$output: ((schema) => startBuilder().$output(schema)),
+		$errors: ((errors) => startBuilder().$errors(errors)),
+		$route: ((route) => startBuilder().$route(route)),
+		$meta: ((meta) => startBuilder().$meta(meta)),
 		subscription: ((...args) => createProcedure("subscription", ...args)),
-		$task: ((config) => {
-			return createTaskFromProcedure(config, config.resolve, null, null, ctxFactory, rootWrapsGetter);
-		}),
-		router: (def) => {
-			const assigned = assignPaths(def);
-			if (rootWraps) {
-				stampRootWraps(def, rootWraps);
-				stampRootWraps(assigned, rootWraps);
-			}
-			const flat = compileRouter(assigned);
-			routerCache.set(def, flat);
-			routerCache.set(assigned, flat);
-			return def;
-		},
-		createCaller: (routerDef, options) => {
-			return createCaller(routerDef, contextFactory, options);
-		},
-		handler: (routerDef, options) => {
-			const prefix = options?.basePath ? normalizePrefix(options.basePath) : void 0;
-			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;
-				for (const v of Object.values(def)) if (checkWs(v)) return true;
-				return false;
-			})(routerDef)) return fetchHandler;
-			let wsHooks;
-			let wsInitPromise;
-			async function initWsHooks() {
-				const { _createWSHooks } = await import("./ws.mjs");
-				wsHooks = _createWSHooks(routerDef, { context: (peer) => {
-					return contextFactory(peer?.request instanceof Request ? peer.request : peer);
-				} });
-			}
-			const wsPath = prefix ? `${prefix}/_ws` : "/_ws";
-			return async (request) => {
-				if (new URL(request.url).pathname === wsPath) {
-					if (!wsHooks) {
-						wsInitPromise ??= initWsHooks();
-						await wsInitPromise;
-					}
-					const response = new Response(null, { status: 200 });
-					response.crossws = wsHooks;
-					return response;
-				}
-				return fetchHandler(request);
-			};
-		},
-		serve: async (routerDef, options) => {
-			const { createServeHandler } = await import("./core/serve.mjs");
-			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) {
-				await startCronJobs(cronTasks);
-				console.log(`  ${cronTasks.length} cron task(s) scheduled`);
-			}
-			const originalClose = server.close.bind(server);
-			const wrappedClose = async (force) => {
-				stopCronJobs();
-				return originalClose(force);
-			};
-			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;
-		}
+		$task: ((cfg) => createTaskFromProcedure(cfg, cfg.resolve, null, null, ctxFactory, rootWrapsGetter)),
+		router: registerRouter,
+		createCaller: (routerDef, options) => createCaller(routerDef, contextFactory, options),
+		handler: buildHandler,
+		serve: buildServe
 	};
 }
 //#endregion

package/dist/ws.d.mts

@@ -7,23 +7,21 @@ interface WSAdapterOptions<TCtx extends Record<string, unknown> = Record<string,
   /**
    * Wire protocol for WebSocket message encoding.
    *
-   * - `'json'` — default, text frames with JSON
-   * - `'messagepack'` — binary frames with MessagePack
+   * - `'json'` — default, text frames with JSON.
+   * - `'messagepack'` — binary frames with MessagePack.
    *
    * @default 'json'
    */
   protocol?: 'json' | 'messagepack';
-  /**
-   * @deprecated Use `protocol: 'messagepack'` instead.
-   */
+  /** @deprecated Use `protocol: 'messagepack'` instead. */
   binary?: boolean;
-  /** Context factory — receives the peer on each message */
+  /** Context factory — invoked for every incoming peer 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`)
+   * - `true`  — enable with library defaults.
+   * - object  — zlib tuning, forwarded to `ws.perMessageDeflate`.
    *
    * @default false
    */
@@ -35,43 +33,44 @@ interface WSAdapterOptions<TCtx extends Record<string, unknown> = Record<string,
     clientMaxWindowBits?: number;
   };
   /**
-   * Maximum allowed message size in bytes.
-   * Messages exceeding this limit will cause the connection to be closed.
+   * Maximum allowed message size in bytes. Exceeding the limit closes
+   * the connection.
    *
    * @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.
+   * Keepalive ping interval in milliseconds. The server sends a ping
+   * every `keepalive` ms; if the client does not pong before the next
+   * ping, the socket is terminated.
    *
-   * Set to `0` or `false` to disable.
+   * Set to `0` or `false` to disable keepalive entirely.
    *
-   * @default 30_000 (30 seconds)
+   * @default 30_000
    */
   keepalive?: number | false;
 }
 /**
- * Internal — build crossws-compatible hooks for Silgi RPC over WebSocket.
+ * Build the crossws hook set that implements silgi's WebSocket RPC.
+ *
+ * @internal
  *
- * Used by `attachWebSocket()`, `serve({ ws: true })`, and `handler()` auto-WS.
- * Not part of the public API; callers should use one of those higher-level entry points.
+ * This is not part of the public API — `silgi({...}).handler()`,
+ * `serve({ ws: true })`, and `attachWebSocket()` are the three supported
+ * entry points. They all go through this builder so protocol behavior
+ * stays identical everywhere.
  */
-/** @internal — exported only for use by silgi.ts handler() and attachWebSocket(). Not part of the public API. */
 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.
+ * Attach silgi's WebSocket RPC to an existing Node.js `http.Server`.
  *
  * @example
- * ```ts
- * import { createServer } from "node:http";
- * import { attachWebSocket } from "silgi/ws";
+ *   import { createServer } from 'node:http'
+ *   import { attachWebSocket } from 'silgi/ws'
  *
- * const server = createServer(httpHandler);
- * attachWebSocket(server, appRouter);
- * server.listen(3000);
- * ```
+ *   const server = createServer(httpHandler)
+ *   await attachWebSocket(server, appRouter)
+ *   server.listen(3000)
  */
 declare function attachWebSocket<TCtx extends Record<string, unknown>>(server: Server, routerDef: RouterDef, options?: WSAdapterOptions<TCtx>): Promise<void>;
 //#endregion