@rzl-zone/utils-js 3.10.0 → 3.11.1

package/dist/formatters/index.d.ts

@@ -2,136 +2,148 @@
  * ====================================================
  * Rzl Utils-JS.
  * ----------------------------------------------------
- * Version: 3.10.0.
+ * Version: 3.11.1.
  * Author: Rizalvin Dwiky.
  * Repository: https://github.com/rzl-zone/utils-js.
  * ====================================================
  */
-import{NumberFormat,CountryCode}from'libphonenumber-js';import{OverrideTypes,ExtractStrict,Prettify,OmitStrict,AnyString}from'@rzl-zone/ts-types-plus';import{FormatOptions,Locale}from'date-fns';type NegativeFormatOptionCustom={
-/** Custom formatter function for the final formatted negative string.
- *  If provided, it ***OVERRIDES*** style & space entirely. */
-custom:(formatted:string)=>string;style?:never;space?:never;};type NegativeFormatOptionUnCustom={custom?:never;
-/** Use style & optional spacing for negative numbers.
- *
- * @default "dash"
- */
-style?:"dash"|"brackets"|"abs";
-/** Whether to include space inside brackets or after dash.
- *
- * Default: false
- * @default false
- */
-space?:boolean;};
+import { NumberFormat, CountryCode } from 'libphonenumber-js';
+import { OverrideTypes, ExtractStrict, Prettify, OmitStrict, AnyString } from '@rzl-zone/ts-types-plus';
+import { FormatOptions, Locale } from 'date-fns';
+
+type NegativeFormatOptionCustom = {
+    /** Custom formatter function for the final formatted negative string.
+     *  If provided, it ***OVERRIDES*** style & space entirely. */
+    custom: (formatted: string) => string;
+    style?: never;
+    space?: never;
+};
+type NegativeFormatOptionUnCustom = {
+    custom?: never;
+    /** Use style & optional spacing for negative numbers.
+     *
+     * @default "dash"
+     */
+    style?: "dash" | "brackets" | "abs";
+    /** Whether to include space inside brackets or after dash.
+     *
+     * Default: false
+     * @default false
+     */
+    space?: boolean;
+};
 /** ---------------------------------------------------------------------------
  * * ***Type for negative number formatting options.***
  * ---------------------------------------------------------------------------
  */
-type NegativeFormatOption="dash"|"brackets"|"abs"|NegativeFormatOptionCustom|NegativeFormatOptionUnCustom;
+type NegativeFormatOption = "dash" | "brackets" | "abs" | NegativeFormatOptionCustom | NegativeFormatOptionUnCustom;
 /** ---------------------------------------------------------------------------
  * * ***Type Options for {@link formatCurrency|`formatCurrency`}.***
  * ---------------------------------------------------------------------------
  */
-type FormatCurrencyOptions={
-/** ---------------------------------------------------------------------------
- * * ***Prefix currency string.***
- * ---------------------------------------------------------------------------
- * **Does not auto-keep input symbols.**
- * - ***DefaultValue:** `""`.*
- * - **Example:** `"Rp "` ➔ `Rp 1.000`.
- *
- * @default ""
- */
-suffixCurrency?:string;
-/** ---------------------------------------------------------------------------
- * * ***Thousands separator.***
- * ---------------------------------------------------------------------------
- * - ***DefaultValue:** `"."`.*
- * - **Example:** `"."` ➔ `1.000.000`.
- * @default "."
- */
-separator?:string;
-/** ---------------------------------------------------------------------------
- * * ***Prefix currency string.***
- * ---------------------------------------------------------------------------
- * **Whether to show decimals, if `false`, decimals are truncated.**
- * - ***DefaultValue:** `false`.*
- * @default false
- */
-decimal?:boolean;
-/** ---------------------------------------------------------------------------
- * * ***Total decimal digits.***
- * ---------------------------------------------------------------------------
- * **If `decimal: true` & `roundedDecimal: false`, simply cuts.**
- * - ***DefaultValue:** `2`.*
- * @default 2
- */
-totalDecimal?:number;
-/** ---------------------------------------------------------------------------
- * * ***Actually append `suffixDecimal`.***
- * ---------------------------------------------------------------------------
- * - ***DefaultValue:** `true`.*
- * @default true
- */
-endDecimal?:boolean;
-/** ---------------------------------------------------------------------------
- * * ***Text appended after decimals.***
- * ---------------------------------------------------------------------------
- * - ***DefaultValue:** `""`.*
- * - **Example:**
- *    -  `".-"` ➔ `1.000,00.-`.
- *    -  `" USD"` ➔ `1.000,00 USD`.
- * @default ""
- */
-suffixDecimal?:string;
-/** ---------------------------------------------------------------------------
- * * ***Rounding mode for decimals.***
- * ---------------------------------------------------------------------------
- * - **Behavior:**
- *     - `"round"` ➔ nearest.
- *     - `"ceil"` ➔ always up.
- *     - `"floor"` ➔ always down.
- *     - `false` ➔ truncate.
- * - ***DefaultValue:** `"round"`.*
- * @default "round"
- */
-roundedDecimal?:"round"|"ceil"|"floor"|false;
-/** ---------------------------------------------------------------------------
- * * ***Decimal separator.***
- * ---------------------------------------------------------------------------
- * - ***DefaultValue:** `","`.*
- * - **Example:** `","` ➔ `1.000,10`.
- * @default ","
- */
-separatorDecimals?:string;
-/** ---------------------------------------------------------------------------
- * * ***Negative formatting option.***
- * ---------------------------------------------------------------------------
- * **Can be string ("dash" | "brackets" | "abs") or object with custom formatter.**
- * - **Behavior:**
- *    - `"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"`.*
- *
- * @default "dash"
- */
-negativeFormat?:NegativeFormatOption;
-/** ---------------------------------------------------------------------------
- * * ***Applies Indian Format.***
- * ---------------------------------------------------------------------------
- * - **Behavior:**
- *    - If `true`, formats as Indian: `12,34,567`.
- *    - Also forces `separator: ","`, `separatorDecimals: "."`.
- * - ***DefaultValue:** `false`.*
- * @default false
- */
-indianFormat?:boolean;};
+type FormatCurrencyOptions = {
+    /** ---------------------------------------------------------------------------
+     * * ***Prefix currency string.***
+     * ---------------------------------------------------------------------------
+     * **Does not auto-keep input symbols.**
+     * - ***DefaultValue:** `""`.*
+     * - **Example:** `"Rp "` ➔ `Rp 1.000`.
+     *
+     * @default ""
+     */
+    suffixCurrency?: string;
+    /** ---------------------------------------------------------------------------
+     * * ***Thousands separator.***
+     * ---------------------------------------------------------------------------
+     * - ***DefaultValue:** `"."`.*
+     * - **Example:** `"."` ➔ `1.000.000`.
+     * @default "."
+     */
+    separator?: string;
+    /** ---------------------------------------------------------------------------
+     * * ***Prefix currency string.***
+     * ---------------------------------------------------------------------------
+     * **Whether to show decimals, if `false`, decimals are truncated.**
+     * - ***DefaultValue:** `false`.*
+     * @default false
+     */
+    decimal?: boolean;
+    /** ---------------------------------------------------------------------------
+     * * ***Total decimal digits.***
+     * ---------------------------------------------------------------------------
+     * **If `decimal: true` & `roundedDecimal: false`, simply cuts.**
+     * - ***DefaultValue:** `2`.*
+     * @default 2
+     */
+    totalDecimal?: number;
+    /** ---------------------------------------------------------------------------
+     * * ***Actually append `suffixDecimal`.***
+     * ---------------------------------------------------------------------------
+     * - ***DefaultValue:** `true`.*
+     * @default true
+     */
+    endDecimal?: boolean;
+    /** ---------------------------------------------------------------------------
+     * * ***Text appended after decimals.***
+     * ---------------------------------------------------------------------------
+     * - ***DefaultValue:** `""`.*
+     * - **Example:**
+     *    -  `".-"` ➔ `1.000,00.-`.
+     *    -  `" USD"` ➔ `1.000,00 USD`.
+     * @default ""
+     */
+    suffixDecimal?: string;
+    /** ---------------------------------------------------------------------------
+     * * ***Rounding mode for decimals.***
+     * ---------------------------------------------------------------------------
+     * - **Behavior:**
+     *     - `"round"` ➔ nearest.
+     *     - `"ceil"` ➔ always up.
+     *     - `"floor"` ➔ always down.
+     *     - `false` ➔ truncate.
+     * - ***DefaultValue:** `"round"`.*
+     * @default "round"
+     */
+    roundedDecimal?: "round" | "ceil" | "floor" | false;
+    /** ---------------------------------------------------------------------------
+     * * ***Decimal separator.***
+     * ---------------------------------------------------------------------------
+     * - ***DefaultValue:** `","`.*
+     * - **Example:** `","` ➔ `1.000,10`.
+     * @default ","
+     */
+    separatorDecimals?: string;
+    /** ---------------------------------------------------------------------------
+     * * ***Negative formatting option.***
+     * ---------------------------------------------------------------------------
+     * **Can be string ("dash" | "brackets" | "abs") or object with custom formatter.**
+     * - **Behavior:**
+     *    - `"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"`.*
+     *
+     * @default "dash"
+     */
+    negativeFormat?: NegativeFormatOption;
+    /** ---------------------------------------------------------------------------
+     * * ***Applies Indian Format.***
+     * ---------------------------------------------------------------------------
+     * - **Behavior:**
+     *    - If `true`, formats as Indian: `12,34,567`.
+     *    - Also forces `separator: ","`, `separatorDecimals: "."`.
+     * - ***DefaultValue:** `false`.*
+     * @default false
+     */
+    indianFormat?: boolean;
+};
+
 /** -------------------------------------------------------
  * * ***Utility: `formatCurrency`.***
  * -------------------------------------------------------
@@ -359,7 +371,8 @@ indianFormat?:boolean;};
  * });
  * // ➔ "Rp 1.121.234,00"
  */
-declare const formatCurrency:(value:string|number,options?:FormatCurrencyOptions)=>string;
+declare const formatCurrency: (value: string | number, options?: FormatCurrencyOptions) => string;
+
 /** ----------------------------------------------------------
  * * ***Utility: `formatNumber`.***
  * ----------------------------------------------------------
@@ -407,7 +420,8 @@ declare const formatCurrency:(value:string|number,options?:FormatCurrencyOptions
  * formatNumber("1234,56", ",");
  * // ➔ "1,234.56"
  */
