@rzl-zone/utils-js 3.12.0 → 3.12.1-beta.1

package/{LICENSE.md → LICENSE}

@@ -1,9 +1,9 @@
 MIT License
 
-Copyright (c) 2025 Rizalvin Dwiky.
+Copyright (c) 2026 Rizalvin Dwiky.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
+of this software and associated documentation files (the “Software”), to deal
 in the Software without restriction, including without limitation the rights
 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 copies of the Software, and to permit persons to whom the Software is
@@ -12,7 +12,7 @@ furnished to do so, subject to the following conditions:
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER

package/README.md

@@ -1,16 +1,16 @@
 <div align="center" style="display: flex; flex-direction: column; align-items: center;gap: 0rem">
-  <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 target="_blank" rel="noopener noreferrer" href="https://raw.githubusercontent.com/rzl-zone/rzl-zone/main/logo-circle.png">
+    <img src="https://raw.githubusercontent.com/rzl-zone/rzl-zone/main/logo-circle.png" align="middle" alt="RzlZone Logo" width="110" style="max-width: 100%;" />
   </a>
 </div>
 
-<h1 align="center"><strong>UtilsJS</strong></h1>
+<h1 align="center"><strong>Utils JS</strong></h1>
 
 <p align="center">
   <i>
-    A lightweight, modern TypeScript utility library for Node.js & browser (via bundlers like <a href="https://webpack.js.org"><code>Webpack</code></a>, <a href="https://vercel.com/blog/turbopack"><code>Turbopack</code></a>, or <a href="https://vite.dev/"><code>Vite</code></a>).
+    A lightweight, modern TypeScript utility library for Node.js & browser (via bundlers like <a href="https://webpack.js.org/"><code>Webpack</code></a>, <a href="https://vercel.com/blog/turbopack/"><code>Turbopack</code></a>, <a href="https://rollupjs.org/"><code>Rollup</code></a>, <a href="https://esbuild.github.io/"><code>esbuild</code></a>, and higher-level tools like <a href="https://vite.dev/"><code>Vite</code></a>, <a href="https://tsup.egoist.dev/"><code>tsup</code></a> and <a href="https://tsdown.dev/"><code>tsdown</code></a>).
   </i><br/>
-  <i>Provides reusable helpers to simplify your JavaScript or TypeScript projects.</i><br/>
+  <i>It provides reusable helpers to simplify everyday JavaScript and TypeScript tasks projects.</i><br/>
   <strong><i>Built with ❤️ by <a href="https://github.com/rzl-zone" target="_blank" rel="nofollow noreferrer noopener">@rzl-zone</a>.</i></strong>
 </p>
 
@@ -28,16 +28,16 @@
     <a href="https://nodejs.org/en/" target="_blank" rel="nofollow noreferrer noopener">
       <img src="https://img.shields.io/badge/Node.js-18.18.0%2B-green.svg?logo=node.js&color=339933&style=flat-rounded" alt="Node.js" />
     </a>
-    <a href="https://github.com/rzl-zone/utils-js/blob/main/CONTRIBUTING.md" target="_blank" rel="nofollow noreferrer noopener">
+    <a href="https://github.com/rzl-zone/rzl-zone/blob/main/CONTRIBUTING.md" target="_blank" rel="nofollow noreferrer noopener">
       <img src="https://img.shields.io/badge/PRs-Welcome-brightgreen.svg?color=28A745" alt="PRs Welcome" />
     </a>
-    <a href="https://github.com/rzl-zone/utils-js/blob/main/LICENSE.md" target="_blank" rel="nofollow noreferrer noopener">
+    <a href="https://github.com/rzl-zone/rzl-zone/blob/main/LICENSE" target="_blank" rel="nofollow noreferrer noopener">
       <img src="https://img.shields.io/badge/License-MIT-blue.svg?color=3DA639" alt="GitHub license" />
     </a>
-    <a href="https://github.com/rzl-zone/utils-js" target="_blank" rel="nofollow noreferrer noopener">
+    <a href="https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js" target="_blank" rel="nofollow noreferrer noopener">
       <img src="https://img.shields.io/badge/Repo-on%20GitHub-181717?logo=github" alt="GitHub" />
     </a>
-    <a href="https://github.com/orgs/rzl-zone/repositories" target="_blank" rel="nofollow noreferrer noopener">
+    <a href="https://github.com/rzl-zone/rzl-zone" target="_blank" rel="nofollow noreferrer noopener">
       <img src="https://img.shields.io/badge/Org-rzl--zone-24292e?logo=github&style=flat-rounded" alt="Repo on GitHub" />
     </a>
   </p>
