silgi 0.52.2 → 0.53.1

package/dist/scalar.mjs

@@ -2,27 +2,43 @@ import { collectProcedures } from "./core/router-utils.mjs";
 import { schemaToJsonSchema } from "./core/schema-converter.mjs";
 //#region src/scalar.ts
 /**
-* Scalar API Reference — v2 OpenAPI integration.
+* Scalar API Reference + OpenAPI 3.1.0 generation
+* --------------------------------------------------
 *
-* Generates OpenAPI 3.1.0 spec from v2 RouterDef and serves
-* Scalar UI at /api/reference + spec at /api/openapi.json.
-*/
-/**
-* Generate OpenAPI 3.1.0 document from a v2 RouterDef.
+* Walks a silgi `RouterDef` and emits an OpenAPI 3.1.0 document, then
+* wraps a Fetch handler so that two additional routes are served:
+*
+*   `{basePath}/openapi.json`  — the raw spec.
+*   `{basePath}/reference`     — the Scalar API Reference UI (HTML).
+*
+* Every procedure becomes one OpenAPI operation per HTTP method. Input
+* schemas become `parameters[in:query]` for GET and `requestBody` for
+* the rest. Typed errors declared via `.$errors()` become typed response
+* shapes grouped by status code. Subscriptions are documented as SSE
+* endpoints (clients are still expected to use the native WebSocket
+* channel; the REST representation is for discoverability).
+*
+* The document respects per-procedure escape hatches in that order:
+*
+*   `route.spec` — either a function `(op) => op` or an object merge.
+*   `route.security` — per-op security override (or `false` for public).
+*   `route.successStatus` / `route.successDescription` — success shape.
 */
 /**
-* Convert `:param` and `:param(regex)` to OpenAPI `{param}` syntax.
-* Returns the converted path and an array of extracted param names.
+* Convert silgi's `:param`, `:param?`, `:param(regex)`, and `**`
+* route syntax to OpenAPI's `{param}` form, and collect the extracted
+* parameter names so callers can list them in the operation's
+* `parameters`.
 */
 function toOpenAPIPath(raw) {
 	const pathParams = [];
-	const httpPath = raw.replace(/:(\w+)\([^)]*\)/g, (_m, name) => {
+	const httpPath = raw.replace(/:(\w+)\([^)]*\)/g, (_match, name) => {
 		pathParams.push(name);
 		return `{${name}}`;
-	}).replace(/:(\w+)\?/g, (_m, name) => {
+	}).replace(/:(\w+)\?/g, (_match, name) => {
 		pathParams.push(name);
 		return `{${name}}`;
-	}).replace(/:(\w+)/g, (_m, name) => {
+	}).replace(/:(\w+)/g, (_match, name) => {
 		pathParams.push(name);
 		return `{${name}}`;
 	}).replace(/\/\*\*$/g, "/{path}").replace(/\/\*\*/g, "/{path}");
@@ -32,208 +48,286 @@ function toOpenAPIPath(raw) {
 		pathParams
 	};
 }