-declare const formatNumber:(value:string|number,separator?:string)=>string;
+declare const formatNumber: (value: string | number, separator?: string) => string;
+
 /** -------------------------------------------------------
  * * ***Output format mode for {@link formatPhoneNumber|`formatPhoneNumber`}.***
  * -------------------------------------------------------
@@ -416,7 +430,7 @@ declare const formatNumber:(value:string|number,separator?:string)=>string;
  * - `'NATIONAL'`   ➔ `0812 3456 7890`
  * - `'INTERNATIONAL'` ➔ `+62 812 3456 7890`
  */
-type OutputFormat=ExtractStrict<NumberFormat,"INTERNATIONAL"|"NATIONAL"|"RFC3966"|"E.164">;
+type OutputFormat = ExtractStrict<NumberFormat, "INTERNATIONAL" | "NATIONAL" | "RFC3966" | "E.164">;
 /** -------------------------------------------------------
  * * ***Single input value for {@link formatPhoneNumber|`formatPhoneNumber`}.***
  * -------------------------------------------------------
@@ -431,7 +445,7 @@ type OutputFormat=ExtractStrict<NumberFormat,"INTERNATIONAL"|"NATIONAL"|"RFC3966
  *      - Prefer using a `string` if the number may begin with `0`.
  *    - E.164 international standard allows **up to 15 digits** (not counting `+`).
  */
-type ValueFormatPhoneNumber=string|number|null|undefined;
+type ValueFormatPhoneNumber = string | number | null | undefined;
 /** -------------------------------------------------------
  * * ***Base option set for {@link formatPhoneNumber|`formatPhoneNumber`}.***
  * -------------------------------------------------------
@@ -446,268 +460,269 @@ type ValueFormatPhoneNumber=string|number|null|undefined;
  *      the regex will still validate numbers without `+`
  *      as long as the digit count ≤ **15**.
  */
