@rzl-zone/utils-js 3.8.0 → 3.9.1

package/README.md

@@ -1,4 +1,8 @@
-<div align="center">
+<div align="center" style="display: flex; flex-direction: column; align-items: center;gap: 0.25rem">
+  <a target="_blank" rel="noopener noreferrer" href="https://raw.githubusercontent.com/rzl-zone/utils-js/main/logo-circle.png">
+    <img src="https://raw.githubusercontent.com/rzl-zone/utils-js/main/logo-circle.png" align="middle" alt="RzlZone Logo" width="110" style="max-width: 100%;">
+  </a>
+
   <h1><strong>⚡️ <code>@rzl-zone/utils-js</code> 🚀</strong></h1>
 </div>
 

package/dist/assertions/index.cjs

@@ -2,40 +2,40 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.8.0.
+ * Version: 3.9.1.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
  */
 'use strict';
 
-var chunk5NN4ZDE2_cjs = require('../chunk-5NN4ZDE2.cjs');
-var chunkK63WO3XA_cjs = require('../chunk-K63WO3XA.cjs');
-var chunk7WBMA2VE_cjs = require('../chunk-7WBMA2VE.cjs');
+var chunkUV5BKAYW_cjs = require('../chunk-UV5BKAYW.cjs');
+var chunkWKM6UVMG_cjs = require('../chunk-WKM6UVMG.cjs');
+var chunkOYFUBKEG_cjs = require('../chunk-OYFUBKEG.cjs');
 require('../chunk-UDA26MCU.cjs');
-var chunkF3WBQKRI_cjs = require('../chunk-F3WBQKRI.cjs');
+var chunk7C7TQC5J_cjs = require('../chunk-7C7TQC5J.cjs');
 
 Object.defineProperty(exports, "assertIsBigInt", {
   enumerable: true,
-  get: function () { return chunk5NN4ZDE2_cjs.assertIsBigInt; }
+  get: function () { return chunkUV5BKAYW_cjs.assertIsBigInt; }
 });
 Object.defineProperty(exports, "assertIsNumber", {
   enumerable: true,
-  get: function () { return chunk5NN4ZDE2_cjs.assertIsNumber; }
+  get: function () { return chunkUV5BKAYW_cjs.assertIsNumber; }
 });
 Object.defineProperty(exports, "assertIsString", {
   enumerable: true,
-  get: function () { return chunkK63WO3XA_cjs.assertIsString; }
+  get: function () { return chunkWKM6UVMG_cjs.assertIsString; }
 });
 Object.defineProperty(exports, "assertIsArray", {
   enumerable: true,
-  get: function () { return chunk7WBMA2VE_cjs.assertIsArray; }
+  get: function () { return chunkOYFUBKEG_cjs.assertIsArray; }
 });
 Object.defineProperty(exports, "assertIsBoolean", {
   enumerable: true,
-  get: function () { return chunkF3WBQKRI_cjs.assertIsBoolean; }
+  get: function () { return chunk7C7TQC5J_cjs.assertIsBoolean; }
 });
 Object.defineProperty(exports, "assertIsPlainObject", {
   enumerable: true,
-  get: function () { return chunkF3WBQKRI_cjs.assertIsPlainObject; }
+  get: function () { return chunk7C7TQC5J_cjs.assertIsPlainObject; }
 });

package/dist/assertions/index.d.ts

@@ -2,7 +2,7 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.8.0.
+ * Version: 3.9.1.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
@@ -81,7 +81,32 @@ type OptionsAssertIs=Prettify<{
  * }
  * ```
  */
-message?:OptionsMessageAssertIs;}& PickStrict<GetPreciseTypeOptions,"formatCase">,{recursive:true;}>;
+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">,{recursive:true;}>;type ErrorType="Error"|"EvalError"|"RangeError"|"ReferenceError"|"SyntaxError"|"TypeError"|"URIError";
 /** -------------------------------------------------------
  * * ***Type guard assertion: `assertIsBoolean`.***
  * -------------------------------------------------------
@@ -90,16 +115,28 @@ message?:OptionsMessageAssertIs;}& PickStrict<GetPreciseTypeOptions,"formatCase"
  *    - 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 `TypeError` with either:
+ *    - ❌ 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`).
- *   - `formatCase`: Controls type formatting (from `GetPreciseTypeOptions`).
+ *    - `message`: A custom error message (`string` or `function`).
+ *    - `errorType`: A custom built-in JavaScript error type to throw.
+ *    - `formatCase`: Controls type formatting (from `GetPreciseTypeOptions`).
  * @returns {boolean} Narrows `value` to `boolean` if no error is thrown.