+const HTTP_METHODS = [
+	"get",
+	"put",
+	"post",
+	"delete",
+	"options",
+	"head",
+	"patch",
+	"trace"
+];
+/** Escape a string for inclusion in HTML attribute or text content. */
+function escapeHtml(s) {
+	return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/**
+* Turn a flat object schema into OpenAPI query-parameter entries. Used
+* for `GET` routes: the body is moved to the URL.
+*/
+function objectSchemaToParams(schema) {
+	if (schema.type !== "object" || !schema.properties) return [];
+	const required = new Set(schema.required ?? []);
+	return Object.entries(schema.properties).map(([name, propSchema]) => ({
+		name,
+		in: "query",
+		required: required.has(name),
+		schema: propSchema,
+		...propSchema.description ? { description: propSchema.description } : {}
+	}));
+}
+/**
+* Collect every typed error declared by a procedure *and* by any guard
+* it uses, keyed by HTTP status. Guard errors merge into the procedure
+* errors on a collision (procedure wins).
+*/
+function collectTypedErrors(proc) {
+	const guards = (proc.use ?? []).filter((m) => typeof m === "object" && m !== null && m.kind === "guard" && !!m.errors);
+	let merged = proc.errors ? { ...proc.errors } : null;
+	for (const guard of guards) merged = merged ? {
+		...merged,
+		...guard.errors
+	} : { ...guard.errors };
+	return merged;
+}
+/** Group typed errors by status code; each status may carry N codes. */
+function groupErrorsByStatus(errors, schemaToJson) {
+	const byStatus = /* @__PURE__ */ new Map();
+	for (const [code, rawDef] of Object.entries(errors)) {
+		const status = typeof rawDef === "number" ? rawDef : rawDef.status;
+		if (!byStatus.has(status)) byStatus.set(status, []);
+		const entry = { code };
+		if (typeof rawDef === "object" && rawDef !== null) {
+			const def = rawDef;
+			if (def.message) entry.message = def.message;
+			if (def.data) entry.schema = schemaToJson(def.data);
+		}
+		byStatus.get(status).push(entry);
+	}
+	return byStatus;
+}
+/** Build one response-object schema for a typed error. */
+function errorEntryToJsonSchema(entry, status) {
+	const schema = {
+		type: "object",
+		properties: {
+			code: {
+				const: entry.code,
+				type: "string"
+			},
+			status: {
+				const: status,
+				type: "integer"
+			},
+			message: {
+				type: "string",
+				...entry.message ? { default: entry.message } : {}
+			}
+		},
+		required: [
+			"code",
+			"status",
+			"message"
+		]
+	};
+	if (entry.schema) {
+		schema.properties.data = entry.schema;
+		schema.required.push("data");
+	}
+	return schema;
+}
+/**
+* Build one OpenAPI operation object (the value for `paths[p][method]`).
+*
+* Parameters are path-params first, then query-params for GETs. Body
+* goes on the request side for non-GETs. Responses are the declared
+* success status plus an auto-documented 400 (when input validation
+* exists) plus one slot per typed-error status.
+*/
+function buildOperation(args) {
+	const { proc, path, method, inputSchema, schemaToJson } = args;
+	const op = {
+		operationId: args.operationId,
+		responses: {}
+	};
+	if (args.tags?.length) op.tags = args.tags;
+	if (args.summary) op.summary = args.summary;
+	if (args.description) op.description = args.description;
+	if (args.deprecated) op.deprecated = true;
+	const route = proc.route;
+	if (route?.security === false) op.security = [];
+	else if (route?.security) op.security = route.security.map((s) => ({ [s]: [] }));
+	else if (args.globalSecurity) op.security = [{ auth: [] }];
+	const parameters = args.pathParams.map((name) => ({
+		name,
+		in: "path",
+		required: true,
+		schema: { type: "string" }
+	}));
+	if (inputSchema) if (method === "get") parameters.push(...objectSchemaToParams(inputSchema));
+	else op.requestBody = {
+		required: true,
+		content: { "application/json": { schema: inputSchema } }
+	};
+	if (parameters.length > 0) op.parameters = parameters;
+	const responses = op.responses;
+	const successStatus = route?.successStatus ?? 200;
+	const successDesc = route?.successDescription ?? "Successful response";
+	if (proc.type === "subscription") {
+		const outputSchema = proc.output ? schemaToJson(proc.output, "output") : { type: "string" };
+		responses[String(successStatus)] = {
+			description: "SSE event stream",
+			content: { "text/event-stream": { schema: {
+				type: "string",
+				description: `Each line: data: ${JSON.stringify(outputSchema)}`
+			} } }
+		};
+	} else if (proc.output) responses[String(successStatus)] = {
+		description: successDesc,
+		content: { "application/json": { schema: schemaToJson(proc.output, "output") } }
+	};
+	else responses[String(successStatus)] = { description: successDesc };
+	if (proc.input) responses["400"] = {
+		description: "BAD_REQUEST — input validation failed",
+		content: { "application/json": { schema: {
+			type: "object",
+			properties: {
+				code: {
+					const: "BAD_REQUEST",
+					type: "string"
+				},
+				status: {
+					const: 400,
+					type: "integer"
+				},
+				message: { type: "string" },
+				data: {
+					type: "object",
+					properties: { issues: { type: "array" } }
+				}
+			},
+			required: [
+				"code",
+				"status",
+				"message"
+			]
+		} } }
+	};
+	const typedErrors = collectTypedErrors(proc);
+	if (typedErrors) {
+		const byStatus = groupErrorsByStatus(typedErrors, schemaToJson);
+		for (const [status, entries] of byStatus) {
+			const schemas = entries.map((entry) => errorEntryToJsonSchema(entry, status));
+			responses[String(status)] = {
+				description: entries.map((e) => e.code).join(" | "),
+				content: { "application/json": { schema: schemas.length === 1 ? schemas[0] : { oneOf: schemas } } }
+			};
+		}
+	}
+	let finalOp = op;
+	if (route?.spec) finalOp = typeof route.spec === "function" ? route.spec(op) : {
+		...op,
+		...route.spec
+	};
+	return finalOp;
+}
+/** Build the `info` field of the doc, plus optional `servers` / `externalDocs`. */
+function buildDocHeader(options) {
+	const info = {
+		title: options.title ?? "Silgi API",
+		version: options.version ?? "1.0.0"
+	};
+	if (options.description) info.description = options.description;
+	if (options.contact) info.contact = options.contact;
+	if (options.license) info.license = options.license;
+	const extras = {};
+	if (options.servers?.length) extras.servers = options.servers;
+	if (options.externalDocs) extras.externalDocs = options.externalDocs;
+	return {
+		info,
+		extras
+	};
+}
+/**
+* Translate our compact `security` option into the OpenAPI
+* `components.securitySchemes` shape. The key under which the scheme
+* lives is hard-coded as `auth` — per-operation `security` values
+* reference it by that name.
+*/
+function buildSecurityScheme(security) {
+	const scheme = { type: security.type };
+	if (security.type === "http") {
+		scheme.scheme = security.scheme ?? "bearer";
+		if (security.bearerFormat) scheme.bearerFormat = security.bearerFormat;
+	} else if (security.type === "apiKey") {
+		scheme.in = security.in ?? "header";
+		scheme.name = security.name ?? "x-api-key";
+	}
+	if (security.description) scheme.description = security.description;
+	return { securitySchemes: { auth: scheme } };
+}
+/**
+* Generate an OpenAPI 3.1.0 document for a `RouterDef`.
+*
+* The document is a plain object and can be re-serialized, cached,
+* piped into any OpenAPI consumer (codegen, docs site, validators). We
+* do not return a typed `OpenAPIV3_1.Document` because the typings in
+* the ecosystem are noisy; downstream consumers usually only care
+* about a handful of keys anyway.
+*/
 function generateOpenAPI(router, options = {}, basePath = "", registry) {
-	const schemaToJsonSchema$1 = (schema, strategy = "input") => schemaToJsonSchema(schema, strategy, registry);
+	const schemaToJson = (schema, strategy = "input") => schemaToJsonSchema(schema, strategy, registry);
 	const paths = {};
 	const tags = /* @__PURE__ */ new Map();
 	collectProcedures(router, (path, proc) => {
 		const route = proc.route;
 		const { httpPath: routePath, pathParams } = toOpenAPIPath(route?.path ?? "/" + path.join("/"));
 		const httpPath = basePath ? basePath.replace(/\/$/, "") + routePath : routePath;
-		const rawMethod = route?.method?.toLowerCase() ?? "post";
-		const methods = rawMethod === "*" ? [
-			"get",
-			"put",
-			"post",
-			"delete",
-			"options",
-			"head",
-			"patch",
-			"trace"
-		] : [rawMethod];
+		const declaredMethod = route?.method?.toLowerCase() ?? "post";
+		const methods = declaredMethod === "*" ? [...HTTP_METHODS] : [declaredMethod];
 		const baseOperationId = route?.operationId ?? path.join("_");
 		const opTags = route?.tags ?? (path.length > 1 ? [path[0]] : void 0);
 		if (opTags) {
-			for (const t of opTags) if (!tags.has(t)) tags.set(t, {});
+			for (const tag of opTags) if (!tags.has(tag)) tags.set(tag, {});
 		}
 		let description = route?.description;
 		if (proc.type === "subscription") {
 			const wsNote = "Streams over WebSocket (`ws://…/_ws`). Send `{ id, path: \"" + path.join("/") + "\", input }` as JSON.";
 			description = description ? `${description}\n\n${wsNote}` : wsNote;
 		}
-		const operation = {
-			operationId: baseOperationId,
-			tags: opTags,
-			summary: route?.summary,
-			description,
-			deprecated: route?.deprecated || void 0,
-			responses: {}
-		};
-		if (!operation.summary) delete operation.summary;
-		if (!operation.description) delete operation.description;
-		if (!operation.deprecated) delete operation.deprecated;
-		if (!operation.tags) delete operation.tags;
-		if (route?.security === false) operation.security = [];
-		else if (route?.security) operation.security = route.security.map((s) => ({ [s]: [] }));
-		else if (options.security) operation.security = [{ auth: [] }];
-		const inputSchema = proc.input ? schemaToJsonSchema$1(proc.input, "input") : null;
-		const successStatus = route?.successStatus ?? 200;
-		const successDesc = route?.successDescription ?? "Successful response";
-		const guards = (proc.use ?? []).filter((m) => m.kind === "guard" && m.errors);
-		let allErrors = proc.errors ? { ...proc.errors } : null;
-		for (const guard of guards) {
-			const ge = guard.errors;
-			if (ge) allErrors = allErrors ? {
-				...allErrors,
-				...ge
-			} : { ...ge };
-		}
+		const inputSchema = proc.input ? schemaToJson(proc.input, "input") : null;
 		paths[httpPath] ??= {};
 		for (const method of methods) {
-			const op = {
-				...operation,
-				responses: {}
-			};
-			if (methods.length > 1) op.operationId = `${baseOperationId}_${method}`;
-			const params = [];
-			for (const p of pathParams) params.push({
-				name: p,
-				in: "path",
-				required: true,
-				schema: { type: "string" }
+			const op = buildOperation({
+				proc,
+				path,
+				method,
+				operationId: methods.length > 1 ? `${baseOperationId}_${method}` : baseOperationId,
+				tags: opTags,
+				summary: route?.summary,
+				description,
+				deprecated: route?.deprecated || void 0,
+				pathParams,
+				inputSchema,
+				schemaToJson,
+				globalSecurity: options.security
 			});
-			if (inputSchema) if (method === "get") params.push(...objectSchemaToParams(inputSchema));
-			else op.requestBody = {
-				required: true,
-				content: { "application/json": { schema: inputSchema } }
-			};
-			if (params.length > 0) op.parameters = params;
-			if (proc.type === "subscription") {
-				const outputSchema = proc.output ? schemaToJsonSchema$1(proc.output, "output") : { type: "string" };
-				op.responses[String(successStatus)] = {
-					description: "SSE event stream",
-					content: { "text/event-stream": { schema: {
-						type: "string",
-						description: `Each line: data: ${JSON.stringify(outputSchema)}`
-					} } }
-				};
-			} else if (proc.output) op.responses[String(successStatus)] = {
-				description: successDesc,
-				content: { "application/json": { schema: schemaToJsonSchema$1(proc.output, "output") } }
-			};
-			else op.responses[String(successStatus)] = { description: successDesc };
-			if (proc.input) op.responses["400"] = {
-				description: "BAD_REQUEST — input validation failed",
-				content: { "application/json": { schema: {
-					type: "object",
-					properties: {
-						code: {
-							const: "BAD_REQUEST",
-							type: "string"
-						},
-						status: {
-							const: 400,
-							type: "integer"
-						},
-						message: { type: "string" },
-						data: {
-							type: "object",
-							properties: { issues: { type: "array" } }
-						}
-					},
-					required: [
-						"code",
-						"status",
-						"message"
-					]
-				} } }
-			};
-			if (allErrors) {
-				const byStatus = /* @__PURE__ */ new Map();
-				for (const [code, def] of Object.entries(allErrors)) {
-					const status = typeof def === "number" ? def : def.status;
-					if (!byStatus.has(status)) byStatus.set(status, []);
-					const entry = { code };
-					if (typeof def === "object") {
-						if (def.message) entry.message = def.message;
-						if (def.data) entry.schema = schemaToJsonSchema$1(def.data);
-					}
-					byStatus.get(status).push(entry);
-				}
-				for (const [status, errors] of byStatus) {
-					const errorSchemas = errors.map((e) => {
-						const s = {
-							type: "object",
-							properties: {
-								code: {
-									const: e.code,
-									type: "string"
-								},
-								status: {
-									const: status,
-									type: "integer"
-								},
-								message: {
-									type: "string",
-									...e.message ? { default: e.message } : {}
-								}
-							},
-							required: [
-								"code",
-								"status",
-								"message"
-							]
-						};
-						if (e.schema) {
-							s.properties.data = e.schema;
-							s.required.push("data");
-						}
-						return s;
-					});
-					op.responses[String(status)] = {
-						description: errors.map((e) => e.code).join(" | "),
-						content: { "application/json": { schema: errorSchemas.length === 1 ? errorSchemas[0] : { oneOf: errorSchemas } } }
-					};
-				}
-			}
-			let finalOp = op;
-			if (route?.spec) if (typeof route.spec === "function") finalOp = route.spec(finalOp);
-			else finalOp = {
-				...finalOp,
-				...route.spec
-			};
-			paths[httpPath][method] = finalOp;
+			paths[httpPath][method] = op;
 		}
 	});
+	const { info, extras } = buildDocHeader(options);
 	const doc = {
 		openapi: "3.1.0",
-		info: {
-			title: options.title ?? "Silgi API",
-			version: options.version ?? "1.0.0",
-			...options.description ? { description: options.description } : {},
-			...options.contact ? { contact: options.contact } : {},
-			...options.license ? { license: options.license } : {}
-		},
-		paths
+		info,
+		paths,
+		...extras
 	};
-	if (options.servers?.length) doc.servers = options.servers;
-	if (options.externalDocs) doc.externalDocs = options.externalDocs;
 	if (tags.size > 0) doc.tags = [...tags.entries()].map(([name, meta]) => ({
 		name,
 		...meta.description ? { description: meta.description } : {}
 	}));
-	if (options.security) {
-		const scheme = { type: options.security.type };
-		if (options.security.type === "http") {
-			scheme.scheme = options.security.scheme ?? "bearer";
-			if (options.security.bearerFormat) scheme.bearerFormat = options.security.bearerFormat;
-		} else if (options.security.type === "apiKey") {
-			scheme.in = options.security.in ?? "header";
-			scheme.name = options.security.name ?? "x-api-key";
-		}
-		if (options.security.description) scheme.description = options.security.description;
-		doc.components = { securitySchemes: { auth: scheme } };
-	}
+	if (options.security) doc.components = buildSecurityScheme(options.security);
 	return doc;
 }
 const SCALAR_CDN_SOURCES = {
@@ -241,6 +335,10 @@ const SCALAR_CDN_SOURCES = {
 	unpkg: "https://unpkg.com/@scalar/api-reference",
 	local: "/__silgi/scalar.js"
 };
+/**
+* Render the minimal HTML shell the Scalar UI needs. The UI itself is
+* a single script that reads the `data-url` attribute to pull the spec.
+*/
 function scalarHTML(specUrl, options = {}) {
 	const title = escapeHtml(options.title ?? "Silgi API");
 	const safeUrl = escapeHtml(specUrl);
@@ -258,23 +356,16 @@ function scalarHTML(specUrl, options = {}) {
 </body>
 </html>`;
 }
-function escapeHtml(s) {
-	return s.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
-}
-function objectSchemaToParams(schema) {
-	if (schema.type !== "object" || !schema.properties) return [];
-	const required = new Set(schema.required ?? []);
-	return Object.entries(schema.properties).map(([name, propSchema]) => ({
-		name,
-		in: "query",
-		required: required.has(name),
-		schema: propSchema,
-		...propSchema.description ? { description: propSchema.description } : {}
-	}));
-}
 /**
-* Wrap a fetch handler to serve Scalar API Reference at /api/reference and /api/openapi.json.
-* Scalar routes are intercepted before the handler — zero overhead for normal requests.
+* Wrap a Fetch handler so that two extra paths are served:
+*
+*   `{basePath}/reference`    — the Scalar UI.
+*   `{basePath}/openapi.json` — the spec.
+*
+* The generated spec is JSON-stringified once at wrap time so every
+* hit to `/openapi.json` is a constant-cost `new Response(cachedJson)`.
+* Requests that do not match either path fall through to the inner
+* handler with zero overhead.
 */
 function wrapWithScalar(handler, routerDef, options = {}, prefix = "/api", registry) {
 	const normPrefix = (prefix.startsWith("/") ? prefix : "/" + prefix).replace(/\/+$/, "");

package/dist/silgi.d.mts

@@ -85,6 +85,41 @@ interface SilgiConfig<TCtx extends Record<string, unknown>> {
    * ```
    */
   schemaConverters?: SchemaConverter[];
+  /**
+   * Root-level wrap middleware applied to every procedure in the router.
+   *
+   * @remarks
+   * Each entry must be created via `instance.wrap(fn)`. Root wraps run
+   * as the outermost layer of the onion: root wraps → route-level
+   * `.$use()` guards/wraps → resolver. Use this for concerns that must
+   * apply to every route (tenant scoping, `AsyncLocalStorage` setup,
+   * trace propagation), where missing one route would be a bug.
+   *
+   * Root wraps cannot mutate the context type — use a route-level
+   * `$use(guard)` for that. The ambient context passed to `next()` is
+   * `TBaseCtx`, identical to the one seen by route-level wraps.
+   *
+   * Applies to every procedure reachable through `handler()`,
+   * `createCaller()`, and HTTP/cron task invocation. Task `dispatch()`
+   * (programmatic, bypasses the pipeline) is not wrapped.
+   *
+   * @example
+   * ```ts
+   * const tenantScopeWrap: WrapDef = {
+   *   kind: 'wrap',
+   *   fn: (ctx, next) => tenantScope.run({ orgId: ctx.user.orgId }, next),
+   * }
+   *
+   * const s = silgi({
+   *   context: (req) => ({ db, user: readUser(req) }),
+   *   wraps: [tenantScopeWrap],
+   * })
+   * ```
+   *
+   * For convenience you can also create wraps with the standalone
+   * helper or from another silgi instance's `wrap()` method.
+   */
+  wraps?: WrapDef<TCtx>[];
   /**
    * Storage configuration — mount drivers by path prefix.
    *