silgi 0.51.7 → 0.51.8

package/dist/core/error.d.mts

@@ -1,7 +1,37 @@
 //#region src/core/error.d.ts
 /**
- * SilgiError — unified RPC error with cross-realm instanceof.
+ * SilgiError — unified RPC error type for the Silgi framework.
+ *
+ * @remarks
+ * Every error thrown through the Silgi request pipeline is either a
+ * `SilgiError` or is wrapped into one by {@link toSilgiError} before it
+ * reaches the wire. The class carries an HTTP `status`, a machine-readable
+ * `code`, optional structured `data`, and a `defined` flag that signals
+ * whether the error was deliberately declared with `$errors()` (safe to
+ * expose verbatim to clients) or is an internal fault that should be
+ * redacted.
+ *
+ * ### Cross-realm `instanceof`
+ * `SilgiError` overrides `Symbol.hasInstance` to check a brand symbol
+ * (`Symbol.for('silgi.error.brand.v1')`) stamped on `SilgiError.prototype`.
+ * Because `Symbol.for` resolves through the global symbol registry shared
+ * across all V8 realms (worker threads, `node:vm` contexts), `instanceof
+ * SilgiError` works even when the `SilgiError` class used to construct the
+ * error originated in a different realm.
+ *
+ * ### Subclassing
+ * User-defined subclasses are fully supported:
+ * ```ts
+ * class AuthError extends SilgiError<'UNAUTHORIZED'> {
+ *   constructor() { super('UNAUTHORIZED', { status: 401 }) }
+ * }
+ * ```
+ * The brand is inherited through the prototype chain automatically — no
+ * extra steps are required in the subclass constructor.
+ *
+ * @category Errors
  */
