silgi 0.53.0 → 0.53.2

package/dist/core/input.mjs

@@ -1,19 +1,45 @@
 import { SilgiError } from "./error.mjs";
 //#region src/core/input.ts
 /**
-* Request input parsing — JSON, MessagePack, devalue, query string.
+* Request input parsing
+* -----------------------
+*
+* Pulls the RPC input payload out of an incoming `Request` and returns
+* it in its decoded form. The shape of the input depends on how the
+* client chose to send it:
+*
+*   - `GET` / no-body  — JSON-encoded, URL-escaped, on `?data=` query.
+*   - `content-type: application/msgpack` — binary, via the msgpack codec.
+*   - `content-type: application/x-devalue` — text, via devalue.
+*   - anything else (typically JSON) — JSON body.
+*
+* Empty bodies always resolve to `undefined` so that a procedure with
+* no input, or one whose schema allows `undefined`, works without the
+* client having to send a payload at all. Malformed non-empty bodies
+* throw `BAD_REQUEST` with a message the client can show to a user.
+*/
+/**
+* The msgpack and devalue codecs are pulled in on first use so that a
+* handler that only ever sees JSON never pays the cost of loading
+* them. `Promise`-cached at module scope: once the first request
+* triggers the import, subsequent calls share the resolved module.
+*
+* Module-global is intentional and safe here — the cached value is a
+* reference to an immutable ES module, not user data. Two silgi
+* instances in the same process legitimately share it.
 */
-let _msgpack;
-let _devalue;
-/** Max allowed size for GET ?data= parameter (bytes). Prevents JSON bomb via URL. */
+let msgpackModule;
+let devalueModule;
+/** Max bytes permitted in the `?data=` query param. Shields against JSON-bomb payloads in a URL. */
 const MAX_QUERY_DATA_LENGTH = 8192;
 /**
 * Find the value of the `data=` query parameter by key, not by substring.
 *
-* The previous `indexOf('data=')` implementation matched `userdata=...`,
-* `xdata=...`, or any other key ending in `data` — silently returning the
-* wrong value. This scans for `data=` at a parameter boundary (either the
-* first param or after `&`).
+* A naive `searchStr.indexOf('data=')` matches `userdata=`, `mydata=`,
+* or any other key that merely ends in `data`, and silently returns
+* the wrong value. This scans for `data=` only at a parameter
+* boundary — i.e. at the start of the search string, or right after
+* an `&`.
 */
 function findDataParam(searchStr) {
 	let i = 0;
@@ -29,31 +55,47 @@ function findDataParam(searchStr) {
 	}
 	return null;
 }
