silgi 0.52.2 → 0.53.1

package/dist/core/schema-converter.mjs

@@ -2,17 +2,9 @@
 /**
 * Build a {@link SchemaRegistry} from an array of converters.
 *
-* @param converters - Array of {@link SchemaConverter} objects, each
-*   declaring their own `vendor`.
-* @returns A `Map<string, SchemaConverter>` keyed by `converter.vendor`.
-*
 * @example
-* ```ts
-* import { zodConverter } from 'silgi/zod'
-* import { createSchemaRegistry } from 'silgi'
-*
-* const registry = createSchemaRegistry([zodConverter])
-* ```
+*   import { zodConverter } from 'silgi/zod'
+*   const registry = createSchemaRegistry([zodConverter])
 *
 * @category Schema
 */
@@ -21,62 +13,99 @@ function createSchemaRegistry(converters = []) {
 	for (const converter of converters) map.set(converter.vendor, converter);
 	return map;
 }
-const _warnedVendors = /* @__PURE__ */ new Set();
 /**
-* Convert any Standard Schema to JSON Schema.
+* Vendor names we've already warned about. Module-scoped so the
+* warning fires at most once per vendor per process lifetime — across
+* every silgi instance in the same process. The set only holds bounded
+* vendor strings (no schema data, no user input), so sharing it
+* globally is safe.
+*/
+const warnedVendors = /* @__PURE__ */ new Set();
+/** Read the `~standard` slot off an AnySchema in one typed step. */
+const readStandardSlot = (schema) => schema["~standard"];
+/**
+* Call the Standard JSON Schema extension on a schema that exposes it.
+* Returns `null` when the extension does not handle this strategy or
+* throws (in which case the caller falls back to the registry).
 *
-* @remarks
-* Resolution order:
-* 1. **Native fast path** — `schema['~standard'].jsonSchema.input()`
-*    (Valibot, ArkType, Zod v4, …). No registry needed.
-* 2. **Registry lookup** — finds a converter by
-*    `schema['~standard'].vendor`. Registry must be passed explicitly;
-*    there is no global mutable state.
-* 3. **Empty schema `{}`** — emits a one-time `console.warn` per vendor
-*    when a registry was provided but contained no matching converter.
-*    No warn when no registry was passed (caller opted out).
+* We strip the `$schema` meta field because it is a JSON Schema marker,
+* not a member of the schema itself — silgi never propagates it.
+*/
+function callNativeJsonSchema(std, opts) {
+	const generator = opts.strategy === "output" ? std.jsonSchema?.output : std.jsonSchema?.input;
+	if (!generator) return null;
+	try {
+		const result = generator({
+			target: opts.target,
+			libraryOptions: opts.libraryOptions
+		});
+		if (!result || typeof result !== "object") return null;
+		const { $schema: _ignored, ...rest } = result;
+		return rest;
+	} catch {
+		return null;
+	}
+}
+/** Warn once per vendor when a registry was passed but had no match. */
+function warnMissingConverter(vendor) {
+	if (warnedVendors.has(vendor)) return;
+	warnedVendors.add(vendor);
+	console.warn(`[silgi] No schema converter registered for vendor "${vendor}". Pass schemaConverters: [${vendor}Converter] to silgi() to enable OpenAPI / analytics schema generation.`);
+}
+/**
+* Convert any Standard Schema to a JSON Schema object.
 *
-* @param schema - Any Standard Schema compatible schema object.
-* @param strategy - `'input'` (default) for pre-transform types; `'output'`
-*   for post-transform.
-* @param registry - Optional {@link SchemaRegistry} built from
-*   {@link createSchemaRegistry}. When omitted the function still handles
-*   schemas that expose the native `jsonSchema.input()` fast path.
-* @returns A JSON Schema object. Returns `{}` when conversion is not possible.
+* @param schema   The schema to convert.
+* @param strategy `'input'` (default) for pre-transform types, `'output'`
+*                 for post-transform. Matters for schemas that coerce
+*                 (e.g. `z.coerce.number()` takes a string and yields a
+*                 number — input and output schemas differ).
+* @param registry Optional fallback registry built by
+*                 {@link createSchemaRegistry}. Omit to rely solely on
+*                 the native Standard JSON Schema extension.
+* @param options  Extra knobs: `target` dialect (default
+*                 `'draft-2020-12'`), opaque `libraryOptions`
+*                 forwarded to the underlying library.
+*
+* @returns A JSON Schema object. `{}` when the schema cannot be
+*          converted (silent fallback — analytics / OpenAPI output
+*          still renders, just without schema detail for that field).
 *
 * @example
-* ```ts
-* import { zodConverter } from 'silgi/zod'
-* import { createSchemaRegistry, schemaToJsonSchema } from 'silgi'
-* import { z } from 'zod'
+*   import { zodConverter } from 'silgi/zod'
+*   import { createSchemaRegistry, schemaToJsonSchema } from 'silgi'
 *
-* const registry = createSchemaRegistry([zodConverter])
-* const json = schemaToJsonSchema(z.object({ name: z.string() }), 'input', registry)
-* ```
+*   const registry = createSchemaRegistry([zodConverter])
+*   const json = schemaToJsonSchema(MySchema, 'input', registry)
 *
 * @category Schema
 */
