@rzl-zone/utils-js 3.2.5-beta.0 → 3.3.0

package/README.md

@@ -3,9 +3,9 @@
 </div>
 
 <p align="center">
-🚀 <strong>Rzl Utility JavaScript</strong> 🚀<br/>
+🚀 <strong>Rzl Utility JS</strong> 🚀<br/>
 A lightweight, modern TypeScript utility library for Node.js & browser (via bundlers like Webpack/Vite).<br/>
-Provides reusable helpers to simplify your JavaScript / TypeScript projects.<br/>
+Provides reusable helpers to simplify your JavaScript or TypeScript projects.<br/>
 <strong>Built with ❤️ by <a href="https://github.com/rzl-app" target="_blank" rel="nofollow noreferrer noopener">@rzl-app</a>.</strong>
 </p>
 
@@ -19,7 +19,7 @@ Provides reusable helpers to simplify your JavaScript / TypeScript projects.<br/
   <img src="https://img.shields.io/npm/dt/@rzl-zone/utils-js?style=flat-rounded" alt="Downloads">
 </a>
 <a href="https://nodejs.org/en/" target="_blank" rel="nofollow noreferrer noopener">
-  <img src="https://img.shields.io/badge/node-≥16.0.0%20%7C%20≥18.17.0-blue.svg?logo=node.js&style=flat-rounded" alt="Node.js">
+  <img src="https://img.shields.io/badge/node-≥16.0.0-blue.svg?logo=node.js&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">
   <img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs Welcome">