+/** Well-known HTTP error codes with their default status and message. */
 declare const COMMON_ERRORS: Readonly<{
   readonly BAD_REQUEST: {
     readonly status: 400;
@@ -73,6 +103,7 @@ declare const COMMON_ERRORS: Readonly<{
   };
 }>;
 type SilgiErrorCode = keyof typeof COMMON_ERRORS | (string & {});
+/** Options passed to the {@link SilgiError} constructor. */
 interface SilgiErrorOptions<TData = unknown> {
   status?: number;
   message?: string;
@@ -80,6 +111,7 @@ interface SilgiErrorOptions<TData = unknown> {
   cause?: unknown;
   defined?: boolean;
 }
+/** Wire-format representation of a {@link SilgiError}, safe to JSON-stringify and transmit to clients. */
 interface SilgiErrorJSON<TCode extends string = string, TData = unknown> {
   defined: boolean;
   code: TCode;
@@ -87,18 +119,167 @@ interface SilgiErrorJSON<TCode extends string = string, TData = unknown> {
   message: string;
   data: TData;
 }
+/**
+ * A typed, serializable RPC error.
+ *
+ * @typeParam TCode - String literal type for the error code.
+ * @typeParam TData - Shape of the optional structured data payload.
+ *
+ * @example
+ * ```ts
+ * throw new SilgiError('NOT_FOUND', { message: 'User 42 not found' })
+ * ```
+ *
+ * @example Checking for Silgi errors in a catch block
+ * ```ts
+ * import { isSilgiError } from 'silgi'
+ *
+ * try {
+ *   await client.users.get({ id: '42' })
+ * } catch (e) {
+ *   if (isSilgiError(e)) {
+ *     console.error(e.code, e.status)
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link isSilgiError} Preferred type-guard over `instanceof` for cross-realm safety.
+ * @see {@link toSilgiError} Wraps any unknown error into a `SilgiError`.
+ * @see {@link fromSilgiErrorJSON} Reconstructs a `SilgiError` from a wire-format JSON object.
+ *
+ * @remarks
+ * **Do not mutate the prototype brand.** Removing or overwriting
+ * `SilgiError.prototype[Symbol.for('silgi.error.brand.v1')]` will break
+ * cross-realm detection for all instances in the current realm.
+ *
+ * **Subclass note.** If a subclass overrides the constructor and somehow
+ * replaces `Object.getPrototypeOf(this)` before construction completes,
+ * the inherited brand may be severed. This is an extremely unusual pattern
+ * and is not supported.
+ *
+ * @category Errors
+ */
 declare class SilgiError<TCode extends string = string, TData = unknown> extends Error {
+  /** Machine-readable error code (e.g. `'NOT_FOUND'`). */
   readonly code: TCode;
+  /** HTTP status code associated with this error. */
   readonly status: number;
+  /** Optional structured payload carrying additional error context. */
   readonly data: TData;
+  /**
+   * `true` when this error was declared via `$errors()` and is safe to
+   * expose verbatim to clients; `false` for internal faults.
+   */
   readonly defined: boolean;
+  /**
+   * @param code - Machine-readable error code. Well-known codes (e.g.
+   *   `'NOT_FOUND'`, `'UNAUTHORIZED'`) resolve default `status` and
+   *   `message` values automatically.
+   * @param options - Override `status`, `message`, `data`, `cause`, and
+   *   `defined` fields.
+   */
   constructor(code: TCode, options?: SilgiErrorOptions<TData>);
+  /**
+   * Serialize this error to a plain object suitable for JSON transmission.
+   *
+   * @remarks
+   * The brand symbol (`Symbol.for('silgi.error.brand.v1')`) is
+   * non-enumerable and lives on the prototype, so it is never included
+   * in the output of `toJSON()` or `JSON.stringify()`.
+   *
+   * @returns A {@link SilgiErrorJSON} with `defined`, `code`, `status`,
+   *   `message`, and `data` fields — and nothing else.
+   */
   toJSON(): SilgiErrorJSON<TCode, TData>;
+  /**
+   * Custom `instanceof` check that works across V8 realms.
+   *
+   * @remarks
+   * Checks for the presence of `Symbol.for('silgi.error.brand.v1')` on
+   * the candidate value's prototype chain. Because `Symbol.for` resolves
+   * through the global symbol registry (shared across all realms), this
+   * correctly identifies `SilgiError` instances that were constructed in a
+   * worker thread or `node:vm` context.
+   *
+   * This is an O(1) property lookup — no prototype walk is performed.
+   *
+   * @param instance - The value to test.
+   * @returns `true` if `instance` carries the Silgi error brand.
+   */
   static [Symbol.hasInstance](instance: unknown): boolean;
 }
+/**
+ * Type guard that returns `true` when `e` is a {@link SilgiError}.
+ *
+ * @remarks
+ * Prefer this function over `instanceof SilgiError` in application code.
+ * The brand check is realm-transparent and does not depend on the
+ * `SilgiError` class reference being the exact same object across module
+ * boundaries. It is also marginally faster than `instanceof` because it
+ * skips the `[Symbol.hasInstance]` dispatch and reads the brand directly.
+ *
+ * @param e - Any value — typically a caught `unknown` error.
+ * @returns `true` if `e` carries the `Symbol.for('silgi.error.brand.v1')` brand.
+ *
+ * @example
+ * ```ts
+ * catch (e) {
+ *   if (isSilgiError(e)) {
+ *     // e is SilgiError — access e.code, e.status, e.data safely
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link SilgiError}
+ * @category Errors
+ */
+declare function isSilgiError(e: unknown): e is SilgiError;
+/**
+ * Returns `true` when `error` is a {@link SilgiError} that was explicitly
+ * declared with `$errors()` (i.e. `defined === true`).
+ *
+ * @remarks
+ * Defined errors are safe to expose verbatim to clients; undefined errors
+ * should be redacted to a generic `INTERNAL_SERVER_ERROR` message.
+ *
+ * @param error - Any value.
+ * @returns A type predicate narrowing to `TError & SilgiError & \{ defined: true \}`.
+ *
+ * @example
+ * ```ts
+ * if (isDefinedError(e)) {
+ *   // e.defined === true — forward error details to the client
+ * }
+ * ```
+ *
+ * @see {@link isSilgiError}
+ * @category Errors
+ */
 declare function isDefinedError<TError>(error: TError): error is TError & SilgiError & {
   defined: true;
 };
+/**
+ * Coerce any caught value into a {@link SilgiError}.
+ *
+ * @remarks
+ * If `error` is already a `SilgiError` it is returned unchanged.
+ * Any other value (plain `Error`, string, etc.) is wrapped in an
+ * `INTERNAL_SERVER_ERROR` with the original value preserved as `cause`.
+ * The wrapper message is intentionally generic to avoid leaking internal
+ * details to clients.
+ *
+ * @param error - Any value — typically the argument of a `catch` block.
+ * @returns The original `SilgiError`, or a new `SilgiError('INTERNAL_SERVER_ERROR')`.
+ *
+ * @example
+ * ```ts
+ * const e = toSilgiError(err)
+ * res.status(e.status).json(e.toJSON())
+ * ```
+ *
+ * @see {@link isSilgiError}
+ * @category Errors
+ */
 declare function toSilgiError(error: unknown): SilgiError;
 //#endregion
-export { SilgiError, SilgiErrorCode, SilgiErrorJSON, SilgiErrorOptions, isDefinedError, toSilgiError };
+export { SilgiError, SilgiErrorCode, SilgiErrorJSON, SilgiErrorOptions, isDefinedError, isSilgiError, toSilgiError };

package/dist/core/error.mjs

@@ -1,7 +1,37 @@
 //#region src/core/error.ts
 /**
-* SilgiError — unified RPC error with cross-realm instanceof.
+* SilgiError — unified RPC error type for the Silgi framework.
+*
+* @remarks
+* Every error thrown through the Silgi request pipeline is either a
+* `SilgiError` or is wrapped into one by {@link toSilgiError} before it
+* reaches the wire. The class carries an HTTP `status`, a machine-readable
+* `code`, optional structured `data`, and a `defined` flag that signals
+* whether the error was deliberately declared with `$errors()` (safe to
+* expose verbatim to clients) or is an internal fault that should be
+* redacted.
+*
+* ### Cross-realm `instanceof`
+* `SilgiError` overrides `Symbol.hasInstance` to check a brand symbol
+* (`Symbol.for('silgi.error.brand.v1')`) stamped on `SilgiError.prototype`.
+* Because `Symbol.for` resolves through the global symbol registry shared
+* across all V8 realms (worker threads, `node:vm` contexts), `instanceof
+* SilgiError` works even when the `SilgiError` class used to construct the
+* error originated in a different realm.
+*
+* ### Subclassing
+* User-defined subclasses are fully supported:
+* ```ts
+* class AuthError extends SilgiError<'UNAUTHORIZED'> {
+*   constructor() { super('UNAUTHORIZED', { status: 401 }) }
+* }
+* ```
+* The brand is inherited through the prototype chain automatically — no
+* extra steps are required in the subclass constructor.
+*
+* @category Errors
 */
+/** Well-known HTTP error codes with their default status and message. */
 const COMMON_ERRORS = /* @__PURE__ */ Object.freeze({
 	BAD_REQUEST: {
 		status: 400,
@@ -72,13 +102,81 @@ const COMMON_ERRORS = /* @__PURE__ */ Object.freeze({
 		message: "Gateway Timeout"
 	}
 });
-const REGISTRY_KEY = Symbol.for("silgi.error.registry");
-const registry = globalThis[REGISTRY_KEY] ??= /* @__PURE__ */ new WeakSet();
+/**
+* Non-enumerable brand symbol stamped on `SilgiError.prototype`.
+*
+* Using `Symbol.for` ensures the key is resolved from the global symbol
+* registry, which is shared across all V8 realms (worker threads,
+* `node:vm` contexts). This makes cross-realm `instanceof` and
+* {@link isSilgiError} checks reliable without any module-level WeakSet
+* or `globalThis` state.
+*
+* The `.brand.v1` suffix prevents accidental collision with user code that
+* might use the shorter `Symbol.for('silgi.error')` for unrelated purposes,
+* and reserves the `v1` slot for a future migration if brand semantics change.
+*
+* @internal
+*/
+const BRAND = Symbol.for("silgi.error.brand.v1");
+/**
+* A typed, serializable RPC error.
+*
+* @typeParam TCode - String literal type for the error code.
+* @typeParam TData - Shape of the optional structured data payload.
+*
+* @example
+* ```ts
+* throw new SilgiError('NOT_FOUND', { message: 'User 42 not found' })
+* ```
+*
+* @example Checking for Silgi errors in a catch block
+* ```ts
+* import { isSilgiError } from 'silgi'
+*
+* try {
+*   await client.users.get({ id: '42' })
+* } catch (e) {
+*   if (isSilgiError(e)) {
+*     console.error(e.code, e.status)
+*   }
+* }
+* ```
+*
+* @see {@link isSilgiError} Preferred type-guard over `instanceof` for cross-realm safety.
+* @see {@link toSilgiError} Wraps any unknown error into a `SilgiError`.
+* @see {@link fromSilgiErrorJSON} Reconstructs a `SilgiError` from a wire-format JSON object.
+*
+* @remarks
+* **Do not mutate the prototype brand.** Removing or overwriting
+* `SilgiError.prototype[Symbol.for('silgi.error.brand.v1')]` will break
+* cross-realm detection for all instances in the current realm.
+*
+* **Subclass note.** If a subclass overrides the constructor and somehow
+* replaces `Object.getPrototypeOf(this)` before construction completes,
+* the inherited brand may be severed. This is an extremely unusual pattern
+* and is not supported.
+*
+* @category Errors
+*/
 var SilgiError = class extends Error {
+	/** Machine-readable error code (e.g. `'NOT_FOUND'`). */
 	code;
+	/** HTTP status code associated with this error. */
 	status;
+	/** Optional structured payload carrying additional error context. */
 	data;
+	/**
+	* `true` when this error was declared via `$errors()` and is safe to
+	* expose verbatim to clients; `false` for internal faults.
+	*/
 	defined;
+	/**
+	* @param code - Machine-readable error code. Well-known codes (e.g.
+	*   `'NOT_FOUND'`, `'UNAUTHORIZED'`) resolve default `status` and
+	*   `message` values automatically.
+	* @param options - Override `status`, `message`, `data`, `cause`, and
+	*   `defined` fields.
+	*/
 	constructor(code, options = {}) {
 		const defaults = COMMON_ERRORS[code];
 		const message = options.message ?? defaults?.message ?? code;
@@ -89,6 +187,17 @@ var SilgiError = class extends Error {
 		this.defined = options.defined ?? false;
 		this.name = "SilgiError";
 	}
+	/**
+	* Serialize this error to a plain object suitable for JSON transmission.
+	*
+	* @remarks
+	* The brand symbol (`Symbol.for('silgi.error.brand.v1')`) is
+	* non-enumerable and lives on the prototype, so it is never included
+	* in the output of `toJSON()` or `JSON.stringify()`.
+	*
+	* @returns A {@link SilgiErrorJSON} with `defined`, `code`, `status`,
+	*   `message`, and `data` fields — and nothing else.
+	*/
 	toJSON() {
 		return {
 			defined: this.defined,
@@ -98,35 +207,169 @@ var SilgiError = class extends Error {
 			data: this.data
 		};
 	}
-	static {
-		registry.add(this);
-	}
+	/**
+	* Custom `instanceof` check that works across V8 realms.
+	*
+	* @remarks
+	* Checks for the presence of `Symbol.for('silgi.error.brand.v1')` on
+	* the candidate value's prototype chain. Because `Symbol.for` resolves
+	* through the global symbol registry (shared across all realms), this
+	* correctly identifies `SilgiError` instances that were constructed in a
+	* worker thread or `node:vm` context.
+	*
+	* This is an O(1) property lookup — no prototype walk is performed.
+	*
+	* @param instance - The value to test.
+	* @returns `true` if `instance` carries the Silgi error brand.
+	*/
 	static [Symbol.hasInstance](instance) {
-		if (typeof instance !== "object" || instance === null) return false;
-		let proto = Object.getPrototypeOf(instance);
-		while (proto) {
-			if (proto.constructor && registry.has(proto.constructor)) return true;
-			proto = Object.getPrototypeOf(proto);
-		}
-		return false;
+		return typeof instance === "object" && instance !== null && instance[BRAND] === true;
 	}
 };
+Reflect.defineProperty(SilgiError.prototype, BRAND, {
+	value: true,
+	enumerable: false,
+	writable: false,
+	configurable: false
+});
+/**
+* Type guard that returns `true` when `e` is a {@link SilgiError}.
+*
+* @remarks
+* Prefer this function over `instanceof SilgiError` in application code.
+* The brand check is realm-transparent and does not depend on the
+* `SilgiError` class reference being the exact same object across module
+* boundaries. It is also marginally faster than `instanceof` because it
+* skips the `[Symbol.hasInstance]` dispatch and reads the brand directly.
+*
+* @param e - Any value — typically a caught `unknown` error.
+* @returns `true` if `e` carries the `Symbol.for('silgi.error.brand.v1')` brand.
+*
+* @example
+* ```ts
+* catch (e) {
+*   if (isSilgiError(e)) {
+*     // e is SilgiError — access e.code, e.status, e.data safely
+*   }
+* }
+* ```
+*
+* @see {@link SilgiError}
+* @category Errors
+*/
+function isSilgiError(e) {
+	return typeof e === "object" && e !== null && e[BRAND] === true;
+}
+/**
+* Returns `true` when `error` is a {@link SilgiError} that was explicitly
+* declared with `$errors()` (i.e. `defined === true`).
+*
+* @remarks
+* Defined errors are safe to expose verbatim to clients; undefined errors
+* should be redacted to a generic `INTERNAL_SERVER_ERROR` message.
+*
+* @param error - Any value.
+* @returns A type predicate narrowing to `TError & SilgiError & \{ defined: true \}`.
+*
+* @example
+* ```ts
+* if (isDefinedError(e)) {
+*   // e.defined === true — forward error details to the client
+* }
+* ```
+*
+* @see {@link isSilgiError}
+* @category Errors
+*/
 function isDefinedError(error) {
-	return error instanceof SilgiError && error.defined === true;
+	return isSilgiError(error) && error.defined === true;
 }
+/**
+* Coerce any caught value into a {@link SilgiError}.
+*
+* @remarks
+* If `error` is already a `SilgiError` it is returned unchanged.
+* Any other value (plain `Error`, string, etc.) is wrapped in an
+* `INTERNAL_SERVER_ERROR` with the original value preserved as `cause`.
+* The wrapper message is intentionally generic to avoid leaking internal
+* details to clients.
+*
+* @param error - Any value — typically the argument of a `catch` block.
+* @returns The original `SilgiError`, or a new `SilgiError('INTERNAL_SERVER_ERROR')`.
+*
+* @example
+* ```ts
+* const e = toSilgiError(err)
+* res.status(e.status).json(e.toJSON())
+* ```
+*
+* @see {@link isSilgiError}
+* @category Errors
+*/
 function toSilgiError(error) {
-	if (error instanceof SilgiError) return error;
+	if (isSilgiError(error)) return error;
 	return new SilgiError("INTERNAL_SERVER_ERROR", {
 		message: "Internal server error",
 		cause: error
 	});
 }
+/**
+* Returns `true` when `status` represents an HTTP error (4xx or 5xx).
+*
+* @param status - An HTTP status code.
+* @returns `true` when `status >= 400`.
+*
+* @example
+* ```ts
+* if (isErrorStatus(response.status)) handleError(response)
+* ```
+*
+* @category Errors
+*/
 function isErrorStatus(status) {
 	return status >= 400;
 }
+/**
+* Type guard that returns `true` when `json` has the shape of a
+* {@link SilgiErrorJSON} wire object.
+*
+* @param json - Any decoded JSON value.
+* @returns `true` when `json` has a string `code` and a numeric `status`.
+*
+* @example
+* ```ts
+* const body = await response.json()
+* if (isSilgiErrorJSON(body)) {
+*   throw fromSilgiErrorJSON(body)
+* }
+* ```
+*
+* @see {@link fromSilgiErrorJSON}
+* @category Errors
+*/
 function isSilgiErrorJSON(json) {
 	return typeof json === "object" && json !== null && "code" in json && "status" in json && typeof json.code === "string";
 }
+/**
+* Reconstruct a {@link SilgiError} from a {@link SilgiErrorJSON} wire object.
+*
+* @remarks
+* Typically used on the client side after receiving an error response.
+* The reconstructed error carries the brand and passes `isSilgiError()`.
+*
+* @param json - A validated {@link SilgiErrorJSON} object (use
+*   {@link isSilgiErrorJSON} to validate before calling this function).
+* @returns A fully-formed `SilgiError` instance.
+*
+* @example
+* ```ts
+* const body = await res.json()
+* if (isSilgiErrorJSON(body)) throw fromSilgiErrorJSON(body)
+* ```
+*
+* @see {@link isSilgiErrorJSON}
+* @category Errors
+*/
 function fromSilgiErrorJSON(json) {
 	return new SilgiError(json.code, {
 		status: json.status,
@@ -136,4 +379,4 @@ function fromSilgiErrorJSON(json) {
 	});
 }
 //#endregion
-export { SilgiError, fromSilgiErrorJSON, isDefinedError, isErrorStatus, isSilgiErrorJSON, toSilgiError };
+export { SilgiError, fromSilgiErrorJSON, isDefinedError, isErrorStatus, isSilgiError, isSilgiErrorJSON, toSilgiError };

package/dist/core/handler.d.mts

@@ -1,14 +1,28 @@
 import { AnalyticsOptions } from "../plugins/analytics/types.mjs";
+import { SchemaRegistry } from "./schema-converter.mjs";
 import { ScalarOptions } from "../scalar.mjs";
+import { SilgiHooks } from "../silgi.mjs";
 import { Hookable } from "hookable";
 
 //#region src/core/handler.d.ts
 type FetchHandler = (request: Request) => Response | Promise<Response>;
 interface WrapHandlerOptions {
-  analytics?: boolean | AnalyticsOptions;
+  analytics?: AnalyticsOptions;
   scalar?: boolean | ScalarOptions;
   /** URL path prefix for the handler (e.g. "/api"). Requests not matching this prefix return 404. */
   basePath?: string;
+  /**
+   * Schema registry for OpenAPI / analytics schema conversion. Built from
+   * `schemaConverters` in the silgi instance config — do not set manually.
+   * @internal
+   */
+  schemaRegistry?: SchemaRegistry;
+  /**
+   * Hookable instance — threaded so `wrapWithAnalytics` can register
+   * lifecycle listeners on `request:prepare` / `response:finalize`.
+   * @internal
+   */
+  hooks?: Hookable<SilgiHooks>;
 }
 //#endregion
 export { FetchHandler, WrapHandlerOptions };