silgi 0.53.0 → 0.53.1

package/dist/core/serve.mjs

@@ -3,19 +3,156 @@ import { createFetchHandler, wrapHandler } from "./handler.mjs";
 import { _createWSHooks } from "../ws.mjs";
 import { serve } from "srvx";
 //#region src/core/serve.ts
+/**
+* `serve()` orchestrator
+* ------------------------
+*
+* Builds a Node/Bun/Deno HTTP server from a silgi router. The heavy
+* lifting (the compiled Fetch handler, analytics/Scalar wrappers) is
+* already done elsewhere; this module stitches them together with the
+* runtime-specific WebSocket upgrade plumbing and hands off to `srvx`.
+*
+* The only per-runtime work that lives here is mounting WebSocket hooks
+* for subscriptions:
+*
+*   - **Bun**   — inject crossws into `serve({ bun: { websocket } })`
+*                 and intercept upgrade requests at the Fetch layer.
+*   - **Deno**  — intercept upgrade requests at the Fetch layer and
+*                 call the crossws Deno adapter directly.
+*   - **Node**  — after srvx exposes the `http.Server`, attach crossws
+*                 via `server.on('upgrade', …)`.
+*
+* Everything else is shared: URL resolution, graceful shutdown, hook
+* firing, and the startup banner.
+*/
+/**
+* Detect the current JavaScript runtime from well-known globals.
+*
+* Written as a plain function rather than reading a module-global so
+* the check re-evaluates when the module is imported into a different
+* runtime (e.g. a test that spawns a Bun child process).
+*/
 function detectRuntime() {
 	if (typeof globalThis.Bun !== "undefined") return "bun";
 	if (typeof globalThis.Deno !== "undefined") return "deno";
 	return "node";
 }
+/**
+* Walk the router tree looking for a subscription. We stop at the first
+* hit because we only need to decide whether to wire up WS at all — we
+* do not need an inventory.
+*
+* Mirrors the helper in `silgi.ts`; kept here so `core/serve.ts` has no
+* runtime dependency on the top-level instance module.
+*/
 function routerHasSubscription(def) {
 	if (!def || typeof def !== "object") return false;
 	if (def.type === "subscription") return true;
-	for (const v of Object.values(def)) if (routerHasSubscription(v)) return true;
+	for (const child of Object.values(def)) if (routerHasSubscription(child)) return true;
 	return false;
 }