-type FormatPhoneNumberMain={
-/** -------------------------------------------------------
- * * ***Separator for formatted output.***
- * -------------------------------------------------------
- * **Defines the string used to separate groups of digits**
- * in the formatted phone number.
- * - **Default:** `" "`.
- * - **Executed only when:**
- *    - Parameter options `checkValidOnly` and `takeNumberOnly` are both `false`.
- *      - (This option is ignored if either `checkValidOnly` or `takeNumberOnly` is `true`.)
- * - **Behavior:**
- *    - The formatter inserts this separator between number blocks
- *      according to the selected `outputFormat`.
- * @default " "
- * @example
- * ```ts
- * // Using dash as separator
- * formatPhoneNumber("081234567890", { defaultCountry: "ID", separator: "-" });
- * // ➔ "+62 812-3456-7890"
- *
- * // Using space as separator
- * formatPhoneNumber("(151) 2345-6789", { defaultCountry: "DE", separator: " " });
- * // ➔ "+49 1512 3456789"
- * ```
- */
-separator?:string;
-/** -------------------------------------------------------
- * * ***Output format style for the returned phone number.***
- * -------------------------------------------------------
- * **Determines how the formatted phone number string is returned.**
- *
- * - **Default:** `"INTERNATIONAL"`.
- * - **Applicable only when:**
- *    - Parameter options `checkValidOnly` and `takeNumberOnly`
- *      are both **`false`**.
- *      - (Ignored if either of those options is `true`.)
- *
- * - **Supported values (from {@link NumberFormat}):**
- *    - `"NATIONAL"` – Local/national format, e.g. `0812 3456 7890`.
- *    - `"INTERNATIONAL"` – International format with leading plus, e.g. `+62 812 3456 7890`.
- *    - `"E.164"` – Compact E.164 format, e.g. `+6281234567890`.
- *    - `"RFC3966"` – RFC 3966 URI format, e.g. `tel:+62-812-3456-7890`.
- *
- * @default "INTERNATIONAL"
- * @example
- * ```ts
- * // Returns a national-format string
- * formatPhoneNumber("+62 81234567890", { outputFormat: "NATIONAL" });
- * // ➔ "0812 3456 7890"
- *
- * // Returns an E.164-format string
- * formatPhoneNumber("+62 81234567890", { outputFormat: "E.164" });
- * // ➔ "+6281234567890"
- * ```
- */
-outputFormat?:OutputFormat;
-/** -------------------------------------------------------
- * * ***Prepend a plus sign and country calling code.***
- * -------------------------------------------------------
- * **Forces the returned phone number to start with a leading `+`
- * followed by the detected country calling code (e.g. `+63`, `+1`).**
- * - **Default:** `true`.
- * - **Executed only when:**
- *    - Parameter options `outputFormat` is set to `"INTERNATIONAL"`.
- *      - (This option is ignored for `"NATIONAL"`, `"E.164"` or `"RFC3966"` formats.).
- * - **Applicable when:**
- *    - You want to guarantee that the result
- *      always contains a plus sign and country code, regardless of
- *      the selected `outputFormat`.
- * - **Behavior:**
- *    - When `true`, the formatter ensures the output begins with
- *      a `+` and the correct country code.
- *    - When `false`, the output follows the chosen `outputFormat`
- *      without forcing a `+` prefix.
- * @default true
- * @example
- * ```ts
- * // Automatically adds +63 (default: `true`) even if input is local format
- * formatPhoneNumber("09171234567", {
- *   country: "PH",
- *   prependPlusCountryCode: true
- * });
- * // ➔ "+63 917 123 4567"
- *
- * formatPhoneNumber("09171234567", {
- *   country: "PH",
- *   prependPlusCountryCode: false
- * });
- * // ➔ "63 917 123 4567"
- *
- * // Leaves number in national format (no plus sign)
- * formatPhoneNumber("+63 9171234567", {
- *   country: "PH",
- *   prependPlusCountryCode: false,
- *   outputFormat: "NATIONAL"
- * });
- * // ➔ "0917 123 4567"
- * ```
- */
-prependPlusCountryCode?:boolean;
-/** -------------------------------------------------------
- * * ***Characters before the country code (e.g. `"("`).***
- * -------------------------------------------------------
- * **Adds a custom string that appears **immediately before** the
- * international country calling code when formatting.**
- * - **Default:** `""` (empty string).
- * - **Behavior:**
- *    - **Active only when:**
- *        - `checkValidOnly` is **false**,
- *        - `takeNumberOnly` is **false**, **and**
- *        - `outputFormat` is `"INTERNATIONAL"`.
- *    - **Ignored if:**
- *        - The value is an empty string (after trimming),
- *        - `checkValidOnly` or `takeNumberOnly` is `true`,
- *        - `outputFormat` is not `"INTERNATIONAL"`,
- *        - `closingNumberCountry` is `undefined` or an empty string (after trimming).
- * - **Invalid input:**
- *    - Returns no effect if the phone number is invalid or not compatible
- *      with the selected `defaultCountry`.
- * @default ""
- * @example
- * ```ts
- * formatPhoneNumber("+63 9171234567", {
- *   outputFormat: "INTERNATIONAL",
- *   openingNumberCountry: "(",
- *   closingNumberCountry: ")"
- * });
- * // ➔ "(+63) 917 123 4567"
- * ```
- */
-openingNumberCountry?:string;
-/** -------------------------------------------------------
- * * ***Characters after the country code (e.g. `")"`).***
- * -------------------------------------------------------
- * **Adds a custom string that appears **immediately after** the
- * international country calling code when formatting.**
- * - **Default:** `""` (empty string).
- * - **Behavior:**
- *    - **Active only when:**
- *        - `checkValidOnly` is **false**,
- *        - `takeNumberOnly` is **false**, **and**
- *        - `outputFormat` is `"INTERNATIONAL"`.
- *    - **Ignored if:**
- *        - The value is an empty string (after trimming),
- *        - `checkValidOnly` or `takeNumberOnly` is `true`,
- *        - `outputFormat` is not `"INTERNATIONAL"`,
- *        - `openingNumberCountry` is `undefined` or an empty string (after trimming).
- * - **Invalid input:**
- *   Returns no effect if the phone number is invalid or not compatible
- *   with the selected `defaultCountry`.
- * @default ""
- * @example
- * ```ts
- * formatPhoneNumber("+63 9171234567", {
- *   outputFormat: "INTERNATIONAL",
- *   openingNumberCountry: "(",
- *   closingNumberCountry: ")"
- * });
- * // ➔ "(+63) 917 123 4567"
- * ```
- */
-closingNumberCountry?:string;
-/** -------------------------------------------------------
- * * ***Return only a boolean validity flag.***
- * -------------------------------------------------------
- * - ***Behavior:***
- *    - **Exclusive mode:**
- *      - ⚠️ When `true`, all formatting options and `takeNumberOnly` must be omitted or are ignored.
- *    - Conflicts with `takeNumberOnly`:
- *      - ⚠️ When `checkValidOnly` is `true` and all formatting options and `takeNumberOnly` must be
- *        omitted or are ignored.
- *      - But if mistake passing props:
- *        - ⚠️ When `checkValidOnly` is `true` and other of formatting options was passing:
- *          - If `takeNumberOnly` is `true` or `false`:
- *            - Will return a `boolean` because `checkValidOnly` is prioritize first.
- *    - Output:
- *      - Boolean ➔ (`true` or `false`).
- * - ***DefaultValue: false***
- * @default false
- * @example
- * ```ts
- * // Returns `true` if valid number and number with country code (no need `defaultCountry`)
- * formatPhoneNumber("+63 912-123-4567", { checkValidOnly: true });
- * // ➔ true
- *
- * // Returns `true` if valid number and number without country code but with `defaultCountry`
- * formatPhoneNumber("213-373-4253", { defaultCountry: "US", checkValidOnly: true });
- * // ➔ true
- *
- * // Returns `false` if without country code.
- * formatPhoneNumber("213-373-4253", { checkValidOnly: true });
- * // ➔ false
- *
- * // Returns `false` for invalid number.
- * formatPhoneNumber("abcd", { checkValidOnly: true });
- * // ➔ false
- * ```
- */
-checkValidOnly?:boolean;
-/** -------------------------------------------------------
- * * ***Return only the digits of the phone number (local number only).***
- * -------------------------------------------------------
- * **Returns a string containing only numeric characters** from the **local number**,
- * ignoring any country code, spaces, plus signs, or separators.
- * - **Default:** `false`
- * - **Behavior:**
- *    - **Exclusive mode:**
- *        - ⚠️ When set to `true`, all formatting options
- *          (`outputFormat`, `prependPlusCountryCode`, etc.)
- *          and `checkValidOnly` **must be omitted** or will be **ignored**.
- *    - **Conflict handling with `checkValidOnly`:**
- *        - If both `takeNumberOnly` and `checkValidOnly` are `true`,
- *          `checkValidOnly` takes priority and the function
- *          returns a `boolean`.
- *        - If `checkValidOnly` is `false` (or not provided),
- *          and `takeNumberOnly` is `true`,
- *          the function returns a **numeric string of the local number**.
- *    - **Invalid input:**
- *        - If the input is invalid or cannot be parsed
- *          (e.g. not matching the `defaultCountry`),
- *          the function returns an **empty string** (`""`).
- * - **Output example:**
- *   - Valid input ➔ `"81234567890"`  // country code removed
- *   - Invalid input ➔ `""`
- * @default false
- * @example
- * ```ts
- * // Returns only digits of the local number with country code (no need `defaultCountry`)
- * formatPhoneNumber("+63 912-123-4567", { takeNumberOnly: true });
- * // ➔ "09121234567"
- *
- * // Returns only digits of the local number without country code but with `defaultCountry`
- * formatPhoneNumber("213-373-4253", { defaultCountry: "US", takeNumberOnly: true });
- * // ➔ "2133734253"
- *
- * // Returns empty string if without country code.
- * formatPhoneNumber("213-373-4253", { takeNumberOnly: true });
- * // ➔ ""
- *
- * // Returns empty string for invalid number.
- * formatPhoneNumber("abcd", { takeNumberOnly: true });
- * // ➔ ""
- * ```
- */
-takeNumberOnly?:boolean;
-/** -------------------------------------------------------
- * * ***A "country code" is a two-letter ISO ([`ISO-3166-1 alpha-2`](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)) country code (like `"US"` | `"ID"` | `"DE"`).***
- * -------------------------------------------------------
- * **Used to interpret numbers without an explicit `+<countryCode>`.**
- * - ***Behavior:***
- *    - Required if the input without country code (`+`).
- *    - Ignored if the input already starts with `+`.
- * - ***Examples:***
- *      - `"ID"` ➔ Indonesian.
- *      - `"US"` ➔ United States.
- *      - `"GB"` ➔ United Kingdom.
- * - ***DefaultValue: `undefined`***.
- * @example
- * formatPhoneNumber("081234567890", { defaultCountry: "ID" });
- * @default undefined
- */
-defaultCountry?:CountryCode;};
+type FormatPhoneNumberMain = {
+    /** -------------------------------------------------------
+     * * ***Separator for formatted output.***
+     * -------------------------------------------------------
+     * **Defines the string used to separate groups of digits**
+     * in the formatted phone number.
+     * - **Default:** `" "`.
+     * - **Executed only when:**
+     *    - Parameter options `checkValidOnly` and `takeNumberOnly` are both `false`.
+     *      - (This option is ignored if either `checkValidOnly` or `takeNumberOnly` is `true`.)
+     * - **Behavior:**
+     *    - The formatter inserts this separator between number blocks
+     *      according to the selected `outputFormat`.
+     * @default " "
+     * @example
+     * ```ts
+     * // Using dash as separator
+     * formatPhoneNumber("081234567890", { defaultCountry: "ID", separator: "-" });
+     * // ➔ "+62 812-3456-7890"
+     *
+     * // Using space as separator
+     * formatPhoneNumber("(151) 2345-6789", { defaultCountry: "DE", separator: " " });
+     * // ➔ "+49 1512 3456789"
+     * ```
+     */
+    separator?: string;
+    /** -------------------------------------------------------
+     * * ***Output format style for the returned phone number.***
+     * -------------------------------------------------------
+     * **Determines how the formatted phone number string is returned.**
+     *
+     * - **Default:** `"INTERNATIONAL"`.
+     * - **Applicable only when:**
+     *    - Parameter options `checkValidOnly` and `takeNumberOnly`
+     *      are both **`false`**.
+     *      - (Ignored if either of those options is `true`.)
+     *
+     * - **Supported values (from {@link NumberFormat}):**
+     *    - `"NATIONAL"` – Local/national format, e.g. `0812 3456 7890`.
+     *    - `"INTERNATIONAL"` – International format with leading plus, e.g. `+62 812 3456 7890`.
+     *    - `"E.164"` – Compact E.164 format, e.g. `+6281234567890`.
+     *    - `"RFC3966"` – RFC 3966 URI format, e.g. `tel:+62-812-3456-7890`.
+     *
+     * @default "INTERNATIONAL"
+     * @example
+     * ```ts
+     * // Returns a national-format string
+     * formatPhoneNumber("+62 81234567890", { outputFormat: "NATIONAL" });
+     * // ➔ "0812 3456 7890"
+     *
+     * // Returns an E.164-format string
+     * formatPhoneNumber("+62 81234567890", { outputFormat: "E.164" });
+     * // ➔ "+6281234567890"
+     * ```
+     */
+    outputFormat?: OutputFormat;
+    /** -------------------------------------------------------
+     * * ***Prepend a plus sign and country calling code.***
+     * -------------------------------------------------------
+     * **Forces the returned phone number to start with a leading `+`
+     * followed by the detected country calling code (e.g. `+63`, `+1`).**
+     * - **Default:** `true`.
+     * - **Executed only when:**
+     *    - Parameter options `outputFormat` is set to `"INTERNATIONAL"`.
+     *      - (This option is ignored for `"NATIONAL"`, `"E.164"` or `"RFC3966"` formats.).
+     * - **Applicable when:**
+     *    - You want to guarantee that the result
+     *      always contains a plus sign and country code, regardless of
+     *      the selected `outputFormat`.
+     * - **Behavior:**
+     *    - When `true`, the formatter ensures the output begins with
+     *      a `+` and the correct country code.
+     *    - When `false`, the output follows the chosen `outputFormat`
+     *      without forcing a `+` prefix.
+     * @default true
+     * @example
+     * ```ts
+     * // Automatically adds +63 (default: `true`) even if input is local format
+     * formatPhoneNumber("09171234567", {
+     *   country: "PH",
+     *   prependPlusCountryCode: true
+     * });
+     * // ➔ "+63 917 123 4567"
+     *
+     * formatPhoneNumber("09171234567", {
+     *   country: "PH",
+     *   prependPlusCountryCode: false
+     * });
+     * // ➔ "63 917 123 4567"
+     *
+     * // Leaves number in national format (no plus sign)
+     * formatPhoneNumber("+63 9171234567", {
+     *   country: "PH",
+     *   prependPlusCountryCode: false,
+     *   outputFormat: "NATIONAL"
+     * });
+     * // ➔ "0917 123 4567"
+     * ```
+     */
+    prependPlusCountryCode?: boolean;
+    /** -------------------------------------------------------
+     * * ***Characters before the country code (e.g. `"("`).***
+     * -------------------------------------------------------
+     * **Adds a custom string that appears **immediately before** the
+     * international country calling code when formatting.**
+     * - **Default:** `""` (empty string).
+     * - **Behavior:**
+     *    - **Active only when:**
+     *        - `checkValidOnly` is **false**,
+     *        - `takeNumberOnly` is **false**, **and**
+     *        - `outputFormat` is `"INTERNATIONAL"`.
+     *    - **Ignored if:**
+     *        - The value is an empty string (after trimming),
+     *        - `checkValidOnly` or `takeNumberOnly` is `true`,
+     *        - `outputFormat` is not `"INTERNATIONAL"`,
+     *        - `closingNumberCountry` is `undefined` or an empty string (after trimming).
+     * - **Invalid input:**
+     *    - Returns no effect if the phone number is invalid or not compatible
+     *      with the selected `defaultCountry`.
+     * @default ""
+     * @example
+     * ```ts
+     * formatPhoneNumber("+63 9171234567", {
+     *   outputFormat: "INTERNATIONAL",
+     *   openingNumberCountry: "(",
+     *   closingNumberCountry: ")"
+     * });
+     * // ➔ "(+63) 917 123 4567"
+     * ```
+     */
+    openingNumberCountry?: string;
+    /** -------------------------------------------------------
+     * * ***Characters after the country code (e.g. `")"`).***
+     * -------------------------------------------------------
+     * **Adds a custom string that appears **immediately after** the
+     * international country calling code when formatting.**
+     * - **Default:** `""` (empty string).
+     * - **Behavior:**
+     *    - **Active only when:**
+     *        - `checkValidOnly` is **false**,
+     *        - `takeNumberOnly` is **false**, **and**
+     *        - `outputFormat` is `"INTERNATIONAL"`.
+     *    - **Ignored if:**
+     *        - The value is an empty string (after trimming),
+     *        - `checkValidOnly` or `takeNumberOnly` is `true`,
+     *        - `outputFormat` is not `"INTERNATIONAL"`,
+     *        - `openingNumberCountry` is `undefined` or an empty string (after trimming).
+     * - **Invalid input:**
+     *   Returns no effect if the phone number is invalid or not compatible
+     *   with the selected `defaultCountry`.
+     * @default ""
+     * @example
+     * ```ts
+     * formatPhoneNumber("+63 9171234567", {
+     *   outputFormat: "INTERNATIONAL",
+     *   openingNumberCountry: "(",
+     *   closingNumberCountry: ")"
+     * });
+     * // ➔ "(+63) 917 123 4567"
+     * ```
+     */
+    closingNumberCountry?: string;
+    /** -------------------------------------------------------
+     * * ***Return only a boolean validity flag.***
+     * -------------------------------------------------------
+     * - ***Behavior:***
+     *    - **Exclusive mode:**
+     *      - ⚠️ When `true`, all formatting options and `takeNumberOnly` must be omitted or are ignored.
+     *    - Conflicts with `takeNumberOnly`:
+     *      - ⚠️ When `checkValidOnly` is `true` and all formatting options and `takeNumberOnly` must be
+     *        omitted or are ignored.
+     *      - But if mistake passing props:
+     *        - ⚠️ When `checkValidOnly` is `true` and other of formatting options was passing:
+     *          - If `takeNumberOnly` is `true` or `false`:
+     *            - Will return a `boolean` because `checkValidOnly` is prioritize first.
+     *    - Output:
+     *      - Boolean ➔ (`true` or `false`).
+     * - ***DefaultValue: false***
+     * @default false
+     * @example
+     * ```ts
+     * // Returns `true` if valid number and number with country code (no need `defaultCountry`)
+     * formatPhoneNumber("+63 912-123-4567", { checkValidOnly: true });
+     * // ➔ true
+     *
+     * // Returns `true` if valid number and number without country code but with `defaultCountry`
+     * formatPhoneNumber("213-373-4253", { defaultCountry: "US", checkValidOnly: true });
+     * // ➔ true
+     *
+     * // Returns `false` if without country code.
+     * formatPhoneNumber("213-373-4253", { checkValidOnly: true });
+     * // ➔ false
+     *
+     * // Returns `false` for invalid number.
+     * formatPhoneNumber("abcd", { checkValidOnly: true });
+     * // ➔ false
+     * ```
+     */
+    checkValidOnly?: boolean;
+    /** -------------------------------------------------------
+     * * ***Return only the digits of the phone number (local number only).***
+     * -------------------------------------------------------
+     * **Returns a string containing only numeric characters** from the **local number**,
+     * ignoring any country code, spaces, plus signs, or separators.
+     * - **Default:** `false`
+     * - **Behavior:**
+     *    - **Exclusive mode:**
+     *        - ⚠️ When set to `true`, all formatting options
+     *          (`outputFormat`, `prependPlusCountryCode`, etc.)
+     *          and `checkValidOnly` **must be omitted** or will be **ignored**.
+     *    - **Conflict handling with `checkValidOnly`:**
+     *        - If both `takeNumberOnly` and `checkValidOnly` are `true`,
+     *          `checkValidOnly` takes priority and the function
+     *          returns a `boolean`.
+     *        - If `checkValidOnly` is `false` (or not provided),
+     *          and `takeNumberOnly` is `true`,
+     *          the function returns a **numeric string of the local number**.
+     *    - **Invalid input:**
+     *        - If the input is invalid or cannot be parsed
+     *          (e.g. not matching the `defaultCountry`),
+     *          the function returns an **empty string** (`""`).
+     * - **Output example:**
+     *   - Valid input ➔ `"81234567890"`  // country code removed
+     *   - Invalid input ➔ `""`
+     * @default false
+     * @example
+     * ```ts
+     * // Returns only digits of the local number with country code (no need `defaultCountry`)
+     * formatPhoneNumber("+63 912-123-4567", { takeNumberOnly: true });
+     * // ➔ "09121234567"
+     *
+     * // Returns only digits of the local number without country code but with `defaultCountry`
+     * formatPhoneNumber("213-373-4253", { defaultCountry: "US", takeNumberOnly: true });
+     * // ➔ "2133734253"
+     *
+     * // Returns empty string if without country code.
+     * formatPhoneNumber("213-373-4253", { takeNumberOnly: true });
+     * // ➔ ""
+     *
+     * // Returns empty string for invalid number.
+     * formatPhoneNumber("abcd", { takeNumberOnly: true });
+     * // ➔ ""
+     * ```
+     */
+    takeNumberOnly?: boolean;
+    /** -------------------------------------------------------
+     * * ***A "country code" is a two-letter ISO ([`ISO-3166-1 alpha-2`](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements)) country code (like `"US"` | `"ID"` | `"DE"`).***
+     * -------------------------------------------------------
+     * **Used to interpret numbers without an explicit `+<countryCode>`.**
+     * - ***Behavior:***
+     *    - Required if the input without country code (`+`).
+     *    - Ignored if the input already starts with `+`.
+     * - ***Examples:***
+     *      - `"ID"` ➔ Indonesian.
+     *      - `"US"` ➔ United States.
+     *      - `"GB"` ➔ United Kingdom.
+     * - ***DefaultValue: `undefined`***.
+     * @example
+     * formatPhoneNumber("081234567890", { defaultCountry: "ID" });
+     * @default undefined
+     */
+    defaultCountry?: CountryCode;
+};
 /** -------------------------------------------------------
  * * ***Specialized options for the `transformPhoneNumber` variant of {@link formatPhoneNumber|`formatPhoneNumber`}.***
  * -------------------------------------------------------
@@ -719,106 +734,109 @@ defaultCountry?:CountryCode;};
  *
  * **Example Output:** `+62 812 3456 7890`
  */
