@arkyn/server 3.0.1-beta.143 → 3.0.1-beta.144

package/dist/bundle.js

@@ -7,48 +7,22 @@ import Qe from "node:dns";
 import { countries as et } from "@arkyn/templates";
 class ee {
   /**
-   * Sets the file name to be ignored during stack trace analysis.
+   * Adds a file name to the ignore list so it is skipped when resolving the caller in stack traces.
    *
-   * This method configures the debug service to skip specific files when
-   * determining the actual caller of a function. This is useful when you have
-   * adapter or wrapper functions that you want to be transparent in the debug output.
-   *
-   * @param {string} file - The name of the file to ignore in stack traces (e.g., "httpAdapter.ts")
-   *
-   * @example
-   * ```typescript
-   * // Ignore the HTTP adapter file so debug shows the actual business logic caller
-   * DebugService.setIgnoreFile("httpAdapter.ts");
-   * ```
+   * @param file - File name to ignore (e.g. `"httpAdapter.ts"`).
    */
   static setIgnoreFile(e) {
     this.ignoreFiles.push(e);
   }
-  /**
-   * Clears all configured ignore files.
-   *
-   * This method resets the ignore file configuration, allowing all files to be
-   * considered in stack trace analysis again.
-   *
-   * @example
-   * ```typescript
-   * // Clear all ignore file configurations
-   * DebugService.clearIgnoreFiles();
-   * ```
-   */
+  /** Resets the ignore list, restoring full stack trace analysis. */
   static clearIgnoreFiles() {
     this.ignoreFiles = [];
   }
   /**
-   * Retrieves information about the caller of the current function.
+   * Resolves the file path and function name of the code that triggered the current debug call,
+   * skipping internal node modules and any files registered with `setIgnoreFile`.
    *
-   * This function analyzes the stack trace to determine the file path and function name
-   * of the caller. It excludes stack trace entries related to the `@arkyn/server` package
-   * and attempts to resolve the file path relative to the project root directory.
-   *
-   * @returns An object containing:
-   * - `functionName`: The name of the function that called the current function, or "Unknown function" if it cannot be determined.
-   * - `callerInfo`: The file path of the caller relative to the project root, or "Unknown caller" if it cannot be determined.
+   * @returns `{ functionName, callerInfo }` — caller function name and file path relative to `process.cwd()`.
    */
   static getCaller() {
     const e = process.cwd(), n = (new Error().stack || "").split(`
@@ -159,20 +133,13 @@ class p {
 }
 class tt extends p {
   /**
-   * Creates an instance of the `BadGateway` class.
-   *
-   * @param {string} message - A descriptive message explaining the cause of the error.
-   * @param {any} cause - Optional additional information about the cause of the error.
+   * @param message - Error description sent in the response body and logged for debugging.
+   * @param cause - Optional extra context (serialized to JSON in the response).
    */
   constructor(e, d) {
     super(), this.name = "BadGateway", this.status = 502, this.statusText = e, this.cause = d ? JSON.stringify(d) : void 0, this.onDebug();
   }
-  /**
-   * Converts the `BadGateway` instance into a `Response` object with a JSON body.
-   * This method ensures the response has the appropriate headers, status, and status text.
-   *
-   * @returns {Response} A `Response` object with the serialized JSON body and response metadata.
-   */
+  /** Converts to a `Response` with `Content-Type: application/json` header. */
   toResponse() {
     const e = {
       headers: { "Content-Type": "application/json" },
@@ -181,12 +148,7 @@ class tt extends p {
     };
     return new Response(JSON.stringify(this.makeBody()), e);
   }
-  /**
-   * Converts the `BadGateway` instance into a `Response` object using the `Response.json` method.
-   * This method is an alternative to `toResponse` for generating JSON error responses.
-   *
-   * @returns {Response["json"]} A `Response` object with the JSON body and response metadata.
-   */
+  /** Converts to a `Response` using `Response.json()`. Alternative to `toResponse()`. */
   toJson() {
     const e = {
       status: this.status,
@@ -197,20 +159,13 @@ class tt extends p {
 }
 class V extends p {
   /**
-   * Creates an instance of the `BadRequest` class.
-   *
-   * @param {string} message - A descriptive message explaining the cause of the error.
-   * @param {any} cause - Optional additional information about the cause of the error.
+   * @param message - Error description.
+   * @param cause - Optional extra context (serialized to JSON).
    */
   constructor(e, d) {
     super(), this.name = "BadRequest", this.status = 400, this.statusText = e, this.cause = d ? JSON.stringify(d) : void 0, this.onDebug();
   }
-  /**
-   * Converts the `BadRequest` instance into a `Response` object with a JSON body.
-   * This method ensures the response has the appropriate headers, status, and status text.
-   *
-   * @returns {Response} A `Response` object with the serialized JSON body and response metadata.
-   */
+  /** Converts to a `Response` with `Content-Type: application/json` header. */
   toResponse() {
     const e = {
       headers: { "Content-Type": "application/json" },
@@ -219,12 +174,7 @@ class V extends p {
     };
     return new Response(JSON.stringify(this.makeBody()), e);
   }
-  /**
-   * Converts the `BadRequest` instance into a `Response` object using the `Response.json` method.
-   * This method is an alternative to `toResponse` for generating JSON error responses.
-   *
-   * @returns {Response["json"]} A `Response` object with the JSON body and response metadata.
-   */
+  /** Converts to a `Response` using `Response.json()`. Alternative to `toResponse()`. */
   toJson() {
     const e = {
       status: this.status,
@@ -235,20 +185,13 @@ class V extends p {
 }
 class dt extends p {
   /**
-   * Creates an instance of the `Conflict` class.
-   *
-   * @param {string} message - A descriptive message explaining the cause of the conflict.
-   * @param {any} cause - Optional additional information about the cause of the conflict.
+   * @param message - Error description.
+   * @param cause - Optional extra context (serialized to JSON).
    */
   constructor(e, d) {
     super(), this.name = "Conflict", this.status = 409, this.statusText = e, this.debugColor = "yellow", this.cause = d ? JSON.stringify(d) : void 0, this.onDebug();
   }
-  /**
-   * Converts the `Conflict` instance into a `Response` object with a JSON body.
-   * This method ensures the response has the appropriate headers, status, and status text.
-   *
-   * @returns {Response} A `Response` object with the serialized JSON body and response metadata.
-   */
+  /** Converts to a `Response` with `Content-Type: application/json` header. */
   toResponse() {
     const e = {
       headers: { "Content-Type": "application/json" },
@@ -257,12 +200,7 @@ class dt extends p {
     };
     return new Response(JSON.stringify(this.makeBody()), e);
   }
-  /**
-   * Converts the `Conflict` instance into a `Response` object using the `Response.json` method.
-   * This method is an alternative to `toResponse` for generating JSON error responses.
-   *
-   * @returns {Response["json"]} A `Response` object with the JSON body and response metadata.
-   */
+  /** Converts to a `Response` using `Response.json()`. Alternative to `toResponse()`. */
   toJson() {
     const e = {
       status: this.status,
@@ -273,20 +211,13 @@ class dt extends p {
 }
 class rt extends p {
   /**
-   * Creates an instance of the `Forbidden` class.
-   *
-   * @param {string} message - A descriptive message explaining why access is forbidden.
-   * @param {any} cause - Optional additional information about the cause of the error.
+   * @param message - Error description.
+   * @param cause - Optional extra context (serialized to JSON).
    */
   constructor(e, d) {
     super(), this.name = "Forbidden", this.status = 403, this.statusText = e, this.cause = d ? JSON.stringify(d) : void 0, this.onDebug();
   }
-  /**
-   * Converts the `Forbidden` instance into a `Response` object with a JSON body.
-   * This method ensures the response has the appropriate headers, status, and status text.
-   *
-   * @returns {Response} A `Response` object with the serialized JSON body and response metadata.
-   */
+  /** Converts to a `Response` with `Content-Type: application/json` header. */
   toResponse() {
     const e = {
       headers: { "Content-Type": "application/json" },
@@ -295,12 +226,7 @@ class rt extends p {
     };
     return new Response(JSON.stringify(this.makeBody()), e);
   }
-  /**
-   * Converts the `Forbidden` instance into a `Response` object using the `Response.json` method.
-   * This method is an alternative to `toResponse` for generating JSON error responses.
-   *
-   * @returns {Response["json"]} A `Response` object with the JSON body and response metadata.
-   */
+  /** Converts to a `Response` using `Response.json()`. Alternative to `toResponse()`. */
   toJson() {
     const e = {
       status: this.status,
@@ -311,20 +237,13 @@ class rt extends p {
 }
 class nt extends p {
   /**
-   * Creates an instance of the `NotFound` class.
-   *
-   * @param {string} message - A descriptive message explaining the reason the resource was not found.
-   * @param {any} cause - Optional additional information about the cause of the error.
+   * @param message - Error description.
+   * @param cause - Optional extra context (serialized to JSON).
    */
   constructor(e, d) {
     super(), this.name = "NotFound", this.status = 404, this.statusText = e, this.cause = d ? JSON.stringify(d) : void 0, this.onDebug();
   }
-  /**
-   * Converts the `NotFound` instance into a `Response` object with a JSON body.
-   * This method ensures the response has the appropriate headers, status, and status text.
-   *
-   * @returns {Response} A `Response` object with the serialized JSON body and response metadata.
-   */
+  /** Converts to a `Response` with `Content-Type: application/json` header. */
   toResponse() {
     const e = {
       headers: { "Content-Type": "application/json" },
@@ -333,12 +252,7 @@ class nt extends p {
     };
     return new Response(JSON.stringify(this.makeBody()), e);
   }
-  /**
-   * Converts the `NotFound` instance into a `Response` object using the `Response.json` method.
-   * This method is an alternative to `toResponse` for generating JSON error responses.
-   *
-   * @returns {Response["json"]} A `Response` object with the JSON body and response metadata.
-   */
+  /** Converts to a `Response` using `Response.json()`. Alternative to `toResponse()`. */
   toJson() {
     const e = {
       status: this.status,
@@ -349,20 +263,13 @@ class nt extends p {
 }
 class st extends p {
   /**
-   * Creates an instance of the `NotImplemented` class.
-   *
-   * @param {string} message - A descriptive message explaining why the functionality is not implemented.
-   * @param {any} cause - Optional additional information about the cause of the error.
+   * @param message - Error description.
+   * @param cause - Optional extra context (serialized to JSON).
    */
   constructor(e, d) {
     super(), this.name = "NotImplemented", this.status = 501, this.statusText = e, this.cause = d ? JSON.stringify(d) : void 0, this.onDebug();
   }
-  /**
-   * Converts the `NotImplemented` instance into a `Response` object with a JSON body.
-   * This method ensures the response has the appropriate headers, status, and status text.
-   *
-   * @returns {Response} A `Response` object with the serialized JSON body and response metadata.
-   */
+  /** Converts to a `Response` with `Content-Type: application/json` header. */
   toResponse() {
     const e = {
       headers: { "Content-Type": "application/json" },
@@ -371,12 +278,7 @@ class st extends p {
     };
     return new Response(JSON.stringify(this.makeBody()), e);
   }
-  /**
-   * Converts the `NotImplemented` instance into a `Response` object using the `Response.json` method.
-   * This method is an alternative to `toResponse` for generating JSON error responses.
-   *
-   * @returns {Response["json"]} A `Response` object with the JSON body and response metadata.
-   */
+  /** Converts to a `Response` using `Response.json()`. Alternative to `toResponse()`. */
   toJson() {
     const e = {
       status: this.status,
@@ -387,20 +289,13 @@ class st extends p {
 }
 class W extends p {
   /**
-   * Creates an instance of the `ServerError` class.
-   *
-   * @param {string} message - A descriptive message explaining the cause of the server error.
-   * @param {any} cause - Optional additional information about the cause of the error.
+   * @param message - Error description.
+   * @param cause - Optional extra context (serialized to JSON).
    */
   constructor(e, d) {
     super(), this.name = "ServerError", this.status = 500, this.statusText = e, this.cause = d ? JSON.stringify(d) : void 0, this.onDebug();
   }
-  /**
-   * Converts the `ServerError` instance into a `Response` object with a JSON body.
-   * This method ensures the response has the appropriate headers, status, and status text.
-   *
-   * @returns {Response} A `Response` object with the serialized JSON body and response metadata.
-   */
+  /** Converts to a `Response` with `Content-Type: application/json` header. */
   toResponse() {
     const e = {
       headers: { "Content-Type": "application/json" },
@@ -409,12 +304,7 @@ class W extends p {
     };
     return new Response(JSON.stringify(this.makeBody()), e);
   }
-  /**
-   * Converts the `ServerError` instance into a `Response` object using the `Response.json` method.
-   * This method is an alternative to `toResponse` for generating JSON error responses.
-   *
-   * @returns {Response["json"]} A `Response` object with the JSON body and response metadata.
-   */
+  /** Converts to a `Response` using `Response.json()`. Alternative to `toResponse()`. */
   toJson() {
     const e = {
       status: this.status,
@@ -425,20 +315,13 @@ class W extends p {
 }
 class $t extends p {
   /**
-   * Creates an instance of the `Unauthorized` class.
-   *
-   * @param message - A descriptive message explaining why the request is unauthorized.
-   * @param cause - Optional additional information about the cause of the error.
+   * @param message - Error description.
+   * @param cause - Optional extra context (serialized to JSON).
    */
   constructor(e, d) {
     super(), this.name = "Unauthorized", this.status = 401, this.statusText = e, this.debugColor = "yellow", this.cause = d ? JSON.stringify(d) : void 0, this.onDebug();
   }
-  /**
-   * Converts the `Unauthorized` instance into a `Response` object with a JSON body.
-   * This method ensures the response has the appropriate headers, status, and status text.
-   *
-   * @returns {Response} A `Response` object with the serialized JSON body and response metadata.
-   */
+  /** Converts to a `Response` with `Content-Type: application/json` header. */
   toResponse() {
     const e = {
       headers: { "Content-Type": "application/json" },
@@ -447,12 +330,7 @@ class $t extends p {
     };
     return new Response(JSON.stringify(this.makeBody()), e);
   }
-  /**
-   * Converts the `Unauthorized` instance into a `Response` object using the `Response.json` method.
-   * This method is an alternative to `toResponse` for generating JSON error responses.
-   *
-   * @returns {Response["json"]} A `Response` object with the JSON body and response metadata.
-   */
+  /** Converts to a `Response` using `Response.json()`. Alternative to `toResponse()`. */
   toJson() {
     const e = {
       status: this.status,
@@ -463,13 +341,10 @@ class $t extends p {
 }
 class K extends p {
   /**
-   * Creates an instance of the `UnprocessableEntity` class.
-   *
-   * @param {object} props - An object containing details about the error, such as:
-   * @param {any} [props.data] - `data`: Additional data related to the error.
-   * @param {Record<string, string>} [props.fieldErrors] - `fieldErrors`: A record of field-specific error messages.
-   * @param {Record<string, string>} [props.fields] - `fields`: A record of field values that caused the error.
-   * @param {string} [props.message] - `message`: A descriptive message explaining the error.
+   * @param props.message - Human-readable description of the error.
+   * @param props.fieldErrors - Per-field validation messages keyed by field name.
+   * @param props.fields - Original submitted field values (useful for repopulating forms).
+   * @param props.data - Any extra data to include in the response body.
    */
   constructor(e) {
     super(), this.name = "UnprocessableEntity", this.status = 422, this.statusText = e.message || "Unprocessable entity", this.debugColor = "yellow", this.cause = {
@@ -478,12 +353,7 @@ class K extends p {
       fields: e.fields
     }, this.onDebug();
   }
-  /**
-   * Converts the `UnprocessableEntity` instance into a `Response` object with a JSON body.
-   * This method ensures the response has the appropriate headers, status, and status text.
-   *
-   * @returns {Response} A `Response` object with the serialized JSON body and response metadata.
-   */
+  /** Converts to a `Response` with `Content-Type: application/json` header. */
   toResponse() {
     const e = {
       headers: { "Content-Type": "application/json" },
@@ -492,12 +362,7 @@ class K extends p {
     };
     return new Response(JSON.stringify(this.makeBody()), e);
   }
-  /**
-   * Converts the `UnprocessableEntity` instance into a `Response` object using the `Response.json` method.
-   * This method is an alternative to `toResponse` for generating JSON error responses.
-   *
-   * @returns {Response["json"]} A `Response` object with the JSON body and response metadata.
-   */
+  /** Converts to a `Response` using `Response.json()`. Alternative to `toResponse()`. */
   toJson() {
     const e = {
       status: this.status,
@@ -569,18 +434,13 @@ class A {
 }
 class it extends A {
   /**
-   * Creates an instance of the `Created` class.
-   *
-   * @param {string} message - A message describing the creation status.
-   * @param {any} body - The response body to be included in the HTTP response.
+   * @param message - Description included in the response status text.
+   * @param body - Data to include in the response body.
    */
   constructor(e, d) {
     super(), this.name = "Created", this.status = 201, this.statusText = e, this.body = d || void 0, this.onDebug();
   }
-  /**
-   * Converts the `Created` instance into a `Response` object.
-   * @returns {Response} A `Response` object with the body and response metadata.
-   */
+  /** Converts to a `Response` with `Content-Type: application/json` header. */
   toResponse() {
     const e = {
       headers: { "Content-Type": "application/json" },
@@ -589,11 +449,7 @@ class it extends A {
     };
     return new Response(JSON.stringify(this.body), e);
   }
-  /**
-   * Converts the `Created` instance into a `Response` object using the `Response.json` method.
-   * This method is an alternative to `toResponse` for generating JSON responses.
-   * @returns {Response["json"]} A `Response` object with the JSON body and response metadata.
-   */
+  /** Converts to a `Response` using `Response.json()`. Alternative to `toResponse()`. */
   toJson() {
     const e = {
       status: this.status,
@@ -604,18 +460,13 @@ class it extends A {
 }
 class ot extends A {
   /**
-   * Creates an instance of the `Found` class.
-   *
-   * @param {string} message - A message describing the creation status.
-   * @param {any} body - The response body to be included in the HTTP response.
+   * @param message - Description included in the response status text.
+   * @param body - Data to include in the response body.
    */
   constructor(e, d) {
     super(), this.name = "Found", this.status = 302, this.statusText = e, this.body = d || void 0, this.onDebug();
   }
-  /**
-   * Converts the `Found` instance into a `Response` object.
-   * @returns {Response} A `Response` object with the body and response metadata.
-   */
+  /** Converts to a `Response` with `Content-Type: application/json` header. */
   toResponse() {
     const e = {
       headers: { "Content-Type": "application/json" },
@@ -624,11 +475,7 @@ class ot extends A {
     };
     return new Response(JSON.stringify(this.body), e);
   }
-  /**
-   * Converts the `Found` instance into a `Response` object using the `Response.json` method.
-   * This method is an alternative to `toResponse` for generating JSON responses.
-   * @returns {Response["json"]} A `Response` object with the JSON body and response metadata.
-   */
+  /** Converts to a `Response` using `Response.json()`. Alternative to `toResponse()`. */
   toJson() {
     const e = {
       status: this.status,
@@ -639,16 +486,12 @@ class ot extends A {
 }
 class at extends A {
   /**
-   * Creates an instance of the `NoContent` class.
-   * @param {string} message - A message describing the creation status.
+   * @param message - Description included in the response status text.
    */
   constructor(e) {
     super(), this.name = "NoContent", this.status = 204, this.statusText = e, this.onDebug();
   }
-  /**
-   * Converts the `NoContent` instance into a `Response` object.
-   * @returns {Response} A `Response` object with the body and response metadata.
-   */
+  /** Converts to a `Response` with `Content-Type: application/json` header and no body. */
   toResponse() {
     const e = {
       headers: { "Content-Type": "application/json" },
@@ -660,18 +503,13 @@ class at extends A {
 }
 class ut extends A {
   /**
-   * Creates an instance of the `Success` class.
-   *
-   * @param {string} message - A message describing the creation status.
-   * @param {any} body - The response body to be included in the HTTP response.
+   * @param message - Description included in the response status text.
+   * @param body - Data to include in the response body.
    */
   constructor(e, d) {
     super(), this.name = "Success", this.status = 200, this.statusText = e, this.body = d || void 0, this.onDebug();
   }
-  /**
-   * Converts the `Success` instance into a `Response` object.
-   * @returns {Response} A `Response` object with the body and response metadata.
-   */
+  /** Converts to a `Response` with `Content-Type: application/json` header. */
   toResponse() {
     const e = {
       headers: { "Content-Type": "application/json" },
@@ -680,11 +518,7 @@ class ut extends A {
     };
     return new Response(JSON.stringify(this.body), e);
   }
-  /**
-   * Converts the `Success` instance into a `Response` object using the `Response.json` method.
-   * This method is an alternative to `toResponse` for generating JSON responses.
-   * @returns {Response["json"]} A `Response` object with the JSON body and response metadata.
-   */
+  /** Converts to a `Response` using `Response.json()`. Alternative to `toResponse()`. */
   toJson() {
     const e = {
       status: this.status,
@@ -695,18 +529,13 @@ class ut extends A {
 }
 class lt extends A {
   /**
-   * Creates an instance of the `Updated` class.
-   *
-   * @param {string} message - A message describing the creation status.
-   * @param {any} body - The response body to be included in the HTTP response.
+   * @param message - Description included in the response status text.
+   * @param body - Data to include in the response body.
    */
   constructor(e, d) {
     super(), this.name = "Updated", this.status = 200, this.statusText = e, this.body = d || void 0, this.onDebug();
   }
-  /**
-   * Converts the `Updated` instance into a `Response` object.
-   * @returns {Response} A `Response` object with the body and response metadata.
-   */
+  /** Converts to a `Response` with `Content-Type: application/json` header. */
   toResponse() {
     const e = {
       headers: { "Content-Type": "application/json" },
@@ -715,11 +544,7 @@ class lt extends A {
     };
     return new Response(JSON.stringify(this.body), e);
   }
-  /**
-   * Converts the `Updated` instance into a `Response` object using the `Response.json` method.
-   * This method is an alternative to `toResponse` for generating JSON responses.
-   * @returns {Response["json"]} A `Response` object with the JSON body and response metadata.
-   */
+  /** Converts to a `Response` using `Response.json()`. Alternative to `toResponse()`. */
   toJson() {
     const e = {
       status: this.status,
@@ -779,23 +604,18 @@ class ct {
 }
 class Fe {
   /**
-   * Sets the log service configuration only once.
-   * If the configuration is already set, the call is ignored.
+   * Sets the log service configuration once. Subsequent calls are ignored.
    *
-   * @param {object} config - Service configuration parameters.
-   * @param {string} config.trafficSourceId - Traffic source identifier.
-   * @param {string} config.userToken - User token for authentication.
-   * @param {string} [config.logBaseApiUrl] - Optional base URL for the log service.
+   * @param config.trafficSourceId - Traffic source identifier.
+   * @param config.userToken - User token for authentication.
+   * @param config.logBaseApiUrl - Override the default log ingestion base URL.
    */
   static setConfig(e) {
     if (this.config) return;
     const { trafficSourceId: d, userToken: r, logBaseApiUrl: n } = e, $ = `${n || "http://62.238.8.44:8081"}/ingest-log`;
     this.config = { trafficSourceId: d, userToken: r, apiUrl: $ };
   }
-  /**
-   * Returns the current service configuration, if it exists.
-   * @returns {{ trafficSourceId: string; userToken: string; apiUrl: string } | undefined} The stored configuration or `undefined` if not set.
-   */
+  /** Returns the stored configuration, or `undefined` if `setConfig` has not been called. */
   static getConfig() {
     return this.config;
   }
@@ -1210,68 +1030,34 @@ function Pt(t) {
 }
 class od {
   /**
-   * Creates a new SchemaValidator instance.
-   * @param {T} schema - The Zod schema to use for validation.
+   * @param schema - The Zod schema used for all validation methods on this instance.
    */
   constructor(e) {
     this.schema = e;
   }
   /**
-   * Checks if the provided data is valid according to the schema without throwing errors.
+   * Returns `true` if the data satisfies the schema, `false` otherwise. Never throws.
    *
-   * @param {any} data - The data to validate.
-   *
-   * @returns {boolean} True if the data is valid, false otherwise.
-   *
-   * @example
-   * ```typescript
-   * const validator = new SchemaValidator(userSchema);
-   * const isValid = validator.isValid({ name: "John", email: "invalid-email" });
-   * console.log(isValid); // false
-   * ```
+   * @param data - The value to check.
    */
   isValid(e) {
     return this.schema.safeParse(e).success;
   }
   /**
-   * Safely validates data and returns the complete parse result without throwing errors.
+   * Validates data and returns the raw Zod `safeParseResult` without throwing.
+   * Useful when you need access to the full error details.
    *
-   * @param {any} data - The data to validate.
-   * @returns {z.ZodSafeParseResult<z.infer<T>>} The Zod safe parse result containing success status and data or error.
-   *
-   * @example
-   * ```typescript
-   * const validator = new SchemaValidator(userSchema);
-   * const result = validator.safeValidate({ name: "", email: "john@example.com" });
-   *
-   * if (result.success) {
-   *   console.log(result.data); // Validated data
-   * } else {
-   *   console.log(result.error.issues); // Validation errors
-   * }
-   * ```
+   * @param data - The value to validate.
    */
   safeValidate(e) {
     return this.schema.safeParse(e);
   }
   /**
-   * Validates data and returns the parsed result, throwing a ServerError on validation failure.
+   * Validates data and returns the typed result, throwing `ServerError` on failure.
+   * Use for validating internal/trusted data (e.g. env vars, config objects).
    *
-   * @param {any} data - The data to validate.
-   * @throws {ServerError} When validation fails, with a formatted error message.
-   * @returns {z.infer<T>} The validated and parsed data.
-   *
-   * @example
-   * ```typescript
-   * const validator = new SchemaValidator(userSchema);
-   *
-   * try {
-   *   const validUser = validator.validate({ name: "John", email: "john@example.com", age: 25 });
-   *   console.log(validUser); // { name: "John", email: "john@example.com", age: 25 }
-   * } catch (error) {
-   *   console.error(error.message); // "Error validating:\n-> name: String must contain at least 1 character(s)"
-   * }
-   * ```
+   * @param data - The value to validate.
+   * @throws `ServerError` with a formatted field-by-field error message.
    */
   validate(e) {
     try {
@@ -1281,26 +1067,17 @@ class od {
     }
   }
   /**
-   * Validates form data and returns the parsed result, throwing an UnprocessableEntity error on validation failure.
-   * This method is specifically designed for form validation in web applications.
+   * Validates form data and returns the typed result, throwing `UnprocessableEntity` on failure.
+   * The error includes `fieldErrors`, `fields`, and `data.scrollTo` (first failing field name).
    *
-   * @param {any} data - The form data to validate.
-   * @param {string} [message] - Optional custom error message.
-   * @throws {UnprocessableEntity} When validation fails, with structured field errors for form handling.
-   * @returns {z.infer<T>} The validated and parsed form data.
+   * @param data - The raw form data to validate.
+   * @param message - Optional human-readable error message for the 422 response.
+   * @throws `UnprocessableEntity` with structured field errors for client-side form handling.
    *
    * @example
    * ```typescript
-   * const validator = new SchemaValidator(userSchema);
-   *
-   * try {
-   *   const validFormData = validator.formValidate(requestBody, "User data is invalid");
-   *   console.log(validFormData);
-   * } catch (error) {
-   *   // UnprocessableEntity with fieldErrors, fields, and scrollTo data
-   *   console.log(error.fieldErrors); // { name: "Name is required", email: "Invalid email" }
-   *   console.log(error.data.scrollTo); // "name" (first error field)
-   * }
+   * const validator = new SchemaValidator(registerSchema);
+   * const body = validator.formValidate(await decodeRequestBody(request));
    * ```
    */
   formValidate(e, d) {
@@ -1317,26 +1094,16 @@ class od {
     return r.data;
   }
   /**
-   * Asynchronously validates form data and returns the parsed result, throwing an UnprocessableEntity error on validation failure.
-   * This method is the async version of formValidate, designed for form validation with async schemas.
+   * Async version of `formValidate` for schemas with async refinements (e.g. uniqueness checks).
    *
-   * @param {any} data - The form data to validate.
-   * @param {string} [message] - Optional custom error message.
-   * @throws {UnprocessableEntity} When validation fails, with structured field errors for form handling.
-   * @returns {Promise<z.infer<T>>} A promise that resolves to the validated and parsed form data.
+   * @param data - The raw form data to validate.
+   * @param message - Optional human-readable error message for the 422 response.
+   * @throws `UnprocessableEntity` with structured field errors for client-side form handling.
    *
    * @example
    * ```typescript
-   * const validator = new SchemaValidator(userSchemaWithAsyncValidation);
-   *
-   * try {
-   *   const validFormData = await validator.formAsyncValidate(requestBody, "User data is invalid");
-   *   console.log(validFormData);
-   * } catch (error) {
-   *   // UnprocessableEntity with fieldErrors, fields, and scrollTo data
-   *   console.log(error.fieldErrors); // { name: "Name is required", email: "Invalid email" }
-   *   console.log(error.data.scrollTo); // "name" (first error field)
-   * }
+   * const validator = new SchemaValidator(registerSchema);
+   * const body = await validator.formAsyncValidate(await decodeRequestBody(request));
    * ```
    */
   async formAsyncValidate(e, d) {