@rzl-zone/utils-js 3.0.2-beta.2 → 3.1.1-beta.0

package/dist/assertions/index.d.ts

@@ -1,428 +1,408 @@
-import{G as GetPreciseTypeOptions,I as IsNumberOptions,a as IsPlainObjectResult}from'../isPlainObject-BKYaI6a8.js';import'../type-data-DDs-u2kq.js';
+import{G as GetPreciseTypeOptions,I as IsNumberOptions,a as IsPlainObjectResult}from'../isPlainObject-BVhBAPHX.js';import'../type-data-DDs-u2kq.js';
 /** -------------------------------------------------------
-* * ***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 `AssertIsOptions`.
-*
-* - `currentType` ➔ the actual detected runtime type of the value.
-* - `validType`   ➔ the required/expected type name that the value must match.
-*
-* @example
-* ```ts
-* const options: AssertIsOptions = {
-*   message: ({ currentType, validType }) =>
-*     `Expected ${validType} but got ${currentType}`
-* };
-* ```
-*/
-type AssertIsOptionsMessageFunction={
+ * * ***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 `OptionsAssertIs`.
+ *
+ * - `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 }) =>
+ *     `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).
-*/
+ *
+ * - 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;};type AssertIsOptions={
-/** 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 }) =>
-*     `Expected ${validType} but got ${currentType}`
-* }
-* ```
-*/
-message?:string|(({currentType,validType}:AssertIsOptionsMessageFunction)=>string);}& GetPreciseTypeOptions;
+ *
+ * - Example: `"boolean"`, `"string"`, `"big-int"`, `"plain-object"`, (will force format to `kebab-case`).
+ */
+validType:string;};type OptionsAssertIs={
 /** -------------------------------------------------------
-* * ***Asserts that a value is of type `boolean`.***
-* -------------------------------------------------------
-* Validates that the given `value` is a **boolean**.
-*
-* - ✅ If `value` is a boolean → execution continues normally.
-* - ❌ If `value` is not a boolean → throws a `TypeError` with either:
-*   - A custom error message (`options.message`), or
-*   - A default message including the actual type.
-*
-* This function is an **assertion function**.
-* After it returns successfully, TypeScript narrows the type of `value` to `boolean`.
-*
-* @param value - The value to validate.
-* @param options - Optional configuration:
-*   - `message`: A custom error message (string or function).
-*   - `formatCase`: Controls type formatting (from `GetPreciseTypeOptions`).
-*
-* @returns {asserts value is boolean} Narrows `value` to `boolean` if no error is thrown.
-* @throws {TypeError} If the value is not a boolean.
-*
-* @example
-* ```ts
-* // ✅ Simple usage
-* assertIsBoolean(true);
-* // No error, value is boolean
-*
-* // ❌ Throws TypeError with default message
-* assertIsBoolean(42);
-* // ➔ TypeError: "Parameter input (`value`) must be of type `boolean`, but received: `number`."
-*
-* // ❌ Throws with custom string message
-* assertIsBoolean(42, { message: "Must be boolean!" });
-* // ➔ TypeError: "Must be boolean!"
-*
-* // ❌ Throws with custom function message + case formatting
-* assertIsBoolean(123n, {
-*   message: ({ currentType, validType }) =>
-*     `Expected ${validType} but got (${currentType}).`,
-*   formatCase: "toKebabCase"
-* });
-* // ➔ TypeError: "Expected boolean but got (big-int)."
-* ```
-*
-* -------------------------------------------------------
-* ✅ ***Real-world usage example***:
-* ```ts
-* type User = { name: string; email: string };
-*
-* const mixedValue: string | User | boolean | number | undefined = getUserInput();
-*
-* // ❌ Throws if not boolean
-* // ⚠️ Code below after this call, will NOT be executed if TypeError is thrown
-* assertIsBoolean(mixedValue, { message: "Must be boolean!" });
-*
-* // ✅ After this call, TypeScript knows `mixedValue` is boolean
-* const result: boolean = mixedValue; // ➔ Safe to use
-* ```
-*/
-declare const assertIsBoolean:(value:unknown,options?:AssertIsOptions)=>asserts value is boolean;
+ * * ***Custom error message for assertion failures.***
+ * -------------------------------------------------------
+ *
+ * @description
+ * 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 }) =>
+ *     `Expected ${validType} but got ${currentType}`
+ * }
+ * ```
+ */
+message?:string|(({currentType,validType}:OptionsMessageFunctionAssertIs)=>string);}& GetPreciseTypeOptions;
 /** -------------------------------------------------------
-* * ***Asserts that a value is of type `bigint`.***
-* -------------------------------------------------------
-* Validates that the given `value` is a **bigint**.
-*
-* - ✅ If `value` is a bigint → execution continues normally.
-* - ❌ If `value` is not a bigint → throws a `TypeError` with either:
-*   - A custom error message (`options.message`), or
-*   - A default message including the actual type.
-*
-* This function is an **assertion function**.
-* After it returns successfully, TypeScript narrows the type of `value` to `bigint`.
-*
-* ℹ️ 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))`.
-*
-* @param value - The value to validate.
-* @param options - Optional configuration:
-*   - `message`: A custom error message (string or function).
-*   - `formatCase`: Controls type formatting (from `GetPreciseTypeOptions`).
-*
-* @returns {asserts value is bigint} Narrows `value` to `bigint` if no error is thrown.
-* @throws {TypeError} If the value is not a bigint.
-*
-* @example
-* ```ts
-* // ✅ Simple usage
-* assertIsBigInt(123n);
-* // No error, value is bigint
-*
-* // ❌ Throws TypeError with default message
-* assertIsBigInt(42);
-* // ➔ TypeError: "Parameter input (`value`) must be of type `bigint`, but received: `number`."
-*
-* // ❌ Throws with custom string message
-* assertIsBigInt("123", { message: "Must be a bigint!" });
-* // ➔ TypeError: "Must be a bigint!"
-*
-* // ❌ Throws with custom function message + case formatting
-* assertIsBigInt(42, {
-*   message: ({ currentType, validType }) =>
-*     `Expected ${validType} but got (${currentType}).`,
-*   formatCase: "toKebabCase"
-* });
-* // ➔ TypeError: "Expected bigint but got (number)."
-* ```
-*
-* -------------------------------------------------------
-* ✅ ***Real-world usage example***:
-* ```ts
-* const mixedValue: string | bigint | undefined = getUserInput();
-*
-* // ❌ Throws if not bigint
-* // ⚠️ Code below after this call, will NOT be executed if TypeError is thrown
-* assertIsBigInt(mixedValue, { message: "Must be a bigint!" });
-*
-* // ✅ After this call, TypeScript knows `mixedValue` is bigint
-* const result: bigint = mixedValue; // ➔ Safe to use
-* console.log(result + 100n);
-* ```
-*/
-declare const assertIsBigInt:(value:unknown,options?:AssertIsOptions)=>asserts value is bigint;type AssertIsNumberOptions=AssertIsOptions & IsNumberOptions;
+ * * ***Type guard assertion: `assertIsBoolean`.***
+ * -------------------------------------------------------
+ * **This function is an **assertion function**.**
+ *  - Validates that the given `value` is a **boolean**.
+ *  - After it returns successfully, TypeScript narrows the type of `value` to `boolean`.
+ * - **Behavior:**
+ *   - ✅ If `value` is a `boolean` ➔ execution continues normally.
+ *   - ❌ If `value` is not a `boolean` ➔ throws a `TypeError` with either:
+ *     - A custom error message (`options.message`), or
+ *     - A default message including the actual type.
+ * @param {*} value - The value to validate.
+ * @param {OptionsAssertIs} [options] - Optional configuration:
+ *   - `message`: A custom error message (`string` or `function`).
+ *   - `formatCase`: Controls type formatting (from `GetPreciseTypeOptions`).
+ * @returns {boolean} Narrows `value` to `boolean` if no error is thrown.
+ * @throws {TypeError} If the value is not a boolean.
+ * @example
+ * ```ts
+ * // ✅ Simple usage
+ * assertIsBoolean(true);
+ * // No error, value is boolean
+ *
+ * // ❌ Throws TypeError with default message
+ * assertIsBoolean(42);
+ * // ➔ TypeError: "Parameter input (`value`) must be of type `boolean`, but received: `number`."
+ *
+ * // ❌ Throws with custom string message
+ * assertIsBoolean(42, { message: "Must be boolean!" });
+ * // ➔ TypeError: "Must be boolean!"
+ *
+ * // ❌ Throws with custom function message + case formatting
+ * assertIsBoolean(123n, {
+ *   message: ({ currentType, validType }) =>
+ *     `Expected ${validType} but got (${currentType}).`,
+ *   formatCase: "toKebabCase"
+ * });
+ * // ➔ TypeError: "Expected boolean but got (big-int)."
+ * ```
+ * -------------------------------------------------------
+ * ✅ ***Real-world usage example***:
+ * ```ts
+ * type User = { name: string; email: string };
+ * const mixedValue: string | User | boolean | number | undefined = getUserInput();
+ *
+ * // ❌ Throws if not boolean
+ * // ⚠️ Code below after this call, will NOT be executed if TypeError is thrown
+ * assertIsBoolean(mixedValue, { message: "Must be boolean!" });
+ *
+ * // ✅ After this call, TypeScript knows `mixedValue` is boolean
+ * const result: boolean = mixedValue; // ➔ Safe to use
+ * ```
+ */
+declare const assertIsBoolean:(value:unknown,options?:OptionsAssertIs)=>asserts value is boolean;
 /** -------------------------------------------------------
-* * ***Asserts that a value is of type `number`.***
-* -------------------------------------------------------
-* Validates that the given `value` is a **number**.
-*
-* - ✅ If `value` is a number → execution continues normally.
-* - ❌ If `value` is not a number → throws a `TypeError` with either:
-*   - A custom error message (`options.message`), or
-*   - A default message including the actual type.
-*
-* This function is an **assertion function**.
-* After it returns successfully, TypeScript narrows the type of `value` to `number`.
-*
-* ℹ️ Notes:
-* - 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 }`.
-*
-* @param value - The value to validate.
-* @param options - Optional configuration:
-*   - `message`: A custom error message (string or function).
-*   - `formatCase`: Controls type formatting (from `GetPreciseTypeOptions`).
-*   - `includeNaN`: Whether to treat `NaN` as valid.
-*
-* @returns {asserts value is number} Narrows `value` to `number` if no error is thrown.
-* @throws {TypeError} If the value is not a number (or is `NaN` when `includeNaN` is `false`).
-*
-* @example
-* ```ts
-* // ✅ Simple usage
-* assertIsNumber(123);
-* // No error, value is number
-*
-* // ❌ Throws TypeError with default message
-* assertIsNumber("42");
-* // ➔ TypeError: "Parameter input (`value`) must be of type `number`, but received: `string`."
-*
-* // ❌ Throws with custom string message
-* assertIsNumber(true, { message: "Must be a number!" });
-* // ➔ TypeError: "Must be a number!"
-*
-* // ❌ Throws with custom function message + case formatting
-* assertIsNumber("hello", {
-*   message: ({ currentType, validType }) =>
-*     `Expected ${validType} but got (${currentType}).`,
-*   formatCase: "toKebabCase"
-* });
-* // ➔ TypeError: "Expected number but got (string)."
-*
-* // ⚠️ NaN is invalid by default
-* assertIsNumber(NaN);
-* // ➔ TypeError: "Parameter input (`value`) must be of type `number`, but received: `NaN`."
-*
-* // ✅ Allow NaN explicitly
-* assertIsNumber(NaN, { includeNaN: true });
-* // No error
-* ```
-*
-* -------------------------------------------------------
-* ✅ ***Real-world usage example***:
-* ```ts
-* const mixedValue: string | number | undefined = getUserInput();
-*
-* // ❌ Throws if not number
-* // ⚠️ Code below after this call, will NOT be executed if TypeError is thrown
-* assertIsNumber(mixedValue, { message: "Must be a number!" });
-*
-* // ✅ After this call, TypeScript knows `mixedValue` is number
-* const result: number = mixedValue; // ➔ Safe to use
-* console.log(result + 100);
-* ```
-*/
-declare const assertIsNumber:(value:unknown,options?:AssertIsNumberOptions)=>asserts value is number;
+ * * ***Type guard assertion: `assertIsBigInt`.***
+ * -------------------------------------------------------
+ * **This function is an **assertion function**.**
+ * - Validates that the given `value` is a **bigint**.
+ * - After it returns successfully, TypeScript narrows the type of `value` to `bigint`.
+ * - **Behavior:**
+ *    - ✅ If `value` is a `bigint` ➔ execution continues normally.
+ *    - ❌ If `value` is not a `bigint` ➔ throws a `TypeError` 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))`.
+ * @param {*} value - The value to validate.
+ * @param {OptionsAssertIs} [options] - Optional configuration:
+ *   - `message`: A custom error message (`string` or `function`).
+ *   - `formatCase`: Controls type formatting (from `GetPreciseTypeOptions`).
+ * @returns {boolean} Narrows `value` to `bigint` if no error is thrown.
+ * @throws {TypeError} If the value is not a bigint.
+ * @example
+ * ```ts
+ * // ✅ Simple usage
+ * assertIsBigInt(123n);
+ * // No error, value is bigint
+ *
+ * // ❌ Throws TypeError with default message
+ * assertIsBigInt(42);
+ * // ➔ TypeError: "Parameter input (`value`) must be of type `bigint`, but received: `number`."
+ *
+ * // ❌ Throws with custom string message
+ * assertIsBigInt("123", { message: "Must be a bigint!" });
+ * // ➔ TypeError: "Must be a bigint!"
+ *
+ * // ❌ Throws with custom function message + case formatting
+ * assertIsBigInt(42, {
+ *   message: ({ currentType, validType }) =>
+ *     `Expected ${validType} but got (${currentType}).`,
+ *   formatCase: "toKebabCase"
+ * });
+ * // ➔ TypeError: "Expected bigint but got (number)."
+ * ```
+ * -------------------------------------------------------
+ * ✅ ***Real-world usage example***:
+ * ```ts
+ * const mixedValue: string | bigint | undefined = getUserInput();
+ *
+ * // ❌ Throws if not bigint
+ * // ⚠️ Code below after this call, will NOT be executed if TypeError is thrown
+ * assertIsBigInt(mixedValue, { message: "Must be a bigint!" });
+ *
+ * // ✅ After this call, TypeScript knows `mixedValue` is bigint
+ * const result: bigint = mixedValue; // ➔ Safe to use
+ * console.log(result + 100n);
+ * ```
+ */
+declare const assertIsBigInt:(value:unknown,options?:OptionsAssertIs)=>asserts value is bigint;type OptionsAssertIsNumber=OptionsAssertIs & IsNumberOptions;
 /** -------------------------------------------------------
-* * ***Asserts that a value is of type `array`.***
-* -------------------------------------------------------
-* Validates that the given `value` is an **array**.
-*
-* - ✅ If `value` is an array → execution continues normally.
-* - ❌ If `value` is not an array → throws a `TypeError` with either:
-*   - A custom error message (`options.message`), or
-*   - A default message including the actual type.
-*
-* This function is an **assertion function**.
-* After it returns successfully, TypeScript narrows the type of `value`
-* to `AssertIsArrayResult<T>`.
-*
-* @template T - The input type being asserted.
-*
-* @param value - The value to validate.
-* @param options - Optional configuration:
-*   - `message`: A custom error message (string or function).
-*   - `formatCase`: Controls type formatting (from `GetPreciseTypeOptions`).
-*
-* @returns {asserts value is AssertIsArrayResult<T>} Narrows `value` to an array if no error is thrown.
-* @throws {TypeError} If the value is not an array.
-*
-* @example
-* ```ts
-* // ✅ Simple usage
-* assertIsArray([1, 2, 3]);
-* // No error, value is array
-*
-* // ❌ Throws TypeError with default message
-* assertIsArray({ a: 1 });
-* // ➔ TypeError: "Parameter input (`value`) must be of type `array`, but received: `plain-object`."
-*
-* // ❌ Throws with custom string message
-* assertIsArray(42, { message: "Must be an array!" });
-* // ➔ TypeError: "Must be an array!"
-*
-* // ❌ Throws with custom function message + case formatting
-* assertIsArray(42n, {
-*   message: ({ currentType, validType }) =>
-*     `Expected ${validType} but got (${currentType}).`,
-*   formatCase: "toKebabCase"
-* });
-* // ➔ TypeError: "Expected array but got (big-int)."
-* ```
-*
-* -------------------------------------------------------
-* ✅ ***Real-world usage with generic narrowing***:
-* ```ts
-* const mixedValue: string | number[] | undefined = getUserInput();
-*
-* // ❌ Throws if not array
-* // ⚠️ Code below after this call, will NOT be executed if TypeError is thrown
-* assertIsArray(mixedValue, { message: "Must be an array!" });
-*
-* // ✅ After this call, TypeScript knows `mixedValue` is narrowed to number[]
-* const result: number[] = mixedValue; // ➔ Safe to use
-* console.log(result.length);
-* ```
-*/
-declare function assertIsArray<T extends unknown[]>(value:T,options?:AssertIsOptions):value is Extract<T,unknown[]>;declare function assertIsArray<T extends readonly unknown[]>(value:T,options?:AssertIsOptions):value is Extract<T,readonly unknown[]>;declare function assertIsArray(value:unknown,options?:AssertIsOptions):value is unknown[];
+ * * ***Type guard assertion: `assertIsNumber`.***
+ * -------------------------------------------------------
+ * **This function is an **assertion function**.**
+ * - Validates that the given `value` is a **number**.
+ * - After it returns successfully, TypeScript narrows the type of `value` to `number`.
+ * - **Behavior:**
+ *    - ✅ If `value` is a `number` ➔ execution continues normally.
+ *    - ❌ If `value` is not a `number` ➔ throws a `TypeError` 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 }`.
+ * @param {*} value - The value to validate.
+ * @param {OptionsAssertIsNumber} [options] - Optional configuration:
+ *   - `message`: A custom error message (`string` or `function`).
+ *   - `formatCase`: Controls type formatting (from `GetPreciseTypeOptions`).
+ *   - `includeNaN`: Whether to treat `NaN` as valid.
+ * @returns {boolean} Narrows `value` to `number` if no error is thrown.
+ * @throws {TypeError} If the value is not a number (or is `NaN` when `includeNaN` is `false`).
+ * @example
+ * ```ts
+ * // ✅ Simple usage
+ * assertIsNumber(123);
+ * // No error, value is number
+ *
+ * // ❌ Throws TypeError with default message
+ * assertIsNumber("42");
+ * // ➔ TypeError: "Parameter input (`value`) must be of type `number`, but received: `string`."
+ *
+ * // ❌ Throws with custom string message
+ * assertIsNumber(true, { message: "Must be a number!" });
+ * // ➔ TypeError: "Must be a number!"
+ *
+ * // ❌ Throws with custom function message + case formatting
+ * assertIsNumber("hello", {
+ *   message: ({ currentType, validType }) =>
+ *     `Expected ${validType} but got (${currentType}).`,
+ *   formatCase: "toKebabCase"
+ * });
+ * // ➔ TypeError: "Expected number but got (string)."
+ *
+ * // ⚠️ NaN is invalid by default
+ * assertIsNumber(NaN);
+ * // ➔ TypeError: "Parameter input (`value`) must be of type `number`, but received: `NaN`."
+ *
+ * // ✅ Allow NaN explicitly
+ * assertIsNumber(NaN, { includeNaN: true });
+ * // No error
+ * ```
+ *
+ * -------------------------------------------------------
+ * ✅ ***Real-world usage example***:
+ * ```ts
+ * const mixedValue: string | number | undefined = getUserInput();
+ *
+ * // ❌ Throws if not number
+ * // ⚠️ Code below after this call, will NOT be executed if TypeError is thrown
+ * assertIsNumber(mixedValue, { message: "Must be a number!" });
+ *
+ * // ✅ After this call, TypeScript knows `mixedValue` is number
+ * const result: number = mixedValue; // ➔ Safe to use
+ * console.log(result + 100);
+ * ```
+ */
+declare const assertIsNumber:(value:unknown,options?:OptionsAssertIsNumber)=>asserts value is number;
 /** -------------------------------------------------------
-* * ***Asserts that a value is a plain object.***
-* -------------------------------------------------------
-* Ensures that the given `value` is a **plain object**.
-* - Throws a `TypeError` if the value is **not a plain object**.
-*
-* @template T - The input type being asserted.
-* After assertion, TypeScript will refine `value` to `IsPlainObjectResult<T>`.
-*
-* @param {T} value - The value to check.
-* @param {AssertIsOptions} [options] - Optional configuration, such as:
-*   - Custom error message (`string` or `(info) => string`)
-*   - Message formatting (`formatCase`)
-*   - Expected `validType` description override
-* @throws {TypeError} If `value` is not a plain object (with either a default or custom message).
-*
-* @example
-* ```ts
-* // ✅ Simple usage
-* assertIsPlainObject({ a: 1, b: 2 });
-* // ➔ ok, value is plain object
-*
-* // ❌ Throws TypeError with default message
-* assertIsPlainObject([1, 2, 3]);
-* // ➔ TypeError: "Parameter input (`value`) must be of type `plain-object`, but received: `array`."
-*
-* // ❌ Throws with custom string message
-* assertIsPlainObject("hello", { message: "Must be plain object!" });
-* // ➔ TypeError: "Must be plain object!"
-*
-* // ❌ Throws with custom message function and formatCase
-* assertIsPlainObject(42n, {
-*   message: ({ currentType, validType }) =>
-*     `Expected ${validType} but got (${currentType}).`,
-*   formatCase: "toKebabCase"
-* });
-* // ➔ TypeError: "Expected plain-object but got (big-int)."
-* ```
-* -------------------------------------------------------
-* ✅ ***Real-world usage with generic narrowing***:
-* ```ts
-* type User = { name: string; email: string };
-*
-* const mixedValue: string | User | boolean | number | undefined = getUserInput();
-*
-* // Throws TypeError if not plain object
-* assertIsPlainObject(mixedValue, { message: "Must be plain object!" });
-*
-* // After this call, TypeScript knows `mixedValue` is narrowed to User
-* const user: User = mixedValue; // ➔ safe
-* console.log(user.email);       // ➔ type-safe
-* ```
-*/
-declare function assertIsPlainObject<T>(value:T,options?:AssertIsOptions):asserts value is IsPlainObjectResult<T>;
+ * * ***Type guard assertion: `assertIsArray`.***
+ * -------------------------------------------------------
+ * **This function is an **assertion function**.**
+ * - Validates that the given `value` is a **array**.
+ * - After it returns successfully, TypeScript narrows the type of `value` to `array` **(generic support)**.
+ * - **Behavior:**
+ *    - ✅ If `value` is an `array` ➔ execution continues normally.
+ *    - ❌ If `value` is not an `array` ➔ throws a `TypeError` with either:
+ *      - A custom error message (`options.message`), or
+ *      - A default message including the actual type.
+ * @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`).
+ *   - `formatCase`: Controls type formatting (from `GetPreciseTypeOptions`).
+ * @returns {boolean} Narrows `value` to an `array` **(generic support)** if no error is thrown.
+ * @throws {TypeError} If the value is not an array.
+ * @example
+ * ```ts
+ * // ✅ Simple usage
+ * assertIsArray([1, 2, 3]);
+ * // No error, value is array
+ *
+ * // ❌ Throws TypeError with default message
+ * assertIsArray({ a: 1 });
+ * // ➔ TypeError: "Parameter input (`value`) must be of type `array`, but received: `plain-object`."
+ *
+ * // ❌ Throws with custom string message
+ * assertIsArray(42, { message: "Must be an array!" });
+ * // ➔ TypeError: "Must be an array!"
+ *
+ * // ❌ Throws with custom function message + case formatting
+ * assertIsArray(42n, {
+ *   message: ({ currentType, validType }) =>
+ *     `Expected ${validType} but got (${currentType}).`,
+ *   formatCase: "toKebabCase"
+ * });
+ * // ➔ TypeError: "Expected array but got (big-int)."
+ * ```
+ *
+ * -------------------------------------------------------
+ * ✅ ***Real-world usage with generic narrowing***:
+ * ```ts
+ * const mixedValue: string | number[] | undefined = getUserInput();
+ *
+ * // ❌ Throws if not array
+ * // ⚠️ Code below after this call, will NOT be executed if TypeError is thrown
+ * assertIsArray(mixedValue, { message: "Must be an array!" });
+ *
+ * // ✅ After this call, TypeScript knows `mixedValue` is narrowed to number[]
+ * const result: number[] = mixedValue; // ➔ Safe to use
+ * console.log(result.length);
+ * ```
+ */
+declare function assertIsArray<T extends unknown[]>(value:T,options?:OptionsAssertIs):value is Extract<T,unknown[]>;declare function assertIsArray<T extends readonly unknown[]>(value:T,options?:OptionsAssertIs):value is Extract<T,readonly unknown[]>;declare function assertIsArray(value:unknown,options?:OptionsAssertIs):value is unknown[];
 /** -------------------------------------------------------
-* * ***Asserts that a value is a string.***
-* -------------------------------------------------------
-* Ensures that the given value is a **primitive string**.
-* - Throws a `TypeError` if the value is **not a string**.
-*
-* ℹ️ Note:
-* - A "string" refers strictly to a JavaScript primitive string type
-*   (e.g., `"hello"`, `""`, `"123"`).
-* - This function excludes `String` objects created with `new String()`.
-*
-* @param {unknown} value - The value to check.
-* @param {AssertIsOptions} [options] - Optional configuration including custom error message and formatting.
-* @returns {asserts value is string}
-* After this call, `value` is guaranteed to be a **primitive string**.
-* @throws {TypeError} If the value is not a string.
-*
-* @example
-* ```ts
-* // ✅ Simple usage
-* assertIsString("hello");
-* // ➔ ✅ ok value is string, no error
-*
-* // ❌ Throws TypeError with default message
-* assertIsString(42);
-* // ➔ TypeError: "Parameter input (`value`) must be of type `string`, but received: `number`."
-*
-* // ❌ Throws with custom string message
-* assertIsString(42, { message: "Must be a string!" });
-* // ➔ TypeError: "Must be a string!"
-*
-* // ❌ Throws with custom message function and formatCase
-* assertIsString(42n, {
-*   message: ({ currentType, validType }) => `Expected ${currentType} but got (${currentType}).`,
-*   formatCase: "toKebabCase"
-* });
-* // ➔ TypeError: "Expected string but got (big-int)."
-* ```
-* -------------------------------------------------------
-* ✅ ***Real-world usage with generic narrowing***:
-* ```ts
-* type User = { name: string; email: string };
-*
-* const mixedValue: string | User | undefined = getUserInput();
-*
-* // Throws TypeError if the value is not string
-* // ⚠️ Code below after this call, will NOT be executed if TypeError is thrown
-* assertIsString(mixedValue, { message: "Must be a string!" });
-*
-* // After this call, TypeScript knows `mixedValue` is string
-* const result: string = mixedValue; // ➔ ✅ safe to use
-* console.log(result.toUpperCase()); // ➔ ✅ type-safe
-* ```
-*/
-declare const assertIsString:(value:unknown,options?:AssertIsOptions)=>asserts value is string;export{assertIsArray,assertIsBigInt,assertIsBoolean,assertIsNumber,assertIsPlainObject,assertIsString};
+ * * ***Type guard assertion: `assertIsPlainObject`.***
+ * -------------------------------------------------------
+ * **This function is an **assertion function**.**
+ * - Validates that the given `value` is a **plain-object**.
+ * - After it returns successfully, TypeScript narrows the type of `value` to `plain-object` **(generic support)**.
+ * - **Behavior:**
+ *    - ✅ If `value` is a `plain-object` ➔ execution continues normally.
+ *    - ❌ If `value` is not a `plain-object` ➔ throws a `TypeError` with either:
+ *      - A custom error message (`options.message`), or
+ *      - A default message including the actual type.
+ * @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`).
+ *   - `formatCase`: Controls type formatting (from `GetPreciseTypeOptions`).
+ * @returns {boolean} Narrows `value` to a `plain-object` **(generic support)** if no error is thrown.
+ * @throws {TypeError} If `value` is not a `plain-object`.
+ * @example
+ * ```ts
+ * // ✅ Simple usage
+ * assertIsPlainObject({ a: 1, b: 2 });
+ * // ➔ ok, value is plain object
+ *
+ * // ❌ Throws TypeError with default message
+ * assertIsPlainObject([1, 2, 3]);
+ * // ➔ TypeError: "Parameter input (`value`) must be of type `plain-object`, but received: `array`."
+ *
+ * // ❌ Throws with custom string message
+ * assertIsPlainObject("hello", { message: "Must be plain object!" });
+ * // ➔ TypeError: "Must be plain object!"
+ *
+ * // ❌ Throws with custom message function and formatCase
+ * assertIsPlainObject(42n, {
+ *   message: ({ currentType, validType }) =>
+ *     `Expected ${validType} but got (${currentType}).`,
+ *   formatCase: "toKebabCase"
+ * });
+ * // ➔ TypeError: "Expected plain-object but got (big-int)."
+ * ```
+ * -------------------------------------------------------
+ * ✅ ***Real-world usage with generic narrowing***:
+ * ```ts
+ * type User = { name: string; email: string };
+ * const mixedValue: string | User | boolean | number | undefined = getUserInput();
+ *
+ * // Throws TypeError if not plain object
+ * assertIsPlainObject(mixedValue, { message: "Must be plain object!" });
+ *
+ * // After this call, TypeScript knows `mixedValue` is narrowed to User
+ * const user: User = mixedValue; // ➔ safe
+ * console.log(user.email);       // ➔ type-safe
+ * ```
+ */
+declare function assertIsPlainObject<T>(value:T,options?:OptionsAssertIs):asserts value is IsPlainObjectResult<T>;
+/** -------------------------------------------------------
+ * * ***Type guard assertion: `assertIsString`.***
+ * -------------------------------------------------------
+ * **This function is an **assertion function**.**
+ * - Validates that the given `value` is a **primitive-string**.
+ * - After it returns successfully, TypeScript narrows the type of `value` to `primitive-string`.
+ * - **Behavior:**
+ *    - ✅ If `value` is a `primitive-string` ➔ execution continues normally.
+ *    - ❌ If `value` is not a `primitive-string` ➔ throws a `TypeError` 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()`.
+ * @param {*} value - The value to validate.
+ * @param {OptionsAssertIs} [options] - Optional configuration:
+ *   - `message`: A custom error message (`string` or `function`).
+ *   - `formatCase`: Controls type formatting (from `GetPreciseTypeOptions`).
+ * @returns {boolean} Narrows `value` to `string` if no error is thrown.
+ * @throws {TypeError} If the value is not a string.
+ * @example
+ * ```ts
+ * // ✅ Simple usage
+ * assertIsString("hello");
+ * // ➔ ✅ ok value is string, no error
+ *
+ * // ❌ Throws TypeError with default message
+ * assertIsString(42);
+ * // ➔ TypeError: "Parameter input (`value`) must be of type `string`, but received: `number`."
+ *
+ * // ❌ Throws with custom string message
+ * assertIsString(42, { message: "Must be a string!" });
+ * // ➔ TypeError: "Must be a string!"
+ *
+ * // ❌ Throws with custom message function and formatCase
+ * assertIsString(42n, {
+ *   message: ({ currentType, validType }) => `Expected ${currentType} but got (${currentType}).`,
+ *   formatCase: "toKebabCase"
+ * });
+ * // ➔ TypeError: "Expected string but got (big-int)."
+ * ```
+ * -------------------------------------------------------
+ * ✅ ***Real-world usage with generic narrowing***:
+ * ```ts
+ * type User = { name: string; email: string };
+ * const mixedValue: string | User | undefined = getUserInput();
+ *
+ * // Throws TypeError if the value is not string
+ * // ⚠️ Code below after this call, will NOT be executed if TypeError is thrown
+ * assertIsString(mixedValue, { message: "Must be a string!" });
+ *
+ * // After this call, TypeScript knows `mixedValue` is string
+ * const result: string = mixedValue; // ➔ ✅ safe to use
+ * console.log(result.toUpperCase()); // ➔ ✅ type-safe
+ * ```
+ */
+declare const assertIsString:(value:unknown,options?:OptionsAssertIs)=>asserts value is string;export{assertIsArray,assertIsBigInt,assertIsBoolean,assertIsNumber,assertIsPlainObject,assertIsString};