-type FormatPhoneNumberTransform=OverrideTypes<FormatPhoneNumberMain,{
-/** -------------------------------------------------------
- * * ***Return only a boolean validity flag.***
- * -------------------------------------------------------
- * - ***Behavior:***
- *    - **Exclusive mode:**
- *      - ⚠️ When `true`, all formatting options and `takeNumberOnly` must be omitted or are ignored.
- *    - Conflicts with `takeNumberOnly`:
- *      - ⚠️ When `checkValidOnly` is `true` and all formatting options and `takeNumberOnly` must be
- *        omitted or are ignored.
- *      - But if mistake passing props:
- *        - ⚠️ When `checkValidOnly` is `true` and other of formatting options was passing:
- *          - If `takeNumberOnly` is `true` or `false`:
- *            - Will return a `boolean` because `checkValidOnly` is prioritize first.
- *    - Output:
- *      - Boolean ➔ (`true` or `false`).
- * - ***DefaultValue: false***
- * @default false
- * @requires `false` or `undefined`
- */
-checkValidOnly?:never;
-/** -------------------------------------------------------
- * * ***Return only the digits of the phone number (local number only).***
- * -------------------------------------------------------
- * **Returns a string containing only numeric characters** from the **local number**,
- * ignoring any country code, spaces, plus signs, or separators.
- * - **Default:** `false`
- * - **Behavior:**
- *    - **Exclusive mode:**
- *        - ⚠️ When set to `true`, all formatting options
- *          (`outputFormat`, `prependPlusCountryCode`, etc.)
- *          and `checkValidOnly` **must be omitted** or will be **ignored**.
- *    - **Conflict handling with `checkValidOnly`:**
- *        - If both `takeNumberOnly` and `checkValidOnly` are `true`,
- *          `checkValidOnly` takes priority and the function
- *          returns a `boolean`.
- *        - If `checkValidOnly` is `false` (or not provided),
- *          and `takeNumberOnly` is `true`,
- *          the function returns a **numeric string of the local number**.
- *    - **Invalid input:**
- *        - If the input is invalid or cannot be parsed
- *          (e.g. not matching the `defaultCountry`),
- *          the function returns an **empty string** (`""`).
- * - **Output example:**
- *   - Valid input ➔ `"81234567890"`  // country code removed
- *   - Invalid input ➔ `""`
- * @default false
- * @requires `false` or `undefined`
- */
-takeNumberOnly?:never;}>;type NeverForRestFormatPhoneNumberTransform={
-/** -------------------------------------------------------
- * * ***Not used in this mode **`(Never allowed in this mode)`**.***
- * -------------------------------------------------------
- * - ***Behavior:***
- *    - **Exclusive mode:**
- *      - ⚠️ When `true`, all formatting options must be omitted or are ignored.
- *    - Conflicts with `takeNumberOnly` and `checkValidOnly`:
- *      - If both `takeNumberOnly` and `checkValidOnly` are `true`,
- *        `checkValidOnly` takes priority and the function
- *        returns a `boolean`.
- *      - If `checkValidOnly` is `false` (or not provided),
- *        and `takeNumberOnly` is `true`,
- *        the function returns a **numeric string of the local number**.
- * @requires `undefined`
- */
-separator?:never;
-/** -------------------------------------------------------
- * * ***Not used in this mode **`(Never allowed in this mode)`**.***
- * -------------------------------------------------------
- * - ***Behavior:***
- *    - **Exclusive mode:**
- *      - ⚠️ When `true`, all formatting options must be omitted or are ignored.
- *    - Conflicts with `takeNumberOnly` and `checkValidOnly`:
- *      - If both `takeNumberOnly` and `checkValidOnly` are `true`,
- *        `checkValidOnly` takes priority and the function
- *        returns a `boolean`.
- *      - If `checkValidOnly` is `false` (or not provided),
- *        and `takeNumberOnly` is `true`,
- *        the function returns a **numeric string of the local number**.
- *
- * @requires `undefined`
- */
-openingNumberCountry?:never;
-/** -------------------------------------------------------
- * * ***Not used in this mode **`(Never allowed in this mode)`**.***
- * -------------------------------------------------------
- * - ***Behavior:***
- *    - **Exclusive mode:**
- *      - ⚠️ When `true`, all formatting options must be omitted or are ignored.
- *    - Conflicts with `takeNumberOnly` and `checkValidOnly`:
- *      - If both `takeNumberOnly` and `checkValidOnly` are `true`,
- *        `checkValidOnly` takes priority and the function
- *        returns a `boolean`.
- *      - If `checkValidOnly` is `false` (or not provided),
- *        and `takeNumberOnly` is `true`,
- *        the function returns a **numeric string of the local number**.
- *
- * @requires `undefined`
- */
-closingNumberCountry?:never;};
+type FormatPhoneNumberTransform = OverrideTypes<FormatPhoneNumberMain, {
+    /** -------------------------------------------------------
+     * * ***Return only a boolean validity flag.***
+     * -------------------------------------------------------
+     * - ***Behavior:***
+     *    - **Exclusive mode:**
+     *      - ⚠️ When `true`, all formatting options and `takeNumberOnly` must be omitted or are ignored.
+     *    - Conflicts with `takeNumberOnly`:
+     *      - ⚠️ When `checkValidOnly` is `true` and all formatting options and `takeNumberOnly` must be
+     *        omitted or are ignored.
+     *      - But if mistake passing props:
+     *        - ⚠️ When `checkValidOnly` is `true` and other of formatting options was passing:
+     *          - If `takeNumberOnly` is `true` or `false`:
+     *            - Will return a `boolean` because `checkValidOnly` is prioritize first.
+     *    - Output:
+     *      - Boolean ➔ (`true` or `false`).
+     * - ***DefaultValue: false***
+     * @default false
+     * @requires `false` or `undefined`
+     */
+    checkValidOnly?: never;
+    /** -------------------------------------------------------
+     * * ***Return only the digits of the phone number (local number only).***
+     * -------------------------------------------------------
+     * **Returns a string containing only numeric characters** from the **local number**,
+     * ignoring any country code, spaces, plus signs, or separators.
+     * - **Default:** `false`
+     * - **Behavior:**
+     *    - **Exclusive mode:**
+     *        - ⚠️ When set to `true`, all formatting options
+     *          (`outputFormat`, `prependPlusCountryCode`, etc.)
+     *          and `checkValidOnly` **must be omitted** or will be **ignored**.
+     *    - **Conflict handling with `checkValidOnly`:**
+     *        - If both `takeNumberOnly` and `checkValidOnly` are `true`,
+     *          `checkValidOnly` takes priority and the function
+     *          returns a `boolean`.
+     *        - If `checkValidOnly` is `false` (or not provided),
+     *          and `takeNumberOnly` is `true`,
+     *          the function returns a **numeric string of the local number**.
+     *    - **Invalid input:**
+     *        - If the input is invalid or cannot be parsed
+     *          (e.g. not matching the `defaultCountry`),
+     *          the function returns an **empty string** (`""`).
+     * - **Output example:**
+     *   - Valid input ➔ `"81234567890"`  // country code removed
+     *   - Invalid input ➔ `""`
+     * @default false
+     * @requires `false` or `undefined`
+     */
+    takeNumberOnly?: never;
+}>;
+type NeverForRestFormatPhoneNumberTransform = {
+    /** -------------------------------------------------------
+     * * ***Not used in this mode **`(Never allowed in this mode)`**.***
+     * -------------------------------------------------------
+     * - ***Behavior:***
+     *    - **Exclusive mode:**
+     *      - ⚠️ When `true`, all formatting options must be omitted or are ignored.
+     *    - Conflicts with `takeNumberOnly` and `checkValidOnly`:
+     *      - If both `takeNumberOnly` and `checkValidOnly` are `true`,
+     *        `checkValidOnly` takes priority and the function
+     *        returns a `boolean`.
+     *      - If `checkValidOnly` is `false` (or not provided),
+     *        and `takeNumberOnly` is `true`,
+     *        the function returns a **numeric string of the local number**.
+     * @requires `undefined`
+     */
+    separator?: never;
+    /** -------------------------------------------------------
+     * * ***Not used in this mode **`(Never allowed in this mode)`**.***
+     * -------------------------------------------------------
+     * - ***Behavior:***
+     *    - **Exclusive mode:**
+     *      - ⚠️ When `true`, all formatting options must be omitted or are ignored.
+     *    - Conflicts with `takeNumberOnly` and `checkValidOnly`:
+     *      - If both `takeNumberOnly` and `checkValidOnly` are `true`,
+     *        `checkValidOnly` takes priority and the function
+     *        returns a `boolean`.
+     *      - If `checkValidOnly` is `false` (or not provided),
+     *        and `takeNumberOnly` is `true`,
+     *        the function returns a **numeric string of the local number**.
+     *
+     * @requires `undefined`
+     */
+    openingNumberCountry?: never;
+    /** -------------------------------------------------------
+     * * ***Not used in this mode **`(Never allowed in this mode)`**.***
+     * -------------------------------------------------------
+     * - ***Behavior:***
+     *    - **Exclusive mode:**
+     *      - ⚠️ When `true`, all formatting options must be omitted or are ignored.
+     *    - Conflicts with `takeNumberOnly` and `checkValidOnly`:
+     *      - If both `takeNumberOnly` and `checkValidOnly` are `true`,
+     *        `checkValidOnly` takes priority and the function
+     *        returns a `boolean`.
+     *      - If `checkValidOnly` is `false` (or not provided),
+     *        and `takeNumberOnly` is `true`,
+     *        the function returns a **numeric string of the local number**.
+     *
+     * @requires `undefined`
+     */
+    closingNumberCountry?: never;
+};
 /** -------------------------------------------------------
  * * ***Options subset for **validity-check mode** of
  * {@link formatPhoneNumber|`formatPhoneNumber`}.***
@@ -832,55 +850,56 @@ closingNumberCountry?:never;};
  * formatPhoneNumber("+6281234567890", { checkValidOnly: true }) // boolean
  * ```
  */