@@ -50,7 +50,7 @@ Provides reusable helpers to simplify your JavaScript / TypeScript projects.<br/
 - ❤️ [Sponsor](#sponsor-this-package)
 - 📜 [Changelog](#changelog)
 - 🤝 [Contributing](#contributing)
-- <svg width="20" height="16" viewBox="0 0 500 500" fill="#0066ffff" xmlns="http://www.w3.org/2000/svg"><path d="M466.5 83.7L266.5 15.7c-6.4-2.1-13.5-2.1-19.9 0l-200 68c-9.4 3.2-15.7 12-15.7 22.1V256c0 120.9 83.7 230.2 200 256 116.3-25.8 200-135.1 200-256V105.8c0-10.1-6.3-18.9-15.7-22.1z"/></svg> [Security](#security)
+- 🔒 [Security](#security)
 - 🙌 [Credits](#credits)
 - 📄 [License](#license)
 
@@ -58,7 +58,7 @@ Provides reusable helpers to simplify your JavaScript / TypeScript projects.<br/
 
 <h2 id="requirements">💻 Requirements</h2>
 
-- **Node.js `≥16.0.0` or `≥18.17.0`**  
+- **Node.js `≥16.0.0`**  
   This package leverages modern JavaScript & TypeScript features that require Node.js version 16.0.0 if not using Next.js, and for Next.js it must follow the official minimum Node.js version requirement depending on the version you use.  
   - 🔗 See official Next.js documentation: 
       <a href="https://nextjs.org/docs/getting-started/installation#system-requirements" target="_blank" rel="nofollow noreferrer noopener">NextJS Installation Requirements</a>
@@ -99,7 +99,7 @@ Provides reusable helpers to simplify your JavaScript / TypeScript projects.<br/
 - 📦 Works in **Node.js** & modern browsers
 - ❤️ Simple API, easy to extend
 - 🧬 **Next.js support**: helpers for dynamic routes, building URLs, reading env, extracting client IP
-- 🛠 Additional TypeScript types: `OmitStrict`, `PartialByKeys`, etc.
+- 🛠 Additional TypeScript types: `OmitStrict`, `PartialOnly`, etc.
 
 ---
 
@@ -132,25 +132,23 @@ This package also provides utilities specially built for Next.js environments, n
   
   ```ts
   import { | } from "@rzl-zone/utils-js/assertions";
-  import { | } from "@rzl-zone/utils-js/conversions";
-  import { | } from "@rzl-zone/utils-js/env";
+  import { | } from "@rzl-zone/utils-js/conversions"; 
   import { | } from "@rzl-zone/utils-js/events";
-  import { | } from "@rzl-zone/utils-js/formatting";
-  import { | } from "@rzl-zone/utils-js/generator";
-  import { | } from "@rzl-zone/utils-js/generator";
+  import { | } from "@rzl-zone/utils-js/formatters";
+  import { | } from "@rzl-zone/utils-js/generators";
   import { | } from "@rzl-zone/utils-js/next";
   import { | } from "@rzl-zone/utils-js/next/server";
   import { | } from "@rzl-zone/utils-js/operations";
   import { | } from "@rzl-zone/utils-js/parsers";
   import { | } from "@rzl-zone/utils-js/predicates";
-  import { | } from "@rzl-zone/utils-js/promise";
+  import { | } from "@rzl-zone/utils-js/promises";
   import { | } from "@rzl-zone/utils-js/strings";
-  import { | } from "@rzl-zone/utils-js/stylings";
+  import { | } from "@rzl-zone/utils-js/tailwind";
   import { | } from "@rzl-zone/utils-js/urls";
 
   import type { | } from "@rzl-zone/utils-js/types";
   ```
-  #### Just place your cursor right inside `{ }` or from after import from `"@rzl-zone/utils-js/"` like the pipe ("|") above then ctrl + space, there are many functions or types and then hover to each function is complete with how to use it because I have added tsDoc.
+  #### Just place your cursor right inside `{ }` or after import from `"@rzl-zone/utils-js/{{ | }}"` like the pipe ("|") above then ctrl + space, there are many functions or types and then hover to each function is complete with how to use it because I have added tsDoc.
 
   <!-- - <h4 id="detailed-features--assertions">
       Assertions - 
@@ -182,10 +180,10 @@ This package also provides utilities specially built for Next.js environments, n
 #### Example Function Import:
 
 ```ts
-import { isServer } from "@rzl-zone/utils-js/env";
+import { isServer } from "@rzl-zone/utils-js/predicates";
 
 console.log(isServer());
-// true if running on Node.js, false if browser
+// ➔ `true` if running on server-side, `false` if in browser.
 ```
 
 #### Example Types Helper Import:
@@ -193,7 +191,7 @@ console.log(isServer());
 ```ts
 import type { OmitStrict } from "@rzl-zone/utils-js/types";
 
-type MyType = OmitStrict<OtherType, "omitedProps">;
+type MyType = OmitStrict<OtherType, "omittingProps">;
 // Fully strict TS omit that requires all keys to exist in target
 ```
 
@@ -218,9 +216,7 @@ See [CONTRIBUTING](CONTRIBUTING.md).
 
 ---
 
-<h2 id="security"><svg width="20" height="20" viewBox="0 0 512 512" fill="#0066ffff" xmlns="http://www.w3.org/2000/svg">
-  <path d="M466.5 83.7L266.5 15.7c-6.4-2.1-13.5-2.1-19.9 0l-200 68c-9.4 3.2-15.7 12-15.7 22.1V256c0 120.9 83.7 230.2 200 256 116.3-25.8 200-135.1 200-256V105.8c0-10.1-6.3-18.9-15.7-22.1z"/>
-</svg> Security</h2>
+<h2 id="security">🔒 Security</h2>
 
 Please report issues to [rizalvindwiky1998@gmail.com](mailto:rizalvindwiky1998@gmail.com).
 

package/dist/NumberRangeUnion-B6bhM2s7.d.ts

@@ -0,0 +1,33 @@
+/** --------------------------------------------------
+ * * ***Internal Utility Type for: {@link NumberRangeUnion | `NumberRangeUnion`}.***
+ * --------------------------------------------------
+ * @template N - Starting/Ending number of the range (inclusive).
+ * @template Acc - Internal accumulator for recursion (do not set manually).
+ */
+type Enumerate<N extends number,Acc extends number[]=[]>=Acc["length"] extends N?Acc[number]:Enumerate<N,[...Acc,Acc["length"]]>;
+/** --------------------------------------------------
+ * * ***Utility Type: `NumberRangeUnion`.***
+ * --------------------------------------------------
+ * **Generate a union type of numbers from `From` to `To` using enumeration.**
+ * @description
+ * Produces a **numeric union type** from `From` to `To` (inclusive),
+ * using a simpler approach based on `Enumerate<N>` helper type.
+ * - ✅ Straightforward & easy to reason about.
+ * - ⚠️ Still limited by TypeScript recursion depth (safe up to `999`).
+ * - ⚙️ Best used for **smaller ranges** (`≤ 100`) or when readability matters.
+ * - ℹ️ For **larger ranges** (`≥ 101`) use {@link NumberRangeLimit | `NumberRangeLimit`} instead.
+ * @template From - Starting number of the range (inclusive).
+ * @template To - Ending number of the range (inclusive).
+ * @example
+ * ```ts
+ * type RangeA = NumberRangeUnion<3, 6>;
+ * // ➔ 3 | 4 | 5 | 6
+ * type RangeB = NumberRangeUnion<0, 2>;
+ * // ➔ 0 | 1 | 2
+ * type RangeC = NumberRangeUnion<8, 8>;
+ * // ➔ 8
+ * type RangeD = NumberRangeUnion<20, 10>;
+ * // ➔ 10
+ * ```
+ */
+type NumberRangeUnion<From extends number,To extends number>=From extends To?From:Exclude<Enumerate<To>,Enumerate<From>>extends never?To:Exclude<Enumerate<To>,Enumerate<From>>|To;export type{NumberRangeUnion as N};

package/dist/{any-BmdI8UbK.d.ts → any-v4TsK9ES.d.ts}

@@ -1,11 +1,11 @@
-import{I as If}from'./if-CvT4R7Kh.js';
+import{I as If}from'./if-ChM35c_q.js';
 /** -------------------------------------------------------
- * * ***IsAny.***
+ * * ***Utility Type: `IsAny`.***
  * -------------------------------------------------------
- * A type-level utility that checks whether a type is ***`any`***.
- * - Returns `true` if `T` is `any`.
- * - Returns `false` otherwise.
- *
+ * **A type-level utility that checks whether a type is ***`any`***.**
+ * - **Behavior:**
+ *    - Returns `true` if `T` is `any`.
+ *    - Returns `false` for otherwise.
  * @template T - The type to evaluate.
  * @example
  * ```ts
@@ -17,18 +17,16 @@ import{I as If}from'./if-CvT4R7Kh.js';
  */
 type IsAny<T>=0 extends 1 & T?true:false;
 /** -------------------------------------------------------
- * * ***IfAny.***
+ * * ***Utility Type: `IfAny`.***
  * -------------------------------------------------------
- *
- * A type-level conditional utility that returns one type if ***`T` is `any`***,
- * and another type otherwise.
- * - Defaults to `true` when `T` is `any`.
- * - Defaults to `false` otherwise.
- *
+ * **A type-level conditional utility that returns one type if ***`T` is `any`***,
+ * and another type otherwise.**
+ * - **Behavior:**
+ *    - Defaults to `true` when `T` is `any`.
+ *    - Defaults to `false` for otherwise.
  * @template T - The type to check.
- * @template IfTrue - The type to return if `T` is `any`. *(default: `true`)*
- * @template IfFalse - The type to return if `T` is not `any`. *(default: `false`)*
- *
+ * @template IfTrue - The type to return if `T` is `any`, *(default: `true`)*.
+ * @template IfFalse - The type to return if `T` is not `any`, *(default: `false`)*.
  * @example
  * ```ts
  * type A = IfAny<any, string, number>;
@@ -38,7 +36,9 @@ type IsAny<T>=0 extends 1 & T?true:false;
  * ```
  */
 type IfAny<T,IfTrue=true,IfFalse=false>=If<IsAny<T>,IfTrue,IfFalse>;
-/** Configuration options for a type-level utility `AnifyProperties`. */
+/** * ***Configuration options for a type-level utility for
+ * {@link AnifyProperties | `AnifyProperties`}.***
+ */
 type AnifyPropertiesOptions={
 /** If `makeOptional: true`, all properties become optional, otherwise, all properties are required and typed as `any`, defaultValue: `false`.
  *
@@ -46,20 +46,19 @@ type AnifyPropertiesOptions={
  */
 makeOptional:boolean;};
 /** -------------------------------------------------------
- * * ***AnifyProperties.***
+ * * ***Utility Type: `AnifyProperties`.***
  * -------------------------------------------------------
- *
- * A type-level utility that transforms all properties of an object into ***`any`***.
- * - If `makeOptional: true`, all properties become optional.
- * - Otherwise, all properties are required and typed as `any`.
- *
- * @template T - The object type to transform.
- * @template Options - Configuration options. Defaults to `{ makeOptional: false }`.
+ * **A type-level utility that transforms all properties of an object
+ * into ***`any`***.**
+ * - **Behavior:**
+ *    - If `makeOptional: true`, all properties become optional.
+ *    - Otherwise, all properties are required and typed as `any`.
+ * @template T The object type to transform.
+ * @template Options Configuration options, defaults to `{ makeOptional: false }`.
  * @example
  * ```ts
  * type A = AnifyProperties<{a: string; b: number}>;
  * // ➔ { a: any; b: any }
- *
  * type B = AnifyProperties<{a: string; b: number}, { makeOptional: true }>;
  * // ➔ { a?: any; b?: any }
  * ```

package/dist/{arrays-normalize-recursive-CnjYJ9xg.d.ts → arrays-normalize-recursive-BqmVuFlD.d.ts}

@@ -1,11 +1,11 @@
 /** -------------------------------------------------------
- * * ***FixNeverArrayRecursive.***
+ * * ***Utility Type: `FixNeverArrayRecursive`.***
  * -------------------------------------------------------
- * A type-level utility that **recursively transforms arrays of type `never[]` into empty arrays**.
- * - Preserves `readonly` modifiers.
- * - Applies recursively for nested arrays.
- * - Leaves other types unchanged.
- *
+ * **A type-level utility that **recursively transforms arrays of type `never[]` into empty arrays**.**
+ * - **Behavior:**
+ *    - Preserves `readonly` modifiers.
+ *    - Applies recursively for nested arrays.
+ *    - Leaves other types unchanged.
  * @template T - The input type to recursively fix.
  * @example
  * ```ts
@@ -23,13 +23,13 @@
  */
 type FixNeverArrayRecursive<T>=T extends readonly never[]?T extends never[]?[]:readonly []:T extends(infer U)[]?FixNeverArrayRecursive<U>[]:T extends readonly(infer U)[]?readonly FixNeverArrayRecursive<U>[]:T;
 /** -------------------------------------------------------
- * * ***NormalizeEmptyArraysRecursive.***
+ * * ***Utility Type: `NormalizeEmptyArraysRecursive`.***
  * -------------------------------------------------------
- * A type-level utility that **recursively normalizes empty array types** by converting arrays whose element type is `never`, `null`, or `undefined` into empty tuple types (`[]`).
- * - Preserves `readonly` modifiers.
- * - Recurses into nested arrays.
- * - Leaves other array types unchanged.
- *
+ * **A type-level utility that **recursively normalizes empty array types** by converting arrays whose element type is `never`, `null`, or `undefined` into empty tuple types (`[]`).**
+ * - **Behavior:**
+ *    - Preserves `readonly` modifiers.
+ *    - Recurses into nested arrays.
+ *    - Leaves other array types unchanged.
  * @template T - The input type to normalize.
  * @example
  * ```ts
@@ -47,15 +47,15 @@ type FixNeverArrayRecursive<T>=T extends readonly never[]?T extends never[]?[]:r
  */
 type NormalizeEmptyArraysRecursive<T>=T extends readonly(infer U)[]?U extends never|null|undefined?T extends readonly unknown[]?T extends(infer E)[]?[]:readonly []:never:T extends(infer E)[]?NormalizeEmptyArraysRecursive<U>[]:readonly NormalizeEmptyArraysRecursive<U>[]:T;
 /** -------------------------------------------------------
- * * ***RemoveEmptyArrayElements.***
+ * * ***Utility Type: `RemoveEmptyArrayElements`.***
  * -------------------------------------------------------
- * A type-level utility that **recursively removes empty array elements (`[]`) from a tuple type**.
- * - If `T` is a tuple, checks the first element:
- *    - If `Head` is an empty array type (`[]`), it is removed.
- *    - Otherwise, `Head` is preserved.
- * - Repeats recursively on the rest of the tuple.
- * - Leaves non-tuple types unchanged.
- *
+ * **A type-level utility that **recursively removes empty array elements (`[]`) from a tuple type**.**
+ * - **Behavior:**
+ *    - If `T` is a tuple, checks the first element:
+ *        - If `Head` is an empty array type (`[]`), it is removed.
+ *        - Otherwise, `Head` is preserved.
+ *    - Repeats recursively on the rest of the tuple.
+ *    - Leaves non-tuple types unchanged.
  * @template T - The tuple type to process.
  * @example
  * ```ts

package/dist/assertions/index.cjs

@@ -1 +1 @@
-"use strict";var e=require("../chunk-GGWPB23G.cjs"),r=require("../chunk-VHAPTHEA.cjs"),t=require("../chunk-VCFXNV3Q.cjs");require("../chunk-UDA26MCU.cjs");var s=require("../chunk-D3VSHABU.cjs");Object.defineProperty(exports,"assertIsBigInt",{enumerable:!0,get:function(){return e.assertIsBigInt}}),Object.defineProperty(exports,"assertIsNumber",{enumerable:!0,get:function(){return e.assertIsNumber}}),Object.defineProperty(exports,"assertIsArray",{enumerable:!0,get:function(){return r.assertIsArray}}),Object.defineProperty(exports,"assertIsString",{enumerable:!0,get:function(){return t.assertIsString}}),Object.defineProperty(exports,"assertIsBoolean",{enumerable:!0,get:function(){return s.assertIsBoolean}}),Object.defineProperty(exports,"assertIsPlainObject",{enumerable:!0,get:function(){return s.assertIsPlainObject}});
+"use strict";var e=require("../chunk-IVL7CKVH.cjs"),r=require("../chunk-HYRQMTRH.cjs"),t=require("../chunk-6JFZL7YE.cjs");require("../chunk-UDA26MCU.cjs");var s=require("../chunk-PZQ6I4JJ.cjs");Object.defineProperty(exports,"assertIsBigInt",{enumerable:!0,get:function(){return e.assertIsBigInt}}),Object.defineProperty(exports,"assertIsNumber",{enumerable:!0,get:function(){return e.assertIsNumber}}),Object.defineProperty(exports,"assertIsString",{enumerable:!0,get:function(){return r.assertIsString}}),Object.defineProperty(exports,"assertIsArray",{enumerable:!0,get:function(){return t.assertIsArray}}),Object.defineProperty(exports,"assertIsBoolean",{enumerable:!0,get:function(){return s.assertIsBoolean}}),Object.defineProperty(exports,"assertIsPlainObject",{enumerable:!0,get:function(){return s.assertIsPlainObject}});

package/dist/assertions/index.d.ts

@@ -1,51 +1,64 @@
-import{G as GetPreciseTypeOptions,I as IsNumberOptions,a as IsPlainObjectResult}from'../isPlainObject-BVhBAPHX.js';import'../type-data-DDs-u2kq.js';
+import{P as Prettify}from'../prettify-3o8_Kw6b.js';import{P as PickStrict}from'../pick-BSMX6Xe2.js';import{G as GetPreciseTypeOptions,I as IsNumberOptions,a as IsPlainObjectResult}from'../isPlainObject-DGJkcFYw.js';import'../if-ChM35c_q.js';import'../never-D89PbPh5.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 `OptionsAssertIs`.
- *
- * - `currentType` ➔ the actual detected runtime type of the value.
- * - `validType`   ➔ the required/expected type name that the value must match.
- *
+ * **This type describes the parameters received when `options.message`
+ * is defined as a function in {@link OptionsAssertIs | `OptionsAssertIs`}.**
+ * - **Parameter:**
+ *    - `currentType` ➔ the actual detected runtime type of the value.
+ *    - `validType`   ➔ the required/expected type name that the value must match.
  * @example
  * ```ts
  * const options: OptionsAssertIs = {
- *   message: ({ currentType, validType }) =>
- *     `Expected ${validType} but got ${currentType}`
+ *   message: ({ currentType, validType }) => {
+ *     return `Expected ${validType} but got ${currentType}`;
+ *   };
  * };
  * ```
  */
 type OptionsMessageFunctionAssertIs={
-/** The actual runtime type of the value being checked.
- *
- * - Example: `"number"`, `"big-int"`, `"plain-object"`, (depends `formatCase` options).
+/** ---------------------------------------------------------------------------
+ * * ***The actual runtime type of the value being checked.***
+ * ---------------------------------------------------------------------------
+ * - ***Example:***
+ *    - `"number"`, `"big-int"`, `"plain-object"`, (depends `formatCase` options).
  */
 currentType:string;
-/** The required/expected type that the value must conform to.
- *
- * - Example: `"boolean"`, `"string"`, `"big-int"`, `"plain-object"`, (will force format to `kebab-case`).
+/** ---------------------------------------------------------------------------
+ * * ***The required/expected type that the value must conform to.***
+ * ---------------------------------------------------------------------------
+ * - ***Example:***
+ *    - `"boolean"`, `"string"`, `"big-int"`, `"plain-object"`, (will force format to `kebab-case`).
+ */
+validType:string;};
+/** -------------------------------------------------------
+ * * ***Custom error-message type for assertions option {@link OptionsAssertIs | `OptionsAssertIs`}.***
+ * -------------------------------------------------------
+ * - ***Accepts:***
+ *    - A static string message.
+ *    - A function receiving `{ currentType, validType }` and returning a string.
+ */
+type OptionsMessageAssertIs=string|(({currentType,validType}:OptionsMessageFunctionAssertIs)=>string);
+/** ---------------------------------------------------------------------------
+ * * ***Base options for `assertIs*` functions.***
+ * ---------------------------------------------------------------------------
  */
-validType:string;};type OptionsAssertIs={
+type OptionsAssertIs=Prettify<{
 /** -------------------------------------------------------
  * * ***Custom error message for assertion failures.***
  * -------------------------------------------------------
- *
- * @description
- * This option allows overriding the **default error message** when a value
- * does not match the required type.
- *
+ * **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.
- *
+ *    - 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.
- *
+ *    - **Must** return a **string**:
+ *      - **If** the **returned string is** `empty` or `whitespace`,
+ *        the **default message** will be used instead.
  * @example
  * ```ts
  * // Static message
@@ -53,25 +66,27 @@ validType:string;};type OptionsAssertIs={
  *
  * // Dynamic message
  * {
- *   message: ({ currentType, validType }) =>
- *     `Expected ${validType} but got ${currentType}`
+ *   message: ({ currentType, validType }) => {
+ *     return `Expected ${validType} but got ${currentType}`;
+ *   };
  * }
  * ```
  */
-message?:string|(({currentType,validType}:OptionsMessageFunctionAssertIs)=>string);}& GetPreciseTypeOptions;
+message?:OptionsMessageAssertIs;}& PickStrict<GetPreciseTypeOptions,"formatCase">,{recursive:true;}>;
 /** -------------------------------------------------------
  * * ***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:
+ *    - 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:
+ *      - 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.
@@ -92,8 +107,9 @@ message?:string|(({currentType,validType}:OptionsMessageFunctionAssertIs)=>strin
  *
  * // ❌ Throws with custom function message + case formatting
  * assertIsBoolean(123n, {
- *   message: ({ currentType, validType }) =>
- *     `Expected ${validType} but got (${currentType}).`,
+ *   message: ({ currentType, validType }) => {
+ *     return `Expected ${validType} but got (${currentType}).`;
+ *   },
  *   formatCase: "toKebabCase"
  * });
  * // ➔ TypeError: "Expected boolean but got (big-int)."
@@ -117,9 +133,9 @@ declare const assertIsBoolean:(value:unknown,options?:OptionsAssertIs)=>asserts
  * * ***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:**
+ *    - 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:
  *      - A custom error message (`options.message`), or
@@ -127,8 +143,9 @@ declare const assertIsBoolean:(value:unknown,options?:OptionsAssertIs)=>asserts
  *  - **ℹ️ 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:
+ * @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.
@@ -149,8 +166,9 @@ declare const assertIsBoolean:(value:unknown,options?:OptionsAssertIs)=>asserts
  *
  * // ❌ Throws with custom function message + case formatting
  * assertIsBigInt(42, {
- *   message: ({ currentType, validType }) =>
- *     `Expected ${validType} but got (${currentType}).`,
+ *   message: ({ currentType, validType }) => {
+ *     return `Expected ${validType} but got (${currentType}).`;
+ *   },
  *   formatCase: "toKebabCase"
  * });
  * // ➔ TypeError: "Expected bigint but got (number)."
@@ -174,9 +192,9 @@ declare const assertIsBigInt:(value:unknown,options?:OptionsAssertIs)=>asserts v
  * * ***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:**
+ *    - 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:
  *      - A custom error message (`options.message`), or
@@ -185,8 +203,9 @@ declare const assertIsBigInt:(value:unknown,options?:OptionsAssertIs)=>asserts v
  *    - 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:
+ * @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.
@@ -208,8 +227,9 @@ declare const assertIsBigInt:(value:unknown,options?:OptionsAssertIs)=>asserts v
  *
  * // ❌ Throws with custom function message + case formatting
  * assertIsNumber("hello", {
- *   message: ({ currentType, validType }) =>
- *     `Expected ${validType} but got (${currentType}).`,
+ *   message: ({ currentType, validType }) => {
+ *     return `Expected ${validType} but got (${currentType}).`;
+ *   },
  *   formatCase: "toKebabCase"
  * });
  * // ➔ TypeError: "Expected number but got (string)."
@@ -242,16 +262,17 @@ declare const assertIsNumber:(value:unknown,options?:OptionsAssertIsNumber)=>ass
  * * ***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:**
+ *    - Validates that the given `value` is a **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:
  *      - 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:
+ * @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.
@@ -272,13 +293,13 @@ declare const assertIsNumber:(value:unknown,options?:OptionsAssertIsNumber)=>ass
  *
  * // ❌ Throws with custom function message + case formatting
  * assertIsArray(42n, {
- *   message: ({ currentType, validType }) =>
- *     `Expected ${validType} but got (${currentType}).`,
+ *   message: ({ currentType, validType }) => {
+ *     return `Expected ${validType} but got (${currentType}).`;
+ *   },
  *   formatCase: "toKebabCase"
  * });
  * // ➔ TypeError: "Expected array but got (big-int)."
  * ```
- *
  * -------------------------------------------------------
  * ✅ ***Real-world usage with generic narrowing***:
  * ```ts
@@ -298,16 +319,17 @@ declare function assertIsArray<T extends unknown[]>(value:T,options?:OptionsAsse
  * * ***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:**
+ *    - 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:
  *      - 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:
+ * @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.
@@ -328,8 +350,9 @@ declare function assertIsArray<T extends unknown[]>(value:T,options?:OptionsAsse
  *
  * // ❌ Throws with custom message function and formatCase
  * assertIsPlainObject(42n, {
- *   message: ({ currentType, validType }) =>
- *     `Expected ${validType} but got (${currentType}).`,
+ *   message: ({ currentType, validType }) => {
+ *     return `Expected ${validType} but got (${currentType}).`;
+ *   },
  *   formatCase: "toKebabCase"
  * });
  * // ➔ TypeError: "Expected plain-object but got (big-int)."
@@ -353,9 +376,9 @@ declare function assertIsPlainObject<T>(value:T,options?:OptionsAssertIs):assert
  * * ***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:**
+ *    - 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:
  *      - A custom error message (`options.message`), or
@@ -363,8 +386,9 @@ declare function assertIsPlainObject<T>(value:T,options?:OptionsAssertIs):assert
  * - **ℹ️ 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:
+ * @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.
@@ -385,7 +409,9 @@ declare function assertIsPlainObject<T>(value:T,options?:OptionsAssertIs):assert
  *
  * // ❌ Throws with custom message function and formatCase
  * assertIsString(42n, {
- *   message: ({ currentType, validType }) => `Expected ${currentType} but got (${currentType}).`,
+ *   message: ({ currentType, validType }) => {
+ *     return `Expected ${validType} but got (${currentType}).`;
+ *   },
  *   formatCase: "toKebabCase"
  * });
  * // ➔ TypeError: "Expected string but got (big-int)."

package/dist/assertions/index.js

@@ -1 +1 @@
-export{assertIsBigInt,assertIsNumber}from"../chunk-OGPPP2S3.js";export{assertIsArray}from"../chunk-ECRNH4FW.js";export{assertIsString}from"../chunk-T4CIAKEK.js";import"../chunk-QNKGP5DY.js";export{assertIsBoolean,assertIsPlainObject}from"../chunk-EW3I4O7X.js";
+export{assertIsBigInt,assertIsNumber}from"../chunk-3VA554KW.js";export{assertIsString}from"../chunk-SBKGWRS5.js";export{assertIsArray}from"../chunk-CKTLUNWX.js";import"../chunk-QNKGP5DY.js";export{assertIsBoolean,assertIsPlainObject}from"../chunk-CMW2TBOQ.js";

package/dist/chunk-2CQX5CBG.js

@@ -0,0 +1 @@
+import{isEmptyArray as e,isEmptyObject as r}from"./chunk-6JFCSH7J.js";import{noop as t}from"./chunk-YWHHVDT4.js";import{safeStableStringify as o}from"./chunk-PET42Z7W.js";import{isNonEmptyString as n,getPreciseType as s,isNull as a,isUndefined as c,isString as i,isArray as m,isObject as l,isNumber as u,isNaN as v,isError as f,assertIsPlainObject as N,hasOwnProp as d,isBoolean as p,isFunction as g}from"./chunk-CMW2TBOQ.js";var y=(e,r)=>{if(!n(e)||!n(r))throw new TypeError(`Parameter \`dateString\` and \`format\` must be of type \`string\` and not empty-string, but received: "['dateString': \`${s(e)}\` - (current value: \`${o(e)}\`), 'format': \`${s(r)}\` - (current value: \`${o(r)}\`)]".`);const t=e.split(/[-/]/).map(Number);if(3!==t.length||t.some(isNaN))return null;let a,c,i;if("DD/MM/YYYY"===r)[a,c,i]=t;else{if("MM/DD/YYYY"!==r)return null;[c,a,i]=t}c-=1;const m=new Date(i,c,a);return m.getFullYear()!==i||m.getMonth()!==c||m.getDate()!==a?null:m},b=(e={})=>{N(e,{message:({currentType:e,validType:r})=>`Second parameter (\`options\`) must be of type \`${r}\`, but received: \`${e}\`.`});const r=!!d(e,"convertBooleans")&&e.convertBooleans,o=!!d(e,"convertDates")&&e.convertDates,n=!!d(e,"convertNumbers")&&e.convertNumbers,a=!!d(e,"loggingOnFail")&&e.loggingOnFail,c=!!d(e,"removeEmptyArrays")&&e.removeEmptyArrays,i=!!d(e,"removeEmptyObjects")&&e.removeEmptyObjects,l=!!d(e,"removeNulls")&&e.removeNulls,u=!!d(e,"removeUndefined")&&e.removeUndefined,v=!!d(e,"strictMode")&&e.strictMode,f=!!d(e,"checkSymbols")&&e.checkSymbols,y=!!d(e,"convertNaN")&&e.convertNaN,b=d(e,"customDateFormats")?e.customDateFormats:[],E=d(e,"onError")?e.onError:t;if(!(p(r)&&p(o)&&p(n)&&p(y)&&p(f)&&p(a)&&p(c)&&p(i)&&p(l)&&p(u)&&p(v)&&m(b)&&g(E)))throw new TypeError(`Invalid \`options\` parameter (second argument): \`convertBooleans\`, \`convertDates\`, \`convertNumbers\`, \`loggingOnFail\`, \`removeEmptyArrays\`, \`removeEmptyObjects\`, \`removeNulls\`, \`removeUndefined\`, \`strictMode\` expected to be a \`boolean\` type, \`customDateFormats\` expected to be a \`array\` type and \`onError\` expected to be a \`void function\` type. But received: ['convertBooleans': \`${s(r)}\`, 'convertDates': \`${s(o)}\`, 'convertNumbers': \`${s(n)}\`, 'loggingOnFail': \`${s(a)}\`, 'removeEmptyArrays': \`${s(c)}\`, 'removeEmptyObjects': \`${s(i)}\`, 'removeNulls': \`${s(l)}\`, 'removeUndefined': \`${s(u)}\`, 'strictMode': \`${s(v)}\`, 'customDateFormats': \`${s(b)}\`, 'onError': \`${s(E)}\`].`);return{convertBooleans:r,convertDates:o,convertNumbers:n,convertNaN:y,loggingOnFail:a,removeEmptyArrays:c,removeEmptyObjects:i,removeNulls:l,removeUndefined:u,strictMode:v,customDateFormats:b,onError:E,checkSymbols:f}},E=(t,o={})=>{const n=b(o);if(a(t))return n.removeNulls?void 0:null;if(!c(t)){if(i(t)){const e=t.trim();if(n.convertNaN&&"NaN"===e)return NaN;if(n.convertNumbers&&!isNaN(Number(e)))return Number(e);if(n.convertBooleans){if("true"===e)return!0;if("false"===e)return!1}if(n.convertDates){if(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(e))return new Date(e);if(n.customDateFormats?.length)for(const r of n.customDateFormats){const t=y(e,r);if(t)return t}}return n.strictMode?void 0:e}if(m(t)){const r=t.map(e=>E(e,n)).filter(e=>!c(e));return n.removeEmptyArrays&&e(r)?void 0:r}if(l(t)){const e={};for(const r in t)if(Object.prototype.hasOwnProperty.call(t,r)){const o=E(t[r],n);c(o)||(e[r]=o)}return n.removeEmptyObjects&&r(e,{checkSymbols:n.checkSymbols})?void 0:e}return n.strictMode?void 0:t}n.removeUndefined},D=e=>{if(!i(e)&&!u(e))return 0;const r=String(e).trim().replace(/[^0-9]/g,"");return Number(r)||0};function h(e,r={}){if(a(e))return null;const t=b(r);if(t.convertNaN&&(v(e)||n(e)&&"NaN"===e))return NaN;if(t.convertNumbers&&!v(Number(e))&&u(D(e)))return Number(e);if(i(e))try{let r=function(e){const r=new Set(["\\",'"',"/","b","f","n","r","t","u"]);let t="",o=!1,n=!1,s=!1;for(let a=0;a<e.length;a++){const c=e[a];if(s)o?"'"===c?t+="'":r.has(c)?t+="\\"===c?"\\\\":'"'===c?'\\"':"\\"+c:t+="\\\\"+c:n?'"'===c?t+='\\"':r.has(c)?t+="\\"+c:t+="\\\\"+c:t+="\\"+c,s=!1;else if("\\"!==c){if(o||n){if(o){if("'"===c){t+='"',o=!1;continue}}else if(n&&'"'===c){t+='"',n=!1;continue}}else{if("'"===c){t+='"',o=!0;continue}if('"'===c){t+='"',n=!0;continue}}t+=c}else s=!0}return t}(e);r=t.removeUndefined?r.replace(/,\s*"[^"]*"\s*:\s*undefined(?=\s*[},])/g,"").replace(/"[^"]*"\s*:\s*undefined\s*(,)?/g,""):r.replace(/:\s*undefined(?=\s*[,}])/g,":null"),r=t.convertNaN?r.replace(/:\s*NaN(?=\s*[,}])/g,':"NaN"'):r.replace(/:\s*NaN(?=\s*[,}])/g,':"NaN"').replace(/,\s*"[^"]*"\s*:\s*NaN(?=\s*[},])/g,"").replace(/"[^"]*"\s*:\s*NaN\s*(,)?/g,""),r=r.replace(/,(\s*[}\]])/g,"$1");const o=JSON.parse(r);return E(o,t)}catch(e){return t.loggingOnFail&&console.error("Failed to parsing at `safeJsonParse`:",e),void t.onError(f(e)?new Error(e.message.replace(/^JSON\.parse:/,"Failed to parsing")):new Error(String(e)))}}export{E as cleanParsedData,D as extractDigits,y as parseCustomDate,h as safeJsonParse};