@@ -75,7 +75,7 @@
 - **Works with:**
   - ✅ Node.js (18.18.0+) - ***Without NextJS***.
   - ✅ Node.js (20.9.0, or higher depending on NextJS version) - ***With NextJS***.
-  - ✅ Modern browsers (via bundlers like [`Webpack`](https://webpack.js.org), [`Turbopack`](https://vercel.com/blog/turbopack), or [`Vite`](https://vite.dev)).
+  - ✅ Modern browsers (via **ESM-compatible** bundlers such as [`Webpack`](https://webpack.js.org/), [`Turbopack`](https://vercel.com/blog/turbopack), [`Rollup`](https://rollupjs.org/), [`esbuild`](https://esbuild.github.io/), and higher-level tools like [`Vite`](https://vite.dev/), [`tsup`](https://tsup.egoist.dev/), and [`tsdown`](https://tsdown.dev/)).
 
 - **TypeScript Build Info:**
   - Target: `ES2022`.
@@ -130,7 +130,7 @@ pnpm add @rzl-zone/utils-js@latest
 
   ✅ Safe to use in both Next.js pages & API routes.
 
-  [**Read More Docs**](/docs/next-js/global.md#docs-sub-main--title)
+  [**Read More Docs**](https://github.com/rzl-zone/rzl-zone/blob/main/packages/utils-js/docs/next-js/global.md#docs-sub-main--title)
 
   ---
 
@@ -139,7 +139,7 @@ pnpm add @rzl-zone/utils-js@latest
   
   > ⚠️ Will throw Error if used outside a ***Next.js* server environment**.
 
-  [**Read More Docs**](/docs/next-js/server-only.md#docs-sub-main--title)
+  [**Read More Docs**](https://github.com/rzl-zone/rzl-zone/blob/main/packages/utils-js/docs/next-js/server-only.md#docs-sub-main--title)
 
 ---
 
@@ -201,7 +201,7 @@ pnpm add @rzl-zone/utils-js@latest
   >   - Category utils of `tailwind`, `next`, `next/server`.  
   >   - Server-only features (like Next.js helpers) will **not** be available.  
   > - The global object provided is `RzlUtilsJs`.  
-  > - The CDN bundle is **~350KB minified**, for production, consider using bundlers or npm packages for smaller size and tree-shaking.
+  > - The CDN bundle is **~370KB+ minified**, for production, consider using bundlers or npm packages for smaller size and tree-shaking.
 
 ---
 
@@ -211,104 +211,77 @@ pnpm add @rzl-zone/utils-js@latest
   </strong>
 </h3>
 
-#### Make TypeScript & VSCode automatically provide autocomplete for `@rzl-zone/utils-js` without needing triple-slash references in every file:
+Improve TypeScript editor import suggestions for `@rzl-zone/utils-js`, so all functions, types, and modules appear instantly when triggering autocomplete — press `Ctrl+Space` (**Windows/Linux**), `⌘+Space` (**macOS**), or your editor’s autocomplete shortcut.
 
-- 1️⃣ **Install @rzl-zone/utils-js.**
-
-  - Make sure the package is installed:
+This works across modern TypeScript-supported editors (e.g., `VSCode`, `WebStorm`, `Vim extensions`, `NeoVim LSP`, `Cursor`) without requiring triple-slash references — the package is fully indexed automatically through your editor’s TypeScript language service, follow steps:
 
-      ```bash
-      npm install @rzl-zone/utils-js@latest
-      # or
-      yarn add @rzl-zone/utils-js@latest
-      # or
-      pnpm add @rzl-zone/utils-js@latest
-      ```
+- 1️⃣ **Install @rzl-zone/utils-js.**
+  - Make sure the package is installed, see [**Installation Guide**](#installation).
 
 - 2️⃣ **Create a types folder.**
-
   - Inside your project root, make a folder called `types`:
 
-      ```pgsql
-      project-root/
-        ├─ src/
-        ├─ types/
-        │  └─ index.d.ts
-        ├─ tsconfig.json
-        └─ jsconfig.json
-      ```
+    ```pgsql
+    project-root/
+      ├─ src/
+      ├─ types/
+      │  └─ index.d.ts
+      ├─ tsconfig.json
+      └─ jsconfig.json
+    ```
 
 - 3️⃣ **Add the global reference file.**
-
   - Create `types/index.d.ts` with this content:
 
-      ```ts
-      /// <reference types="@rzl-zone/utils-js" />
-      ```
+    ```ts
+    /// <reference types="@rzl-zone/utils-js/.references" />
+    ```
 
-    - This tells TypeScript to include the types from `@rzl-zone/utils-js` globally.
-    - You can add more references here if needed, for example:
+  - You can add more references here if needed, for example:
 
-      ```ts
-      /// <reference types="@rzl-zone/utils-js" />
+    ```ts
+    /// <reference types="@rzl-zone/utils-js/.references" />
 
-      // eg more references (if needed):
-      /// <reference types="node" />
-      /// <reference types="react" />
-      ```
+    // eg more references (if needed):
+    /// <reference types="node" />
+    /// <reference types="react" />
+    ```
 
 - 4️⃣ **Update tsconfig.json.**
+  - Make sure add `types` folder to `"include"`, so **TypeScript** automatically picks up your types folder:
 
-  - Make sure not to override "types" (or leave it empty) so TypeScript automatically picks up your types folder:
-
-      ```jsonc
-      // tsconfig.json
-      {
-        "compilerOptions": { 
-          "strict": true,
-          "typeRoots": [
-            "./types", 
-            "./node_modules/@types"
-          ],
-          // other your config...
-        },
-        "include": [
-          "src", 
-          "types"
-        ],
+    ```jsonc
+    // tsconfig.json
+    {
+      "compilerOptions": {
+        "strict": true,
         // other your config...
-      }
-      ```
-
-    - `typeRoots` tells TS where to look for global type definitions.
-    - The `types` folder comes first, so your references override or add to the default `@types` packages.
+      },
+      "include": ["src", "types"]
+      // other your config...
+    }
+    ```
 
 - 5️⃣ **Update jsconfig.json (for JavaScript projects).**
-
   - If you also work with JS, do the same:
 
-      ```jsonc
-      // jsconfig.json
-      {
-        "compilerOptions": {
-          "checkJs": true,  // Optional, enables type checking 
-          "typeRoots": [
-            "./types", 
-            "./node_modules/@types"
-          ],
-          // other your config...
-        },
-        "include": [
-          "src", 
-          "types"
-        ],
+    ```jsonc
+    // jsconfig.json
+    {
+      "compilerOptions": {
+        "checkJs": true, // Optional, enables type checking
         // other your config...
-      }
-      ```
+      },
+      "include": ["src", "types"]
+      // other your config...
+    }
+    ```
 
-      >ℹ️ ***Tip:*** *For JS projects, consider adding "checkJs": true for better IntelliSense.*
+    > ℹ️ ***Tip:*** *For JS projects, consider adding `"checkJs": true` for better IntelliSense.*
 
-#### **Now, all types from `@rzl-zone/utils-js` are globally available, and you don’t need `"types": ["@rzl-zone/utils-js"]` in tsconfig.json.**
+- 6️⃣ **Restart your editor/IDE.**
+  - This forces your TypeScript language service to re-index the package.
+  - After restart, **all functions, types, and modules from `@rzl-zone/utils-js` will appear instantly in autocomplete**.
 
 ---
 
@@ -336,13 +309,13 @@ console.log(isServer());
 
 <h2 id="changelog">📝 <strong>Changelog</strong></h2>
 
-**See [CHANGELOG](CHANGELOG.md).**
+**See [CHANGELOG](https://github.com/rzl-zone/rzl-zone/blob/main/packages/utils-js/CHANGELOG.md).**
 
 ---
 
 <h2 id="contributing">🤝 <strong>Contributing</strong></h2>
 
-**See [CONTRIBUTING](CONTRIBUTING.md).**
+**See [CONTRIBUTING](https://github.com/rzl-zone/rzl-zone/blob/main/CONTRIBUTING.md).**
 
 ---
 
@@ -354,20 +327,20 @@ console.log(isServer());
 
 <h2 id="credits">🙌 <strong>Credits</strong></h2>
 
-**- [Rzl App](https://github.com/rzl-app)**  
-**- [All Contributors](../../contributors)**
+**- [Rzl App](https://github.com/rzl-app).**  
+**- [All Contributors](https://github.com/rzl-zone/rzl-zone/graphs/contributors).**
 
 ---
 
 <h2 id="license">📜 <strong>License</strong></h2>
 
-**The MIT License (MIT).**
-*Please see **[License File](LICENSE.md)** for more information.*
+**The MIT License (MIT).**  
+*Please see **[License File](https://github.com/rzl-zone/rzl-zone/blob/main/LICENSE)** for more information.*
 
 ---
 
-<h2>✅ <strong>Enjoy using <code>@rzl-zone/utils-js</code>?</strong></h2>
-
-*Star this repo [⭐](https://github.com/rzl-zone/utils-js) and share it with other JavaScript developers!*
+✅ **Enjoy using `@rzl-zone/utils-js`?**  
+*Star the monorepo [⭐](https://github.com/rzl-zone/rzl-zone) and share it with other JavaScript developers!*  
+📦 Explore other packages under [`@rzl-zone`](https://github.com/rzl-zone/rzl-zone)
 
 ---

package/dist/.references/index.d.cts

@@ -0,0 +1,25 @@
+/*!
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.1`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+
+//! References Paths:
+/// <reference path="../assertions/index.d.cts" />
+/// <reference path="../conversions/index.d.cts" />
+/// <reference path="../events/index.d.cts" />
+/// <reference path="../formatters/index.d.cts" />
+/// <reference path="../generators/index.d.cts" />
+/// <reference path="../next/index.d.cts" />
+/// <reference path="../next/server/index.d.cts" />
+/// <reference path="../operations/index.d.cts" />
+/// <reference path="../parsers/index.d.cts" />
+/// <reference path="../predicates/index.d.cts" />
+/// <reference path="../promises/index.d.cts" />
+/// <reference path="../strings/index.d.cts" />
+/// <reference path="../tailwind/index.d.cts" />
+/// <reference path="../urls/index.d.cts" />

package/dist/.references/index.d.ts

@@ -0,0 +1,25 @@
+/*!
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.1`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+
+//! References Paths:
+/// <reference path="../assertions/index.d.ts" />
+/// <reference path="../conversions/index.d.ts" />
+/// <reference path="../events/index.d.ts" />
+/// <reference path="../formatters/index.d.ts" />
+/// <reference path="../generators/index.d.ts" />
+/// <reference path="../next/index.d.ts" />
+/// <reference path="../next/server/index.d.ts" />
+/// <reference path="../operations/index.d.ts" />
+/// <reference path="../parsers/index.d.ts" />
+/// <reference path="../predicates/index.d.ts" />
+/// <reference path="../promises/index.d.ts" />
+/// <reference path="../strings/index.d.ts" />
+/// <reference path="../tailwind/index.d.ts" />
+/// <reference path="../urls/index.d.ts" />

package/dist/assertIsArray-DJXkjHZs.cjs

@@ -0,0 +1,26 @@
+/*!
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.1`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+"use strict";
+const require_assertIsBoolean = require('./assertIsBoolean-C8WEXVr2.cjs');
+function assertIsArray(value, options) {
+	if (require_assertIsBoolean.isArray(value)) return;
+	require_assertIsBoolean.resolveErrorMessageAssertions({
+		value,
+		options,
+		requiredValidType: "array"
+	});
+}
+Object.defineProperty(exports, 'assertIsArray', {
+  enumerable: true,
+  get: function () {
+    return assertIsArray;
+  }
+});
+//# sourceMappingURL=assertIsArray-DJXkjHZs.cjs.map

package/dist/assertIsArray-DJXkjHZs.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertIsArray-DJXkjHZs.cjs","names":["isArray"],"sources":["../src/assertions/objects/assertIsArray.ts"],"sourcesContent":["import type {\n  IsArray,\n  IsReadonlyArray,\n  IsUnknown\n} from \"@rzl-zone/ts-types-plus\";\nimport type { ArrayFallback } from \"@/_private/types.arrays\";\n\nimport { isArray } from \"@/predicates/is/isArray\";\n\nimport {\n  resolveErrorMessageAssertions,\n  type OptionsAssertIs\n} from \"../_private/assertIs\";\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\ntype AssertIsArrayResult<T> =\n  IsUnknown<T> extends true\n    ? unknown[] & T\n    : IsReadonlyArray<T> extends true\n      ? T\n      : T extends []\n        ? T\n        : IsArray<T> extends true\n          ? T\n          : Extract<T, unknown[] | [] | readonly []>;\n\n/** -------------------------------------------------------\n * * ***Type guard assertion: `assertIsArray`.***\n * -------------------------------------------------------\n * **This function is an **assertion function**.**\n * - **Behavior:**\n *    - Validates that the given `value` is an **array**.\n *    - After it returns successfully, TypeScript narrows the type of `value` to `array` **(generic support)**.\n *    - ✅ If `value` is an `array` ➔ execution continues normally.\n *    - ❌ If `value` is not an `array` ➔ throws a built-in error with either:\n *      - A custom error message (`options.message`), or\n *      - A default message including the actual type.\n * - **⚠️ Error type selection (`options.errorType`):**\n *    - You can override the type of error thrown when validation fails.\n *    - Must be one of the standard JavaScript built-in errors:\n *      - [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) |\n *        [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) |\n *        [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError) |\n *        [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError) |\n *        [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) |\n *        [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) |\n *        [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError)\n *    - **Default:** `\"TypeError\"` if not provided or invalid.\n * @template T - The input type being asserted.\n * @param {*} value - ***The value to validate.***\n * @param {OptionsAssertIs} [options]\n *  ***Optional configuration:***\n *    - `message`: A custom error message (`string` or `function`).\n *    - `errorType`: Built-in JavaScript error type to throw on failure (default `\"TypeError\"`).\n *    - `formatCase`: Controls how detected type names are formatted case in error messages.\n *    - `useAcronyms`: Control uppercase preservation of recognized acronyms during formatting.\n * @returns {boolean} Narrows `value` to an `array` **(generic support)** if no error is thrown.\n * @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.\n * @example\n * ```ts\n * // ✅ Simple usage\n * assertIsArray([]);\n * assertIsArray([\"123\", 456]);\n * assertIsArray(Array.from([\"abc\"]));\n * // No error, value is array\n *\n * // ❌ Throws TypeError (default behavior)\n * // Case 1: Invalid input type — received a string instead of a array\n * assertIsArray(\"42\");\n * // ➔ TypeError: \"Parameter input (`value`) must be of type `array`, but received: `string`.\"\n *\n * // ❌ Throws custom error type (e.g., RangeError)\n * assertIsArray(async function () {}, { errorType: \"RangeError\" });\n * // ➔ RangeError: \"Parameter input (`value`) must be of type `array`, but received: `async-function`.\"\n *\n * // ❌ Throws a TypeError with a custom string static message\n * assertIsArray(\"123\", { message: \"Must be a array!\" });\n * // ➔ TypeError: \"Must be a array!\"\n *\n * // ❌ Throws a TypeError with a custom message function and formatCase\n * assertIsArray(/regex/, {\n *   message: ({ currentType, validType }) => {\n *     return `Expected ${validType} but got (${currentType}).`\n *   },\n *   formatCase: \"toPascalCaseSpace\"\n * });\n * // ➔ TypeError: \"Expected array but got (Reg Exp).\"\n *\n * // ❌ Throws a TypeError with a custom useAcronyms option\n * // Case 1:\n * assertIsArray(new URL(\"https://example.com\"),{\n *   message: ({ currentType, validType }) => {\n *     return `Expected ${validType} but got (${currentType}).`\n *   },\n * });\n * // ➔ TypeError: \"Expected array but got (url).\"\n * assertIsArray(new URL(\"https://example.com\"), {\n *   useAcronyms: true,\n *   message: ({ currentType, validType }) => {\n *     return `Expected ${validType} but got (${currentType}).`\n *   },\n * });\n * // ➔ TypeError: \"Expected array but got (URL).\"\n *\n * // Case 2:\n * assertIsArray(new URLSearchParams, {\n *   formatCase: \"toPascalCase\",\n *   message: ({ currentType, validType }) => {\n *     return `Expected ${validType} but got (${currentType}).`\n *   },\n * });\n * // ➔ TypeError: \"Expected array but got (UrlSearchParams).\"\n * assertIsArray(new URLSearchParams, {\n *   useAcronyms: true,\n *   formatCase: \"toPascalCase\",\n *   message: ({ currentType, validType }) => {\n *     return `Expected ${validType} but got (${currentType}).`\n *   },\n * });\n * // ➔ TypeError: \"Expected array but got (URLSearchParams).\"\n * ```\n * -------------------------------------------------------\n * ✅ ***Real-world usage example***:\n * ```ts\n * const mixedValue: string | number[] | undefined = getUserInput();\n *\n * // Runtime assertion: throws if `mixedValue` is not a `number[]`\n * assertIsArray(mixedValue, {\n *   errorType: \"RangeError\",\n *   message: \"Must be array!\"\n * });\n *\n * // ✅ If no error thrown, TypeScript narrows `mixedValue` to `number[]` here\n * const result: number[] = mixedValue; // ➔ Safe type assignment\n * console.log(result.push(1, 2, 3));   // ➔ Safe to use array methods\n * ```\n */\nexport function assertIsArray(\n  value: [],\n  options?: OptionsAssertIs\n): asserts value is [];\nexport function assertIsArray<T>(\n  value: T,\n  options?: OptionsAssertIs\n): asserts value is ArrayFallback<T>;\nexport function assertIsArray(\n  value: unknown,\n  options?: OptionsAssertIs\n): asserts value is unknown[];\nexport function assertIsArray<T>(value: T, options?: OptionsAssertIs) {\n  if (isArray(value)) return;\n\n  resolveErrorMessageAssertions({ value, options, requiredValidType: \"array\" });\n}\n"],"mappings":";;;;;;;;;;;;;AAqJA,SAAgB,cAAiB,OAAU,SAA2B;CACpE,IAAIA,gCAAQ,MAAM,EAAE;CAEpB,sDAA8B;EAAE;EAAO;EAAS,mBAAmB;EAAS,CAAC"}

package/dist/assertIsArray-bTA3XLjq.js

@@ -0,0 +1,20 @@
+/*!
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.1`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+import { M as isArray, n as resolveErrorMessageAssertions } from "./assertIsBoolean-DR1SaXPD.js";
+function assertIsArray(value, options) {
+	if (isArray(value)) return;
+	resolveErrorMessageAssertions({
+		value,
+		options,
+		requiredValidType: "array"
+	});
+}
+export { assertIsArray as t };
+//# sourceMappingURL=assertIsArray-bTA3XLjq.js.map

package/dist/assertIsArray-bTA3XLjq.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertIsArray-bTA3XLjq.js","names":[],"sources":["../src/assertions/objects/assertIsArray.ts"],"sourcesContent":["import type {\n  IsArray,\n  IsReadonlyArray,\n  IsUnknown\n} from \"@rzl-zone/ts-types-plus\";\nimport type { ArrayFallback } from \"@/_private/types.arrays\";\n\nimport { isArray } from \"@/predicates/is/isArray\";\n\nimport {\n  resolveErrorMessageAssertions,\n  type OptionsAssertIs\n} from \"../_private/assertIs\";\n\n// eslint-disable-next-line @typescript-eslint/no-unused-vars\ntype AssertIsArrayResult<T> =\n  IsUnknown<T> extends true\n    ? unknown[] & T\n    : IsReadonlyArray<T> extends true\n      ? T\n      : T extends []\n        ? T\n        : IsArray<T> extends true\n          ? T\n          : Extract<T, unknown[] | [] | readonly []>;\n\n/** -------------------------------------------------------\n * * ***Type guard assertion: `assertIsArray`.***\n * -------------------------------------------------------\n * **This function is an **assertion function**.**\n * - **Behavior:**\n *    - Validates that the given `value` is an **array**.\n *    - After it returns successfully, TypeScript narrows the type of `value` to `array` **(generic support)**.\n *    - ✅ If `value` is an `array` ➔ execution continues normally.\n *    - ❌ If `value` is not an `array` ➔ throws a built-in error with either:\n *      - A custom error message (`options.message`), or\n *      - A default message including the actual type.\n * - **⚠️ Error type selection (`options.errorType`):**\n *    - You can override the type of error thrown when validation fails.\n *    - Must be one of the standard JavaScript built-in errors:\n *      - [`TypeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError) |\n *        [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) |\n *        [`EvalError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError) |\n *        [`RangeError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError) |\n *        [`ReferenceError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) |\n *        [`SyntaxError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError) |\n *        [`URIError`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/URIError)\n *    - **Default:** `\"TypeError\"` if not provided or invalid.\n * @template T - The input type being asserted.\n * @param {*} value - ***The value to validate.***\n * @param {OptionsAssertIs} [options]\n *  ***Optional configuration:***\n *    - `message`: A custom error message (`string` or `function`).\n *    - `errorType`: Built-in JavaScript error type to throw on failure (default `\"TypeError\"`).\n *    - `formatCase`: Controls how detected type names are formatted case in error messages.\n *    - `useAcronyms`: Control uppercase preservation of recognized acronyms during formatting.\n * @returns {boolean} Narrows `value` to an `array` **(generic support)** if no error is thrown.\n * @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.\n * @example\n * ```ts\n * // ✅ Simple usage\n * assertIsArray([]);\n * assertIsArray([\"123\", 456]);\n * assertIsArray(Array.from([\"abc\"]));\n * // No error, value is array\n *\n * // ❌ Throws TypeError (default behavior)\n * // Case 1: Invalid input type — received a string instead of a array\n * assertIsArray(\"42\");\n * // ➔ TypeError: \"Parameter input (`value`) must be of type `array`, but received: `string`.\"\n *\n * // ❌ Throws custom error type (e.g., RangeError)\n * assertIsArray(async function () {}, { errorType: \"RangeError\" });\n * // ➔ RangeError: \"Parameter input (`value`) must be of type `array`, but received: `async-function`.\"\n *\n * // ❌ Throws a TypeError with a custom string static message\n * assertIsArray(\"123\", { message: \"Must be a array!\" });\n * // ➔ TypeError: \"Must be a array!\"\n *\n * // ❌ Throws a TypeError with a custom message function and formatCase\n * assertIsArray(/regex/, {\n *   message: ({ currentType, validType }) => {\n *     return `Expected ${validType} but got (${currentType}).`\n *   },\n *   formatCase: \"toPascalCaseSpace\"\n * });\n * // ➔ TypeError: \"Expected array but got (Reg Exp).\"\n *\n * // ❌ Throws a TypeError with a custom useAcronyms option\n * // Case 1:\n * assertIsArray(new URL(\"https://example.com\"),{\n *   message: ({ currentType, validType }) => {\n *     return `Expected ${validType} but got (${currentType}).`\n *   },\n * });\n * // ➔ TypeError: \"Expected array but got (url).\"\n * assertIsArray(new URL(\"https://example.com\"), {\n *   useAcronyms: true,\n *   message: ({ currentType, validType }) => {\n *     return `Expected ${validType} but got (${currentType}).`\n *   },\n * });\n * // ➔ TypeError: \"Expected array but got (URL).\"\n *\n * // Case 2:\n * assertIsArray(new URLSearchParams, {\n *   formatCase: \"toPascalCase\",\n *   message: ({ currentType, validType }) => {\n *     return `Expected ${validType} but got (${currentType}).`\n *   },\n * });\n * // ➔ TypeError: \"Expected array but got (UrlSearchParams).\"\n * assertIsArray(new URLSearchParams, {\n *   useAcronyms: true,\n *   formatCase: \"toPascalCase\",\n *   message: ({ currentType, validType }) => {\n *     return `Expected ${validType} but got (${currentType}).`\n *   },\n * });\n * // ➔ TypeError: \"Expected array but got (URLSearchParams).\"\n * ```\n * -------------------------------------------------------\n * ✅ ***Real-world usage example***:\n * ```ts\n * const mixedValue: string | number[] | undefined = getUserInput();\n *\n * // Runtime assertion: throws if `mixedValue` is not a `number[]`\n * assertIsArray(mixedValue, {\n *   errorType: \"RangeError\",\n *   message: \"Must be array!\"\n * });\n *\n * // ✅ If no error thrown, TypeScript narrows `mixedValue` to `number[]` here\n * const result: number[] = mixedValue; // ➔ Safe type assignment\n * console.log(result.push(1, 2, 3));   // ➔ Safe to use array methods\n * ```\n */\nexport function assertIsArray(\n  value: [],\n  options?: OptionsAssertIs\n): asserts value is [];\nexport function assertIsArray<T>(\n  value: T,\n  options?: OptionsAssertIs\n): asserts value is ArrayFallback<T>;\nexport function assertIsArray(\n  value: unknown,\n  options?: OptionsAssertIs\n): asserts value is unknown[];\nexport function assertIsArray<T>(value: T, options?: OptionsAssertIs) {\n  if (isArray(value)) return;\n\n  resolveErrorMessageAssertions({ value, options, requiredValidType: \"array\" });\n}\n"],"mappings":";;;;;;;;;;;;;AAqJA,SAAgB,cAAiB,OAAU,SAA2B;CACpE,IAAI,QAAQ,MAAM,EAAE;CAEpB,8BAA8B;EAAE;EAAO;EAAS,mBAAmB;EAAS,CAAC"}