-type FormatPhoneNumberCheckValidOnly=Prettify<OverrideTypes<FormatPhoneNumberMain,{
-/** -------------------------------------------------------
- * * ***Return only a boolean validity flag.***
- * -------------------------------------------------------
- * - ***Behavior:***
- *    - **Exclusive mode:**
- *      - ⚠️ When `true`, all formatting options and `takeNumberOnly` must be omitted or are ignored.
- *    - Conflicts with `takeNumberOnly`:
- *      - ⚠️ When `checkValidOnly` is `true` and all formatting options and `takeNumberOnly` must be
- *        omitted or are ignored.
- *      - But if mistake passing props:
- *        - ⚠️ When `checkValidOnly` is `true` and other of formatting options was passing:
- *          - If `takeNumberOnly` is `true` or `false`:
- *            - Will return a `boolean` because `checkValidOnly` is prioritize first.
- *    - Output:
- *      - Boolean ➔ (`true` or `false`).
- * - ***DefaultValue: false***
- * @default false
- */
-checkValidOnly:true;
-/** -------------------------------------------------------
- * * ***Return only the digits of the phone number (local number only).***
- * -------------------------------------------------------
- * **Returns a string containing only numeric characters** from the **local number**,
- * ignoring any country code, spaces, plus signs, or separators.
- * - **Default:** `false`
- * - **Behavior:**
- *    - **Exclusive mode:**
- *        - ⚠️ When set to `true`, all formatting options
- *          (`outputFormat`, `prependPlusCountryCode`, etc.)
- *          and `checkValidOnly` **must be omitted** or will be **ignored**.
- *    - **Conflict handling with `checkValidOnly`:**
- *        - If both `takeNumberOnly` and `checkValidOnly` are `true`,
- *          `checkValidOnly` takes priority and the function
- *          returns a `boolean`.
- *        - If `checkValidOnly` is `false` (or not provided),
- *          and `takeNumberOnly` is `true`,
- *          the function returns a **numeric string of the local number**.
- *    - **Invalid input:**
- *        - If the input is invalid or cannot be parsed
- *          (e.g. not matching the `defaultCountry`),
- *          the function returns an **empty string** (`""`).
- * - **Output example:**
- *   - Valid input ➔ `"81234567890"`  // country code removed
- *   - Invalid input ➔ `""`
- * @default false
- * @requires `false` or `undefined`
- */
-takeNumberOnly?:false;}& NeverForRestFormatPhoneNumberTransform>>;
+type FormatPhoneNumberCheckValidOnly = Prettify<OverrideTypes<FormatPhoneNumberMain, {
+    /** -------------------------------------------------------
+     * * ***Return only a boolean validity flag.***
+     * -------------------------------------------------------
+     * - ***Behavior:***
+     *    - **Exclusive mode:**
+     *      - ⚠️ When `true`, all formatting options and `takeNumberOnly` must be omitted or are ignored.
+     *    - Conflicts with `takeNumberOnly`:
+     *      - ⚠️ When `checkValidOnly` is `true` and all formatting options and `takeNumberOnly` must be
+     *        omitted or are ignored.
+     *      - But if mistake passing props:
+     *        - ⚠️ When `checkValidOnly` is `true` and other of formatting options was passing:
+     *          - If `takeNumberOnly` is `true` or `false`:
+     *            - Will return a `boolean` because `checkValidOnly` is prioritize first.
+     *    - Output:
+     *      - Boolean ➔ (`true` or `false`).
+     * - ***DefaultValue: false***
+     * @default false
+     */
+    checkValidOnly: true;
+    /** -------------------------------------------------------
+     * * ***Return only the digits of the phone number (local number only).***
+     * -------------------------------------------------------
+     * **Returns a string containing only numeric characters** from the **local number**,
+     * ignoring any country code, spaces, plus signs, or separators.
+     * - **Default:** `false`
+     * - **Behavior:**
+     *    - **Exclusive mode:**
+     *        - ⚠️ When set to `true`, all formatting options
+     *          (`outputFormat`, `prependPlusCountryCode`, etc.)
+     *          and `checkValidOnly` **must be omitted** or will be **ignored**.
+     *    - **Conflict handling with `checkValidOnly`:**
+     *        - If both `takeNumberOnly` and `checkValidOnly` are `true`,
+     *          `checkValidOnly` takes priority and the function
+     *          returns a `boolean`.
+     *        - If `checkValidOnly` is `false` (or not provided),
+     *          and `takeNumberOnly` is `true`,
+     *          the function returns a **numeric string of the local number**.
+     *    - **Invalid input:**
+     *        - If the input is invalid or cannot be parsed
+     *          (e.g. not matching the `defaultCountry`),
+     *          the function returns an **empty string** (`""`).
+     * - **Output example:**
+     *   - Valid input ➔ `"81234567890"`  // country code removed
+     *   - Invalid input ➔ `""`
+     * @default false
+     * @requires `false` or `undefined`
+     */
+    takeNumberOnly?: false;
+} & NeverForRestFormatPhoneNumberTransform>>;
 /** -------------------------------------------------------
  * * ***Options subset for calling {@link formatPhoneNumber|`formatPhoneNumber`} in
  * **digits-only mode**.***
@@ -893,214 +912,219 @@ takeNumberOnly?:false;}& NeverForRestFormatPhoneNumberTransform>>;
  *
  * **Example Output:** `"6281234567890"`
  */
