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

package/dist/formatting/index.d.ts

@@ -1,4 +1,4 @@
-import{O as OmitStrict}from'../omit-VvmIsZmX.js';import{Locale}from'date-fns/locale';import{FormatOptions}from'date-fns';import'../prettify-C4xLcYOP.js';import'../if-CvT4R7Kh.js';import'../type-data-DDs-u2kq.js';import'../never-BfayMBF9.js';type ValueFormatPhoneNumber=string|number|null;type FormatPhoneNumberProps={
+import{O as OmitStrict}from'../omit-VvmIsZmX.js';import{FormatOptions,Locale}from'date-fns';import{A as AnyString}from'../string-XA-til3C.js';import{P as Prettify}from'../prettify-C4xLcYOP.js';import'../if-CvT4R7Kh.js';import'../never-BfayMBF9.js';import'../type-data-DDs-u2kq.js';type ValueFormatPhoneNumber=string|number|null;type FormatPhoneNumberProps={
 /** @default " " */
 separator?:string;
 /** @default "" */
@@ -66,8 +66,7 @@ separator?:string;
 /** ---------------------------------------------------------------------------
 * * ***Prefix currency string.***
 * ---------------------------------------------------------------------------
-*
-* If `false`, rounds to integer.
+* Whether to show decimals. If `false`, decimals are truncated.
 *
 * *DefaultValue: `false`.*
 *
@@ -169,263 +168,318 @@ negativeFormat?:NegativeFormatOption;
 */
 indianFormat?:boolean;};
 /** -------------------------------------------------------
-* * ***Formats a number or messy currency string into a
-*   beautifully formatted currency string, with highly
-*   customizable separators, decimal control, rounding,
-*   currency symbols, and negative styling.***
+* * ***Utility: `formatCurrency`.***
 * -------------------------------------------------------
-*
-* ✅ Highlights:
-* - Accepts:
-*    - Pure numbers: `15300.95`
-*    - Messy currency strings from **any locale**:
-*      - `"Rp 15.000,21"` (Indonesian / Euro)
-*      - `"$12,345.60"` (US)
-*      - `"CHF 12'345.60"` (Swiss)
-*      - `"1,23,456.78"` (Indian)
+*  **Formats a number or messy currency string into a
+*  beautifully formatted currency string, with highly
+*  customizable separators, decimal control, rounding,
+*  currency symbols, and negative styling.**
+* - **✅ Highlights:**
+*    - ***Accepts:***
+*        - Pure numbers: `15300.95`.
+*        - Messy currency strings from **any locale**:
+*          - `"Rp 15.000,21"` ***(Indonesian / Euro)***.
+*          - `"$12,345.60"` ***(US)***.
+*          - `"CHF 12'345.60"` ***(Swiss)***.
+*          - `"1,23,456.78"` ***(Indian)***.
 * - Auto extracts numeric value with smart multi-locale parsing
-*   via `parseCurrencyString`.
-* - Handles:
-*    - Thousands separators: `.`, `,`, `'`, ` `
-*    - Decimal separators: `,`, `.`
-*    - Decimal suffix (eg. `".-"`, `" USD"`)
-*    - Currency prefix (eg. `"Rp "`, `"$ "`)
-*    - Rounding: `"round"`, `"ceil"`, `"floor"`, or truncate
-*    - Negative styling: dash `-`, brackets `( )`, absolute, or custom
+*   via ***{@link parseCurrencyString | `parseCurrencyString`}***.
+* - **Handles:**
+*    - Thousands separators: `.`, `,`, `'`, ` `.
+*    - Decimal separators: `,`, `.`.
+*    - Decimal suffix (eg. `".-"`, `" USD"`).
+*    - Currency prefix (eg. `"Rp "`, `"$ "`).
+*    - Rounding: `"round"`, `"ceil"`, `"floor"`, or truncate.
+*    - Negative styling: dash `-`, brackets `( )`, absolute, or custom.
 * - Strong type checks & clear errors for misconfigured options.
-*
-* ✅ How input is parsed:
-* - Removes all non-digit except `.`, `,`, `'` and spaces.
-* - Detects bracket negatives: `"(15.000,10)"` ➔ `-15000.10`
-* - Uses last `,` or `.` as decimal separator (others are thousands).
-* - Ignores currency symbols like `Rp`, `$` (must re-apply with `suffixCurrency`).
-*
-* ✅ Options:
+* - **✅ How input is parsed:**
+*    - Removes all non-digit except `.`, `,`, `'` and spaces.
+*    - Detects bracket negatives: `"(15.000,10)"` ➔ `-15000.10`.
+*    - Uses last `,` or `.` as decimal separator (others are thousands).
+*    - Ignores currency symbols like `Rp`, `$` (must re-apply with `suffixCurrency`).
+* - **ℹ️ Note:**
+*    - Always re-apply symbols via `suffixCurrency`.
+*    - `parseCurrencyString` smartly detects last decimal,
+*   so `"1.121.234,56"` and `"1,121,234.56"` both parsed correctly.
 * @param {string|number} value The input value to format, examples:
-*    - `"Rp 15.000,21"`
-*    - `"$12,345.60"`
-*    - `"CHF 12'345.60"`
-*    - `15300.95`
-*
+*    - `"Rp 15.000,21"`.
+*    - `"$12,345.60"`.
+*    - `"CHF 12'345.60"`.
+*    - `15300.95`.
 * @param {FormatCurrencyOptions} [options] Optional configuration object.
-*
-* @param {string} [options.separator] Thousands separator:
+* @param {FormatCurrencyOptions["separator"]} [options.separator] Thousands separator:
 *    - `{ separator: "." }` ➔ `1.000.000`.
 *    - ***DefaultValue: `"."`***.
-*
-* @param {string} [options.separatorDecimals] Decimal separator:
+* @param {FormatCurrencyOptions["separatorDecimals"]} [options.separatorDecimals] Decimal separator:
 *    - `{ separatorDecimals: "," }` ➔ `1.000,10`.
 *    - ***DefaultValue: `","`***.
-*
-* @param {string} [options.suffixCurrency] Prefix currency string:
+* @param {FormatCurrencyOptions["suffixCurrency"]} [options.suffixCurrency] Prefix currency string:
 *    - Does **not auto-keep input symbols**.
 *    - Must set manually e.g: `{ suffixCurrency: "Rp " }`.
 *        - `{ suffixCurrency: "Rp " }` ➔ `Rp 1.000`.
 *    - ***DefaultValue: `""`***.
-*
-* @param {boolean} [options.decimal] Show decimals:
-*    - If `false`, rounds to integer.
+* @param {FormatCurrencyOptions["decimal"]} [options.decimal] Whether to show decimals. If `false`, decimals are truncated:
+*    - If `false`, cut the decimal.
 *    - ***DefaultValue: `false`***.
-*
-* @param {number} [options.totalDecimal] Total decimal digits:
+* @param {FormatCurrencyOptions["totalDecimal"]} [options.totalDecimal] Total decimal digits:
 *    - If `decimal: true` & `roundedDecimal: false`, simply cuts.
 *    - ***DefaultValue: `2`***.
-*
-* @param {string} [options.suffixDecimal] Text appended after decimals:
+* @param {FormatCurrencyOptions["separatorDecimals"]} [options.suffixDecimal] Text appended after decimals:
 *    - E.g: (`".-"`, `" USD"`).
 *    - Example 1: `".-"` ➔ `1.000,00.-`.
 *    - Example 2: `" USD"` ➔ `1.000,00 USD`.
 *    - ***DefaultValue: `""`***.
-*
-* @param {boolean} [options.endDecimal] Actually append `suffixDecimal`:
+* @param {FormatCurrencyOptions["endDecimal"]} [options.endDecimal] Actually append `suffixDecimal`:
 *    - ***DefaultValue: `true`***.
-*
-* @param {"round"|"ceil"|"floor"|false} [options.roundedDecimal] Rounding mode:
-*    - `"round"` ➔ nearest
-*    - `"ceil"` ➔ always up
-*    - `"floor"` ➔ always down
-*    - `false` ➔ truncate
+* @param {FormatCurrencyOptions["roundedDecimal"]} [options.roundedDecimal] Rounding mode:
+*    - `"round"` ➔ nearest.
+*    - `"ceil"` ➔ always up.
+*    - `"floor"` ➔ always down.
+*    - `false` ➔ truncate.
 *    - ***DefaultValue: `"round"`***.
-*
-* @param {"dash"|"brackets"|"abs"|{style?, space?, custom?}} [options.negativeFormat] How to format negatives:
-*    - `"dash"` ➔ `-15.000`
-*    - `"brackets"` ➔ `(15.000)`
-*    - `"abs"` ➔ `15.000` (always positive)
-*    - Or object:
-*         `{
-*            style: "dash"|"brackets"|"abs",
-*            space: true|false,
-*            custom: (formatted) => string
-*         }`.
+* @param {FormatCurrencyOptions["negativeFormat"]} [options.negativeFormat]
+* - How to format negatives:
+*    - `"dash"` ➔ `-15.000`.
+*    - `"brackets"` ➔ `(15.000)`.
+*    - `"abs"` ➔ `15.000` (always positive).
+*    - Or object: `{ style: "dash"|"brackets"|"abs", space: true|false, custom: (formatted) => string }`.
 *    - ***DefaultValue: `"dash"`.***
-*
-* @param {boolean} [options.indianFormat] Applies Indian Format:
+* @param {FormatCurrencyOptions["indianFormat"]} [options.indianFormat] Applies Indian Format:
 *    - If `true`, formats as Indian: `12,34,567`.
 *    - Also forces `separator: ","`, `separatorDecimals: "."`.
-*
 * @returns {string} Nicely formatted currency string, examples:
-*    - `"15.000,10"`
-*    - `"Rp 15.000,10.-"`
-*    - `"15'000.10 USD"`
-*    - `"12,34,567.89"`
-*
+*    - `"15.000,10"`.
+*    - `"Rp 15.000,10.-"`.
+*    - `"15'000.10 USD"`.
+*    - `"12,34,567.89"`.
 * @throws {TypeError} Will throw TypeError If:
-*    - `value` is not string or number
-*    - cannot parse to valid number
-*    - options have invalid types
+*    - `value` is not string or number.
+*    - cannot parse to valid number.
+*    - options have invalid types.
+* @example
+* // --- Number input (default, decimals off) ---
+* formatCurrency(1234567.89);
+* // ➔ "1.234.567"
+*
+* // --- Decimals enabled ---
+* formatCurrency(1234567.89, { decimal: true });
+* // ➔ "1.234.567,89"
+*
+* // --- Indian format ---
+* formatCurrency(1234567.89, { decimal: true, indianFormat: true });
+* // ➔ "12,34,567.89"
+*
+* // --- String input (Indonesian style) ---
+* formatCurrency("Rp 15.000,21", { decimal: true });
+* // ➔ "15.000,21"
+*
+* // --- String input (US style) ---
+* formatCurrency("$12,345.60", { decimal: true });
+* // ➔ "12.345,60"
+*
+* // --- String input (Swiss style) ---
+* formatCurrency("CHF 12'345.60", { decimal: true });
+* // ➔ "12'345,60"
+*
+* // --- String input (Indian style) ---
+* formatCurrency("1,23,456.78", { decimal: true, indianFormat: true });
+* // ➔ "12,34,567.78"
+*
+* // --- Negative numbers (dash) ---
+* formatCurrency(-1234.56, { decimal: true });
+* // ➔ "-1.234,56"
+*
+* // --- Negative numbers (brackets) ---
+* formatCurrency(-1234.56, {
+*   decimal: true,
+*   negativeFormat: "brackets"
+* });
+* // ➔ "(1.234,56)"
 *
-* ---
+* // --- Negative numbers (custom object style) ---
+* formatCurrency(-1234.56, {
+*   decimal: true,
+*   negativeFormat: { style: "brackets", space: true }
+* });
+* // ➔ "( 1.234,56 )"
 *
-* ***✅ Notes:***
-* - Always re-apply symbols via `suffixCurrency`.
-* - `parseCurrencyString` smartly detects last decimal,
-*   so `"1.121.234,56"` and `"1,121,234.56"` both parsed correctly.
+* // --- Negative numbers (custom function) ---
+* formatCurrency(-1234.56, {
+*   decimal: true,
+*   negativeFormat: { custom: (val) => `NEGATIVE[${val}]` }
+* });
+* // ➔ "NEGATIVE[1.234,56]"
+*
+* // --- With prefix currency ---
+* formatCurrency(1234.56, {
+*   decimal: true,
+*   suffixCurrency: "Rp "
+* });
+* // ➔ "Rp 1.234,56"
+*
+* // --- With suffix decimal ---
+* formatCurrency(1234.56, {
+*   decimal: true,
+*   suffixDecimal: ".-"
+* });
+* // ➔ "1.234,56.-"
+*
+* // --- With suffix currency + suffix decimal ---
+* formatCurrency(1234.56, {
+*   decimal: true,
+*   suffixCurrency: "Rp ",
+*   suffixDecimal: ".-"
+* });
+* // ➔ "Rp 1.234,56.-"
+*
+* // --- Custom separators ---
+* formatCurrency(1234567.89, {
+*   decimal: true,
+*   separator: "'",
+*   separatorDecimals: "."
+* });
+* // ➔ "1'234'567.89"
+*
+* // --- Rounding: ceil ---
+* formatCurrency(1234.561, {
+*   decimal: true,
+*   roundedDecimal: "ceil"
+* });
+* // ➔ "1.234,57"
+*
+* // --- Rounding: floor ---
+* formatCurrency(1234.569, {
+*   decimal: true,
+*   roundedDecimal: "floor"
+* });
+* // ➔ "1.234,56"
+*
+* // --- Rounding: truncate (false) ---
+* formatCurrency(1234.569, {
+*   decimal: true,
+*   roundedDecimal: false
+* });
+* // ➔ "1.234,56"
+*
+* // --- Force no decimals (decimal: false) ---
+* formatCurrency(1234.567, { decimal: false });
+* // ➔ "1.235"
+*
+* // --- Edge case: messy input with dots & commas ---
+* formatCurrency("1.121.234,561", {
+*   decimal: true,
+*   totalDecimal: 2,
+*   roundedDecimal: "ceil",
+*   suffixCurrency: "Rp ",
+*   negativeFormat: { style: "brackets" }
+* });
+* // ➔ "(Rp 1.121.234,57)"
+*
+* // --- Edge case: integer string input ---
+* formatCurrency("1.121.234", {
+*   decimal: true,
+*   suffixCurrency: "Rp ",
+*   roundedDecimal: "ceil"
+* });
+* // ➔ "Rp 1.121.234,00"
 */
 declare const formatCurrency:(value:string|number,options?:FormatCurrencyOptions)=>string;
 /** ----------------------------------------------------------
-* * ***Formats a number or numeric string by adding a custom separator
-* every three digits (thousands separator), and intelligently
-* flips the decimal separator according to the chosen separator.***
+* * ***Utility: `formatNumber`.***
 * ----------------------------------------------------------
-*
-* - Converts a number to string before formatting.
-* - Defaults to using `,` as the thousands separator.
-* - If `.` is used as the separator, the decimal will automatically become `,`, and vice versa.
-* - Handles input with existing formatting (e.g. "1,234,567.89") and normalizes it.
-* - Supports custom separators, including spaces.
-* - Preserves decimals even if more than 2 digits.
-*
-* @param {string | number} value - The numeric value or string to format.
-*   Can be plain numbers, or already formatted strings like "1,234,567.89".
-* @param {string} [separator=","] - The thousands separator to use.
-*   Examples: "," (default), ".", " ", etc.
-*
+* **Formats a number or numeric string by adding a custom separator
+* every three digits (thousands separator), and intelligently flips
+* the decimal separator according to the chosen separator.**
+* - **Features:**
+*    - Converts a number to string before formatting.
+*    - Defaults to using `,` as the thousands separator.
+*    - If `.` is used as the separator, the decimal will automatically
+*      become `,`, and vice versa.
+*    - Handles input with existing formatting (e.g. "1,234,567.89") and normalizes it.
+*    - Supports custom separators, including spaces.
+*    - Preserves decimals even if more than 2 digits.
+* @param {string | number} value - The numeric value or string to format, can be plain numbers, or already formatted strings like `"1,234,567.89"`.
+* @param {string} [separator=","] - The thousands separator to use, examples: `","` ***(default)***, `"."`, `" "`, etc.
 * @returns {string} The formatted string with thousands separators and
 *   appropriate decimal separator.
-*
 * @throws {TypeError} If `value` is not a string or number,
 * or `separator` is not a string.
-*
 * @example
 * formatNumber(1000000);
-* // → "1,000,000"
-*
+* // ➔ "1,000,000"
 * formatNumber("987654321");
-* // → "987,654,321"
-*
+* // ➔ "987,654,321"
 * formatNumber(1234567.89);
-* // → "1,234,567.89"
-*
+* // ➔ "1,234,567.89"
 * formatNumber("1234567,89");
-* // → "1,234,567.89"
-*
+* // ➔ "1,234,567.89"
 * formatNumber("1234567.892");
-* // → "1,234,567.892"
-*
+* // ➔ "1,234,567.892"
 * formatNumber("1234567.89", ".");
-* // → "1.234.567,89"
-*
+* // ➔ "1.234.567,89"
 * formatNumber("1234567,89", ",");
-* // → "1,234,567.89"
-*
+* // ➔ "1,234,567.89"
 * formatNumber("987654321", " ");
-* // → "987 654 321"
-*
+* // ➔ "987 654 321"
 * formatNumber("1,234,567.89");
-* // → "1,234,567.89"
-*
+* // ➔ "1,234,567.89"
 * formatNumber("1.234.567,89", ",");
-* // → "1,234,567.89"
-*
+* // ➔ "1,234,567.89"
 * formatNumber("1.234.567,893", ".");
-* // → "1.234.567,893"
-*
+* // ➔ "1.234.567,893"
 * formatNumber("1234.56", ".");
-* // → "1.234,56"
-*
+* // ➔ "1.234,56"
 * formatNumber("1234,56", ",");
-* // → "1,234.56"
-*
+* // ➔ "1,234.56"
 */
 declare const formatNumber:(value:string|number,separator?:string)=>string;
 /** -------------------------------------------------------
-* * ***Formats a phone number into a customizable local or international style.***
+* * ***Utility: `formatPhoneNumber`.***
 * -------------------------------------------------------
-*
-* Can also:
-* - Return only digits (`takeNumberOnly`).
-* - Check validity (`checkValidOnly`) using a regex for international-style phone numbers.
-*
-* Validation (`checkValidOnly: true`)
-* Valid if:
-* - Only contains digits, optional leading `+`, spaces, parentheses `()`, hyphens `-`, or dots `.`.
-* - Digits-only length < 24.
-*
-* Example:
+* **Formats a phone number into a customizable local or international style.**
+* - **Can also:**
+*    - Return only digits (`takeNumberOnly`).
+*    - Check validity (`checkValidOnly`) using a regex for international-style phone numbers.
+* - **Validation (`checkValidOnly: true`):**
+*    - ***Valid if:***
+*       - Only contains digits, optional leading `+`, spaces, parentheses `()`,
+*         hyphens `-`, or dots `.`.
+*       - Digits-only length < 24.
+* @example
 * ```js
 * formatPhoneNumber("081234567890")
-* // => "0812 3456 7890"
-* ```
-*
-* Example:
-* ```js
+* // ➔ "0812 3456 7890"
 * formatPhoneNumber("(0812) 3456-7890", { takeNumberOnly: true })
-* // => "081234567890"
-* ```
-*
-* Example:
-* ```js
+* // ➔ "081234567890"
 * formatPhoneNumber("(0812) 3456-7890", { checkValidOnly: true })
-* // => true
-* ```
-*
-* Example:
-* ```js
+* // ➔ true
 * formatPhoneNumber("+6281234567890", { checkValidOnly: true })
-* // => true
-* ```
-*
-* Example:
-* ```js
+* // ➔ true
 * formatPhoneNumber("+1 (800) 123-4567", { checkValidOnly: true })
-* // => true
+* // ➔ true
 * formatPhoneNumber("+44 20 7946 0958", { checkValidOnly: true })
-* // => true
-* ```
-*
-* Example:
-* ```js
+* // ➔ true
 * formatPhoneNumber("0812-3456-7890", { checkValidOnly: true })
-* // => true
+* // ➔ true
 * formatPhoneNumber("(0812) 3456 7890", { checkValidOnly: true })
-* // => true
+* // ➔ true
 * formatPhoneNumber("0812 3456 7890", { checkValidOnly: true })
-* // => true
-* ```
-*
-* Example:
-* ```js
+* // ➔ true
 * formatPhoneNumber("+62abc123", { checkValidOnly: true })
-* // => false
+* // ➔ false
 * formatPhoneNumber("0812-3456-hello", { checkValidOnly: true })
-* // => false
+* // ➔ false
 * formatPhoneNumber("+62 123456789012345678901234", { checkValidOnly: true })
-* // => false
+* // ➔ false
 * formatPhoneNumber("++6281234567890", { checkValidOnly: true })
-* // => false
+* // ➔ false
 * formatPhoneNumber("invalid@@@", { checkValidOnly: true })
-* // => false
-* ```
-*
-* Example:
-* ```js
+* // ➔ false
 * formatPhoneNumber("+62.812.3456.7890", { checkValidOnly: true })
-* // => true
+* // ➔ true
 * formatPhoneNumber("+62(812)3456-7890", { checkValidOnly: true })
-* // => true
+* // ➔ true
 * ```
-*
-* Example:
 * ```js
 * formatPhoneNumber("081234567890", {
 *   separator: "-",
@@ -433,30 +487,28 @@ declare const formatNumber:(value:string|number,separator?:string)=>string;
 *   openingNumberCountry: "(",
 *   closingNumberCountry: ")",
 * })
-* // => "(+44) 8123-4567-890"
+* // ➔ "(+44) 8123-4567-890"
 * ```
-*
 * @throws {TypeError} If `value` is not string, number, null or undefined.
 * @throws {TypeError} If `options` is not an object or contains wrong types.
 *
-* @overload
-* @param value The phone number input (string or number).
-* @param options With `checkValidOnly: true`.
-* @returns A boolean indicating whether the input is a valid phone number.
+* @overload Return a boolean if options With `checkValidOnly: true`.
+* @param {ValueFormatPhoneNumber} [value] The phone number input (string or number).
+* @param {FormatPhoneNumberPropsBoolean} [options] With `checkValidOnly: true`.
+* @returns {boolean} A boolean indicating whether the input is a valid phone number.
 *
-* @overload
-* @param value The phone number input (string or number).
-* @param options With `takeNumberOnly: true`.
-* @returns A string of digits only.
+* @overload Return a string of digits only, if options With `takeNumberOnly: true`.
+* @param {ValueFormatPhoneNumber} [value] The phone number input (string or number).
+* @param {FormatPhoneNumberPropsTransform} [options] With `takeNumberOnly: true`.
+* @returns {string} A string of digits only.
 *
-* @overload
-* @param value The phone number input (string or number).
-* @param options Options to customize format output (country code, separator, etc).
-* @returns A formatted phone number string.
+* @overload Return a formatted phone number string, if options Options to customize format output (country code, separator, etc).
+* @param {ValueFormatPhoneNumber} [value] The phone number input (string or number).
+* @param {FormatPhoneNumberPropsString} [options] Options to customize format output (country code, separator, etc).
+* @returns {string} A formatted phone number string.
 */
 declare function formatPhoneNumber(value?:ValueFormatPhoneNumber,options?:FormatPhoneNumberPropsString):string;declare function formatPhoneNumber(value?:ValueFormatPhoneNumber,options?:FormatPhoneNumberPropsBoolean):boolean;declare function formatPhoneNumber(value?:ValueFormatPhoneNumber,options?:FormatPhoneNumberPropsTransform):string;
-/**
-* -------------------------------------------------------------
+/** -------------------------------------------------------------
 * * ***Supported IETF BCP-47 locale codes for Intl API.***
 * -------------------------------------------------------------
 *
@@ -474,258 +526,268 @@ declare function formatPhoneNumber(value?:ValueFormatPhoneNumber,options?:Format
 * new Intl.DateTimeFormat(locale).format(new Date());
 */
 type SupportedLocales="en-US"|"en-GB"|"en-AU"|"en-CA"|"en-NZ"|"en-ZA"|"en-IN"|"en-IE"|"en-SG"|"en-HK"|"en-PH"|"en-MY"|"en-PK"|"en-KE"|"en-TZ"|"en-NG"|"en-LK"|"en-BW"|"en-ZM"|"id-ID"|"ms-MY"|"th-TH"|"vi-VN"|"tl-PH"|"ms-BN"|"zh-CN"|"zh-HK"|"zh-TW"|"zh-SG"|"zh-MO"|"ja-JP"|"ko-KR"|"fr-FR"|"fr-CA"|"fr-BE"|"fr-CH"|"fr-LU"|"fr-MA"|"fr-SN"|"fr-CM"|"fr-CI"|"fr-HT"|"fr-DZ"|"fr-TN"|"fr-ML"|"fr-NC"|"fr-PF"|"fr-GP"|"fr-MQ"|"fr-GF"|"de-DE"|"de-AT"|"de-CH"|"de-LU"|"de-LI"|"es-ES"|"es-MX"|"es-AR"|"es-CL"|"es-CO"|"es-PE"|"es-UY"|"es-VE"|"es-CR"|"es-EC"|"es-GT"|"es-HN"|"es-NI"|"es-PA"|"es-PR"|"es-SV"|"es-BO"|"es-PY"|"es-DO"|"es-CU"|"es-GQ"|"pt-BR"|"pt-PT"|"pt-MZ"|"pt-AO"|"pt-GW"|"pt-CV"|"pt-ST"|"it-IT"|"it-CH"|"it-SM"|"it-VA"|"nl-NL"|"nl-BE"|"nl-SR"|"nl-AW"|"nl-CW"|"ru-RU"|"uk-UA"|"kk-KZ"|"uz-UZ"|"ky-KG"|"tt-RU"|"ba-RU"|"cv-RU"|"sah-RU"|"pl-PL"|"cs-CZ"|"sk-SK"|"hu-HU"|"sl-SI"|"sv-SE"|"da-DK"|"no-NO"|"fi-FI"|"is-IS"|"ro-RO"|"bg-BG"|"hr-HR"|"sr-RS"|"mk-MK"|"bs-BA"|"me-ME"|"sq-AL"|"sq-XK"|"el-GR"|"el-CY"|"tr-TR"|"tr-CY"|"he-IL"|"ar-SA"|"ar-AE"|"ar-EG"|"ar-MA"|"ar-JO"|"ar-LB"|"ar-QA"|"ar-KW"|"ar-OM"|"ar-BH"|"ar-IQ"|"ar-LY"|"ar-TN"|"ar-YE"|"ar-SY"|"ar-PS"|"ar-SD"|"ar-DZ"|"ar-MR"|"ar-DJ"|"ar-SO"|"lt-LT"|"lv-LV"|"et-EE"|"hi-IN"|"bn-BD"|"pa-IN"|"ta-IN"|"te-IN"|"ml-IN"|"gu-IN"|"kn-IN"|"mr-IN"|"or-IN"|"as-IN"|"ne-IN"|"fa-IR"|"ur-PK"|"ps-AF"|"dv-MV"|"sw-KE"|"sw-TZ"|"zu-ZA"|"af-ZA"|"xh-ZA"|"ss-SZ"|"ts-ZA"|"tn-BW"|"ny-MW"|"lo-LA"|"mt-MT"|"ga-IE"|"cy-GB"|"ne-NP"|"si-LK"|"am-ET"|"om-ET"|"ti-ER"|"km-KH"|"my-MM"|"mn-MN"|"tg-TJ"|"tk-TM"|"hy-AM"|"ka-GE"|"az-AZ"|"be-BY"|"mo-MD"|"ro-MD"|"ht-HT"|"jw-ID"|"su-ID"|"to-TO"|"sm-WS"|"mi-NZ"|"bi-VU"|"fj-FJ"|"ty-PF"|"pau-PW"|"niu-NU"|"ck-CK"|"rw-RW"|"ln-CD"|"kg-CD"|"ha-NE"|"yo-NG"|"ig-NG"|"ak-GH"|"lg-UG"|"bo-CN"|"dz-BT"|"iu-CA"|"kl-GL"|"cv-RU"|"pap-AW"|"chr-US"|"haw-US"|"gv-IM"|"gd-GB"|"br-FR"|"co-FR"|"rm-CH"|"wa-BE"|"lb-LU"|"fur-IT"|"sc-IT"|"vec-IT"|"nap-IT"|"gsw-CH"|"rha-CH"|({}& string);
-/** ----------------------------------------------------------
-* * ***Formats a date and time into a custom string format.***
-* ----------------------------------------------------------
+/** ----------------------------------------------------------------
+* * ***Options for formatting dates with `Intl.DateTimeFormat`.***
+* ----------------------------------------------------------------
 *
-* - Supports only `YYYY`, `MM`, `DD`, `hh`, `mm`, and `ss` as placeholders.
-* - Uses a simple string replace (no locale).
-* - Returns `null` if the date is invalid or not provided.
-* - Defaults to `"YYYY-MM-DD hh:mm:ss"` format if none is specified.
+* Extends the native
+* **{@link Intl.DateTimeFormatOptions | `Intl.DateTimeFormatOptions`}** with
+* an additional `locale` property that is validated against **{@link SupportedLocales | `SupportedLocales`}**.
 *
-* @param {string | Date | null} [date] - The date to format.
-* @param {string} [format="YYYY-MM-DD hh:mm:ss"] - The desired date format.
-* @returns {string | null} The formatted date string or `null` if invalid.
+*/
+type FormatDateIntlOptions=Intl.DateTimeFormatOptions &{
+/** ------------------------------------------------------------
+* * Locale for date formatting.
+* ------------------------------------------------------------
+*
+* - Must be a valid [***BCP-47 locale***](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument),
+*   validated against {@link SupportedLocales | **`SupportedLocales`**}.
+* - If `locale` is `undefined` or an empty string (after trimming),
+*   it will **default to `"en-US"`**.
 *
+* @default "en-US"
 * @example
-* formatDateTime(new Date());
-* // => "2024-02-09 14:30:45" (example output with current time)
+* { year: "numeric", month: "long" }
+* // Unset locale, default locale ➔ "en-US"
+* { locale: "fr-FR", ...}
+* // Explicit locale
+* { locale: "   ", ...}
+* // Empty string locale ➔ defaults to "en-US"
+* { locale: " en-GB ", ...}
+* // Value will trimming ➔ "en-GB"
 *
-* formatDateTime("2023-07-01T14:30:45");
-* // => "2023-07-01 14:30:45"
+*/
+locale?:SupportedLocales;};
+/** ----------------------------------------------------------------------
+* * ***Options for formatting dates with `date-fns/format`.***
+* ----------------------------------------------------------------------
 *
-* formatDateTime("2023-07-01T14:30:45", "DD/MM/YYYY");
-* // => "01/07/2023"
+* Extends the base **{@link FormatOptions | *`FormatOptions`*}** (without **`locale`**) with extra options
+* for handling output formatting, localization, and parsing non-standard inputs.
 *
-* formatDateTime("2023-07-01T14:30:45", "YYYY/MM/DD hh-mm-ss");
-* // => "2023/07/01 14-30-45"
+*/
+type FormatDateFnsOptions=Prettify<OmitStrict<FormatOptions,"locale",true,false>&{
+/** ------------------------------------------------------------
+* * Output format string passed to `date-fns/format`.
+* ------------------------------------------------------------
 *
-* formatDateTime("2023-07-01T14:30:45", "hh:mm");
-* // => "14:30"
+* - Determines how the date will be rendered.
+* - Uses the full power of `date-fns` tokens.
 *
-* formatDateTime("2023-07-01T14:30:45", "DATE: YYYY.MM.DD");
-* // => "DATE: 2023.07.01"
+* ***Default Value***: `"dd MMM yyyy - HH:mm:ss"`.
+* @example
+* "dd MMMM yyyy, HH:mm:ss" // ➔ "03 September 2025, 10:25:42"
+* @default "dd MMM yyyy - HH:mm:ss"
+*/
+format?:string;
+/** ------------------------------------------------------------
+* * Locale used for formatting.
+* ------------------------------------------------------------
 *
-* formatDateTime("2023-07-01T14:30:45", "Year: YYYY, Time: hh:mm:ss");
-* // => "Year: 2023, Time: 14:30:45"
+* - If `string`: only accepts `"id"` (Indonesian) or `"en"` (English) - **(default)**.
+* - If `Locale`: accepts a locale object from `date-fns/locale`.
 *
-* formatDateTime("2023-07-01T14:30:45", "YYYY-MM");
-* // => "2023-07"
+* ***Default Value***: `"en"`.
+* ```ts
+* import { ar } from "date-fns/locale";
 *
-* formatDateTime("2023-07-01T14:30:45", "YYYYYYYY");
-* // => "20232023"
+* formatDateFns(new Date(), {
+*   locale: ar,
+*   format: "dd MMMM yyyy"
+* });
+* // ➔ "03 سبتمبر 2025"
+* ```
+* @default "en"
+*/
+locale?:"id"|"en"|AnyString|Locale;
+/** ------------------------------------------------------------
+* * Input locale used when parsing non-standard string dates.
+* ------------------------------------------------------------
 *
-* formatDateTime("2023-07-01T14:30:45", "hh:mm:ss:ss");
-* // => "14:30:45:45"
+* - Required if `date` is a **localized string**
+*   (e.g. `"03 Mei 2025 10:25:42"` in Indonesian).
+* - Same accepted types as `locale` parameter.
 *
-* formatDateTime("invalid-date");
-* // => null
+* ***Default Value***: `"en"`.
+* ```ts
+* import { ar } from "date-fns/locale";
 *
-* formatDateTime(null);
-* // => null
+* formatDateFns("03 مايو 2025 10:25:42", {
+*   inputFormat: "dd MMMM yyyy HH:mm:ss",
+*   inputLocale: ar,
+*   format: "PPpp"
+* });
+* // ➔ "May 3, 2025 at 10:25:42 AM"
+* ```
+* @default "en"
+*/
+inputLocale?:"id"|"en"|AnyString|Locale;
+/** ------------------------------------------------------------
+* * Input format string for parsing non-ISO string dates.
+* ------------------------------------------------------------
 *
+* - Required if `date` is **not ISO-8601** and not a native `Date`.
+* - Works together with `inputLocale` parameter.
+*
+* ***Default Value***: `undefined`.
+* @default undefined
+* @example
+* "dd MMMM yyyy HH:mm:ss" // ➔ "03 May 2025 10:25:42"
+*/
+inputFormat?:string;}>;
+/** ----------------------------------------------------------
+* * ***Utility: `formatDateTime`.***
+* ----------------------------------------------------------
+* **Formats a date and time into a custom string format.**
+*  - **Features:**
+*    - Supports only `YYYY`, `MM`, `DD`, `hh`, `mm`, and `ss` as placeholders.
+*    - Uses a simple string replace (no locale).
+*    - Returns `null` if the date is invalid or not provided.
+*    - Defaults to `"YYYY-MM-DD hh:mm:ss"` format if none is specified.
+* @param {string | Date | null| undefined} date - The date to format.
+* @param {string} [format="YYYY-MM-DD hh:mm:ss"] - The desired date format, if format is `null` or `undefined` will force to defaultValue, defaultValue: `"YYYY-MM-DD hh:mm:ss"`.
+* @returns {string | null} The formatted date string or `null` if invalid.
+* @example
+* formatDateTime(new Date());
+* // ➔ "2024-02-09 14:30:45" (example output with current time)
+* formatDateTime("2023-07-01T14:30:45");
+* // ➔ "2023-07-01 14:30:45"
+* formatDateTime("2023-07-01T14:30:45", "DD/MM/YYYY");
+* // ➔ "01/07/2023"
+* formatDateTime("2023-07-01T14:30:45", "YYYY/MM/DD hh-mm-ss");
+* // ➔ "2023/07/01 14-30-45"
+* formatDateTime("2023-07-01T14:30:45", "hh:mm");
+* // ➔ "14:30"
+* formatDateTime("2023-07-01T14:30:45", "DATE: YYYY.MM.DD");
+* // ➔ "DATE: 2023.07.01"
+* formatDateTime("2023-07-01T14:30:45", "Year: YYYY, Time: hh:mm:ss");
+* // ➔ "Year: 2023, Time: 14:30:45"
+* formatDateTime("2023-07-01T14:30:45", "YYYY-MM");
+* // ➔ "2023-07"
+* formatDateTime("2023-07-01T14:30:45", "YYYYYYYY");
+* // ➔ "20232023"
+* formatDateTime("2023-07-01T14:30:45", "hh:mm:ss:ss");
+* // ➔ "14:30:45:45"
+* formatDateTime("invalid-date");
+* // ➔ null
+* formatDateTime(null);
+* // ➔ null
 * formatDateTime(undefined);
-* // => null
+* // ➔ null
 */
-declare const formatDateTime:(date?:string|Date|null,
-/** @default "YYYY-MM-DD hh:mm:ss" */
-format?:string)=>string|null;
+declare const formatDateTime:(date:string|Date|null|undefined,format?:string)=>string|null;
 /** ----------------------------------------------------------
-* * ***Formats a date using the `Intl.DateTimeFormat` API.***
+* * ***Utility: `formatDateIntl`.***
 * ----------------------------------------------------------
-*
-* - Supports custom locales (type-safe `SupportedLocales`).
-* - Accepts additional `Intl.DateTimeFormatOptions` like `timeZone`, `hour12`, etc.
-* - Defaults to `"en-US"` if `locale` is not provided or is an empty string.
-* - Returns `null` if the date is invalid, not provided, or options are invalid.
-*
-* @param {string | Date | null | undefined} [date] - The date to format.
-*   Can be a `Date` object or an ISO string. If invalid or not provided, returns `null`.
-*
-* @param {Intl.DateTimeFormatOptions & { locale?: SupportedLocales | SupportedLocales[] }} [options]
+* **Formats a date using the `Intl.DateTimeFormat` API.**
+*  - **Features:**
+*    - Supports custom locales (type-safe `SupportedLocales`).
+*    - Accepts additional `Intl.DateTimeFormatOptions` like `timeZone`, `hour12`, etc.
+*    - Defaults to `"en-US"` if `locale` is not provided or is an empty string.
+*    - Returns `null` if the date is invalid, not provided, or options are invalid.
+* @param {string | Date | null | undefined} date The date to format.
+*    - Can be a `Date` object or an ISO string.
+*    - If invalid or not provided, returns `null`.
+* @param {FormatDateIntlOptions} [options]
 *   - Optional formatting options for `Intl.DateTimeFormat`.
 *   - Use `locale` to specify the language & region format.
-*
 * @returns {string | null}
 *   - Formatted date string.
 *   - Returns `null` if date is invalid or options are of wrong type.
-*
 * @example
 * formatDateIntl(new Date());
-* // => "7/14/2025"
-*
+* // ➔ "7/14/2025"
 * formatDateIntl("2025-07-14T00:00:00Z", { locale: "fr-FR", dateStyle: "long" });
-* // => "14 juillet 2025"
-*
+* // ➔ "14 juillet 2025"
 * formatDateIntl(null);
-* // => null
-*
+* // ➔ null
 * formatDateIntl(new Date(), { timeZone: "UTC", hour: "2-digit", minute: "2-digit" });
-* // => "01:30 AM"
+* // ➔ "01:30 AM"
 */
-declare const formatDateIntl:(date?:string|Date|null,options?:Intl.DateTimeFormatOptions &{locale?:SupportedLocales|SupportedLocales[];})=>string|null;
+declare const formatDateIntl:(date:string|Date|null|undefined,options?:FormatDateIntlOptions)=>string|null;
 /** ----------------------------------------------------------
-* * ***Formats a date into a human-readable string using `date-fns`.***
+* * ***Utility: `formatDateFns`.***
 * ----------------------------------------------------------
-*
-* - Supports custom output formats using `date-fns/format`.
-* - Can parse localized non-ISO strings via `inputFormat` & `inputLocale`.
-* - Supports `locale` as `"id"`, `"en"` or `date-fns` `Locale` objects (like `id` or `enUS`).
-* - Returns `null` if the date is invalid, not provided, or parsing fails.
-*
-* @param {string | Date | null} [date] - The date input to format. Can be:
+* Formats a date into a human-readable string using `date-fns`.
+*  - **Features:**
+*    - Supports custom output formats using `date-fns/format`.
+*    - Can parse localized non-ISO strings via `inputFormat` & `inputLocale`.
+*    - Supports `locale` as `"id"`, `"en"` or `date-fns` `Locale` objects (like `id` or `enUS`).
+*    - Returns `null` if the date is invalid, not provided, or parsing fails.
+* @param {string | Date | null | undefined} date - The date input to format. Can be:
 *   - A `Date` object
 *   - An ISO string (e.g. `"2024-01-01T12:00:00Z"`)
 *   - A localized string (requires `inputFormat` + `inputLocale`)
-*
-* @param {object} [options] - Options for formatting and parsing.
-*
-* @param {string} [options.format="dd MMM yyyy - HH:mm:ss"]
+* @param {FormatDateFnsOptions} [options] - Options for formatting and parsing.
+* @param {FormatDateFnsOptions["format"]} [options.format="dd MMM yyyy - HH:mm:ss"]
 *   The output format string (passed to `date-fns/format`).
-*   E.g. `"dd MMMM yyyy, HH:mm:ss" => "14 Juli 2025, 17:25:42"`
-*
-* @param {"id" | "en" | (string & {}) | Locale} [options.locale="id"]
+*   E.g. `"dd MMMM yyyy, HH:mm:ss" ➔ "14 Juli 2025, 17:25:42"`
+* @param {FormatDateFnsOptions["locale"]} [options.locale="id"]
 *   The output locale. If string, only `"id"` (Indonesian) or `"en"` (English)
 *   is recognized. Or you can pass a `date-fns` `Locale` object.
-*   Example:
+*   - Example:
 *   ```ts
 *     import { ar } from "date-fns/locale";
 *     formatDateFns(new Date(), { locale: ar, format: "PPPppp" });
 *   ```
-*
-* @param {"id" | "en" | (string & {}) | Locale} [options.inputLocale]
+* @param {FormatDateFnsOptions["inputLocale"]} [options.inputLocale]
 *   Required if `date` is a localized non-ISO string. Used with `inputFormat`.
-*   Example for Indonesian string:
+*   - Example for Indonesian string:
 *   ```ts
-*     formatDateFns("14 Juli 2025 10:25:42", {
-*       inputFormat: "dd MMMM yyyy HH:mm:ss",
-*       inputLocale: "id",
-*     });
+*     formatDateFns("14 Juli 2025 10:25:42", { inputFormat: "dd MMMM yyyy HH:mm:ss", inputLocale: "id" });
 *   ```
-*
-* @param {string} [options.inputFormat]
+* @param {FormatDateFnsOptions["inputFormat"]} [options.inputFormat]
 *   The format string to parse `date` if it is a non-ISO string.
 *   Required together with `inputLocale`.
-*
 * @returns {string | null} A formatted date string or `null` if input is invalid.
-*
 * @example
 * formatDateFns(new Date());
-* // "14 Jul 2025 - 17:25:42"
-*
+* // ➔ "14 Jul 2025 - 17:25:42"
 * formatDateFns("2025-07-14T10:25:42Z", { format: "dd/MM/yyyy", locale: "en" });
-* // "14/07/2025"
-*
+* // ➔ "14/07/2025"
 * formatDateFns("14 Juli 2025 10:25:42", {
 *   inputFormat: "dd MMMM yyyy HH:mm:ss",
 *   inputLocale: "id",
 *   format: "yyyy-MM-dd"
 * });
-* // "2025-07-14"
-*
+* // ➔ "2025-07-14"
 * formatDateFns(null);
-* // null
-*/
-declare const formatDateFns:(date?:string|Date|null,
-/**
-* Options for formatting and parsing a date using `date-fns`.
-*/
-options?:OmitStrict<FormatOptions,"locale",true,false>&{
-/**
-* Output format string using `date-fns/format`.
-* @default "dd MMM yyyy - HH:mm:ss"
-* @example "dd MMMM yyyy, HH:mm:ss"
-*/
-format?:string;
-/**
-* The locale to be used for formatting.
-* If `string` Only Accepts "id" for Indonesian or "en" for English.
-* Or you can put props `Locale` from `date-fns/locale`, e.g :
-*
-* ```ts
-*    import { ar } from "date-fns/locale";
-*
-*    // then passing `ar` to this props.
-*    formatDateFns(
-*    // your date input...,
-*    {
-*       locale: ar,
-*       //.... other options.
-*    });
-*
-* ```
-* @default "id"
+* // ➔ null
 */
-locale?:"id"|"en"|(string &{})|Locale;
-/**
-* The Input locale to be used for parsing `inputFormat`.
-* If `string` Only Accepts "id" for Indonesian or "en" for English.
-* Required if `date` is a non-standard string like "03 Mei 2025 10:25:42").
-*
-*  Or you can put props `Locale` from `date-fns/locale`, e.g :
-*
-* ```ts
-*    import { ar } from "date-fns/locale";
-*
-*    // then passing `ar` to this props.
-*    formatDateFns(
-*    // your date input...,
-*    {
-*        inputLocale: ar,
-*        //.... other options.
-*    });
-*```
-
-* @default undefined
-*/
-inputLocale?:"id"|"en"|(string &{})|Locale;
-/**
-* Input format string for parsing non-ISO string dates
-* (e.g., localized strings like "03 Mei 2025 10:25:42").
-* Required if `date` is a non-standard string.
-* @example "dd MMMM yyyy HH:mm:ss"
-*/
-inputFormat?:string;})=>string|null;
+declare const formatDateFns:(date:string|Date|null|undefined,options?:FormatDateFnsOptions)=>string|null;
 /** ----------------------------------------------------------
-* * ***Returns the formatted GMT offset (e.g., `+0700`, `-0500`) for a given date.***
+* * ***Utility: `getGMTOffset`.***
 * ----------------------------------------------------------
-*
-* - If `date` is **not provided** or empty string, it defaults to the current date/time.
-* - If `date` is **invalid** or of wrong type (like object or number), it returns `"0"`.
-* - The returned string follows the **GMT offset format** (`±HHMM`), where:
-*   - `±` is `+` if ahead of UTC, `-` if behind.
-*   - `HH` is two-digit hours.
-*   - `MM` is two-digit minutes.
-*
+* Returns the formatted GMT offset (e.g., `+0700`, `-0500`) for a given date.
+*  - **Features:**
+*    - If `date` is **not provided** or empty string, it defaults to the current date/time.
+*    - If `date` is **invalid** or of wrong type (like object or number), it returns `"0"`.
+*    - The returned string follows the **GMT offset format** (`±HHMM`), where:
+*      - `±` is `+` if ahead of UTC, `-` if behind.
+*      - `HH` is two-digit hours.
+*      - `MM` is two-digit minutes.
 * @param {string | Date | null} [date] - The date to get the GMT offset from.
 *   - Accepts `Date` object or ISO date string (e.g., `"2024-01-01T12:00:00Z"`).
 *   - If `null`, `undefined`, or empty string, uses current system date.
 *   - If invalid date or wrong type (like `123` or `{}`), returns `"0"`.
-*
 * @returns {string} The GMT offset string in format `±HHMM`,
 *   e.g. `"+0700"`, `"-0530"`, or `"0"` if invalid.
-*
 * @example
 * getGMTOffset();
-* // => "+0700" (depends on system timezone)
-*
+* // ➔ "+0700" (depends on your system timezone)
 * getGMTOffset(new Date("2024-02-09T12:00:00Z"));
-* // => "+0000"
-*
+* // ➔ "+0000"
 * getGMTOffset("2024-02-09");
-* // => "+0700" (depends on your timezone)
-*
+* // ➔ "+0700" (depends on your system timezone)
 * getGMTOffset("invalid-date");
-* // => "0"
-*
+* // ➔ "0"
 * getGMTOffset(123);
-* // => "0"
+* // ➔ "0"
 */
 declare const getGMTOffset:(date?:string|Date|null)=>string;type CensorEmailOptions={
 /** ----------------------------------------------------------
 * * ***Censorship Mode.***
 * ----------------------------------------------------------
-*
 * **Valid value:**
 * - `"fixed"` (default) – Deterministic censorship based on a hash of the email.
 *   The same input always produces the same output.
@@ -733,24 +795,19 @@ declare const getGMTOffset:(date?:string|Date|null)=>string;type CensorEmailOpti
 */
 mode?:"random"|"fixed";};
 /** ----------------------------------------------------------
-* * ***Censors an email by replacing characters with "\*" while supporting random or fixed mode.***
+* * ***Utility: `censorEmail`.***
 * ----------------------------------------------------------
-*
-* This function replaces parts of an email with asterisks to protect privacy.
-*
-* **Modes:**
-* - `"fixed"` (default) – Deterministic censorship based on a hash of the email. Same input always produces the same output.
-* - `"random"` – Each character is randomly replaced every time the function is called.
-*
-* Invalid emails or non-string input will return an empty string.
-*
-* @param {string | null | undefined} [email] - The email address to censor.
+* **Censors an email by replacing characters with "\*" while supporting random or fixed mode.**
+* - **This function replaces parts of an email with asterisks to protect privacy.**
+*    - **Modes:**
+*        - `"fixed"` (default) – Deterministic censorship based on a hash of the email, same input always produces the same output.
+*        - `"random"` – Each character is randomly replaced every time the function is called.
+*    - **ℹ️ Note:**
+*        - Invalid emails or non-string input will return an empty string.
+* @param {string | null | undefined} email - The email address to censor.
 * @param {CensorEmailOptions} [options={}] - Options object for mode.
-*
 * @returns {string} The censored email, or an empty string if input is invalid.
-*
 * @throws {TypeError} If `options` is not a plain object or `mode` is invalid.
-*
 * @example
 * // Fixed mode (default, deterministic)
 * censorEmail("john.doe@gmail.com");
@@ -768,9 +825,8 @@ mode?:"random"|"fixed";};
 * censorEmail("invalid-email");
 * // ➔ ""
 */
-declare const censorEmail:(email?:string|null,options?:CensorEmailOptions)=>string;type ChunkStringOptions={
-/**
-* The separator string to insert between characters or words.
+declare const censorEmail:(email:string|null|undefined,options?:CensorEmailOptions)=>string;type ChunkStringOptions={
+/** The separator string to insert between characters or words.
 *
 * - Used when inserting separators every `limiter` characters.
 * - Default is a single space `" "`.
@@ -778,60 +834,52 @@ declare const censorEmail:(email?:string|null,options?:CensorEmailOptions)=>stri
 * @default " "
 */
 separator?:string;
-/**
-* Determines whether counting for `limiter` resets after each space.
+/** Determines whether counting for `limiter` resets after each space.
 *
 * - If `true`, the string is treated as words separated by spaces,
 *   and separators are applied within words, then words are grouped.
-* - If `false`, counting is continuous across the whole string,
+* - If `false` ***(default)***, counting is continuous across the whole string,
 *   treating spaces as normal characters.
 *
 * @default false
 */
 reCountAfterSpace?:boolean;};
 /** ----------------------------------------------
-* * ***Chunks a string by inserting a separator every `limiter` characters.***
+* * ***Utility: `chunkString`.***
 * ----------------------------------------------
-*
-* This function handles two main behaviors based on `reCountAfterSpace`:
-*
-* 1. If `reCountAfterSpace` is `false` (default):
-* The separator is inserted strictly every `limiter` characters throughout the entire string,
-* regardless of spaces. Spaces are treated as regular characters in the count.
-* Example: `chunkString("1234567890", 3, "-")` returns `"123-456-789-0"`.
-* Example: `chunkString("Hello World", 3, "-")` returns `"Hel-lo -Wor-ld"`.
-*
-* 2. If `reCountAfterSpace` is `true`:
-* The function first processes the input string to replace any multiple consecutive spaces
-* with a single space (e.g., "A   B" becomes "A B").
-* Then, it treats the string as a sequence of "words" (segments separated by single spaces).
-* - Each word is processed independently: if a word's length exceeds the `limiter`,
-* separators are inserted internally within that word.
-* - Words are then grouped. Each group will contain `limiter` number of words.
-* Words within the same group are joined by the specified `separator`.
-* - Finally, these groups are joined by a single space, preserving the original word separation structure
-* between groups.
-*
+* **Chunks a string by inserting a separator every `limiter` characters.**
+* - **This function handles two main behaviors based on `reCountAfterSpace`:**
+*    1. ***If `reCountAfterSpace` is `false` (default):***
+*        - The separator is inserted strictly every `limiter` characters throughout the entire string, regardless of spaces, spaces are treated as regular characters in the count.
+*            - Example: `chunkString("1234567890", 3, "-")` ➔ `"123-456-789-0"`.
+*            - Example: `chunkString("Hello World", 3, "-")` ➔ `"Hel-lo -Wor-ld"`.
+*    2. ***If `reCountAfterSpace` is `true`:***
+*        - The function first processes the input string to replace any multiple consecutive spaces with a
+*          single space (e.g., "A   B" becomes "A B").
+*      Then, it treats the string as a sequence of "words" (segments separated by single spaces).
+*            - Each word is processed independently:
+*              - if a word's length exceeds the `limiter`, separators are inserted internally within that word.
+*              - Words are then grouped. Each group will contain `limiter` number of words.
+*              - Words within the same group are joined by the specified `separator`.
+*              - Finally, these groups are joined by a single space, preserving the original word separation
+*                structure between groups.
 * @param {string} subject - The target string to chunk.
 * @param {number} limiter - The interval (number of characters) for inserting separators.
 *   - If `reCountAfterSpace = false`, it counts characters.
 *   - If `reCountAfterSpace = true`, it counts both characters within words and words per group.
 * @param {ChunkStringOptions} [options={}] - Optional settings for separator and counting behavior.
-* @returns {string} - The formatted string with separators.
-*
+* @returns {string} Return the formatted string with separators.
 * @example
 * // Basic usage
 * chunkString("1234567890", 3);
 * // ➔ "123 456 789 0"
 *
-* @example
 * // Basic usage `reCountAfterSpace = false` (default)
 * chunkString("1234567890", 3, { separator: "-");
 * // ➔ "123-456-789-0"
 * chunkString("HelloWorld", 2, { separator: "_", reCountAfterSpace: false });
 * // ➔ "He_ll_oW_or_ld"
 *
-* @example
 * // Usage with reCountAfterSpace = true:
 * // Multiple spaces are normalized to single spaces before processing.
 * chunkString("AB  CD   EF GH", 2, { separator: "-", reCountAfterSpace: true });
@@ -839,7 +887,6 @@ reCountAfterSpace?:boolean;};
 * // Words "AB" and "CD" form a group and are joined by "-", "EF" and "GH" form another group.
 * // The groups "AB-CD" and "EF-GH" are then joined by a space.
 *
-* @example
 * // Another usage with reCountAfterSpace = true:
 * chunkString("ABC DEF GHI JKL", 3, { separator: "-", reCountAfterSpace: true });
 * // ➔ "ABC-DEF-GHI JKL"
@@ -866,47 +913,38 @@ ending?:string;
 */
 trim?:boolean;};
 /** ----------------------------------------------------------
-* * ***Truncates a string to a specified length and optionally appends an ending.***
-* * ***Supports trimming the input before truncation.***
-* * ***If truncation occurs, trailing spaces before the ending are removed.***
-* * ***The `ending` parameter is always trimmed first; if empty, it defaults to `"..."`.***
+* * ***Utility: `truncateString`.***
 * ----------------------------------------------------------
-*
+* **Features:**
+* - Truncates a string to a specified length and optionally appends an ending.
+* - Supports trimming the input before truncation.
+* - If truncation occurs, trailing spaces before the ending are removed.
+* - The `ending` parameter is always trimmed first; if empty, it defaults to `"..."`.
 * @param {string|null|undefined} text - The input string to truncate.
 *        If `null`, `undefined`, or empty after trim, returns `""`.
 * @param {TruncateStringOptions} [options] - Optional settings:
 *        - `length` (number, default 10): Maximum length of the truncated string.
 *        - `ending` (string, default `"..."`): String to append if truncation occurs.
-*        - `trim` (boolean, default true): Whether to trim the input before truncation.
-*
+*        - `trim` (boolean, default `true`): Whether to trim the input before truncation.
 * @returns {string} The truncated string with optional trimming and ending.
 *                   Returns `""` if input is empty or length < 1.
-*
 * @throws {TypeError} If `options.length` is not a finite number,
 *                     or if `options.ending` is not a string,
 *                     or if `options.trim` is not a boolean.
-*
 * @example
 * truncateString("hello world", { length: 5 });
 * // ➔ "hello..."
-*
 * truncateString("hello world", { length: 5, ending: "---" });
 * // ➔ "hello---"
-*
 * truncateString("hello world", { length: 5, ending: "   " });
 * // ➔ "hello..." (ending trimmed to default)
-*
 * truncateString("hello world", { length: 5, ending: "   !!!   " });
 * // ➔ "hello!!!" (ending trimmed)
-*
 * truncateString("   long data string   ", { length: 8, ending: "...", trim: true });
 * // ➔ "long dat..."
-*
 * truncateString("   long data string   ", { length: 8, ending: "...", trim: false });
 * // ➔ "   long ..."
-*
 * truncateString(null, { length: 5 });
 * // ➔ ""
-*
 */
-declare const truncateString:(text?:string|null,options?:TruncateStringOptions)=>string;export{censorEmail,chunkString,formatCurrency,formatDateFns,formatDateIntl,formatDateTime,formatNumber,formatPhoneNumber,getGMTOffset,truncateString};
+declare const truncateString:(text:string|null|undefined,options?:TruncateStringOptions)=>string;export{censorEmail,chunkString,formatCurrency,formatDateFns,formatDateIntl,formatDateTime,formatNumber,formatPhoneNumber,getGMTOffset,truncateString};