- * @throws **{@link TypeError | `TypeError`}** if the value is not a boolean.
+ * @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
@@ -114,11 +151,13 @@ message?:OptionsMessageAssertIs;}& PickStrict<GetPreciseTypeOptions,"formatCase"
  * assertIsBoolean(42, { message: "Must be boolean!" });
  * // ➔ TypeError: "Must be boolean!"
  *
+ * // ❌ Throws RangeError instead of TypeError
+ * assertIsBoolean(42, { errorType: "RangeError" });
+ * // ➔ RangeError: "Parameter input (`value`) must be of type `boolean`, but received: `number`."
+ *
  * // ❌ Throws with custom function message + case formatting
  * assertIsBoolean(123n, {
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`;
- *   },
+ *   message: ({ currentType, validType }) => `Expected ${validType} but got (${currentType}).`,
  *   formatCase: "toKebabCase"
  * });
  * // ➔ TypeError: "Expected boolean but got (big-int)."
@@ -130,8 +169,8 @@ message?:OptionsMessageAssertIs;}& PickStrict<GetPreciseTypeOptions,"formatCase"
  * 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!" });
+ * // ⚠️ Code below after this call, will NOT be executed if the error is thrown
+ * assertIsBoolean(mixedValue, { message: "Must be boolean!", errorType: "RangeError" });
  *
  * // ✅ After this call, TypeScript knows `mixedValue` is boolean
  * const result: boolean = mixedValue; // ➔ Safe to use
@@ -146,19 +185,31 @@ declare const assertIsBoolean:(value:unknown,options?:OptionsAssertIs)=>asserts
  *    - 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 `TypeError` with either:
+ *    - ❌ 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 type formatting (from `GetPreciseTypeOptions`).
  * @returns {boolean} Narrows `value` to `bigint` if no error is thrown.
- * @throws **{@link TypeError | `TypeError`}** if the value is not a bigint.
+ * @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
@@ -175,12 +226,21 @@ declare const assertIsBoolean:(value:unknown,options?:OptionsAssertIs)=>asserts
  *
  * // ❌ Throws with custom function message + case formatting
  * assertIsBigInt(42, {
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`;
- *   },
+ *   message: ({ currentType, validType }) => `Expected ${validType} but got (${currentType}).`,
  *   formatCase: "toKebabCase"
  * });
  * // ➔ TypeError: "Expected bigint but got (number)."
+ *
+ * // ❌ Throws with custom function message + formatCase showing big-int
+ * assertIsBigInt(123, {
+ *   message: ({ currentType, validType }) => `Expected ${validType} but got (${currentType}).`,
+ *   formatCase: "toKebabCase"
+ * });
+ * // ➔ TypeError: "Expected bigint but got (number)."
+ *
+ * // ❌ Throws custom error type (e.g., RangeError)
+ * assertIsBigInt(42, { errorType: "RangeError" });
+ * // ➔ RangeError: "Parameter input (`value`) must be of type `bigint`, but received: `number`."
  * ```
  * -------------------------------------------------------
  * ✅ ***Real-world usage example***:
@@ -188,11 +248,10 @@ declare const assertIsBoolean:(value:unknown,options?:OptionsAssertIs)=>asserts
  * 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!" });
+ * assertIsBigInt(mixedValue, { message: "Must be a bigint!", errorType: "TypeError" });
  *
  * // ✅ After this call, TypeScript knows `mixedValue` is bigint
- * const result: bigint = mixedValue; // ➔ Safe to use
+ * const result: bigint = mixedValue;
  * console.log(result + 100n);
  * ```
  */
@@ -205,21 +264,33 @@ declare const assertIsBigInt:(value:unknown,options?:OptionsAssertIs)=>asserts v
  *    - 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 `TypeError` with either:
+ *    - ❌ 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 type formatting (from `GetPreciseTypeOptions`).
  *   - `includeNaN`: Whether to treat `NaN` as valid.
  * @returns {boolean} Narrows `value` to `number` if no error is thrown.
- * @throws **{@link TypeError | `TypeError`}** if the value is not a number (or is `NaN` when `includeNaN` is `false`).
+ * @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
@@ -234,11 +305,13 @@ declare const assertIsBigInt:(value:unknown,options?:OptionsAssertIs)=>asserts v
  * assertIsNumber(true, { message: "Must be a number!" });
  * // ➔ TypeError: "Must be a number!"
  *