-type FormatPhoneNumberTakeNumberOnly=Prettify<OverrideTypes<FormatPhoneNumberMain,{
-/** -------------------------------------------------------
- * * ***Return only a boolean validity flag.***
- * -------------------------------------------------------
- * - ***Behavior:***
- *    - **Exclusive mode:**
- *      - ⚠️ When `true`, all formatting options and `takeNumberOnly` must be omitted or are ignored.
- *    - Conflicts with `takeNumberOnly`:
- *      - ⚠️ When `checkValidOnly` is `true` and all formatting options and `takeNumberOnly` must be
- *        omitted or are ignored.
- *      - But if mistake passing props:
- *        - ⚠️ When `checkValidOnly` is `true` and other of formatting options was passing:
- *          - If `takeNumberOnly` is `true` or `false`:
- *            - Will return a `boolean` because `checkValidOnly` is prioritize first.
- *    - Output:
- *      - Boolean ➔ (`true` or `false`).
- * - ***DefaultValue: false***
- * @default false
- * @requires `false` or `undefined`
- */
-checkValidOnly?:false;
-/** -------------------------------------------------------
- * * ***Return only the digits of the phone number (local number only).***
- * -------------------------------------------------------
- * **Returns a string containing only numeric characters** from the **local number**,
- * ignoring any country code, spaces, plus signs, or separators.
- * - **Default:** `false`
- * - **Behavior:**
- *    - **Exclusive mode:**
- *        - ⚠️ When set to `true`, all formatting options
- *          (`outputFormat`, `prependPlusCountryCode`, etc.)
- *          and `checkValidOnly` **must be omitted** or will be **ignored**.
- *    - **Conflict handling with `checkValidOnly`:**
- *        - If both `takeNumberOnly` and `checkValidOnly` are `true`,
- *          `checkValidOnly` takes priority and the function
- *          returns a `boolean`.
- *        - If `checkValidOnly` is `false` (or not provided),
- *          and `takeNumberOnly` is `true`,
- *          the function returns a **numeric string of the local number**.
- *    - **Invalid input:**
- *        - If the input is invalid or cannot be parsed
- *          (e.g. not matching the `defaultCountry`),
- *          the function returns an **empty string** (`""`).
- * - **Output example:**
- *   - Valid input ➔ `"81234567890"`  // country code removed
- *   - Invalid input ➔ `""`
- * @default false
- */
-takeNumberOnly:true;}& NeverForRestFormatPhoneNumberTransform>>;
+type FormatPhoneNumberTakeNumberOnly = Prettify<OverrideTypes<FormatPhoneNumberMain, {
+    /** -------------------------------------------------------
+     * * ***Return only a boolean validity flag.***
+     * -------------------------------------------------------
+     * - ***Behavior:***
+     *    - **Exclusive mode:**
+     *      - ⚠️ When `true`, all formatting options and `takeNumberOnly` must be omitted or are ignored.
+     *    - Conflicts with `takeNumberOnly`:
+     *      - ⚠️ When `checkValidOnly` is `true` and all formatting options and `takeNumberOnly` must be
+     *        omitted or are ignored.
+     *      - But if mistake passing props:
+     *        - ⚠️ When `checkValidOnly` is `true` and other of formatting options was passing:
+     *          - If `takeNumberOnly` is `true` or `false`:
+     *            - Will return a `boolean` because `checkValidOnly` is prioritize first.
+     *    - Output:
+     *      - Boolean ➔ (`true` or `false`).
+     * - ***DefaultValue: false***
+     * @default false
+     * @requires `false` or `undefined`
+     */
+    checkValidOnly?: false;
+    /** -------------------------------------------------------
+     * * ***Return only the digits of the phone number (local number only).***
+     * -------------------------------------------------------
+     * **Returns a string containing only numeric characters** from the **local number**,
+     * ignoring any country code, spaces, plus signs, or separators.
+     * - **Default:** `false`
+     * - **Behavior:**
+     *    - **Exclusive mode:**
+     *        - ⚠️ When set to `true`, all formatting options
+     *          (`outputFormat`, `prependPlusCountryCode`, etc.)
+     *          and `checkValidOnly` **must be omitted** or will be **ignored**.
+     *    - **Conflict handling with `checkValidOnly`:**
+     *        - If both `takeNumberOnly` and `checkValidOnly` are `true`,
+     *          `checkValidOnly` takes priority and the function
+     *          returns a `boolean`.
+     *        - If `checkValidOnly` is `false` (or not provided),
+     *          and `takeNumberOnly` is `true`,
+     *          the function returns a **numeric string of the local number**.
+     *    - **Invalid input:**
+     *        - If the input is invalid or cannot be parsed
+     *          (e.g. not matching the `defaultCountry`),
+     *          the function returns an **empty string** (`""`).
+     * - **Output example:**
+     *   - Valid input ➔ `"81234567890"`  // country code removed
+     *   - Invalid input ➔ `""`
+     * @default false
+     */
+    takeNumberOnly: true;
+} & NeverForRestFormatPhoneNumberTransform>>;
 /** -------------------------------------------------------
  * * ***Options subset for calling {@link formatPhoneNumber|`formatPhoneNumber`} force to **Validity-check Mode**.***
  * -------------------------------------------------------
  */
-type FormatPhoneNumberAllPassing=OverrideTypes<FormatPhoneNumberMain,{
-/** -------------------------------------------------------
- * * ***Return only a boolean validity flag.***
- * -------------------------------------------------------
- * - ***Behavior:***
- *    - **Exclusive mode:**
- *      - ⚠️ When `true`, all formatting options and `takeNumberOnly` must be omitted or are ignored.
- *    - Conflicts with `takeNumberOnly`:
- *      - ⚠️ When `checkValidOnly` is `true` and all formatting options and `takeNumberOnly` must be
- *        omitted or are ignored.
- *      - But if mistake passing props:
- *        - ⚠️ When `checkValidOnly` is `true` and other of formatting options was passing:
- *          - If `takeNumberOnly` is `true` or `false`:
- *            - Will return a `boolean` because `checkValidOnly` is prioritize first.
- *    - Output:
- *      - Boolean ➔ (`true` or `false`).
- * - ***DefaultValue: false***
- * @default false
- */
-checkValidOnly:true;
-/** -------------------------------------------------------
- * * ***Return only the digits of the phone number (local number only).***
- * -------------------------------------------------------
- * **Returns a string containing only numeric characters** from the **local number**,
- * ignoring any country code, spaces, plus signs, or separators.
- * - **Default:** `false`
- * - **Behavior:**
- *    - **Exclusive mode:**
- *        - ⚠️ When set to `true`, all formatting options
- *          (`outputFormat`, `prependPlusCountryCode`, etc.)
- *          and `checkValidOnly` **must be omitted** or will be **ignored**.
- *    - **Conflict handling with `checkValidOnly`:**
- *        - If both `takeNumberOnly` and `checkValidOnly` are `true`,
- *          `checkValidOnly` takes priority and the function
- *          returns a `boolean`.
- *        - If `checkValidOnly` is `false` (or not provided),
- *          and `takeNumberOnly` is `true`,
- *          the function returns a **numeric string of the local number**.
- *    - **Invalid input:**
- *        - If the input is invalid or cannot be parsed
- *          (e.g. not matching the `defaultCountry`),
- *          the function returns an **empty string** (`""`).
- * - **Output example:**
- *   - Valid input ➔ `"81234567890"`  // country code removed
- *   - Invalid input ➔ `""`
- * @default false
- * @requires `false` or `undefined`
- */
-takeNumberOnly:true;}>;
+type FormatPhoneNumberAllPassing = OverrideTypes<FormatPhoneNumberMain, {
+    /** -------------------------------------------------------
+     * * ***Return only a boolean validity flag.***
+     * -------------------------------------------------------
+     * - ***Behavior:***
+     *    - **Exclusive mode:**
+     *      - ⚠️ When `true`, all formatting options and `takeNumberOnly` must be omitted or are ignored.
+     *    - Conflicts with `takeNumberOnly`:
+     *      - ⚠️ When `checkValidOnly` is `true` and all formatting options and `takeNumberOnly` must be
+     *        omitted or are ignored.
+     *      - But if mistake passing props:
+     *        - ⚠️ When `checkValidOnly` is `true` and other of formatting options was passing:
+     *          - If `takeNumberOnly` is `true` or `false`:
+     *            - Will return a `boolean` because `checkValidOnly` is prioritize first.
+     *    - Output:
+     *      - Boolean ➔ (`true` or `false`).
+     * - ***DefaultValue: false***
+     * @default false
+     */
+    checkValidOnly: true;
+    /** -------------------------------------------------------
+     * * ***Return only the digits of the phone number (local number only).***
+     * -------------------------------------------------------
+     * **Returns a string containing only numeric characters** from the **local number**,
+     * ignoring any country code, spaces, plus signs, or separators.
+     * - **Default:** `false`
+     * - **Behavior:**
+     *    - **Exclusive mode:**
+     *        - ⚠️ When set to `true`, all formatting options
+     *          (`outputFormat`, `prependPlusCountryCode`, etc.)
+     *          and `checkValidOnly` **must be omitted** or will be **ignored**.
+     *    - **Conflict handling with `checkValidOnly`:**
+     *        - If both `takeNumberOnly` and `checkValidOnly` are `true`,
+     *          `checkValidOnly` takes priority and the function
+     *          returns a `boolean`.
+     *        - If `checkValidOnly` is `false` (or not provided),
+     *          and `takeNumberOnly` is `true`,
+     *          the function returns a **numeric string of the local number**.
+     *    - **Invalid input:**
+     *        - If the input is invalid or cannot be parsed
+     *          (e.g. not matching the `defaultCountry`),
+     *          the function returns an **empty string** (`""`).
+     * - **Output example:**
+     *   - Valid input ➔ `"81234567890"`  // country code removed
+     *   - Invalid input ➔ `""`
+     * @default false
+     * @requires `false` or `undefined`
+     */
+    takeNumberOnly: true;
+}>;
 /** -------------------------------------------------------
  * * ***Options subset for calling {@link formatPhoneNumber|`formatPhoneNumber`} force to **Validity-check Mode**.***
  * -------------------------------------------------------
  */
