@rzl-zone/build-tools 0.0.5

package/dist/utils/client.d.cts

@@ -0,0 +1,887 @@
+/*!
+* ========================================================================
+*  @rzl-zone/build-tools
+* ------------------------------------------------------------------------
+*  Version: `0.0.5`
+*  Author: `Rizalvin Dwiky <rizalvindwiky1998@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/build-tools`
+* ========================================================================
+*/
+
+import { Colors } from "picocolors/types";
+
+type Picocolors = Colors & {
+  createColors: (enabled?: boolean) => Colors;
+};
+/** ----------------------------------------------------------------
+* * ***Re-export of the `picocolors` default export.***
+* ----------------------------------------------------------------
+* This utility provides a lightweight and dependency-free
+* terminal color formatting helper, identical to the
+* original `picocolors` package export.
+*
+* - **It is re-exported to:**
+*      - Provide a stable internal import path.
+*      - Avoid direct dependency imports in consumers.
+*      - Ensure consistent color handling across the codebase.
+*
+* @see {@link https://github.com/alexeyraspopov/picocolors | **`picocolors repository`**.}
+*/
+declare const picocolors: Picocolors;
+/** ----------------------------------------------------------------
+* * ***Normalized newline character.***
+* ----------------------------------------------------------------
+*
+* Represents a single line feed character (`\n`), used as a
+* **consistent newline** across all platforms.
+*
+* This value is intentionally **not platform-specific** and does
+* not vary between operating systems (e.g. Windows CRLF vs POSIX LF).
+* It is suitable for generated files, formatters, and build tools
+* where deterministic output is required.
+*
+* The value is base64-encoded to avoid embedding a literal newline
+* in the bundled output during minification.
+*
+* @type {string}
+*/
+declare const NEWLINE: string;
+/** ----------------------------------------------------------------
+* * ***Platform-specific end-of-line character.***
+* ----------------------------------------------------------------
+*
+* Resolves to the operating system's default end-of-line sequence:
+* - `\n` on POSIX systems (Linux, macOS)
+* - `\r\n` on Windows
+*
+* Used to ensure generated multiline strings are compatible
+* with the host environment.
+*
+* In non-Node environments, this value falls back to `\n`.
+* The fallback is encoded to avoid embedding a literal newline
+* in the bundled output during minification.
+*
+* @type {string}
+*/
+declare const EOL: string;
+/** -------------------------------------------------------
+* * ***Utility Function: `plural`.***
+* -------------------------------------------------------
+* **Returns the correct singular or plural form of a word
+* based on a numeric count.**
+*
+* This helper is commonly used when generating human-readable
+* CLI messages where a word must change depending on quantity.
+*
+* By default, the function pluralizes a word by appending `"s"`
+* when the `count` is not equal to `1`.
+*
+* For irregular plural forms, a custom `pluralWord` may be
+* provided explicitly.
+*
+* ⚠️ This utility performs **simple English pluralization only**.
+* It does **not** automatically handle irregular plural forms
+* such as `person ➔ people` or `child ➔ children` unless the
+* plural form is provided manually.
+*
+* - **Behavior:**
+*      - If `count === 1` ➔ returns the singular `word`.
+*      - Otherwise ➔ returns `pluralWord` if provided,
+*        or `${word}s` by default.
+*
+* @param count - The numeric count used to determine pluralization.
+* @param word - The singular form of the word.
+* @param pluralWord - Optional explicit plural form.
+*
+* @returns The appropriate singular or plural word form.
+*
+* @example
+* ```ts
+* plural(1, "file");
+* // ➔ "file"
+*
+* plural(3, "file");
+* // ➔ "files"
+* ```
+*
+* @example
+* ```ts
+* plural(1, "person", "people");
+* // ➔ "person"
+*
+* plural(5, "person", "people");
+* // ➔ "people"
+* ```
+*
+* @example
+* ```ts
+* const count = 2;
+* console.log(`${count} ${plural(count, "file")} copied`);
+* // ➔ "2 files copied"
+* ```
+*/
+declare function plural(count: number, word: string, pluralWord?: string): string;
+/** ----------------------------------------------------------------
+* * ***Conditionally pads a value with leading and/or trailing spaces.***
+* ----------------------------------------------------------------
+*
+* Formats a value by optionally prepending and/or appending a single
+* space character (`" "`), depending on the provided options.
+*
+* Only **valid non-empty strings** are padded.
+* A value is considered **invalid** when it is:
+* - not a string.
+* - an empty string (`""`).
+* - a string containing only whitespace.
+*
+* When the value is invalid, this utility can optionally return
+* a single space instead of an empty string.
+*
+* @param {unknown} value - The value to be padded.
+* @param {{ start?: boolean; end?: boolean; padOnInvalid?: boolean; }} options - Padding behavior configuration.
+* @param options.start - Prepend a single space before the value.
+* @param options.end - Append a single space after the value.
+* @param options.padOnInvalid - Return a single space when the value
+* is not a valid non-empty string.
+*
+* @returns A formatted string with optional leading and/or trailing
+* spaces, or a single space / empty string when the input is invalid.
+*
+* @example
+* ```ts
+* padText("hello");
+* // ➔ " hello "
+* ```
+*
+* @example
+* ```ts
+* padText("hello", { start: true, end: false });
+* // ➔ " hello"
+* ```
+*
+* @example
+* ```ts
+* padText("", { padOnInvalid: true });
+* // ➔ " "
+* ```
+*
+* @example
+* ```ts
+* padText(null, { padOnInvalid: false });
+* // ➔ ""
+* ```
+*/
+declare function padText(value: unknown, options?: {
+  /**
+  * Whether to prepend a single space to the output.
+  *
+  * @default true
+  */
+  start?: boolean;
+  /**
+  * Whether to append a single space to the output.
+  *
+  * @default true
+  */
+  end?: boolean;
+  /**
+  * Return a single space when the input is not a valid non-empty string.
+  *
+  * This applies to non-string values, empty strings,
+  * or strings containing only whitespace.
+  *
+  * @default true
+  */
+  padOnInvalid?: boolean;
+}): string;
+/** ----------------------------------------------------------------
+* * ***Joins text segments into a compact space-separated string.***
+* ----------------------------------------------------------------
+*
+* Joins multiple values into a single string separated by a
+* **single space character** (`" "`).
+*
+* This utility removes all non-renderable values before joining,
+* producing a compact inline string without unintended spacing.
+*
+* - *Filtering behavior:*
+*     - `false`, `null`, and `undefined` are removed.
+*     - Empty strings (`""`) are also removed.
+*
+* This makes the output suitable for inline text composition
+* where line breaks and extra spacing are not desired.
+*
+* - *Useful for:*
+*     - Inline CLI messages.
+*     - Error summaries.
+*     - Concatenating optional labels or fragments.
+*     - Single-line log output.
+*
+* @param {Array<string | false | null | undefined>} text - A list of
+* strings or falsy values to be joined. Empty strings are excluded
+* to prevent extra spaces in the output.
+*
+* @returns {string} A single string with values joined by a
+* single space character.
+*
+* @example
+* ```ts
+* joinInline("Hello", false, "", "world");
+* // ➔ "Hello world"
+* ```
+*
+* @example
+* ```ts
+* joinInline(
+*   "Error:",
+*   undefined,
+*   "Invalid",
+*   null,
+*   "input"
+* );
+* // ➔ "Error: Invalid input"
+* ```
+*/
+declare function joinInline(...text: Array<string | false | null | undefined>): string;
+/** ----------------------------------------------------------------
+* * ***Joins text lines into a compact newline-separated string.***
+* ----------------------------------------------------------------
+*
+* Joins multiple values into a single string separated by the
+* platform-specific end-of-line character ({@link EOL | **`EOL`**}).
+*
+* This utility removes all non-renderable values before joining,
+* ensuring a compact output with no unintended blank lines.
+*
+* - *Filtering behavior:*
+*     - `false`, `null`, and `undefined` are removed.
+*     - Empty strings (`""`) are also removed.
+*
+* This makes the output dense and suitable for cases where
+* vertical spacing should not be preserved.
+*
+* - *Useful for:*
+*     - CLI error messages.
+*     - Compact help or status output.
+*     - Multi-line logs without spacing gaps.
+*
+* @param {Array<string | false | null | undefined>} text - A list of
+* strings or falsy values to be joined. Empty strings are excluded
+* to prevent blank lines in the output.
+*
+* @returns {string} A single string joined using the OS-specific
+* end-of-line character.
+*
+* @example
+* ```ts
+* joinLines("Line 1", false, "", "Line 2");
+* // ➔ "Line 1\nLine 2"
+* ```
+*
+* @example
+* ```ts
+* joinLines(
+*   "Header",
+*   undefined,
+*   "",
+*   "Body",
+*   null,
+*   "Footer"
+* );
+* // ➔ "Header\nBody\nFooter"
+* ```
+*/
+declare function joinLines(...text: Array<string | false | null | undefined>): string;
+/** ----------------------------------------------------------------
+* * ***Joins text lines while preserving explicit empty lines.***
+* ----------------------------------------------------------------
+*
+* Joins multiple values into a single string separated by the
+* platform-specific end-of-line character ({@link EOL | **`EOL`**}).
+*
+* Unlike {@link joinLines | **`joinLines`**}, this variant **preserves empty strings**
+* (`""`) to intentionally create blank lines in the output.
+*
+* - *Filtering behavior:*
+*     - `false`, `null`, and `undefined` are removed.
+*     - Empty strings (`""`) are kept as-is.
+*
+* This allows precise control over vertical spacing when composing
+* formatted text.
+*
+* - *Useful for:*
+*     - CLI help output with paragraph separation.
+*     - Multi-section descriptions.
+*     - Human-readable documentation formatting.
+*
+* @param {Array<string | false | null | undefined>} text - A list of
+* strings or falsy values to be joined. Empty strings are preserved
+* to produce blank lines in the output.
+*
+* @returns {string} A single string joined using the OS-specific
+* end-of-line character.
+*
+* @example
+* ```ts
+* joinLinesLoose(
+*   "Line one",
+*   "Line two",
+*   "",
+*   "New paragraph"
+* );
+* // ➔ "Line one\nLine two\n\nNew paragraph"
+* ```
+*
+* @example
+* ```ts
+* joinLinesLoose(
+*   "Header",
+*   null,
+*   "",
+*   "Body",
+*   false,
+*   null,
+*   undefined
+* );
+* // ➔ "Header\n\nBody"
+* ```
+*/
+declare function joinLinesLoose(...text: Array<string | false | null | undefined>): string;
+type FormatOptionValueOptions = {
+  /** @default false */pretty?: boolean; /** @default 2 */
+  indent?: number; /** @default false */
+  sortKeys?: boolean; /** @default false */
+  sortArray?: boolean;
+};
+/** ----------------------------------------------------------------
+* * Formats a value into a compact, colorized CLI representation.
+* ----------------------------------------------------------------
+*
+* Recursively converts an arbitrary value into a human-readable,
+* ANSI-colored string intended strictly for terminal output.
+*
+* This formatter is designed for developer-facing CLI diagnostics
+* and must NOT be used for logging, serialization, persistence,
+* or programmatic comparison.
+*
+* - *Behavior:*
+*     - Arrays are rendered inline: `[a, b, c]`.
+*     - `Set` values are converted to arrays before rendering.
+*     - `Map` values are converted to plain objects via `Object.fromEntries`.
+*     - Plain objects are rendered inline: `{ key: value }`.
+*     - `RegExp` values are colorized by delimiter, source, and flags.
+*     - Strings are wrapped in double quotes.
+*     - Numbers (including `NaN`) and booleans are highlighted.
+*     - `null` and `undefined` are red-bright color.
+*     - Other objects fall back to `Object.prototype.toString`.
+*
+* - *Characteristics:*
+*     - Recursive.
+*     - Compact (single-line).
+*     - No pretty-print indentation.
+*     - No key or array sorting.
+*     - No JSON serialization.
+*     - No circular reference handling.
+*
+* @param value - The value to format for CLI display.
+*
+* @returns A colorized string optimized for terminal readability.
+*
+* @example
+* formatOptionValue(["a", "b"]);
+* // ➔ [ "a", "b" ]
+*
+* @example
+* formatOptionValue({ foo: 1, bar: true });
+* // ➔ { foo: 1, bar: true }
+*
+* @example
+* formatOptionValue(new Set(["dist/**"]));
+* // ➔ [ "dist/**" ]
+*
+* @example
+* formatOptionValue(/abc/i);
+* // ➔ /abc/i (colorized segments)
+*/
+declare function formatOptionValue(value: unknown, options?: FormatOptionValueOptions): string;
+/** ----------------------------------------------------------------
+* * ***Structured metadata for {@link ConfigurationError | `ConfigurationError`}.***
+* ----------------------------------------------------------------
+*
+* Describes machine-readable contextual information attached to a
+* {@link ConfigurationError | `ConfigurationError`} instance.
+*
+* - ***This structure is designed to:***
+*       - Provide debugging insight without parsing the error message.
+*       - Support structured logging and telemetry pipelines.
+*       - Remain extensible while preserving strong autocomplete support.
+*
+* ----------------------------------------------------------------
+* #### Common Fields:
+* ----------------------------------------------------------------
+*
+* - `received` — The actual value that failed validation.
+* - `context`  — Logical origin of the validation
+*                (e.g. function or factory name).
+*
+* Additional custom metadata may be attached as needed.
+*
+* ----------------------------------------------------------------
+* @remarks
+* - All properties are optional.
+* - This type intentionally allows arbitrary additional keys.
+* - Intended for machine-readable data (not human-facing text).
+*/
+interface ConfigurationErrorDetails {
+  /** * ***The actual received value that caused the validation failure.*** */
+  readonly received?: unknown;
+  /** * ***Logical origin of the validation (e.g. function name).*** */
+  readonly context?: string;
+  /** * ***Additional arbitrary metadata.*** */
+  readonly [key: string]: unknown;
+}
+/** ----------------------------------------------------------------
+* * ***Represents a developer configuration error.***
+* ----------------------------------------------------------------
+*
+* Thrown when invalid, inconsistent, or malformed configuration
+* is detected during application or library initialization.
+*
+* This error indicates a **programmer mistake** in how a component,
+* module, or library has been configured. It should **not** be used
+* for runtime user input validation.
+*
+* ----------------------------------------------------------------
+* #### When to use?
+* ----------------------------------------------------------------
+*
+* Use `ConfigurationError` for configuration-related issues such as:
+*
+* - Invalid initialization or factory options.
+* - Incorrect constructor arguments.
+* - Broken integration or adapter contracts.
+* - Misconfigured environment or setup parameters.
+* - Violations of expected configuration schemas.
+*
+* Do **not** use this error type for runtime user input validation
+* (such as request payloads, form data, or command arguments).
+* Those scenarios should use domain-specific validation errors instead.
+*
+* ----------------------------------------------------------------
+* #### Behavior
+* ----------------------------------------------------------------
+*
+* - Extends the native {@link Error | `Error`}.
+* - Sets `.name` to `"ConfigurationError"`.
+* - Preserves the original stack trace.
+* - Supports contextual metadata via `details`.
+* - Exposes a stable `code` identifier for programmatic handling.
+*
+* ----------------------------------------------------------------
+* #### Handling
+* ----------------------------------------------------------------
+*
+* Consumers may safely narrow using `instanceof`
+* or {@link ConfigurationError.is | `ConfigurationError.is`}
+* to access structured metadata.
+*
+* @example
+* ```ts
+* try {
+*   initializeSetup(options);
+* } catch (err) {
+*   if (err instanceof ConfigurationError) {
+*     console.error(err.message);
+*     console.error("Code:", err.code);
+*     console.error("Details:", err.details);
+*   }
+* }
+* ```
+*
+* @example
+* ```ts
+* throw ConfigurationError.invalid(
+*   "options.timeout",
+*   "must be a positive number",
+*   { received: value },
+*   "createComponent"
+* );
+* ```
+*
+* @example
+* ```ts
+* throw ConfigurationError.type(
+*   "config.adapter",
+*   "function",
+*   value
+* );
+* ```
+*
+* ----------------------------------------------------------------
+* @remarks
+* - Represents a **programmer-level configuration mistake**.
+* - Typically indicates a **non-recoverable initialization failure**.
+* - Intended for validating configuration in libraries or frameworks.
+*/
+declare class ConfigurationError extends Error {
+  /** ----------------------------------------------------------------
+  * * ***Creates a new `ConfigurationError` instance.***
+  * ----------------------------------------------------------------
+  *
+  * @param message - Fully formatted error message.
+  * @param details - Optional structured metadata describing the error.
+  *
+  * @remarks
+  * - The message is expected to be finalized (including punctuation).
+  * - Restores the prototype chain for ES5 targets.
+  * - Captures a clean stack trace in Node.js environments.
+  */
+  constructor(message: string, details?: Readonly<ConfigurationErrorDetails>);
+  /** ----------------------------------------------------------------
+  * * ***Stable runtime name for this error type.***
+  * ----------------------------------------------------------------
+  *
+  * - ***Mirrors the class identifier and is used to:***
+  *       - Set the `.name` property consistently.
+  *       - Provide cross-runtime identification.
+  *       - Avoid hardcoded string duplication.
+  *
+  * This value should remain stable across versions.
+  */
+  static readonly NAME = "ConfigurationError";
+  /** ----------------------------------------------------------------
+  * * ***Stable error identifier for `ConfigurationError`.***
+  * ----------------------------------------------------------------
+  *
+  * Can be used for:
+  * - Programmatic error discrimination.
+  * - Cross-bundle or cross-runtime error detection.
+  * - Structured logging and telemetry systems.
+  *
+  * This identifier is guaranteed to remain stable across versions.
+  */
+  static readonly CODE = "CONFIGURATION_ERROR";
+  /** ----------------------------------------------------------------
+  * * ***Stable error code associated with this instance.***
+  * ----------------------------------------------------------------
+  *
+  * Mirrors {@link CODE | `ConfigurationError.CODE`}.
+  *
+  * Useful when `instanceof` checks are not reliable
+  * across different runtime contexts.
+  */
+  readonly code: "CONFIGURATION_ERROR";
+  /** ----------------------------------------------------------------
+  * * ***Optional structured metadata associated with this error.***
+  * ----------------------------------------------------------------
+  *
+  * Provides additional contextual information useful for:
+  *
+  * - Debugging.
+  * - Structured logging.
+  * - Programmatic error handling.
+  *
+  * The structure of this object is defined by
+  * {@link ConfigurationErrorDetails| `ConfigurationErrorDetails`}.
+  *
+  * ----------------------------------------------------------------
+  * #### Common Usage
+  * ----------------------------------------------------------------
+  *
+  * @example
+  * ```ts
+  * try {
+  *   throw ConfigurationError.type(
+  *     "options.myFunction",
+  *     "myFunction",
+  *     value
+  *   );
+  * } catch (err) {
+  *   if (err instanceof ConfigurationError) {
+  *     console.log(err.details?.received);
+  *     console.log(err.details?.context);
+  *   }
+  * }
+  * ```
+  * ----------------------------------------------------------------
+  * @remarks
+  * - Intended for machine-readable data.
+  * - Immutable (`readonly`) to prevent accidental mutation.
+  * - May contain additional custom metadata fields.
+  */
+  readonly details?: Readonly<ConfigurationErrorDetails>;
+  /** ----------------------------------------------------------------
+  * * ***Normalizes an error message to ensure a single trailing period.***
+  * ----------------------------------------------------------------
+  *
+  * - Trims surrounding whitespace.
+  * - Removes any existing trailing period(s).
+  * - Appends exactly one `.` at the end.
+  *
+  * This guarantees consistent punctuation regardless of how
+  * the message fragments are constructed.
+  *
+  * ----------------------------------------------------------------
+  * @example
+  * ```ts
+  * ConfigurationError.format("Invalid value")
+  * // ➔ "Invalid value."
+  * ```
+  *
+  * @example
+  * ```ts
+  * ConfigurationError.format("Invalid value.")
+  * // ➔ "Invalid value."
+  * ```
+  *
+  * @example
+  * ```ts
+  * ConfigurationError.format("  Invalid value...  ")
+  * // ➔ "Invalid value."
+  * ```
+  * ----------------------------------------------------------------
+  */
+  static format(message: string): string;
+  /** ----------------------------------------------------------------
+  * * ***Safely wraps a string in a single pair of backticks.***
+  * ----------------------------------------------------------------
+  *
+  * Ensures consistent inline-code formatting while preventing
+  * duplicated or nested backticks.
+  *
+  * - Removes any existing backticks from the input.
+  * - Trims surrounding whitespace.
+  * - Wraps the cleaned value in exactly one pair of backticks.
+  *
+  * This prevents malformed output such as:
+  *
+  * ```text
+  * ``validateConfig``
+  * ```
+  *
+  * ----------------------------------------------------------------
+  * @param value - Raw string to be formatted as inline code.
+  * @returns The sanitized value wrapped in a single pair of backticks.
+  *
+  * ----------------------------------------------------------------
+  * @example
+  * ```ts
+  * ConfigurationError.wrapCode("fieldName")
+  * // ➔ "`fieldName`"
+  * ```
+  *
+  * @example
+  * ```ts
+  * ConfigurationError.wrapCode("`fieldName`")
+  * // ➔ "`fieldName`"
+  * ```
+  *
+  * @example
+  * ```ts
+  * ConfigurationError.wrapCode("  ``fieldName``  ")
+  * // ➔ "`fieldName`"
+  * ```
+  * ----------------------------------------------------------------
+  */
+  static wrapCode(value: string): string;
+  /** ----------------------------------------------------------------
+  * * ***Type guard for `ConfigurationError`.***
+  * ----------------------------------------------------------------
+  *
+  * Provides a robust alternative to `instanceof`,
+  * especially across bundle boundaries or mixed module systems.
+  *
+  * @param value - Unknown value to test.
+  * @returns `true` if the value is a {@link ConfigurationError | `ConfigurationError`}.
+  *
+  * @example
+  * if (ConfigurationError.is(err)) {
+  *   console.error(err.code);
+  * }
+  */
+  static is(value: unknown): value is ConfigurationError;
+  /** ----------------------------------------------------------------
+  * * ***Serializes the error into a structured JSON representation.***
+  * ----------------------------------------------------------------
+  *
+  * Provides a stable, machine-readable representation of the error,
+  * suitable for:
+  *
+  * - Structured logging.
+  * - Transport across process boundaries.
+  * - Diagnostics.
+  * - JSON.stringify().
+  *
+  * Unlike the native `Error` object, this method ensures that:
+  *
+  * - `name`, `message`, and `code` are always included.
+  * - `details` is preserved (if provided).
+  * - `stack` is included only when available.
+  *
+  * This guarantees predictable output when serializing errors.
+  *
+  * ----------------------------------------------------------------
+  * @returns A plain JSON-safe object describing the error.
+  *
+  * ----------------------------------------------------------------
+  * @example
+  * ```ts
+  * const err = ConfigurationError.invalid(
+  *   "options.title",
+  *   "must be a non-empty string",
+  *   { received: "" }
+  * );
+  *
+  * console.log(JSON.stringify(err, null, 2));
+  * ```
+  *
+  * Possible output:
+  *
+  * ```json
+  * {
+  *   "name": "ConfigurationError",
+  *   "message": "Invalid configuration: `options.title` must be a non-empty string.",
+  *   "code": "CONFIGURATION_ERROR",
+  *   "details": { "received": "" },
+  *   "stack": "ConfigurationError: ..."
+  * }
+  * ```
+  * ----------------------------------------------------------------
+  */
+  toJSON(): {
+    /** ----------------------------------------------------------------
+    * * ***Runtime identifier of the error instance.***
+    * ----------------------------------------------------------------
+    *
+    * Mirrors {@link ConfigurationError.NAME | `ConfigurationError.NAME`}.
+    *
+    * - ***Intended for:***
+    *       - Programmatic error discrimination.
+    *       - Logging and diagnostic pipelines.
+    *       - Cross-runtime error identification.
+    *
+    * This property is useful when `instanceof` checks are unreliable
+    * across module boundaries or bundled execution contexts.
+    */
+    name: string;
+    /** ----------------------------------------------------------------
+    * * ***Fully formatted error message.***
+    * ----------------------------------------------------------------
+    *
+    * The message is guaranteed to be normalized by internal factory helpers.
+    *
+    * - ***Guarantees:***
+    *       - Consistent punctuation rules.
+    *       - Safe inline-code formatting.
+    *       - Stable human-readable output.
+    *
+    * The message is expected to represent a finalized diagnostic string
+    * suitable for display, logging, or transport.
+    */
+    message: string;
+    /** ----------------------------------------------------------------
+    * * ***Stable machine-readable error code.***
+    * ----------------------------------------------------------------
+    *
+    * Mirrors {@link ConfigurationError.CODE | `ConfigurationError.CODE`}.
+    *
+    * - ***Intended for:***
+    *       - Cross-runtime error identification.
+    *       - Structured logging systems.
+    *       - Type-safe error discrimination without relying on `instanceof`.
+    *
+    * This identifier is guaranteed to remain stable across versions.
+    */
+    code: typeof ConfigurationError.CODE;
+    /** ----------------------------------------------------------------
+    * * ***Optional structured debugging metadata attached to the error.***
+    * ----------------------------------------------------------------
+    *
+    * #### Contains machine-readable contextual information such as:
+    * - Validation input values that caused the error.
+    * - Logical origin or execution context.
+    * - Custom diagnostic extensions.
+    *
+    * #### This field is designed for:
+    *    - Developer debugging.
+    *    - Telemetry collection.
+    *    - Internal system analysis.
+    *
+    * The structure is defined by
+    * {@link ConfigurationErrorDetails | `ConfigurationErrorDetails`}.
+    */
+    details?: Readonly<ConfigurationErrorDetails>;
+    /** ----------------------------------------------------------------
+    * * ***Optional stack trace captured at the error creation site.***
+    * ----------------------------------------------------------------
+    *
+    * May be undefined in environments where stack capture is unavailable.
+    *
+    * Stack traces are preserved primarily for debugging and
+    * post-mortem diagnostics.
+    */
+    stack?: string;
+  };
+  /** ----------------------------------------------------------------
+  * * ***Factory helper for generic configuration validation errors.***
+  * ----------------------------------------------------------------
+  *
+  * Produces a standardized error when a configuration field
+  * fails validation.
+  *
+  * @param field    - Dot-notated configuration path (e.g. `"ui.usage"`).
+  * @param reason   - Short descriptive phrase explaining the issue
+  *                   (without trailing period).
+  * @param details  - Optional structured metadata for debugging.
+  * @param context  - Optional logical origin of the validation
+  *                   (e.g. `"validateConfig"`), when provided,
+  *                   it is included in {@link details | `details`}
+  *                   under the `context` key and reflected in the error message.
+  *
+  * @returns A `ConfigurationError` instance with a normalized message.
+  *
+  * @example
+  * ConfigurationError.invalid(
+  *   "ui.usage",
+  *   "must be a non-empty string",
+  *   { received: usage },
+  *   "validateConfig"
+  * );
+  *
+  * // ➔ Invalid configuration in `validateConfig`:
+  * //   `ui.usage` must be a non-empty string.
+  */
+  static invalid(field: string, reason: string, details?: Record<string, unknown>, context?: string): ConfigurationError;
+  /** ----------------------------------------------------------------
+  * * ***Factory helper for configuration type mismatch errors.***
+  * ----------------------------------------------------------------
+  *
+  * Produces a standardized error when a configuration field
+  * does not match the expected type or structural contract.
+  *
+  * @param field    - Dot-notated configuration path.
+  * @param expected - Short description of the expected type or shape
+  *                   (without trailing period).
+  * @param received - The actual received value.
+  * @param context  - Optional logical origin of the validation
+  *                   (e.g. `"myFunction"`), when provided,
+  *                   it is included in {@link details | `details`}
+  *                   under the `context` key and reflected in the error message.
+  *
+  * @returns A `ConfigurationError` instance including the received value.
+  *
+  * @example
+  * ConfigurationError.type(
+  *   "options.myMainFunction",
+  *   "MyMainFunction",
+  *   value,
+  *   "myFunction"
+  * );
+  *
+  * // ➔ Invalid configuration in `myFunction`:
+  * //   `options.myMainFunction` must be MyMainFunction.
+  */
+  static type(field: string, expected: string, received: unknown, context?: string): ConfigurationError;
+}
+export { ConfigurationError, type ConfigurationErrorDetails, EOL, NEWLINE, formatOptionValue, joinInline, joinLines, joinLinesLoose, padText, picocolors, plural };
+//# sourceMappingURL=client.d.cts.map