@rzl-zone/utils-js 3.12.1-beta.0 → 3.13.0-beta.2

package/dist/index-DWWvtHUn.d.cts

@@ -1,822 +0,0 @@
-/*!
-* ========================================================================
-*  @rzl-zone/utils-js
-* ------------------------------------------------------------------------
-*  Version: `3.12.1-beta.0`
-*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
-*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
-* ========================================================================
-*/
-
-import { a as IsNumberOptions, c as GetPreciseTypeOptions, i as ArrayFallback, t as IsPlainObjectResult } from "./isPlainObject-doTI11Ib.cjs";
-import { AnyString, PickStrict, Prettify } from "@rzl-zone/ts-types-plus";
-/** -------------------------------------------------------
- * * ***Shape of the object passed to custom error message functions.***
- * -------------------------------------------------------
- * **This type describes the parameters received when `options.message`
- * is defined as a function in {@link OptionsAssertIs | `OptionsAssertIs`}.**
- * - **Parameter:**
- *    - `currentType` ➔ the actual detected runtime type of the value.
- *    - `validType`   ➔ the required/expected type name that the value must match.
- * @example
- * ```ts
- * const options: OptionsAssertIs = {
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got ${currentType}`;
- *   };
- * };
- * ```
- */
-type OptionsMessageFunctionAssertIs = {
-  /** ---------------------------------------------------------------------------
-   * * ***The actual runtime type of the value being checked.***
-   * ---------------------------------------------------------------------------
-   * - ***Example:***
-   *    - `"number"`, `"big-int"`, `"plain-object"`, (depends `formatCase` options).
-   */
-  currentType: string;
-  /** ---------------------------------------------------------------------------
-   * * ***The required/expected type that the value must conform to.***
-   * ---------------------------------------------------------------------------
-   * - ***Example:***
-   *    - `"boolean"`, `"string"`, `"big-int"`, `"plain-object"`, (will force format to `kebab-case`).
-   */
-  validType: string;
-};
-/** -------------------------------------------------------
- * * ***Custom error-message type for assertions option {@link OptionsAssertIs | `OptionsAssertIs`}.***
- * -------------------------------------------------------
- * - ***Accepts:***
- *    - A static string message.
- *    - A function receiving `{ currentType, validType }` and returning a string.
- */
-type OptionsMessageAssertIs = (({
-  currentType,
-  validType
-}: OptionsMessageFunctionAssertIs) => string) | string;
-/** ---------------------------------------------------------------------------
- * * ***Base options for `assertIs*` functions.***
- * ---------------------------------------------------------------------------
- */
-type OptionsAssertIs = Prettify<{
-  /** -------------------------------------------------------
-   * * ***Custom error message for assertion failures.***
-   * -------------------------------------------------------
-   * **This option allows overriding the **default error message** when a value
-   * does not match the required type.**
-   * - If a **string** is provided:
-   *    - Must be non-empty after trimming.
-   *    - Will be used directly as the error message.
-   * - If a **function** is provided:
-   *    - Receives an object containing:
-   *      - `currentType` ➔ the detected runtime type of the value (depends `formatCase` options, e.g., `"number"`).
-   *      - `validType`  ➔ the expected type name (with format `kebab-case`, e.g., `"boolean"`, `"big-int"`, `"plain-object"`).
-   *    - **Must** return a **string**:
-   *      - **If** the **returned string is** `empty` or `whitespace`,
-   *        the **default message** will be used instead.
-   * @example
-   * ```ts
-   * // Static message
-   * { message: "Must be a boolean!" }
-   *
-   * // Dynamic message
-   * {
-   *   message: ({ currentType, validType }) => {
-   *     return `Expected ${validType} but got ${currentType}`;
-   *   };
-   * }
-   * ```
-   */
-  message?: OptionsMessageAssertIs;
-  /** -------------------------------------------------------
-   * * ***Custom error type for assertion failures.***
-   * -------------------------------------------------------
-   * **This option allows overriding the default error type** that will be thrown
-   * when a value does not match the required type.
-   *
-   * - **Behavior:**
-   *    - Must be one of the standard JavaScript built-in error types:
-   *      `"Error" | "EvalError" | "RangeError" | "ReferenceError" | "SyntaxError" | "TypeError" | "URIError"`
-   *    - **Default:** `"TypeError"` if not provided or if an invalid value is passed.
-   *    - The assertion function will **always throw a valid built-in error**, ensuring
-   *   fallback to `TypeError` in case of an unknown or incorrect type.
-   * @example
-   * ```ts
-   * // Valid: Throw a RangeError instead of TypeError
-   * { errorType: "RangeError" }
-   *
-   * // Valid: Throw a ReferenceError
-   * { errorType: "ReferenceError" }
-   *
-   * // Invalid value ➔ fallback to TypeError
-   * { errorType: "SomeUnknownError" as ErrorType }
-   * ```
-   */
-  errorType?: ErrorType;
-} & PickStrict<GetPreciseTypeOptions, "formatCase" | "useAcronyms">, {
-  recursive: true;
-}>;
-type ErrorType = "Error" | "EvalError" | "RangeError" | "ReferenceError" | "SyntaxError" | "TypeError" | "URIError";
-/** -------------------------------------------------------
- * * ***Type guard assertion: `assertIsBoolean`.***
- * -------------------------------------------------------
- * **This function is an **assertion function**.**
- * - **Behavior:**
- *    - Validates that the given `value` is a **boolean**.
- *    - After it returns successfully, TypeScript narrows the type of `value` to `boolean`.
- *    - ✅ If `value` is a `boolean` ➔ execution continues normally.
- *    - ❌ If `value` is not a `boolean` ➔ throws a built-in error with either:
- *      - A custom error message (`options.message`), or
- *      - A default message including the actual type.
- * - **⚠️ Error type selection (`options.errorType`):**
- *    - You can override the type of error thrown when validation fails.
- *    - Must be one of the standard JavaScript built-in errors:
- *      - [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) |
- *        [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) |
- *        [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError) |
- *        [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError) |
- *        [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) |
- *        [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) |
- *        [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError)
- *    - **Default:** `"TypeError"` if not provided or invalid.
- * @param {*} value - ***The value to validate.***
- * @param {OptionsAssertIs} [options]
- *  ***Optional configuration:***
- *    - `message`: A custom error message (`string` or `function`).
- *    - `errorType`: A custom built-in JavaScript error type to throw.
- *    - `formatCase`: Controls how detected type names are formatted case in error messages.
- *    - `useAcronyms`: Control uppercase preservation of recognized acronyms during formatting.
- * @returns {boolean} Narrows `value` to `boolean` if no error is thrown.
- * @throws [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) | [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) | [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError) | [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError) | [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) | [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) | [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError) if the value is not a boolean.
- * @example
- * ```ts
- * // ✅ Simple usage
- * assertIsBoolean(true);
- * // No error, value is boolean
- *
- * // ❌ Throws TypeError (default behavior)
- * // Case 1: Invalid input type — received a string instead of a boolean
- * assertIsBoolean("hello");
- * // ➔ TypeError: "Parameter input (`value`) must be of type `boolean`, but received: `number`."
- *
- * // Case 2: The new Boolean() is a Boolean object (constructor), not a primitive boolean
- * assertIsBoolean(new Boolean(true));
- * // ➔ TypeError: "Parameter input (`value`) must be of type `boolean`, but received: `boolean-constructor`."
- *
- * // ❌ Throws a TypeError with a custom string static message
- * assertIsBoolean(42, { message: "Must be boolean!" });
- * // ➔ TypeError: "Must be boolean!"
- *
- * // ❌ Throws RangeError (custom error type)
- * assertIsBoolean(42, { errorType: "RangeError" });
- * // ➔ RangeError: "Parameter input (`value`) must be of type `boolean`, but received: `number`."
- *
- * // ❌ Throws a TypeError with a custom message function and formatCase
- * assertIsBoolean(/regex/, {
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- *   formatCase: "toPascalCaseSpace"
- * });
- * // ➔ TypeError: "Expected boolean but got (Reg Exp)."
- *
- * // ❌ Throws a TypeError with a custom useAcronyms option
- * // Case 1:
- * assertIsBoolean(new URL("https://example.com"),{
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected boolean but got (url)."
- * assertIsBoolean(new URL("https://example.com"), {
- *   useAcronyms: true,
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected boolean but got (URL)."
- *
- * // Case 2:
- * assertIsBoolean(new URLSearchParams, {
- *   formatCase: "toPascalCase",
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected boolean but got (UrlSearchParams)."
- * assertIsBoolean(new URLSearchParams, {
- *   useAcronyms: true,
- *   formatCase: "toPascalCase",
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected boolean but got (URLSearchParams)."
- * ```
- * -------------------------------------------------------
- * ✅ ***Real-world usage example***:
- * ```ts
- * const mixedValue: string | boolean | number | undefined = getUserInput();
- *
- * // Runtime assertion: throws if `mixedValue` is not a `boolean`
- * assertIsBoolean(mixedValue, {
- *   errorType: "RangeError",
- *   message: "Must be boolean!"
- * });
- *
- * // ✅ If no error thrown, TypeScript narrows `mixedValue` to `boolean` here
- * const result: boolean = mixedValue; // ➔ Safe type assignment
- * ```
- */
-declare const assertIsBoolean: (value: unknown, options?: OptionsAssertIs) => asserts value is boolean;
-/** -------------------------------------------------------
- * * ***Type guard assertion: `assertIsBigInt`.***
- * -------------------------------------------------------
- * **This function is an **assertion function**.**
- * - **Behavior:**
- *    - Validates that the given `value` is a **bigint**.
- *    - After it returns successfully, TypeScript narrows the type of `value` to `bigint`.
- *    - ✅ If `value` is a `bigint` ➔ execution continues normally.
- *    - ❌ If `value` is not a `bigint` ➔ throws a built-in error with either:
- *      - A custom error message (`options.message`), or
- *      - A default message including the actual type.
- *  - **ℹ️ Note:**
- *    - A `bigint` refers strictly to the JavaScript `bigint` primitive type (e.g., `123n`, `0n`, `-999999999999999999999n`).
- *    - This excludes `BigInt` objects created with `Object(BigInt(123))`.
- *  - **⚠️ Error type selection (`options.errorType`):**
- *    - You can override the type of error thrown when validation fails.
- *    - Must be one of the standard JavaScript built-in errors:
- *      - [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) |
- *        [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) |
- *        [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError) |
- *        [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError) |
- *        [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) |
- *        [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) |
- *        [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError)
- *    - **Default:** `"TypeError"` if not provided or invalid.
- * @param {*} value - ***The value to validate.***
- * @param {OptionsAssertIs} [options]
- *  ***Optional configuration:***
- *    - `message`: A custom error message (`string` or `function`).
- *    - `errorType`: Built-in JavaScript error type to throw on failure (default `"TypeError"`).
- *    - `formatCase`: Controls how detected type names are formatted case in error messages.
- *    - `useAcronyms`: Control uppercase preservation of recognized acronyms during formatting.
- * @returns {boolean} Narrows `value` to `bigint` if no error is thrown.
- * @throws [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) | [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) | [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError) | [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError) | [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) | [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) | [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError) if the value is not a bigint.
- * @example
- * ```ts
- * // ✅ Simple usage
- * assertIsBigInt(123n);
- * // No error, value is bigint
- *
- * // ❌ Throws TypeError (default behavior)
- * assertIsBigInt(42);
- * // ➔ TypeError: "Parameter input (`value`) must be of type `bigint`, but received: `number`."
- *
- * // ❌ Throws a TypeError with a custom string static message
- * assertIsBigInt("123", { message: "Must be a bigint!" });
- * // ➔ TypeError: "Must be a bigint!"
- *
- * // ❌ Throws custom error type (e.g., RangeError)
- * assertIsBigInt(async function () {}, { errorType: "RangeError" });
- * // ➔ RangeError: "Parameter input (`value`) must be of type `bigint`, but received: `async-function`."
- *
- * // ❌ Throws a TypeError with a custom message function and formatCase
- * assertIsBigInt(/regex/, {
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- *   formatCase: "toPascalCaseSpace"
- * });
- * // ➔ TypeError: "Expected bigint but got (Reg Exp)."
- *
- * // ❌ Throws a TypeError with a custom useAcronyms option
- * // Case 1:
- * assertIsBigInt(new URL("https://example.com"),{
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected bigint but got (url)."
- * assertIsBigInt(new URL("https://example.com"), {
- *   useAcronyms: true,
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected bigint but got (URL)."
- *
- * // Case 2:
- * assertIsBigInt(new URLSearchParams, {
- *   formatCase: "toPascalCase",
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected bigint but got (UrlSearchParams)."
- * assertIsBigInt(new URLSearchParams, {
- *   useAcronyms: true,
- *   formatCase: "toPascalCase",
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected bigint but got (URLSearchParams)."
- * ```
- * -------------------------------------------------------
- * ✅ ***Real-world usage example***:
- * ```ts
- * const mixedValue: string | bigint | undefined = getUserInput();
- *
- * // Runtime assertion: throws if `mixedValue` is not a `bigint`
- * assertIsBigInt(mixedValue, {
- *   errorType: "RangeError",
- *   message: "Must be bigint!"
- * });
- *
- * // ✅ If no error thrown, TypeScript narrows `mixedValue` to `bigint` here
- * const result: bigint = mixedValue; // ➔ Safe type assignment
- * console.log(result + 100n);        // ➔ Safe to operation
- * ```
- */
-declare const assertIsBigInt: (value: unknown, options?: OptionsAssertIs) => asserts value is bigint;
-type OptionsAssertIsNumber = OptionsAssertIs & IsNumberOptions;
-/** -------------------------------------------------------
- * * ***Type guard assertion: `assertIsNumber`.***
- * -------------------------------------------------------
- * **This function is an **assertion function**.**
- * - **Behavior:**
- *    - Validates that the given `value` is a **number**.
- *    - After it returns successfully, TypeScript narrows the type of `value` to `number`.
- *    - ✅ If `value` is a `number` ➔ execution continues normally.
- *    - ❌ If `value` is not a `number` ➔ throws a built-in error with either:
- *      - A custom error message (`options.message`), or
- *      - A default message including the actual type.
- * - **ℹ️ Note:**
- *    - A `number` refers strictly to the JavaScript `number` primitive type (e.g., `42`, `3.14`, `-1`, `0`).
- *    - This excludes `Number` objects created with `new Number(123)`.
- *    - By default, `NaN` is **not considered** valid, you can allow it with `{ includeNaN: true }`.
- * - **⚠️ Error type selection (`options.errorType`):**
- *    - You can override the type of error thrown when validation fails.
- *    - Must be one of the standard JavaScript built-in errors:
- *      - [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) |
- *        [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) |
- *        [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError) |
- *        [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError) |
- *        [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) |
- *        [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) |
- *        [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError)
- *    - **Default:** `"TypeError"` if not provided or invalid.
- * @param {*} value - ***The value to validate.***
- * @param {OptionsAssertIsNumber} [options]
- *  ***Optional configuration:***
- *    - `message`: A custom error message (`string` or `function`).
- *    - `errorType`: Built-in JavaScript error type to throw on failure (default `"TypeError"`).
- *    - `formatCase`: Controls how detected type names are formatted case in error messages.
- *    - `useAcronyms`: Control uppercase preservation of recognized acronyms during formatting.
- *    - `includeNaN`: Whether to treat `NaN` as valid.
- * @returns {boolean} Narrows `value` to `number` if no error is thrown.
- * @throws [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) | [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) | [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError) | [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError) | [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) | [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) | [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError) if the value is not a number (or is `NaN` when `includeNaN` is `false`).
- * @example
- * ```ts
- * // ✅ Simple usage
- * assertIsNumber(123);
- * assertIsNumber(NaN, { includeNaN: true });
- * // No error, value is number
- *
- * // ❌ Throws TypeError (default behavior)
- * // Case 1: Invalid input type — received a string instead of a number
- * assertIsNumber("42");
- * // ➔ TypeError: "Parameter input (`value`) must be of type `number`, but received: `string`."
- *
- * // Case 2: Default option includeNaN is false
- * assertIsNumber(NaN);
- * // ➔ TypeError: "Parameter input (`value`) must be of type `number`, but received: `NaN`."
- *
- * // Case 3: The new Number() is a Number object (constructor), not a primitive number
- * assertIsNumber(new Number("123"));
- * // ➔ TypeError: "Parameter input (`value`) must be of type `number`, but received: `number-constructor`."
- *
- * // ❌ Throws custom error type (e.g., RangeError)
- * assertIsNumber(async function () {}, { errorType: "RangeError" });
- * // ➔ RangeError: "Parameter input (`value`) must be of type `number`, but received: `async-function`."
- *
- * // ❌ Throws a TypeError with a custom string static message
- * assertIsNumber("123", { message: "Must be a number!" });
- * // ➔ TypeError: "Must be a number!"
- *
- * // ❌ Throws a TypeError with a custom message function and formatCase
- * assertIsNumber(/regex/, {
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- *   formatCase: "toPascalCaseSpace"
- * });
- * // ➔ TypeError: "Expected number but got (Reg Exp)."
- *
- * // ❌ Throws a TypeError with a custom useAcronyms option
- * // Case 1:
- * assertIsNumber(new URL("https://example.com"),{
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected number but got (url)."
- * assertIsNumber(new URL("https://example.com"), {
- *   useAcronyms: true,
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected number but got (URL)."
- *
- * // Case 2:
- * assertIsNumber(new URLSearchParams, {
- *   formatCase: "toPascalCase",
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected number but got (UrlSearchParams)."
- * assertIsNumber(new URLSearchParams, {
- *   useAcronyms: true,
- *   formatCase: "toPascalCase",
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected number but got (URLSearchParams)."
- * ```
- * -------------------------------------------------------
- * ✅ ***Real-world usage example***:
- * ```ts
- * const mixedValue: string | number | undefined = getUserInput();
- *
- * // Runtime assertion: throws if `mixedValue` is not a `number`
- * assertIsNumber(mixedValue, {
- *   errorType: "RangeError",
- *   message: "Must be number!"
- * });
- *
- * // ✅ If no error thrown, TypeScript narrows `mixedValue` to `number` here
- * const result: number = mixedValue; // ➔ Safe type assignment
- * console.log(result + 100);         // ➔ Safe to operation
- * ```
- */
-declare const assertIsNumber: (value: unknown, options?: OptionsAssertIsNumber) => asserts value is number;
-/** -------------------------------------------------------
- * * ***Type guard assertion: `assertIsArray`.***
- * -------------------------------------------------------
- * **This function is an **assertion function**.**
- * - **Behavior:**
- *    - Validates that the given `value` is an **array**.
- *    - After it returns successfully, TypeScript narrows the type of `value` to `array` **(generic support)**.
- *    - ✅ If `value` is an `array` ➔ execution continues normally.
- *    - ❌ If `value` is not an `array` ➔ throws a built-in error with either:
- *      - A custom error message (`options.message`), or
- *      - A default message including the actual type.
- * - **⚠️ Error type selection (`options.errorType`):**
- *    - You can override the type of error thrown when validation fails.
- *    - Must be one of the standard JavaScript built-in errors:
- *      - [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) |
- *        [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) |
- *        [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError) |
- *        [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError) |
- *        [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) |
- *        [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) |
- *        [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError)
- *    - **Default:** `"TypeError"` if not provided or invalid.
- * @template T - The input type being asserted.
- * @param {*} value - ***The value to validate.***
- * @param {OptionsAssertIs} [options]
- *  ***Optional configuration:***
- *    - `message`: A custom error message (`string` or `function`).
- *    - `errorType`: Built-in JavaScript error type to throw on failure (default `"TypeError"`).
- *    - `formatCase`: Controls how detected type names are formatted case in error messages.
- *    - `useAcronyms`: Control uppercase preservation of recognized acronyms during formatting.
- * @returns {boolean} Narrows `value` to an `array` **(generic support)** if no error is thrown.
- * @throws [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) | [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) | [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError) | [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError) | [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) | [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) | [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError) if the value is not an array.
- * @example
- * ```ts
- * // ✅ Simple usage
- * assertIsArray([]);
- * assertIsArray(["123", 456]);
- * assertIsArray(Array.from(["abc"]));
- * // No error, value is array
- *
- * // ❌ Throws TypeError (default behavior)
- * // Case 1: Invalid input type — received a string instead of a array
- * assertIsArray("42");
- * // ➔ TypeError: "Parameter input (`value`) must be of type `array`, but received: `string`."
- *
- * // ❌ Throws custom error type (e.g., RangeError)
- * assertIsArray(async function () {}, { errorType: "RangeError" });
- * // ➔ RangeError: "Parameter input (`value`) must be of type `array`, but received: `async-function`."
- *
- * // ❌ Throws a TypeError with a custom string static message
- * assertIsArray("123", { message: "Must be a array!" });
- * // ➔ TypeError: "Must be a array!"
- *
- * // ❌ Throws a TypeError with a custom message function and formatCase
- * assertIsArray(/regex/, {
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- *   formatCase: "toPascalCaseSpace"
- * });
- * // ➔ TypeError: "Expected array but got (Reg Exp)."
- *
- * // ❌ Throws a TypeError with a custom useAcronyms option
- * // Case 1:
- * assertIsArray(new URL("https://example.com"),{
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected array but got (url)."
- * assertIsArray(new URL("https://example.com"), {
- *   useAcronyms: true,
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected array but got (URL)."
- *
- * // Case 2:
- * assertIsArray(new URLSearchParams, {
- *   formatCase: "toPascalCase",
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected array but got (UrlSearchParams)."
- * assertIsArray(new URLSearchParams, {
- *   useAcronyms: true,
- *   formatCase: "toPascalCase",
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected array but got (URLSearchParams)."
- * ```
- * -------------------------------------------------------
- * ✅ ***Real-world usage example***:
- * ```ts
- * const mixedValue: string | number[] | undefined = getUserInput();
- *
- * // Runtime assertion: throws if `mixedValue` is not a `number[]`
- * assertIsArray(mixedValue, {
- *   errorType: "RangeError",
- *   message: "Must be array!"
- * });
- *
- * // ✅ If no error thrown, TypeScript narrows `mixedValue` to `number[]` here
- * const result: number[] = mixedValue; // ➔ Safe type assignment
- * console.log(result.push(1, 2, 3));   // ➔ Safe to use array methods
- * ```
- */
-declare function assertIsArray(value: [], options?: OptionsAssertIs): asserts value is [];
-declare function assertIsArray<T>(value: T, options?: OptionsAssertIs): asserts value is ArrayFallback<T>;
-declare function assertIsArray(value: unknown, options?: OptionsAssertIs): asserts value is unknown[];
-/** -------------------------------------------------------
- * * ***Type guard assertion: `assertIsPlainObject`.***
- * -------------------------------------------------------
- * **This function is an **assertion function**.**
- * - **Behavior:**
- *    - Validates that the given `value` is a **plain-object**.
- *    - After it returns successfully, TypeScript narrows the type of `value` to `plain-object` **(generic support)**.
- *    - ✅ If `value` is a `plain-object` ➔ execution continues normally.
- *    - ❌ If `value` is not a `plain-object` ➔ throws a built-in error with either:
- *      - A custom error message (`options.message`), or
- *      - A default message including the actual type.
- * - **A valid `plain object` is:**
- *    - Created by the `Object` constructor, or
- *    - Has a `[[Prototype]]` of `null` (e.g. `Object.create(null)`).
- *     - **✅ Returns `undefined` (valid) for:**
- *         - Empty object literals: `{}`
- *         - Objects with null prototype: `Object.create(null)`
- *     - **❌ Returns `throws` for:**
- *         - Arrays (`[]`, `new Array()`)
- *         - Functions (regular, arrow, or class constructors)
- *         - Built-in objects: `Date`, `RegExp`, `Error`, `Map`, `Set`, `WeakMap`, `WeakSet`
- *         - Boxed primitives: `new String()`, `new Number()`, `new Boolean()`
- *         - `null` or `undefined`
- *         - Symbols
- *         - Class instances
- * - **⚠️ Error type selection (`options.errorType`):**
- *    - You can override the type of error thrown when validation fails.
- *    - Must be one of the standard JavaScript built-in errors:
- *      - [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) |
- *        [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) |
- *        [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError) |
- *        [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError) |
- *        [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) |
- *        [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) |
- *        [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError)
- *    - **Default:** `"TypeError"` if not provided or invalid.
- * @template T - The input type being asserted.
- * @param {*} value - ***The value to validate.***
- * @param {OptionsAssertIs} [options]
- *  ***Optional configuration:***
- *    - `message`: A custom error message (`string` or `function`).
- *    - `errorType`: Built-in JavaScript error type to throw on failure (default `"TypeError"`).
- *    - `formatCase`: Controls how detected type names are formatted case in error messages.
- *    - `useAcronyms`: Control uppercase preservation of recognized acronyms during formatting.
- * @returns {boolean} Narrows `value` to a `plain-object` **(generic support)** if no error is thrown.
- * @throws [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) | [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) | [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError) | [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError) | [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) | [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) | [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError) if `value` is not a plain-object.
- * @example
- * ```ts
- * // ✅ Simple usage
- * assertIsPlainObject({ a: 1, b: 2 });
- * // No error, value is plain-object
- *
- * // ❌ Throws TypeError (default behavior)
- * // Case 1: Invalid input type — received a string instead of a plain-object
- * assertIsPlainObject("42");
- * // ➔ TypeError: "Parameter input (`value`) must be of type `plain-object`, but received: `string`."
- *
- * // ❌ Throws custom error type (e.g., RangeError)
- * assertIsPlainObject(async function () {}, { errorType: "RangeError" });
- * // ➔ RangeError: "Parameter input (`value`) must be of type `plain-object`, but received: `async-function`."
- *
- * // ❌ Throws a TypeError with a custom string static message
- * assertIsPlainObject("123", { message: "Must be a plain-object!" });
- * // ➔ TypeError: "Must be a plain-object!"
- *
- * // ❌ Throws a TypeError with a custom message function and formatCase
- * assertIsPlainObject(/regex/, {
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- *   formatCase: "toPascalCaseSpace"
- * });
- * // ➔ TypeError: "Expected plain-object but got (Reg Exp)."
- *
- * // ❌ Throws a TypeError with a custom useAcronyms option
- * // Case 1:
- * assertIsPlainObject(new URL("https://example.com"),{
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected plain-object but got (url)."
- * assertIsPlainObject(new URL("https://example.com"), {
- *   useAcronyms: true,
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected plain-object but got (URL)."
- *
- * // Case 2:
- * assertIsPlainObject(new URLSearchParams, {
- *   formatCase: "toPascalCase",
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected plain-object but got (UrlSearchParams)."
- * assertIsPlainObject(new URLSearchParams, {
- *   useAcronyms: true,
- *   formatCase: "toPascalCase",
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected plain-object but got (URLSearchParams)."
- * ```
- * -------------------------------------------------------
- * ✅ ***Real-world usage with generic narrowing***:
- * ```ts
- * type User = { name: string; email: string };
- * const mixedValue: string | User | boolean | number | undefined = getUserInput();
- *
- * // Runtime assertion: throws if `mixedValue` is not a `plain-object`
- * assertIsPlainObject(mixedValue, {
- *   errorType: "RangeError",
- *   message: "Must be plain object!"
- * });
- *
- * // ✅ If no error thrown, TypeScript narrows `mixedValue` to `User` here
- * const user: User = mixedValue; // ➔ Safe type assignment
- * console.log(user.email);       // ➔ Safe to access object properties
- * ```
- */
-declare function assertIsPlainObject<T>(value: T, options?: OptionsAssertIs): asserts value is IsPlainObjectResult<T>;
-/** -------------------------------------------------------
- * * ***Type guard assertion: `assertIsString`.***
- * -------------------------------------------------------
- * **This function is an **assertion function**.**
- * - **Behavior:**
- *    - Validates that the given `value` is a **primitive-string**.
- *    - After it returns successfully, TypeScript narrows the type of `value` to `primitive-string`.
- *    - ✅ If `value` is a `primitive-string` ➔ execution continues normally.
- *    - ❌ If `value` is not a `primitive-string` ➔ throws a built-in error with either:
- *      - A custom error message (`options.message`), or
- *      - A default message including the actual type.
- * - **ℹ️ Note:**
- *    - A "string" refers strictly to a JavaScript `primitive-string` type (e.g., `"hello"`, `""`, `"123"`).
- *    - This function excludes `String` objects created with `new String()`.
- * - **⚠️ Error type selection (`options.errorType`):**
- *    - You can override the type of error thrown when validation fails.
- *    - Must be one of the standard JavaScript built-in errors:
- *      - [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) |
- *        [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) |
- *        [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError) |
- *        [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError) |
- *        [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) |
- *        [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) |
- *        [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError)
- *    - **Default:** `"TypeError"` if not provided or invalid.
- * @param {*} value - ***The value to validate.***
- * @param {OptionsAssertIs} [options]
- *  ***Optional configuration:***
- *    - `message`: A custom error message (`string` or `function`).
- *    - `errorType`: Built-in JavaScript error type to throw on failure (default `"TypeError"`).
- *    - `formatCase`: Controls how detected type names are formatted case in error messages.
- *    - `useAcronyms`: Control uppercase preservation of recognized acronyms during formatting.
- * @returns {boolean} Narrows `value` to `string` if no error is thrown.
- * @throws [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) | [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) | [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError) | [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError) | [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) | [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) | [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError) if the value is not a primitive string.
- * @example
- * ```ts
- * // ✅ Simple usage
- * assertIsString("hello");
- * // No error, value is string
- *
- * // ❌ Throws TypeError (default behavior)
- * // Case 1: Invalid input type — received a string instead of a string
- * assertIsString(42);
- * // ➔ TypeError: "Parameter input (`value`) must be of type `string`, but received: `number`."
- *
- * // Case 3: The new String() is a String object (constructor), not a primitive string
- * assertIsString(new String("abc"));
- * // ➔ TypeError: "Parameter input (`value`) must be of type `string`, but received: `string-constructor`."
- *
- * // ❌ Throws custom error type (e.g., RangeError)
- * assertIsString(async function () {}, { errorType: "RangeError" });
- * // ➔ RangeError: "Parameter input (`value`) must be of type `string`, but received: `async-function`."
- *
- * // ❌ Throws a TypeError with a custom string static message
- * assertIsString(123, { message: "Must be a string!" });
- * // ➔ TypeError: "Must be a string!"
- *
- * // ❌ Throws a TypeError with a custom message function and formatCase
- * assertIsString(/regex/, {
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- *   formatCase: "toPascalCaseSpace"
- * });
- * // ➔ TypeError: "Expected string but got (Reg Exp)."
- *
- * // ❌ Throws a TypeError with a custom useAcronyms option
- * // Case 1:
- * assertIsString(new URL("https://example.com"),{
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected string but got (url)."
- * assertIsString(new URL("https://example.com"), {
- *   useAcronyms: true,
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected string but got (URL)."
- *
- * // Case 2:
- * assertIsString(new URLSearchParams, {
- *   formatCase: "toPascalCase",
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected string but got (UrlSearchParams)."
- * assertIsString(new URLSearchParams, {
- *   useAcronyms: true,
- *   formatCase: "toPascalCase",
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`
- *   },
- * });
- * // ➔ TypeError: "Expected string but got (URLSearchParams)."
- * ```
- * -------------------------------------------------------
- * ✅ ***Real-world usage with generic narrowing***:
- * ```ts
- * const mixedValue: string | boolean | undefined = getUserInput();
- *
- * // Runtime assertion: throws if `mixedValue` is not a `string`
- * assertIsString(mixedValue, {
- *   errorType: "RangeError",
- *   message: "Must be a string!"
- * });
- *
- * // ✅ If no error thrown, TypeScript narrows `mixedValue` to `string` here
- * const result: string = mixedValue; // ➔ Safe type assignment
- * console.log(result.toUpperCase()); // ➔ Safe to call String.prototype methods
- * ```
- */
-declare const assertIsString: (value: unknown, options?: OptionsAssertIs) => asserts value is string;
-export { assertIsBigInt as a, assertIsNumber as i, assertIsPlainObject as n, assertIsBoolean as o, assertIsArray as r, assertIsString as t };