-type FormatPhoneNumberAllPassingValidOnly=OverrideTypes<FormatPhoneNumberMain,{
-/** -------------------------------------------------------
- * * ***Return only a boolean validity flag.***
- * -------------------------------------------------------
- * - ***Behavior:***
- *    - **Exclusive mode:**
- *      - ⚠️ When `true`, all formatting options and `takeNumberOnly` must be omitted or are ignored.
- *    - Conflicts with `takeNumberOnly`:
- *      - ⚠️ When `checkValidOnly` is `true` and all formatting options and `takeNumberOnly` must be
- *        omitted or are ignored.
- *      - But if mistake passing props:
- *        - ⚠️ When `checkValidOnly` is `true` and other of formatting options was passing:
- *          - If `takeNumberOnly` is `true` or `false`:
- *            - Will return a `boolean` because `checkValidOnly` is prioritize first.
- *    - Output:
- *      - Boolean ➔ (`true` or `false`).
- * - ***DefaultValue: false***
- * @default false
- */
-checkValidOnly:true;
-/** -------------------------------------------------------
- * * ***Return only the digits of the phone number (local number only).***
- * -------------------------------------------------------
- * **Returns a string containing only numeric characters** from the **local number**,
- * ignoring any country code, spaces, plus signs, or separators.
- * - **Default:** `false`
- * - **Behavior:**
- *    - **Exclusive mode:**
- *        - ⚠️ When set to `true`, all formatting options
- *          (`outputFormat`, `prependPlusCountryCode`, etc.)
- *          and `checkValidOnly` **must be omitted** or will be **ignored**.
- *    - **Conflict handling with `checkValidOnly`:**
- *        - If both `takeNumberOnly` and `checkValidOnly` are `true`,
- *          `checkValidOnly` takes priority and the function
- *          returns a `boolean`.
- *        - If `checkValidOnly` is `false` (or not provided),
- *          and `takeNumberOnly` is `true`,
- *          the function returns a **numeric string of the local number**.
- *    - **Invalid input:**
- *        - If the input is invalid or cannot be parsed
- *          (e.g. not matching the `defaultCountry`),
- *          the function returns an **empty string** (`""`).
- * - **Output example:**
- *   - Valid input ➔ `"81234567890"`  // country code removed
- *   - Invalid input ➔ `""`
- * @default false
- * @requires `false` or `undefined`
- */
-takeNumberOnly?:false;}>;
+type FormatPhoneNumberAllPassingValidOnly = OverrideTypes<FormatPhoneNumberMain, {
+    /** -------------------------------------------------------
+     * * ***Return only a boolean validity flag.***
+     * -------------------------------------------------------
+     * - ***Behavior:***
+     *    - **Exclusive mode:**
+     *      - ⚠️ When `true`, all formatting options and `takeNumberOnly` must be omitted or are ignored.
+     *    - Conflicts with `takeNumberOnly`:
+     *      - ⚠️ When `checkValidOnly` is `true` and all formatting options and `takeNumberOnly` must be
+     *        omitted or are ignored.
+     *      - But if mistake passing props:
+     *        - ⚠️ When `checkValidOnly` is `true` and other of formatting options was passing:
+     *          - If `takeNumberOnly` is `true` or `false`:
+     *            - Will return a `boolean` because `checkValidOnly` is prioritize first.
+     *    - Output:
+     *      - Boolean ➔ (`true` or `false`).
+     * - ***DefaultValue: false***
+     * @default false
+     */
+    checkValidOnly: true;
+    /** -------------------------------------------------------
+     * * ***Return only the digits of the phone number (local number only).***
+     * -------------------------------------------------------
+     * **Returns a string containing only numeric characters** from the **local number**,
+     * ignoring any country code, spaces, plus signs, or separators.
+     * - **Default:** `false`
+     * - **Behavior:**
+     *    - **Exclusive mode:**
+     *        - ⚠️ When set to `true`, all formatting options
+     *          (`outputFormat`, `prependPlusCountryCode`, etc.)
+     *          and `checkValidOnly` **must be omitted** or will be **ignored**.
+     *    - **Conflict handling with `checkValidOnly`:**
+     *        - If both `takeNumberOnly` and `checkValidOnly` are `true`,
+     *          `checkValidOnly` takes priority and the function
+     *          returns a `boolean`.
+     *        - If `checkValidOnly` is `false` (or not provided),
+     *          and `takeNumberOnly` is `true`,
+     *          the function returns a **numeric string of the local number**.
+     *    - **Invalid input:**
+     *        - If the input is invalid or cannot be parsed
+     *          (e.g. not matching the `defaultCountry`),
+     *          the function returns an **empty string** (`""`).
+     * - **Output example:**
+     *   - Valid input ➔ `"81234567890"`  // country code removed
+     *   - Invalid input ➔ `""`
+     * @default false
+     * @requires `false` or `undefined`
+     */
+    takeNumberOnly?: false;
+}>;
 /** -------------------------------------------------------
  * * ***Options subset for calling {@link formatPhoneNumber|`formatPhoneNumber`} force to **Digits-only Mode**.***
  * -------------------------------------------------------
  */
-type FormatPhoneNumberAllPassingTakeOnly=OverrideTypes<FormatPhoneNumberMain,{
-/** -------------------------------------------------------
- * * ***Return only a boolean validity flag.***
- * -------------------------------------------------------
- * - ***Behavior:***
- *    - **Exclusive mode:**
- *      - ⚠️ When `true`, all formatting options and `takeNumberOnly` must be omitted or are ignored.
- *    - Conflicts with `takeNumberOnly`:
- *      - ⚠️ When `checkValidOnly` is `true` and all formatting options and `takeNumberOnly` must be
- *        omitted or are ignored.
- *      - But if mistake passing props:
- *        - ⚠️ When `checkValidOnly` is `true` and other of formatting options was passing:
- *          - If `takeNumberOnly` is `true` or `false`:
- *            - Will return a `boolean` because `checkValidOnly` is prioritize first.
- *    - Output:
- *      - Boolean ➔ (`true` or `false`).
- * - ***DefaultValue: false***
- * @default false
- * @requires `false` or `undefined`
- */
-checkValidOnly?:false;
-/** -------------------------------------------------------
- * * ***Return only the digits of the phone number (local number only).***
- * -------------------------------------------------------
- * **Returns a string containing only numeric characters** from the **local number**,
- * ignoring any country code, spaces, plus signs, or separators.
- * - **Default:** `false`
- * - **Behavior:**
- *    - **Exclusive mode:**
- *        - ⚠️ When set to `true`, all formatting options
- *          (`outputFormat`, `prependPlusCountryCode`, etc.)
- *          and `checkValidOnly` **must be omitted** or will be **ignored**.
- *    - **Conflict handling with `checkValidOnly`:**
- *        - If both `takeNumberOnly` and `checkValidOnly` are `true`,
- *          `checkValidOnly` takes priority and the function
- *          returns a `boolean`.
- *        - If `checkValidOnly` is `false` (or not provided),
- *          and `takeNumberOnly` is `true`,
- *          the function returns a **numeric string of the local number**.
- *    - **Invalid input:**
- *        - If the input is invalid or cannot be parsed
- *          (e.g. not matching the `defaultCountry`),
- *          the function returns an **empty string** (`""`).
- * - **Output example:**
- *   - Valid input ➔ `"81234567890"`  // country code removed
- *   - Invalid input ➔ `""`
- * @default false
- */
-takeNumberOnly:true;}>;
+type FormatPhoneNumberAllPassingTakeOnly = OverrideTypes<FormatPhoneNumberMain, {
+    /** -------------------------------------------------------
+     * * ***Return only a boolean validity flag.***
+     * -------------------------------------------------------
+     * - ***Behavior:***
+     *    - **Exclusive mode:**
+     *      - ⚠️ When `true`, all formatting options and `takeNumberOnly` must be omitted or are ignored.
+     *    - Conflicts with `takeNumberOnly`:
+     *      - ⚠️ When `checkValidOnly` is `true` and all formatting options and `takeNumberOnly` must be
+     *        omitted or are ignored.
+     *      - But if mistake passing props:
+     *        - ⚠️ When `checkValidOnly` is `true` and other of formatting options was passing:
+     *          - If `takeNumberOnly` is `true` or `false`:
+     *            - Will return a `boolean` because `checkValidOnly` is prioritize first.
+     *    - Output:
+     *      - Boolean ➔ (`true` or `false`).
+     * - ***DefaultValue: false***
+     * @default false
+     * @requires `false` or `undefined`
+     */
+    checkValidOnly?: false;
+    /** -------------------------------------------------------
+     * * ***Return only the digits of the phone number (local number only).***
+     * -------------------------------------------------------
+     * **Returns a string containing only numeric characters** from the **local number**,
+     * ignoring any country code, spaces, plus signs, or separators.
+     * - **Default:** `false`
+     * - **Behavior:**
+     *    - **Exclusive mode:**
+     *        - ⚠️ When set to `true`, all formatting options
+     *          (`outputFormat`, `prependPlusCountryCode`, etc.)
+     *          and `checkValidOnly` **must be omitted** or will be **ignored**.
+     *    - **Conflict handling with `checkValidOnly`:**
+     *        - If both `takeNumberOnly` and `checkValidOnly` are `true`,
+     *          `checkValidOnly` takes priority and the function
+     *          returns a `boolean`.
+     *        - If `checkValidOnly` is `false` (or not provided),
+     *          and `takeNumberOnly` is `true`,
+     *          the function returns a **numeric string of the local number**.
+     *    - **Invalid input:**
+     *        - If the input is invalid or cannot be parsed
+     *          (e.g. not matching the `defaultCountry`),
+     *          the function returns an **empty string** (`""`).
+     * - **Output example:**
+     *   - Valid input ➔ `"81234567890"`  // country code removed
+     *   - Invalid input ➔ `""`
+     * @default false
+     */
+    takeNumberOnly: true;
+}>;
+
 /** -------------------------------------------------------
  * * ***Utility: `formatPhoneNumber`.***
  * -------------------------------------------------------
@@ -1224,7 +1248,7 @@ takeNumberOnly:true;}>;
  *    // ➔ false
  *    ```
  */
-declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatPhoneNumberTransform):string;
+declare function formatPhoneNumber(value: ValueFormatPhoneNumber, options?: FormatPhoneNumberTransform): string;
 /** -------------------------------------------------------
  * * ***Utility: `formatPhoneNumber`.***
  * -------------------------------------------------------
@@ -1280,7 +1304,7 @@ declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatP
  * // ➔ ""
  * ```
  */
-declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatPhoneNumberTakeNumberOnly):string;
+declare function formatPhoneNumber(value: ValueFormatPhoneNumber, options?: FormatPhoneNumberTakeNumberOnly): string;
 /** -------------------------------------------------------
  * * ***Utility: `formatPhoneNumber`.***
  * -------------------------------------------------------
@@ -1340,7 +1364,7 @@ declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatP
  * // ➔ false
  * ```
  */
-declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatPhoneNumberCheckValidOnly):boolean;
+declare function formatPhoneNumber(value: ValueFormatPhoneNumber, options?: FormatPhoneNumberCheckValidOnly): boolean;
 /** -------------------------------------------------------
  * * ***Utility: `formatPhoneNumber`.***
  * -------------------------------------------------------
@@ -1456,7 +1480,7 @@ declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatP
  * // ➔ false
  * ```
  */
-declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatPhoneNumberAllPassingValidOnly):boolean;
+declare function formatPhoneNumber(value: ValueFormatPhoneNumber, options?: FormatPhoneNumberAllPassingValidOnly): boolean;
 /** -------------------------------------------------------
  * * ***Utility: `formatPhoneNumber`.***
  * -------------------------------------------------------
@@ -1534,7 +1558,7 @@ declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatP
  * // ➔ ""
  * ```
  */
-declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatPhoneNumberAllPassingTakeOnly):string;
+declare function formatPhoneNumber(value: ValueFormatPhoneNumber, options?: FormatPhoneNumberAllPassingTakeOnly): string;
 /** -------------------------------------------------------
  * * ***Utility: `formatPhoneNumber`.***
  * -------------------------------------------------------
@@ -1675,15 +1699,18 @@ declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatP
  * // ➔ false
  * ```
  */
-declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatPhoneNumberAllPassing):boolean;type CensorEmailOptions={
-/** ----------------------------------------------------------
- * * ***Censorship Mode.***
- * ----------------------------------------------------------
- * - **Valid value:**
- *    - `"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.
- */
-mode?:"random"|"fixed";};
+declare function formatPhoneNumber(value: ValueFormatPhoneNumber, options?: FormatPhoneNumberAllPassing): boolean;
+
+type CensorEmailOptions = {
+    /** ----------------------------------------------------------
+     * * ***Censorship Mode.***
+     * ----------------------------------------------------------
+     * - **Valid value:**
+     *    - `"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.
+     */
+    mode?: "random" | "fixed";
+};
 /** ----------------------------------------------------------
  * * ***Utility: `censorEmail`.***
  * ----------------------------------------------------------
@@ -1715,25 +1742,28 @@ mode?:"random"|"fixed";};
  * censorEmail("invalid-email");
  * // ➔ ""
  */
-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 `" "`.
- *
- * @default " "
- */
-separator?:string;
-/** ***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` ***(default)***, counting is continuous across the whole string,
- *   treating spaces as normal characters.
- *
- * @default false
- */
-reCountAfterSpace?:boolean;};
+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 `" "`.
+     *
+     * @default " "
+     */
+    separator?: string;
+    /** ***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` ***(default)***, counting is continuous across the whole string,
+     *   treating spaces as normal characters.
+     *
+     * @default false
+     */
+    reCountAfterSpace?: boolean;
+};
 /** ----------------------------------------------
  * * ***Utility: `chunkString`.***
  * ----------------------------------------------
@@ -1785,24 +1815,27 @@ reCountAfterSpace?:boolean;};
  * // The word "JKL" forms its own group (as it's the last word and completes no other group).
  * // The groups "ABC-DEF-GHI" and "JKL" are then joined by a space.
  */
-declare function chunkString(subject:string,limiter:number,options?:ChunkStringOptions):string;type TruncateStringOptions={
-/** ***Maximum length of the truncated string **(default: `10`)**.***
- *
- * @default 10
- */
-length?:number;
-/** ***String to append if truncation occurs.***
- *
- * - Will be trimmed first; defaults to `"..."` if empty.
- *
- * @default "..."
- */
-ending?:string;
-/** ***Whether to trim the input string before truncation ***(default: `true`)***.***
- *
- * @default true
- */
-trim?:boolean;};
+declare function chunkString(subject: string, limiter: number, options?: ChunkStringOptions): string;
+
+type TruncateStringOptions = {
+    /** ***Maximum length of the truncated string **(default: `10`)**.***
+     *
+     * @default 10
+     */
+    length?: number;
+    /** ***String to append if truncation occurs.***
+     *
+     * - Will be trimmed first; defaults to `"..."` if empty.
+     *
+     * @default "..."
+     */
+    ending?: string;
+    /** ***Whether to trim the input string before truncation ***(default: `true`)***.***
+     *
+     * @default true
+     */
+    trim?: boolean;
+};
 /** ----------------------------------------------------------
  * * ***Utility: `truncateString`.***
  * ----------------------------------------------------------
@@ -1837,7 +1870,8 @@ trim?:boolean;};
  * truncateString(null, { length: 5 });
  * // ➔ ""
  */
-declare const truncateString:(text:string|null|undefined,options?:TruncateStringOptions)=>string;
+declare const truncateString: (text: string | null | undefined, options?: TruncateStringOptions) => string;
+
 /** ----------------------------------------------------------------------
  * * ***Options for formatting dates with `date-fns/format`.***
  * ----------------------------------------------------------------------
@@ -1847,71 +1881,73 @@ declare const truncateString:(text:string|null|undefined,options?:TruncateString
  *
  * @private ***types for {@link formatDateFns}.***
  */
-type FormatDateFnsOptions=Prettify<OmitStrict<FormatOptions,"locale",true,false>&{
-/** ------------------------------------------------------------
- * * ***Output format string passed to `date-fns/format`.***
- * ------------------------------------------------------------
- * - **Behavior:**
- *    - Determines how the date will be rendered.
- *    - Uses the full power of `date-fns` tokens.
- * - ***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.***
- * ------------------------------------------------------------
- * - **Behavior:**
- *    - If `string`: only accepts `"id"` (Indonesian) or `"en"` (English) - **(default)**.
- *    - If `Locale`: accepts a locale object from `date-fns/locale`.
- * - ***Default Value***: `"en"`.
- * ```ts
- * import { ar } from "date-fns/locale";
- *
- * 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.***
- * ------------------------------------------------------------
- * - **Behavior:**
- *    - Required if `date` is a **localized string**
- *      (e.g. `"03 Mei 2025 10:25:42"` in Indonesian).
- *    - Same accepted types as `locale` parameter.
- * - ***Default Value***: `"en"`.
- * ```ts
- * import { ar } from "date-fns/locale";
- *
- * 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.***
- * ------------------------------------------------------------
- * - **Behavior:**
- *    - 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;}>;
+type FormatDateFnsOptions = Prettify<OmitStrict<FormatOptions, "locale", true, false> & {
+    /** ------------------------------------------------------------
+     * * ***Output format string passed to `date-fns/format`.***
+     * ------------------------------------------------------------
+     * - **Behavior:**
+     *    - Determines how the date will be rendered.
+     *    - Uses the full power of `date-fns` tokens.
+     * - ***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.***
+     * ------------------------------------------------------------
+     * - **Behavior:**
+     *    - If `string`: only accepts `"id"` (Indonesian) or `"en"` (English) - **(default)**.
+     *    - If `Locale`: accepts a locale object from `date-fns/locale`.
+     * - ***Default Value***: `"en"`.
+     * ```ts
+     * import { ar } from "date-fns/locale";
+     *
+     * 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.***
+     * ------------------------------------------------------------
+     * - **Behavior:**
+     *    - Required if `date` is a **localized string**
+     *      (e.g. `"03 Mei 2025 10:25:42"` in Indonesian).
+     *    - Same accepted types as `locale` parameter.
+     * - ***Default Value***: `"en"`.
+     * ```ts
+     * import { ar } from "date-fns/locale";
+     *
+     * 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.***
+     * ------------------------------------------------------------
+     * - **Behavior:**
+     *    - 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: `formatDateFns`.***
  * ----------------------------------------------------------
@@ -1962,7 +1998,8 @@ inputFormat?:string;}>;
  * formatDateFns(null);
  * // ➔ null
  */
-declare const formatDateFns:(date:string|Date|null|undefined,options?:FormatDateFnsOptions)=>string|null;
+declare const formatDateFns: (date: string | Date | null | undefined, options?: FormatDateFnsOptions) => string | null;
+
 /** -------------------------------------------------------------
  * * ***Supported IETF BCP-47 locale codes for Intl API.***
  * -------------------------------------------------------------
@@ -1977,7 +2014,8 @@ declare const formatDateFns:(date:string|Date|null|undefined,options?:FormatDate
  * const locale: SupportedLocales = "fr-CA";
  * 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);
+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);
+
 /** ----------------------------------------------------------------
  * * ***Options for formatting dates with `Intl.DateTimeFormat`.***
  * ----------------------------------------------------------------
@@ -1986,28 +2024,30 @@ type SupportedLocales="en-US"|"en-GB"|"en-AU"|"en-CA"|"en-NZ"|"en-ZA"|"en-IN"|"e
  * an additional `locale` property that is validated against **{@link SupportedLocales | `SupportedLocales`}**.**
  * @private ***types for {@link formatDateIntl}.***
  */
-type FormatDateIntlOptions=Intl.DateTimeFormatOptions &{
-/** ------------------------------------------------------------
- * * ***Locale for date formatting.***
- * ------------------------------------------------------------
- * - **Behavior:**
- *    - 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
- * { 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"
- *
- */
-locale?:SupportedLocales;};
+type FormatDateIntlOptions = Intl.DateTimeFormatOptions & {
+    /** ------------------------------------------------------------
+     * * ***Locale for date formatting.***
+     * ------------------------------------------------------------
+     * - **Behavior:**
+     *    - 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
+     * { 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"
+     *
+     */
+    locale?: SupportedLocales;
+};
+
 /** ----------------------------------------------------------
  * * ***Utility: `formatDateIntl`.***
  * ----------------------------------------------------------
@@ -2035,7 +2075,8 @@ locale?:SupportedLocales;};
  * formatDateIntl(new Date(), { timeZone: "UTC", hour: "2-digit", minute: "2-digit" });
  * // ➔ "01:30 AM"
  */
-declare const formatDateIntl:(date:string|Date|null|undefined,options?:FormatDateIntlOptions)=>string|null;
+declare const formatDateIntl: (date: string | Date | null | undefined, options?: FormatDateIntlOptions) => string | null;
+
 /** ----------------------------------------------------------
  * * ***Utility: `formatDateTime`.***
  * ----------------------------------------------------------
@@ -2076,7 +2117,8 @@ declare const formatDateIntl:(date:string|Date|null|undefined,options?:FormatDat
  * formatDateTime(undefined);
  * // ➔ null
  */
-declare const formatDateTime:(date:string|Date|null|undefined,format?:string)=>string|null;
+declare const formatDateTime: (date: string | Date | null | undefined, format?: string) => string | null;
+
 /** ----------------------------------------------------------
  * * ***Utility: `getGMTOffset`.***
  * ----------------------------------------------------------
@@ -2107,4 +2149,6 @@ declare const formatDateTime:(date:string|Date|null|undefined,format?:string)=>s
  * getGMTOffset(123);
  * // ➔ "0"
  */
-declare const getGMTOffset:(date?:string|Date|null)=>string;export{censorEmail,chunkString,formatCurrency,formatDateFns,formatDateIntl,formatDateTime,formatNumber,formatPhoneNumber,getGMTOffset,truncateString};
+declare const getGMTOffset: (date?: string | Date | null) => string;
+
+export { censorEmail, chunkString, formatCurrency, formatDateFns, formatDateIntl, formatDateTime, formatNumber, formatPhoneNumber, getGMTOffset, truncateString };