+/**
+* Translate our `gracefulShutdown` option into the shape srvx expects.
+*
+* srvx uses `gracefulTimeout`, we expose `timeout` — the rename keeps
+* the public API readable without leaking srvx vocabulary.
+*/
+function resolveShutdown(option) {
+	if (option === void 0 || typeof option === "boolean") return option ?? true;
+	return {
+		gracefulTimeout: option.timeout,
+		forceTimeout: option.forceTimeout
+	};
+}
+/**
+* Build the WS wiring for the current runtime.
+*
+* Everything stays lazy: when no subscriptions exist or WS is
+* explicitly disabled, we return `{ fetch: httpHandler }` and never
+* import the crossws adapters.
+*/
+async function wireWebSocket(routerDef, httpHandler, enabled, wsOpts, runtime, bunServerRef) {
+	if (!enabled) return { fetch: httpHandler };
+	const hooksObj = _createWSHooks(routerDef, wsOpts);
+	if (runtime === "bun") {
+		const bunAdapter = (await import("crossws/adapters/bun")).default;
+		const adapter = bunAdapter({ hooks: hooksObj });
+		return {
+			bunWebsocket: adapter.websocket,
+			fetch: (async (req) => {
+				if (req.headers.get("upgrade") === "websocket" && bunServerRef.current) {
+					const res = await adapter.handleUpgrade(req, bunServerRef.current);
+					if (res) return res;
+				}
+				return httpHandler(req);
+			})
+		};
+	}
+	if (runtime === "deno") {
+		const denoAdapter = (await import("crossws/adapters/deno")).default;
+		const adapter = denoAdapter({ hooks: hooksObj });
+		return { fetch: (async (req) => {
+			if (req.headers.get("upgrade") === "websocket") return adapter.handleUpgrade(req, {});
+			return httpHandler(req);
+		}) };
+	}
+	return {
+		fetch: httpHandler,
+		attachNode: async (httpServer) => {
+			const { attachWebSocket } = await import("../ws.mjs");
+			await attachWebSocket(httpServer, routerDef, wsOpts);
+		}
+	};
+}
+/**
+* Compute the final server URL from srvx's output.
+*
+* srvx usually populates `server.url` itself, but when the caller
+* requests port `0` (pick-any-free) or when HTTP/2 is on, we have to
+* piece it together from the runtime-specific socket info. Trailing
+* slashes are stripped so `${url}/api/foo` always produces exactly one
+* separator.
+*/
+function resolveUrl(server, requestedPort, hostname, http2) {
+	let port = requestedPort;
+	if (server.node?.server) {
+		const addr = server.node.server.address();
+		if (addr && typeof addr === "object") port = addr.port;
+	} else if (server.bun?.server) port = server.bun.server.port ?? requestedPort;
+	const protocol = http2 ? "https" : "http";
+	const raw = server.url || `${protocol}://${hostname}:${port}`;
+	return {
+		url: raw.endsWith("/") ? raw.slice(0, -1) : raw,
+		port
+	};
+}
+/**
+* Print the startup banner.
+*
+* Side-effect-y and intentionally not bypassable — a server starting
+* silently is a surprising default; `silent: true` on srvx suppresses
+* *its* banner, but silgi still wants to show where it bound.
+*/
+function printBanner(url, hostname, port, runtime, options, wsEnabled) {
+	console.log(`\nSilgi server running at ${url}`);
+	if (options?.http2) console.log(`  HTTP/2 enabled (with HTTP/1.1 fallback)`);
+	if (wsEnabled) console.log(`  WebSocket RPC at ws://${hostname}:${port}/_ws (${runtime})`);
+	if (options?.scalar) console.log(`  Scalar API Reference at ${url}/api/reference`);
+	if (options?.analytics) console.log(`  Analytics dashboard at ${url}/api/analytics`);
+	console.log();
+}
+/**
+* Build and start the HTTP (and optionally WebSocket) server.
+*
+* The function is intentionally long because the steps are strictly
+* ordered: WS wiring has to happen before srvx starts (Bun needs its
+* websocket handler at construction time); the `http.Server` only
+* exists once srvx returns (Node attaches WS there); and the banner
+* wants real bound port info. Splitting further would hide the
+* ordering more than it would simplify anything.
+*/
 async function createServeHandler(routerDef, contextFactory, hooks, options, schemaRegistry, bridge) {
-	const port = options?.port ?? 3e3;
+	const requestedPort = options?.port ?? 3e3;
 	const hostname = options?.hostname ?? "127.0.0.1";
 	const prefix = options?.basePath ? normalizePrefix(options.basePath) : void 0;
 	const httpHandler = wrapHandler(createFetchHandler(routerDef, contextFactory, hooks, prefix, bridge), routerDef, options ? {
@@ -26,89 +163,42 @@ async function createServeHandler(routerDef, contextFactory, hooks, options, sch
 		schemaRegistry,
 		hooks
 	}, prefix);
-	const shutdownOpt = options?.gracefulShutdown ?? true;
-	let gracefulShutdown;
-	if (typeof shutdownOpt === "object") gracefulShutdown = {
-		gracefulTimeout: shutdownOpt.timeout,
-		forceTimeout: shutdownOpt.forceTimeout
-	};
-	else gracefulShutdown = shutdownOpt;
-	const wsExplicitlyDisabled = options?.ws === false;
-	const wsOpts = typeof options?.ws === "object" ? options.ws : void 0;
-	const wsEnabled = !wsExplicitlyDisabled && routerHasSubscription(routerDef);
 	const runtime = detectRuntime();
-	let fetchHandler = httpHandler;
-	let bunWebsocket;
+	const wsEnabled = !(options?.ws === false) && routerHasSubscription(routerDef);
+	const wsOpts = typeof options?.ws === "object" ? options.ws : void 0;
 	const bunServerRef = { current: void 0 };
-	let nodeAttach;
-	if (wsEnabled) {
-		const hooksObj = _createWSHooks(routerDef, wsOpts);
-		if (runtime === "bun") {
-			const bunAdapter = (await import("crossws/adapters/bun")).default;
-			const adapter = bunAdapter({ hooks: hooksObj });
-			bunWebsocket = adapter.websocket;
-			fetchHandler = (async (req) => {
-				if (req.headers.get("upgrade") === "websocket" && bunServerRef.current) {
-					const res = await adapter.handleUpgrade(req, bunServerRef.current);
-					if (res) return res;
-				}
-				return httpHandler(req);
-			});
-		} else if (runtime === "deno") {
-			const denoAdapter = (await import("crossws/adapters/deno")).default;
-			const adapter = denoAdapter({ hooks: hooksObj });
-			fetchHandler = (async (req) => {
-				if (req.headers.get("upgrade") === "websocket") return adapter.handleUpgrade(req, {});
-				return httpHandler(req);
-			});
-		} else nodeAttach = async (httpServer) => {
-			const { attachWebSocket } = await import("../ws.mjs");
-			await attachWebSocket(httpServer, routerDef, wsOpts);
-		};
-	}
+	const wiring = await wireWebSocket(routerDef, httpHandler, wsEnabled, wsOpts, runtime, bunServerRef);
 	const server = await serve({
-		port,
+		port: requestedPort,
 		hostname,
-		fetch: fetchHandler,
-		gracefulShutdown,
+		fetch: wiring.fetch,
+		gracefulShutdown: resolveShutdown(options?.gracefulShutdown),
 		silent: true,
-		...options?.http2 && { tls: {
+		...options?.http2 ? { tls: {
 			cert: options.http2.cert,
 			key: options.http2.key
-		} },
-		...bunWebsocket ? { bun: { websocket: bunWebsocket } } : {}
+		} } : {},
+		...wiring.bunWebsocket ? { bun: { websocket: wiring.bunWebsocket } } : {}
 	});
 	await server.ready();
 	if (runtime === "bun" && server.bun?.server) bunServerRef.current = server.bun.server;
-	if (nodeAttach && server.node?.server) await nodeAttach(server.node.server);
-	let resolvedPort = port;
-	if (server.node?.server) {
-		const addr = server.node.server.address();
-		if (addr && typeof addr === "object") resolvedPort = addr.port;
-	} else if (server.bun?.server) resolvedPort = server.bun.server.port ?? port;
-	const protocol = options?.http2 ? "https" : "http";
-	const rawUrl = server.url || `${protocol}://${hostname}:${resolvedPort}`;
-	const url = rawUrl.endsWith("/") ? rawUrl.slice(0, -1) : rawUrl;
-	console.log(`\nSilgi server running at ${url}`);
-	if (options?.http2) console.log(`  HTTP/2 enabled (with HTTP/1.1 fallback)`);
-	if (wsEnabled) console.log(`  WebSocket RPC at ws://${hostname}:${resolvedPort}/_ws (${runtime})`);
-	if (options?.scalar) console.log(`  Scalar API Reference at ${url}/api/reference`);
-	if (options?.analytics) console.log(`  Analytics dashboard at ${url}/api/analytics`);
-	console.log();
+	if (wiring.attachNode && server.node?.server) await wiring.attachNode(server.node.server);
+	const { url, port } = resolveUrl(server, requestedPort, hostname, Boolean(options?.http2));
+	printBanner(url, hostname, port, runtime, options, wsEnabled);
 	await hooks.callHook("serve:start", {
 		url,
-		port: resolvedPort,
+		port,
 		hostname
 	});
 	return {
 		url,
-		port: resolvedPort,
+		port,
 		hostname,
 		async close(forceCloseConnections = false) {
 			await server.close(forceCloseConnections);
 			await hooks.callHook("serve:stop", {
 				url,
-				port: resolvedPort,
+				port,
 				hostname
 			});
 		}

package/dist/core/sse.d.mts

@@ -4,15 +4,14 @@ interface EventMeta {
   retry?: number;
 }
 /**
- * Attach SSE metadata (id, retry) to a value.
+ * Attach SSE `id` / `retry` metadata to a yielded value.
  *
- * Only works with object values (arrays, plain objects, etc.).
- * Primitives cannot carry metadata — wrap them in an object first.
+ * Only object-shaped values can carry metadata; primitives cannot be
+ * keyed in the `WeakMap` and are returned unchanged. Wrap primitives
+ * in a one-field object when you need metadata on them.
  */
 declare function withEventMeta<T>(value: T, meta: EventMeta): T;
-/**
- * Read SSE metadata from a value (if attached).
- */
+/** Read SSE metadata previously attached via `withEventMeta`. */
 declare function getEventMeta(value: unknown): EventMeta | undefined;
 //#endregion
 export { EventMeta, getEventMeta, withEventMeta };

package/dist/core/sse.mjs

@@ -1,36 +1,54 @@
 import { SilgiError } from "./error.mjs";
 //#region src/core/sse.ts
 /**
-* Server-Sent Events (SSE) encoding/decoding.
+* Server-Sent Events
+* -------------------
 *
-* Supports three event types:
-* - message: a yielded value
-* - error: an error event with data
-* - done: the return value (stream complete)
+* silgi subscriptions are yielded to the client as an SSE event stream.
+* This module holds the encoder, the streaming decoder (for client-side
+* consumption), and the iterator ↔ stream bridges in both directions.
 *
-* Event metadata (id, retry) can be attached to object values
-* via withEventMeta() using a WeakMap side-channel.
+* Wire vocabulary
+* ---------------
+*
+*   `event: message`  → one yielded value
+*   `event: error`    → resolver threw (sanitized for undefined errors)
+*   `event: done`     → generator returned; `data` is the return value
+*   `: <comment>`     → keepalive or boot marker; ignored by clients
+*
+* Event metadata (SSE `id` / `retry`) can be attached to any object
+* value via `withEventMeta()` and round-trips through the decoder.
+*/
+/**
+* Metadata store for SSE `id` / `retry` fields.
+*
+* This `WeakMap` is module-scoped (i.e. shared across every subscription
+* in the process). That is safe: entries are keyed by the *value object*
+* the user passes in, and GC reclaims entries as soon as those objects
+* become unreachable. A per-iterator store would add plumbing for
+* nothing — two subscriptions yielding distinct objects never collide.
 */
-const _eventMeta = /* @__PURE__ */ new WeakMap();
+const metaStore = /* @__PURE__ */ new WeakMap();
 /**
-* Attach SSE metadata (id, retry) to a value.
+* Attach SSE `id` / `retry` metadata to a yielded value.
 *
-* Only works with object values (arrays, plain objects, etc.).
-* Primitives cannot carry metadata — wrap them in an object first.
+* Only object-shaped values can carry metadata; primitives cannot be
+* keyed in the `WeakMap` and are returned unchanged. Wrap primitives
+* in a one-field object when you need metadata on them.
 */
 function withEventMeta(value, meta) {
-	if (typeof value === "object" && value !== null) _eventMeta.set(value, meta);
+	if (typeof value === "object" && value !== null) metaStore.set(value, meta);
 	return value;
 }
-/**
-* Read SSE metadata from a value (if attached).
-*/
+/** Read SSE metadata previously attached via `withEventMeta`. */
 function getEventMeta(value) {
 	if (typeof value !== "object" || value === null) return void 0;
-	return _eventMeta.get(value);
+	return metaStore.get(value);
 }
 /**
-* Encode an EventMessage into SSE wire format.
+* Serialize an `EventMessage` into SSE wire format (one event terminated
+* by a blank line). Multi-line `data` and `comment` are split across
+* multiple fields per the SSE spec so embedded newlines survive.
 */
 function encodeEventMessage(msg) {
 	const lines = [];
@@ -42,15 +60,60 @@ function encodeEventMessage(msg) {
 	return lines.join("\n") + "\n\n";
 }
 /**
-* Convert an async iterator to an SSE ReadableStream.
-* Each yielded value becomes a "message" event.
-* Errors become "error" events. Return value becomes "done".
+* Build an SSE `ReadableStream` that consumes an async iterator.
+*
+* Each yielded value becomes a `message` event; the iterator's return
+* value becomes the `done` event; a thrown error becomes an `error`
+* event (and only the message is exposed when the error is not a
+* `SilgiError` flagged `defined` — undefined errors must not leak
+* internals).
+*
+* A comment-only `keepalive` event is emitted every `keepAliveMs` so
+* intermediaries (proxies, load balancers) do not close the connection
+* while the resolver is quiet.
 */
 function iteratorToEventStream(iterator, options = {}) {
 	const serialize = options.serialize ?? JSON.stringify;
 	const keepAliveMs = options.keepAliveMs ?? 3e4;
 	let keepAliveTimer;
 	let cancelled = false;
+	/** Build the wire form of one yielded value, carrying any attached meta. */
+	const encodeValue = (value) => {
+		const meta = getEventMeta(value);
+		return encodeEventMessage({
+			event: "message",
+			data: serialize(value),
+			id: meta?.id,
+			retry: meta?.retry
+		});
+	};
+	/** Build the wire form of the terminal `done` event, if a return value was yielded. */
+	const encodeDone = (value) => {
+		return encodeEventMessage({
+			event: "done",
+			data: value !== void 0 ? serialize(value) : void 0
+		});
+	};
+	/**
+	* Build the wire form of an `error` event.
+	*
+	* Only `SilgiError` with `defined === true` surfaces its `code` and
+	* `message` to the wire — the author opted into publishing those by
+	* declaring the error. Everything else collapses to a generic 500
+	* shape so we do not leak stack traces or internal codes.
+	*/
+	const encodeError = (err) => {
+		return encodeEventMessage({
+			event: "error",
+			data: err instanceof SilgiError && err.defined ? JSON.stringify({
+				message: err.message,
+				code: err.code
+			}) : JSON.stringify({
+				message: "Internal server error",
+				code: "INTERNAL_SERVER_ERROR"
+			})
+		});
+	};
 	return new ReadableStream({
 		start(controller) {
 			if (options.initialComment !== void 0) controller.enqueue(encodeEventMessage({ comment: options.initialComment }));
@@ -64,38 +127,15 @@ function iteratorToEventStream(iterator, options = {}) {
 				if (cancelled) return;
 				if (result.done) {
 					clearInterval(keepAliveTimer);
-					const data = result.value !== void 0 ? serialize(result.value) : void 0;
-					controller.enqueue(encodeEventMessage({
-						event: "done",
-						data
-					}));
+					controller.enqueue(encodeDone(result.value));
 					controller.close();
 					return;
 				}
-				const meta = getEventMeta(result.value);
-				const msg = {
-					event: "message",
-					data: serialize(result.value),
-					id: meta?.id,
-					retry: meta?.retry
-				};
-				controller.enqueue(encodeEventMessage(msg));
+				controller.enqueue(encodeValue(result.value));
 			} catch (error) {
 				clearInterval(keepAliveTimer);
 				if (cancelled) return;
-				let errorData;
-				if (error instanceof SilgiError && error.defined) errorData = JSON.stringify({
-					message: error.message,
-					code: error.code
-				});
-				else errorData = JSON.stringify({
-					message: "Internal server error",
-					code: "INTERNAL_SERVER_ERROR"
-				});
-				controller.enqueue(encodeEventMessage({
-					event: "error",
-					data: errorData
-				}));
+				controller.enqueue(encodeError(error));
 				controller.close();
 			}
 		},

package/dist/core/task.d.mts

@@ -23,7 +23,10 @@ interface TaskDef<TInput = unknown, TOutput = unknown> {
   } | null;
   readonly meta: null;
   readonly _contextFactory: (() => unknown | Promise<unknown>) | null;
-  /** Dispatch the task. Pass ctx from a procedure to auto-record a trace span. */
+  /**
+   * Dispatch the task. Pass the *parent* request's `ctx` as the second
+   * argument to fold the dispatch into that request's trace span.
+   */
   dispatch: undefined extends TInput ? (input?: TInput, ctx?: Record<string, unknown>) => Promise<TOutput> : (input: TInput, ctx?: Record<string, unknown>) => Promise<TOutput>;
 }
 type TaskCompleteCallback = (entry: {
@@ -39,6 +42,11 @@ type TaskCompleteCallback = (entry: {
 }) => void;
 declare function setTaskAnalytics(cb: TaskCompleteCallback | null): void;
 declare function runTask<TInput, TOutput>(task: TaskDef<TInput, TOutput>, ...args: undefined extends TInput ? [input?: TInput] : [input: TInput]): Promise<TOutput>;
+/**
+ * Walk a router tree and collect every task that has a `cron` field set.
+ * Nested namespaces are recursed into; we stop at any node already
+ * tagged as a task so a task's internal structure is never inspected.
+ */
 declare function collectCronTasks(def: Record<string, unknown>): Array<{
   cron: string;
   task: TaskDef<any, any>;
@@ -61,9 +69,12 @@ interface CronRegistry {
   list: () => ScheduledTaskInfo[];
 }
 /**
- * Create an isolated cron registry. Each silgi instance owns one, so
- * `server.close()` on instance A never stops instance B's jobs and
- * `list()` never returns jobs from another instance.
+ * Create an isolated cron registry.
+ *
+ * Each silgi instance owns one, so `server.close()` on instance A
+ * never stops instance B's jobs and `list()` never returns jobs from
+ * another instance. The module-default registry below keeps the
+ * legacy top-level exports working.
  */
 declare function createCronRegistry(): CronRegistry;
 /** @deprecated Use {@link createCronRegistry} — each silgi instance owns its own. */