-function schemaToJsonSchema(schema, strategy = "input", registry) {
-	const std = schema?.["~standard"];
-	if (std?.jsonSchema?.input) try {
-		const result = std.jsonSchema.input({ target: "draft-2020-12" });
-		if (result && typeof result === "object") {
-			const { $schema: _, ...rest } = result;
-			return rest;
-		}
-	} catch {}
-	const vendor = typeof std?.vendor === "string" ? std.vendor : void 0;
-	if (vendor && registry) {
-		const converter = registry.get(vendor);
-		if (converter) try {
-			return converter.toJsonSchema(schema, { strategy });
-		} catch {}
-		else if (!_warnedVendors.has(vendor)) {
-			_warnedVendors.add(vendor);
-			console.warn(`[silgi] No schema converter registered for vendor "${vendor}". Pass schemaConverters: [${vendor}Converter] to silgi() to enable OpenAPI / analytics schema generation.`);
-		}
+function schemaToJsonSchema(schema, strategy = "input", registry, options = {}) {
+	const std = readStandardSlot(schema);
+	if (!std) return {};
+	const target = options.target ?? "draft-2020-12";
+	const native = callNativeJsonSchema(std, {
+		strategy,
+		target,
+		libraryOptions: options.libraryOptions
+	});
+	if (native !== null) return native;
+	const vendor = typeof std.vendor === "string" ? std.vendor : void 0;
+	if (!vendor || !registry) return {};
+	const converter = registry.get(vendor);
+	if (!converter) {
+		warnMissingConverter(vendor);
+		return {};
+	}
+	try {
+		return converter.toJsonSchema(schema, {
+			strategy,
+			target,
+			libraryOptions: options.libraryOptions
+		});
+	} catch {
+		return {};
 	}
-	return {};
 }
 //#endregion
 export { createSchemaRegistry, schemaToJsonSchema };

package/dist/core/serve.d.mts

@@ -5,52 +5,53 @@ import { Hookable } from "hookable";
 
 //#region src/core/serve.d.ts
 interface SilgiServer {
-  /** Server URL (e.g. "http://127.0.0.1:3000") */
+  /** Full server URL, e.g. `http://127.0.0.1:3000`. */
   readonly url: string;
-  /** Configured port */
+  /** Port the server actually bound to (may differ from requested when `0`). */
   readonly port: number;
-  /** Configured hostname */
+  /** Hostname the server bound to. */
   readonly hostname: string;
   /**
-   * Gracefully shut down the server.
+   * Gracefully shut the server down.
    *
-   * By default waits for in-flight requests to complete.
-   * Pass `true` to forcefully terminate all active connections immediately.
+   * Waits for in-flight requests by default. Pass `true` to drop
+   * active connections immediately.
    */
   close(forceCloseConnections?: boolean): Promise<void>;
 }
 interface ServeOptions {
-  /** URL path prefix (e.g. "/api"). Only requests matching this prefix are handled; others return 404. */
+  /** URL path prefix (e.g. `/api`). Requests outside the prefix 404. */
   basePath?: string;
   port?: number;
   hostname?: string;
-  /** Enable Scalar API Reference UI at /api/reference and /api/openapi.json */
+  /** Mount the Scalar API Reference UI at `/api/reference`. */
   scalar?: boolean | ScalarOptions;
-  /** Enable analytics dashboard at /api/analytics — requires `auth` to be set */
+  /** Mount the analytics dashboard at `/api/analytics` (requires `auth`). */
   analytics?: AnalyticsOptions;
   /**
    * WebSocket RPC configuration.
    *
-   * Defaults to auto-enabled when the router contains any subscription procedure.
-   * Pass `false` to disable, or an options object to fine-tune crossws (compression, keepalive, maxPayload).
+   * Auto-enabled when the router contains any subscription procedure.
+   * Pass `false` to disable, or an options object to tune crossws
+   * (compression, keepalive, maxPayload).
    */
   ws?: false | WSAdapterOptions;
-  /** Enable HTTP/2 (requires cert + key for TLS) */
+  /** TLS material for HTTP/2. When set, the server serves HTTPS. */
   http2?: {
     cert: string;
     key: string;
   };
   /**
-   * Graceful shutdown on SIGINT/SIGTERM signals.
+   * Graceful shutdown on `SIGINT` / `SIGTERM`.
    *
-   * - `true` (default): enables graceful shutdown with srvx defaults
-   * - `false`: disables automatic signal handling
-   * - `object`: fine-tune timeouts
+   *   - `true`   — enable with srvx defaults (recommended).
+   *   - `false`  — disable automatic signal handling.
+   *   - object   — fine-tune timeouts.
    *
    * @default true
    */
   gracefulShutdown?: boolean | {
-    /** Max time (ms) to wait for in-flight requests before force-closing */timeout?: number; /** Max time (ms) after graceful period before process.exit */
+    /** Max ms to wait for in-flight requests before force-closing. */timeout?: number; /** Max ms after graceful period before `process.exit`. */
     forceTimeout?: number;
   };
 }

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 };