+ * // ❌ Throws RangeError instead of TypeError
+ * assertIsNumber("42", { errorType: "RangeError" });
+ * // ➔ RangeError: "Parameter input (`value`) must be of type `number`, but received: `string`."
+ *
  * // ❌ Throws with custom function message + case formatting
  * assertIsNumber("hello", {
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`;
- *   },
+ *   message: ({ currentType, validType }) => `Expected ${validType} but got (${currentType}).`,
  *   formatCase: "toKebabCase"
  * });
  * // ➔ TypeError: "Expected number but got (string)."
@@ -251,15 +324,13 @@ declare const assertIsBigInt:(value:unknown,options?:OptionsAssertIs)=>asserts v
  * 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!" });
+ * assertIsNumber(mixedValue, { message: "Must be a number!", errorType: "RangeError" });
  *
  * // ✅ After this call, TypeScript knows `mixedValue` is number
  * const result: number = mixedValue; // ➔ Safe to use
@@ -272,20 +343,32 @@ declare const assertIsNumber:(value:unknown,options?:OptionsAssertIsNumber)=>ass
  * -------------------------------------------------------
  * **This function is an **assertion function**.**
  * - **Behavior:**
- *    - Validates that the given `value` is a **array**.
+ *    - 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 `TypeError` with either:
+ *    - ❌ 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 type formatting (from `GetPreciseTypeOptions`).
  * @returns {boolean} Narrows `value` to an `array` **(generic support)** if no error is thrown.
- * @throws **{@link TypeError | `TypeError`}** if the value is not an array.
+ * @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
@@ -300,11 +383,13 @@ declare const assertIsNumber:(value:unknown,options?:OptionsAssertIsNumber)=>ass
  * assertIsArray(42, { message: "Must be an array!" });
  * // ➔ TypeError: "Must be an array!"
  *
+ * // ❌ Throws RangeError instead of TypeError
+ * assertIsArray(42, { errorType: "RangeError" });
+ * // ➔ RangeError: "Parameter input (`value`) must be of type `array`, but received: `number`."
+ *
  * // ❌ Throws with custom function message + case formatting
  * assertIsArray(42n, {
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`;
- *   },
+ *   message: ({ currentType, validType }) => `Expected ${validType} but got (${currentType}).`,
  *   formatCase: "toKebabCase"
  * });
  * // ➔ TypeError: "Expected array but got (big-int)."
@@ -315,8 +400,7 @@ declare const assertIsNumber:(value:unknown,options?:OptionsAssertIsNumber)=>ass
  * 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!" });
+ * assertIsArray(mixedValue, { message: "Must be an array!", errorType: "RangeError" });
  *
  * // ✅ After this call, TypeScript knows `mixedValue` is narrowed to number[]
  * const result: number[] = mixedValue; // ➔ Safe to use