-/** Parse request input from body or query string */
-async function parseInput(request, url, qMark) {
-	if (request.method === "GET" || !request.body) {
-		if (qMark !== -1) {
-			const encoded = findDataParam(url.slice(qMark + 1));
-			if (encoded !== null) {
-				if (encoded.length > MAX_QUERY_DATA_LENGTH) throw new SilgiError("BAD_REQUEST", { message: "Query data parameter too large" });
-				return JSON.parse(decodeURIComponent(encoded));
-			}
-		}
-		return;
-	}
-	const ct = request.headers.get("content-type");
-	if (ct) {
-		if (ct.includes("msgpack")) {
-			_msgpack ??= await import("../codec/msgpack.mjs");
-			const buf = new Uint8Array(await request.arrayBuffer());
-			return buf.length > 0 ? _msgpack.decode(buf) : void 0;
-		}
-		if (ct.includes("x-devalue")) {
-			_devalue ??= await import("../codec/devalue.mjs");
-			const text = await request.text();
-			return text ? _devalue.decode(text) : void 0;
-		}
-	}
+/**
+* Decode the `?data=` query param as JSON. Returns `undefined` when
+* the query is missing or has no `data=` field. Throws `BAD_REQUEST`
+* when the payload is oversized or unparsable.
+*/
+function decodeQueryInput(url, qMark) {
+	if (qMark === -1) return void 0;
+	const encoded = findDataParam(url.slice(qMark + 1));
+	if (encoded === null) return void 0;
+	if (encoded.length > MAX_QUERY_DATA_LENGTH) throw new SilgiError("BAD_REQUEST", { message: "Query data parameter too large" });
+	return JSON.parse(decodeURIComponent(encoded));
+}
+/**
+* Decode a MessagePack-encoded request body. Empty bodies resolve to
+* `undefined` (procedures with no input work without a payload).
+*/
+async function decodeMsgpackBody(request) {
+	msgpackModule ??= await import("../codec/msgpack.mjs");
+	const buf = new Uint8Array(await request.arrayBuffer());
+	return buf.length > 0 ? msgpackModule.decode(buf) : void 0;
+}
+/** Decode a devalue-encoded request body. Empty bodies resolve to `undefined`. */
+async function decodeDevalueBody(request) {
+	devalueModule ??= await import("../codec/devalue.mjs");
+	const text = await request.text();
+	return text ? devalueModule.decode(text) : void 0;
+}
+/**
+* Decode a JSON-encoded request body.
+*
+* Empty bodies resolve to `undefined` so the input schema sees the
+* same value whether or not the client sent a body at all. Malformed
+* non-empty bodies throw `BAD_REQUEST`.
+*
+* Why we `text()` first and then `JSON.parse` — instead of
+* `request.json()`: Bun's `request.json()` is a fast path, but it
+* throws a generic `SyntaxError` for **both** empty and malformed
+* bodies, so we cannot tell them apart. Reading text first keeps the
+* two cases distinct (and Bun's `text()` is also fast).
+*/
+async function decodeJsonBody(request) {
 	const text = await request.text();
 	if (!text) return void 0;
 	try {
@@ -62,5 +104,25 @@ async function parseInput(request, url, qMark) {
 		throw new SilgiError("BAD_REQUEST", { message: "Malformed JSON body" });
 	}
 }
+/**
+* Decode the input payload off a Fetch `Request`.
+*
+* @param request The incoming request.
+* @param url     The full request URL (reused by the caller — we avoid
+*                re-parsing it here).
+* @param qMark   Byte offset of the `?` in `url`, or `-1` when absent.
+*
+* @returns The decoded input value, or `undefined` when the request
+*          carries no payload.
+*/
+async function parseInput(request, url, qMark) {
+	if (request.method === "GET" || !request.body) return decodeQueryInput(url, qMark);
+	const contentType = request.headers.get("content-type");
+	if (contentType) {
+		if (contentType.includes("msgpack")) return decodeMsgpackBody(request);
+		if (contentType.includes("x-devalue")) return decodeDevalueBody(request);
+	}
+	return decodeJsonBody(request);
+}
 //#endregion
 export { parseInput };

package/dist/core/schema-converter.d.mts

@@ -2,7 +2,9 @@ import { AnySchema } from "./schema.mjs";
 
 //#region src/core/schema-converter.d.ts
 /**
- * JSON Schema subset used for OpenAPI / analytics output.
+ * JSON Schema subset used across silgi's OpenAPI and analytics output.
+ * Intentionally broad (`[key: string]: unknown`) so library-specific
+ * fields (e.g. Zod's `x-native-type`) pass through untouched.
  *
  * @category Schema
  */
@@ -22,54 +24,68 @@ interface JSONSchema {
   default?: unknown;
   [key: string]: unknown;
 }
+/**
+ * JSON Schema dialect passed through to the schema library. Matches the
+ * `target` field of the Standard JSON Schema spec. Unknown strings are
+ * allowed so new dialects can be threaded through without a silgi
+ * release; libraries that do not recognise the value should throw and
+ * the conversion falls back to an empty schema.
+ *
+ * @category Schema
+ */
+type JSONSchemaTarget = 'draft-2020-12' | 'draft-07' | 'openapi-3.0' | (string & {});
 /**
  * Options passed to a converter's `toJsonSchema` method.
  *
  * @category Schema
  */
 interface ConvertOptions {
+  /** `'input'` for pre-transform types, `'output'` for post-transform. */
   strategy: 'input' | 'output';
+  /** JSON Schema dialect to target. Defaults to `'draft-2020-12'`. */
+  target?: JSONSchemaTarget;
+  /** Opaque options the converter may forward to its underlying library. */
+  libraryOptions?: Record<string, unknown>;
 }
 /**
- * A converter that translates a specific Standard Schema vendor's schemas
- * into JSON Schema. Pass instances via `silgi({ schemaConverters: [...] })`.
+ * Fallback converter for a schema library that has not adopted the
+ * Standard JSON Schema extension yet. Pass instances via
+ * `silgi({ schemaConverters: [...] })`.
  *
  * @remarks
- * Implement this interface to add OpenAPI / analytics support for a custom
- * schema library. The `vendor` string must match the `~standard.vendor`
- * property reported by the schema library's Standard Schema implementation.
+ * Libraries that *do* implement the extension (Zod v4.2+, ArkType
+ * v2.1.28+, Valibot v1.2+) are handled without a converter — silgi
+ * calls their native `~standard.jsonSchema` directly. Write a converter
+ * only when you need to support a vendor that has not yet adopted the
+ * spec.
  *
  * @example
- * ```ts
- * import type { SchemaConverter } from 'silgi'
+ *   import type { SchemaConverter } from 'silgi'
  *
- * const myConverter: SchemaConverter = {
- *   vendor: 'my-lib',
- *   toJsonSchema(schema, opts) {
- *     return { type: 'string' }
- *   },
- * }
- * ```
+ *   const myConverter: SchemaConverter = {
+ *     vendor: 'my-lib',
+ *     toJsonSchema(schema, opts) {
+ *       return { type: 'string' }
+ *     },
+ *   }
  *
  * @category Schema
  */
 interface SchemaConverter {
-  /** The Standard Schema `~standard.vendor` string this converter handles (e.g. `"zod"`). */
+  /** Matches the `~standard.vendor` reported by the schema library. */
   vendor: string;
   /**
-   * Convert a schema to a JSON Schema object.
-   *
-   * @param schema - The schema to convert.
-   * @param opts - Conversion options including `strategy` (`'input'` | `'output'`).
-   * @returns A JSON Schema object. Return `{}` for unsupported/unknown schemas.
+   * Convert a schema to a JSON Schema object. Return `{}` for schemas
+   * the converter does not understand.
    */
   toJsonSchema(schema: AnySchema, opts: ConvertOptions): JSONSchema;
 }
 /**
- * A per-instance registry mapping vendor strings to their converters.
- *
- * Built by {@link createSchemaRegistry} and threaded through the handler
- * pipeline to scalar and analytics wrappers.
+ * Per-instance mapping of vendor string → fallback converter. Built by
+ * {@link createSchemaRegistry} and threaded through the handler pipeline
+ * to the scalar and analytics wrappers. Using `Map` gives O(1) lookup
+ * and keyed-by-vendor semantics that match the spec's own extension
+ * contract.
  *
  * @category Schema
  */
@@ -77,55 +93,44 @@ type SchemaRegistry = Map<string, SchemaConverter>;
 /**
  * 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
  */
 declare function createSchemaRegistry(converters?: SchemaConverter[]): SchemaRegistry;
 /**
- * Convert any Standard Schema to JSON Schema.
- *
- * @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).
- *
- * @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.
+ * Convert any Standard Schema to a JSON Schema object.
+ *
+ * @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
  */
-declare function schemaToJsonSchema(schema: AnySchema, strategy?: 'input' | 'output', registry?: SchemaRegistry): JSONSchema;
+declare function schemaToJsonSchema(schema: AnySchema, strategy?: 'input' | 'output', registry?: SchemaRegistry, options?: {
+  target?: JSONSchemaTarget;
+  libraryOptions?: Record<string, unknown>;
+}): JSONSchema;
 //#endregion
 export { ConvertOptions, JSONSchema, SchemaConverter, SchemaRegistry, createSchemaRegistry, schemaToJsonSchema };

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