@@ -332,17 +416,29 @@ declare function assertIsArray<T extends unknown[]>(value:T,options?:OptionsAsse
  *    - 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 `TypeError` with either:
+ *    - ❌ 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.
+ * - **⚠️ 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 type formatting (from `GetPreciseTypeOptions`).
  * @returns {boolean} Narrows `value` to a `plain-object` **(generic support)** if no error is thrown.
- * @throws **{@link TypeError | `TypeError`}** if `value` is not a `plain-object`.
+ * @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
@@ -357,11 +453,13 @@ declare function assertIsArray<T extends unknown[]>(value:T,options?:OptionsAsse
  * assertIsPlainObject("hello", { message: "Must be plain object!" });
  * // ➔ TypeError: "Must be plain object!"
  *
- * // ❌ Throws with custom message function and formatCase
+ * // ❌ Throws RangeError instead of TypeError
+ * assertIsPlainObject(42, { errorType: "RangeError" });
+ * // ➔ RangeError: "Parameter input (`value`) must be of type `plain-object`, but received: `number`."
+ *
+ * // ❌ Throws with custom message function + case formatting
  * assertIsPlainObject(42n, {
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`;
- *   },
+ *   message: ({ currentType, validType }) => `Expected ${validType} but got (${currentType}).`,
  *   formatCase: "toKebabCase"
  * });
  * // ➔ TypeError: "Expected plain-object but got (big-int)."
@@ -372,10 +470,10 @@ declare function assertIsArray<T extends unknown[]>(value:T,options?:OptionsAsse
  * 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!" });
+ * // ❌ Throws if not plain object
+ * assertIsPlainObject(mixedValue, { message: "Must be plain object!", errorType: "RangeError" });
  *
- * // After this call, TypeScript knows `mixedValue` is narrowed to User
+ * // ✅ After this call, TypeScript knows `mixedValue` is narrowed to User
  * const user: User = mixedValue; // ➔ safe
  * console.log(user.email);       // ➔ type-safe
  * ```
@@ -389,24 +487,36 @@ declare function assertIsPlainObject<T>(value:T,options?:OptionsAssertIs):assert
  *    - 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 `TypeError` with either:
+ *    - ❌ 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 type formatting (from `GetPreciseTypeOptions`).
  * @returns {boolean} Narrows `value` to `string` if no error is thrown.
- * @throws **{@link TypeError | `TypeError`}** if the value is not a string.
+ * @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");
- * // ➔ ✅ ok value is string, no error
+ * // ➔ ok value is string, no error
  *
  * // ❌ Throws TypeError with default message
  * assertIsString(42);
@@ -416,11 +526,13 @@ declare function assertIsPlainObject<T>(value:T,options?:OptionsAssertIs):assert
  * assertIsString(42, { message: "Must be a string!" });
  * // ➔ TypeError: "Must be a string!"
  *
- * // ❌ Throws with custom message function and formatCase
+ * // ❌ Throws RangeError instead of TypeError
+ * assertIsString(42, { errorType: "RangeError" });
+ * // ➔ RangeError: "Parameter input (`value`) must be of type `string`, but received: `number`."
+ *
+ * // ❌ Throws with custom message function + case formatting
  * assertIsString(42n, {
- *   message: ({ currentType, validType }) => {
- *     return `Expected ${validType} but got (${currentType}).`;
- *   },
+ *   message: ({ currentType, validType }) => `Expected ${validType} but got (${currentType}).`,
  *   formatCase: "toKebabCase"
  * });
  * // ➔ TypeError: "Expected string but got (big-int)."
@@ -431,13 +543,12 @@ declare function assertIsPlainObject<T>(value:T,options?:OptionsAssertIs):assert
  * 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!" });
+ * // ❌ Throws if the value is not string
+ * assertIsString(mixedValue, { message: "Must be a string!", errorType: "RangeError" });
  *
- * // After this call, TypeScript knows `mixedValue` is string
- * const result: string = mixedValue; // ➔ ✅ safe to use
- * console.log(result.toUpperCase()); // ➔ ✅ type-safe
+ * // ✅ After this call, TypeScript knows `mixedValue` is string
+ * const result: string = mixedValue; // ➔ safe
+ * console.log(result.toUpperCase()); // ➔ type-safe
  * ```
  */
 declare const assertIsString:(value:unknown,options?:OptionsAssertIs)=>asserts value is string;export{assertIsArray,assertIsBigInt,assertIsBoolean,assertIsNumber,assertIsPlainObject,assertIsString};

package/dist/assertions/index.js

@@ -2,13 +2,13 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.8.0.
+ * Version: 3.9.1.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
  */
-export { assertIsBigInt, assertIsNumber } from '../chunk-LEX4TQW2.js';
-export { assertIsString } from '../chunk-FI76UZRF.js';
-export { assertIsArray } from '../chunk-6WMB5AJR.js';
+export { assertIsBigInt, assertIsNumber } from '../chunk-GHU356XQ.js';
+export { assertIsString } from '../chunk-OSSFLQDD.js';
+export { assertIsArray } from '../chunk-TXOVQZPU.js';
 import '../chunk-QNKGP5DY.js';
-export { assertIsBoolean, assertIsPlainObject } from '../chunk-3KTD3QDI.js';
+export { assertIsBoolean, assertIsPlainObject } from '../chunk-J4TT33ZX.js';

package/dist/{chunk-EK7FSI7F.cjs → chunk-2XGQQZ6A.cjs}

@@ -2,17 +2,17 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.8.0.
+ * Version: 3.9.1.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
  */
 'use strict';
 
-var chunkF3WBQKRI_cjs = require('./chunk-F3WBQKRI.cjs');
+var chunk7C7TQC5J_cjs = require('./chunk-7C7TQC5J.cjs');
 
 var parseCurrencyString = (input) => {
-  if (!chunkF3WBQKRI_cjs.isNonEmptyString(input)) return 0;
+  if (!chunk7C7TQC5J_cjs.isNonEmptyString(input)) return 0;
   let trimmed = input.trim().replace(/\u00A0/g, "").replace(/\u202F/g, "");
   let isNegative = false;
   if (/^\(.*\)$/.test(trimmed)) {