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

package/dist/formatters/index.d.ts

@@ -0,0 +1,2106 @@
+import{NumberFormat,CountryCode}from'libphonenumber-js';import{a as OverrideTypes,E as ExtractStrict,O as OmitStrict}from'../override-CL2olHE5.js';import{P as Prettify}from'../prettify-3o8_Kw6b.js';import{FormatOptions,Locale}from'date-fns';import{A as AnyString}from'../string-B1jlOnws.js';import'../if-ChM35c_q.js';import'../never-D89PbPh5.js';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 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;};
+/** -------------------------------------------------------
+ * * ***Utility: `formatCurrency`.***
+ * -------------------------------------------------------
+ * **Formats a number or messy currency string into a
+ *   beautifully formatted currency string, with highly
+ *   customizable separators, decimal control, rounding,
+ *   currency symbols, and negative styling.**
+ * - **✅ Highlights:**
+ *    - ***Accepts:***
+ *        - Pure numbers: `15300.95`.
+ *        - Messy currency strings from **any locale**:
+ *          - `"Rp 15.000,21"` ***(Indonesian / Euro)***.
+ *          - `"$12,345.60"` ***(US)***.
+ *          - `"CHF 12'345.60"` ***(Swiss)***.
+ *          - `"1,23,456.78"` ***(Indian)***.
+ * - Auto extracts numeric value with smart multi-locale parsing
+ *   via ***{@link parseCurrencyString | `parseCurrencyString`}***.
+ * - Strong type checks & clear errors for misconfigured options.
+ * - **Handles:**
+ *    - Thousands separators: `.`, `,`, `'`, ` `.
+ *    - Decimal separators: `,`, `.`.
+ *    - Decimal suffix (eg. `".-"`, `" USD"`).
+ *    - Currency prefix (eg. `"Rp "`, `"$ "`).
+ *    - Rounding: `"round"`, `"ceil"`, `"floor"`, or truncate.
+ *    - Negative styling: dash `-`, brackets `( )`, absolute, or custom.
+ * - **✅ How input is parsed:**
+ *    - Removes all non-digit except `.`, `,`, `'` and spaces.
+ *    - Detects bracket negatives: `"(15.000,10)"` ➔ `-15000.10`.
+ *    - Uses last `,` or `.` as decimal separator (others are thousands).
+ *    - Ignores currency symbols like `Rp`, `$` (must re-apply with `suffixCurrency`).
+ * - **ℹ️ Note:**
+ *    - Always re-apply symbols via `suffixCurrency`.
+ *    - `parseCurrencyString` smartly detects last decimal,
+ *   so `"1.121.234,56"` and `"1,121,234.56"` both parsed correctly.
+ * @param {string|number} value
+ *  ***The input value to format, examples:***
+ *    - `"Rp 15.000,21"`.
+ *    - `"$12,345.60"`.
+ *    - `"CHF 12'345.60"`.
+ *    - `15300.95`.
+ * @param {FormatCurrencyOptions} [options] ***Optional configuration object.***
+ * @param {FormatCurrencyOptions["separator"]} [options.separator]
+ *  ***Thousands separator:***
+ *    - `{ separator: "." }` ➔ `1.000.000`.
+ *    - *DefaultValue: `"."`.*
+ * @param {FormatCurrencyOptions["separatorDecimals"]} [options.separatorDecimals]
+ *  ***Decimal separator:***
+ *    - `{ separatorDecimals: "," }` ➔ `1.000,10`.
+ *    - *DefaultValue: `","`.*
+ * @param {FormatCurrencyOptions["suffixCurrency"]} [options.suffixCurrency]
+ *  ***Prefix currency string:***
+ *    - Does **not auto-keep input symbols**.
+ *    - Must set manually e.g: `{ suffixCurrency: "Rp " }`.
+ *        - `{ suffixCurrency: "Rp " }` ➔ `Rp 1.000`.
+ *    - *DefaultValue: `""`.*
+ * @param {FormatCurrencyOptions["decimal"]} [options.decimal]
+ *  ***Whether to show decimals. If `false`, decimals are truncated:***
+ *    - If `false`, cut the decimal.
+ *    - *DefaultValue: `false`.*
+ * @param {FormatCurrencyOptions["totalDecimal"]} [options.totalDecimal]
+ *  ***Total decimal digits:***
+ *    - If `decimal: true` & `roundedDecimal: false`, simply cuts.
+ *    - *DefaultValue: `2`.*
+ * @param {FormatCurrencyOptions["separatorDecimals"]} [options.suffixDecimal]
+ *  ***Text appended after decimals:***
+ *    - E.g: (`".-"`, `" USD"`).
+ *    - Example 1: `".-"` ➔ `1.000,00.-`.
+ *    - Example 2: `" USD"` ➔ `1.000,00 USD`.
+ *    - *DefaultValue: `""`.*
+ * @param {FormatCurrencyOptions["endDecimal"]} [options.endDecimal]
+ *  ***Actually append `suffixDecimal`:***
+ *    - *DefaultValue: `true`.*
+ * @param {FormatCurrencyOptions["roundedDecimal"]} [options.roundedDecimal]
+ *  ***Rounding mode:***
+ *    - `"round"` ➔ nearest.
+ *    - `"ceil"` ➔ always up.
+ *    - `"floor"` ➔ always down.
+ *    - `false` ➔ truncate.
+ *    - *DefaultValue: `"round"`.*
+ * @param {FormatCurrencyOptions["negativeFormat"]} [options.negativeFormat]
+ *  ***How to format negatives:***
+ *    - `"dash"` ➔ `-15.000`.
+ *    - `"brackets"` ➔ `(15.000)`.
+ *    - `"abs"` ➔ `15.000` (always positive).
+ *    - Or object: `{ style: "dash" | "brackets" | "abs", space: true | false, custom: (formatted) => string }`.
+ *    - *DefaultValue: `"dash"`.*
+ * @param {FormatCurrencyOptions["indianFormat"]} [options.indianFormat]
+ *  ***Applies Indian Format:***
+ *    - If `true`, formats as Indian: `12,34,567`.
+ *    - Also forces `separator: ","`, `separatorDecimals: "."`.
+ * @returns {string}
+ *  ***Nicely formatted currency string, examples:***
+ *    - `"15.000,10"`.
+ *    - `"Rp 15.000,10.-"`.
+ *    - `"15'000.10 USD"`.
+ *    - `"12,34,567.89"`.
+ * @throws {TypeError}
+ *  ***Will throw TypeError If:***
+ *    - The `value` is not string or number.
+ *    - Cannot parse to valid number.
+ *    - Options have invalid types.
+ * @example
+ * // --- Number input (default, decimals off) ---
+ * formatCurrency(1234567.89);
+ * // ➔ "1.234.567"
+ *
+ * // --- Decimals enabled ---
+ * formatCurrency(1234567.89, { decimal: true });
+ * // ➔ "1.234.567,89"
+ *
+ * // --- Indian format ---
+ * formatCurrency(1234567.89, { decimal: true, indianFormat: true });
+ * // ➔ "12,34,567.89"
+ *
+ * // --- String input (Indonesian style) ---
+ * formatCurrency("Rp 15.000,21", { decimal: true });
+ * // ➔ "15.000,21"
+ *
+ * // --- String input (US style) ---
+ * formatCurrency("$12,345.60", { decimal: true });
+ * // ➔ "12.345,60"
+ *
+ * // --- String input (Swiss style) ---
+ * formatCurrency("CHF 12'345.60", { decimal: true });
+ * // ➔ "12'345,60"
+ *
+ * // --- String input (Indian style) ---
+ * formatCurrency("1,23,456.78", { decimal: true, indianFormat: true });
+ * // ➔ "12,34,567.78"
+ *
+ * // --- Negative numbers (dash) ---
+ * formatCurrency(-1234.56, { decimal: true });
+ * // ➔ "-1.234,56"
+ *
+ * // --- Negative numbers (brackets) ---
+ * formatCurrency(-1234.56, {
+ *   decimal: true,
+ *   negativeFormat: "brackets"
+ * });
+ * // ➔ "(1.234,56)"
+ *
+ * // --- Negative numbers (custom object style) ---
+ * formatCurrency(-1234.56, {
+ *   decimal: true,
+ *   negativeFormat: { style: "brackets", space: true }
+ * });
+ * // ➔ "( 1.234,56 )"
+ *
+ * // --- Negative numbers (custom function) ---
+ * formatCurrency(-1234.56, {
+ *   decimal: true,
+ *   negativeFormat: { custom: (val) => `NEGATIVE[${val}]` }
+ * });
+ * // ➔ "NEGATIVE[1.234,56]"
+ *
+ * // --- With prefix currency ---
+ * formatCurrency(1234.56, {
+ *   decimal: true,
+ *   suffixCurrency: "Rp "
+ * });
+ * // ➔ "Rp 1.234,56"
+ *
+ * // --- With suffix decimal ---
+ * formatCurrency(1234.56, {
+ *   decimal: true,
+ *   suffixDecimal: ".-"
+ * });
+ * // ➔ "1.234,56.-"
+ *
+ * // --- With suffix currency + suffix decimal ---
+ * formatCurrency(1234.56, {
+ *   decimal: true,
+ *   suffixCurrency: "Rp ",
+ *   suffixDecimal: ".-"
+ * });
+ * // ➔ "Rp 1.234,56.-"
+ *
+ * // --- Custom separators ---
+ * formatCurrency(1234567.89, {
+ *   decimal: true,
+ *   separator: "'",
+ *   separatorDecimals: "."
+ * });
+ * // ➔ "1'234'567.89"
+ *
+ * // --- Rounding: ceil ---
+ * formatCurrency(1234.561, {
+ *   decimal: true,
+ *   roundedDecimal: "ceil"
+ * });
+ * // ➔ "1.234,57"
+ *
+ * // --- Rounding: floor ---
+ * formatCurrency(1234.569, {
+ *   decimal: true,
+ *   roundedDecimal: "floor"
+ * });
+ * // ➔ "1.234,56"
+ *
+ * // --- Rounding: truncate (false) ---
+ * formatCurrency(1234.569, {
+ *   decimal: true,
+ *   roundedDecimal: false
+ * });
+ * // ➔ "1.234,56"
+ *
+ * // --- Force no decimals (decimal: false) ---
+ * formatCurrency(1234.567, { decimal: false });
+ * // ➔ "1.235"
+ *
+ * // --- Edge case: messy input with dots & commas ---
+ * formatCurrency("1.121.234,561", {
+ *   decimal: true,
+ *   totalDecimal: 2,
+ *   roundedDecimal: "ceil",
+ *   suffixCurrency: "Rp ",
+ *   negativeFormat: { style: "brackets" }
+ * });
+ * // ➔ "(Rp 1.121.234,57)"
+ *
+ * // --- Edge case: integer string input ---
+ * formatCurrency("1.121.234", {
+ *   decimal: true,
+ *   suffixCurrency: "Rp ",
+ *   roundedDecimal: "ceil"
+ * });
+ * // ➔ "Rp 1.121.234,00"
+ */
+declare const formatCurrency:(value:string|number,options?:FormatCurrencyOptions)=>string;
+/** ----------------------------------------------------------
+ * * ***Utility: `formatNumber`.***
+ * ----------------------------------------------------------
+ * **Formats a number or numeric string by adding a custom separator
+ * every three digits (thousands separator), and intelligently flips
+ * the decimal separator according to the chosen separator.**
+ * - **Features:**
+ *    - Converts a number to string before formatting.
+ *    - Defaults to using `,` as the thousands separator.
+ *    - If `.` is used as the separator, the decimal will automatically
+ *      become `,`, and vice versa.
+ *    - Handles input with existing formatting (e.g. "1,234,567.89") and normalizes it.
+ *    - Supports custom separators, including spaces.
+ *    - Preserves decimals even if more than 2 digits.
+ * @param {string | number} value - The numeric value or string to format, can be plain numbers, or already formatted strings like `"1,234,567.89"`.
+ * @param {string} [separator=","] - The thousands separator to use, examples: `","` ***(default)***, `"."`, `" "`, etc.
+ * @returns {string} The formatted string with thousands separators and
+ *   appropriate decimal separator.
+ * @throws {TypeError} If `value` is not a string or number,
+ * or `separator` is not a string.
+ * @example
+ * formatNumber(1000000);
+ * // ➔ "1,000,000"
+ * formatNumber("987654321");
+ * // ➔ "987,654,321"
+ * formatNumber(1234567.89);
+ * // ➔ "1,234,567.89"
+ * formatNumber("1234567,89");
+ * // ➔ "1,234,567.89"
+ * formatNumber("1234567.892");
+ * // ➔ "1,234,567.892"
+ * formatNumber("1234567.89", ".");
+ * // ➔ "1.234.567,89"
+ * formatNumber("1234567,89", ",");
+ * // ➔ "1,234,567.89"
+ * formatNumber("987654321", " ");
+ * // ➔ "987 654 321"
+ * formatNumber("1,234,567.89");
+ * // ➔ "1,234,567.89"
+ * formatNumber("1.234.567,89", ",");
+ * // ➔ "1,234,567.89"
+ * formatNumber("1.234.567,893", ".");
+ * // ➔ "1.234.567,893"
+ * formatNumber("1234.56", ".");
+ * // ➔ "1.234,56"
+ * formatNumber("1234,56", ",");
+ * // ➔ "1,234.56"
+ */
+declare const formatNumber:(value:string|number,separator?:string)=>string;
+/** -------------------------------------------------------
+ * * ***Output format mode for {@link formatPhoneNumber|`formatPhoneNumber`}.***
+ * -------------------------------------------------------
+ * - `'E.164'`      ➔ `+6281234567890`
+ * - `'RFC3966'`    ➔ `tel:+62-812-3456-7890`
+ * - `'NATIONAL'`   ➔ `0812 3456 7890`
+ * - `'INTERNATIONAL'` ➔ `+62 812 3456 7890`
+ */
+type OutputFormat=ExtractStrict<NumberFormat,"INTERNATIONAL"|"NATIONAL"|"RFC3966"|"E.164">;
+/** -------------------------------------------------------
+ * * ***Single input value for {@link formatPhoneNumber|`formatPhoneNumber`}.***
+ * -------------------------------------------------------
+ * - **Accepts:**
+ *    - `string` — e.g. `"0812 3456 7890"`
+ *    - `number` — e.g. `81234567890`
+ *    - `null` or `undefined` — represents no input
+ * - **ℹ️ Notes**
+ *    - The function normalizes all **non-digit characters** (spaces, dots, dashes,
+ *      parentheses, etc.) before validation/formatting.
+ *    - When you pass a `number`, any **leading zeros are lost by JavaScript**.
+ *      - 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;
+/** -------------------------------------------------------
+ * * ***Base option set for {@link formatPhoneNumber|`formatPhoneNumber`}.***
+ * -------------------------------------------------------
+ * **All properties are optional.**
+ * @description
+ * Defaults apply when a property is omitted or `undefined`.
+ *
+ * **⚠️ Overload-aware notes:**
+ *    - If `checkValidOnly` is `true`, **all other properties are ignored**.
+ *    - If `takeNumberOnly` is `true`, **all formatting properties are ignored**.
+ *    - The leading `+` is **recommended** but not required;
+ *      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;};
+/** -------------------------------------------------------
+ * * ***Specialized options for the `transformPhoneNumber` variant of {@link formatPhoneNumber|`formatPhoneNumber`}.***
+ * -------------------------------------------------------
+ * **Ensures that `checkValidOnly` and `takeNumberOnly` are both
+ * forced to `false` when transforming/formatting.**
+ *
+ * This type is intended for scenarios where you **must** receive a formatted
+ * string as output and never a `boolean` or digit-only result.
+ *
+ * **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;};
+/** -------------------------------------------------------
+ * * ***Options subset for **validity-check mode** of
+ * {@link formatPhoneNumber|`formatPhoneNumber`}.***
+ * -------------------------------------------------------
+ * Only `checkValidOnly` is allowed.
+ * All formatting-related properties are **intentionally disallowed**
+ * to avoid mixing validation with formatting.
+ *
+ * **Example Usage:**
+ * ```ts
+ * 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>>;
+/** -------------------------------------------------------
+ * * ***Options subset for calling {@link formatPhoneNumber|`formatPhoneNumber`} in
+ * **digits-only mode**.***
+ * -------------------------------------------------------
+ * **Only `takeNumberOnly` is allowed; all other formatting options are
+ * intentionally disallowed.**
+ *
+ * Use this when you want a pure numeric string without any separators or country
+ * decorations, but still want the function to normalize the input.
+ *
+ * **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>>;
+/** -------------------------------------------------------
+ * * ***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;}>;
+/** -------------------------------------------------------
+ * * ***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;}>;
+/** -------------------------------------------------------
+ * * ***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;}>;
+/** -------------------------------------------------------
+ * * ***Utility: `formatPhoneNumber`.***
+ * -------------------------------------------------------
+ * **Formats a phone number into a customizable local or international style.**
+ * - **Type:** ***`Formatting Number`.***
+ * - **Can also:**
+ *    - Return only digits string when **digits-only mode** (`takeNumberOnly`):
+ *      - Return empty-string (""), if invalid number phone.
+ *    - Return boolean when **validity-check mode** (`checkValidOnly`):
+ *      - ***Return `true` if:***
+ *          - A phone number is "valid" when it has valid length, and the actual phone number digits match the
+ *            regular expressions for its country (parameter options `defaultCountry`).
+ * - **E.164 compliance:**
+ *    - Optional leading `+` is recommended but **not required**.
+ *    - If Without leading `+`, you must passing `defaultCountry`.
+ * @throws {TypeError} If `value` is not string, number, null or undefined.
+ * @throws {TypeError} If `options` is not an object or contains wrong types.
+ * @param {ValueFormatPhoneNumber} value
+ *  ***Phone number to format, accepts:***
+ *   - `string` (recommended to preserve leading zeros).
+ *   - `number` (leading zeros will be lost).
+ *   - `null` or `undefined` (returns empty string).
+ * @param {FormatPhoneNumberMain} [options]
+ *  ***Main options object controlling:***
+ *   - `separator` (**string**): Group separator, default `" "`.
+ *   - `plusNumberCountry` (**string**): Country code with optional leading `+`.
+ *   - `openingNumberCountry` (**string**): Characters before the country code, e.g. `"("`.
+ *   - `closingNumberCountry` (**string**): Characters after the country code, e.g. `")"`.
+ *   - `checkValidOnly` (**boolean**): Return only validity.
+ *   - `takeNumberOnly` (**boolean**): Return digits only.
+ *   - `defaultCountry` (**string** - **`<ISO-3166-1 alpha-2>`**): Used to interpret numbers without an explicit `+<countryCode>`.
+ * @returns {string|boolean} Formatted phone number string, digits-only string, or boolean.
+ * @overload
+ * @param {ValueFormatPhoneNumber} value The phone number input (string or number).
+ * @param {FormatPhoneNumberCheckValidOnly} [options] With `checkValidOnly: true`.
+ * Return a **validity-check mode** when `checkValidOnly: true`.
+ * @returns {boolean} A boolean indicating whether the input is a valid phone number.
+ * @overload
+ * @param {ValueFormatPhoneNumber} value The phone number input (string or number).
+ * @param {FormatPhoneNumberTransform} [options] With `takeNumberOnly: true`.
+ * Return **digits-only mode** when `takeNumberOnly: true`.
+ * @returns {string} A string of digits only.
+ * @overload
+ * @param {ValueFormatPhoneNumber} value The phone number input (string or number).
+ * @param {FormatPhoneNumberTakeNumberOnly} [options] Options to customize format output (country code, separator, etc).
+ * Return a **formatted phone number string** with custom formatting and (`checkValidOnly: false`, `takeNumberOnly: false`).
+ * @returns {string} Formatting number. return a string of digits only with formatter.
+ * @example
+ * 1. ***Formatting Phone Number String:***
+ * ```ts
+ * formatPhoneNumber("081234567890");
+ * // ➔ "0812 3456 7890"
+ * formatPhoneNumber("081234567890", {
+ *   separator: "-",
+ *   plusNumberCountry: "+44",
+ *   openingNumberCountry: "(",
+ *   closingNumberCountry: ")"
+ * });
+ * // ➔ "(+44) 8123-4567-890"
+ * ```
+ * 2. ***Digits-Only Mode:***
+ *    ```ts
+ *    formatPhoneNumber("(0812) 3456-7890", {
+ *      takeNumberOnly: true,
+ *      defaultCountry: "ID"
+ *    });
+ *    // ➔ "081234567890"
+ *    formatPhoneNumber("(0812) 3456-7890", { takeNumberOnly: true });
+ *    // ➔ ""
+ *    formatPhoneNumber("(63) 917 123 4567", {
+ *      takeNumberOnly: true,
+ *      defaultCountry: "PH"
+ *    });
+ *    // ➔ "0917 123 4567"
+ *    formatPhoneNumber("(63) 4567-8901", {
+ *      takeNumberOnly: true,
+ *      defaultCountry: "PH"
+ *    });
+ *    // ➔ "" // is not valid number from PH.
+ *    formatPhoneNumber("(63) 917 123 4567", { takeNumberOnly: true });
+ *    // ➔ ""
+ *    formatPhoneNumber("49 (151) 2345 6789", {
+ *      takeNumberOnly: true,
+ *      defaultCountry: "DE"
+ *    });
+ *    // ➔ "015123456789"
+ *    formatPhoneNumber("49 (151) 2345 6789", { takeNumberOnly: true });
+ *    // ➔ ""
+ *    ```
+ * 3. ***Validity-Check Mode:***
+ *    ```ts
+ *    formatPhoneNumber("+6281234567890", { checkValidOnly: true });
+ *    // ➔ true
+ *    formatPhoneNumber("0812-3456-7890", {
+ *      checkValidOnly: true,
+ *      defaultCountry: "ID"
+ *    });
+ *    // ➔ true
+ *    formatPhoneNumber("0812 3456 7890", { checkValidOnly: true });
+ *    // ➔ false
+ *    formatPhoneNumber("(0812) 3456-7890", {
+ *      checkValidOnly: true,
+ *      defaultCountry: "ID"
+ *    });
+ *    // ➔ true
+ *    formatPhoneNumber("(0812) 3456-7890", { checkValidOnly: true});
+ *    // ➔ false
+ *    formatPhoneNumber("+44 20 7946 0958", { checkValidOnly: true });
+ *    // ➔ true
+ *    formatPhoneNumber("+1 (800) 123-4567", { checkValidOnly: true });
+ *    // ➔ true
+ *    formatPhoneNumber("+62.812.3456.7890", { checkValidOnly: true });
+ *    // ➔ true
+ *    formatPhoneNumber("+62(812)3456-7890", { checkValidOnly: true });
+ *    // ➔ true
+ *    formatPhoneNumber("+62abc123", { checkValidOnly: true });
+ *    // ➔ false
+ *    formatPhoneNumber("invalid@@@", { checkValidOnly: true });
+ *    // ➔ false
+ *    formatPhoneNumber("0812-3456-hello", { checkValidOnly: true });
+ *    // ➔ false
+ *    ```
+ */
+declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatPhoneNumberTransform):string;
+/** -------------------------------------------------------
+ * * ***Utility: `formatPhoneNumber`.***
+ * -------------------------------------------------------
+ * **Formats a phone number into a customizable local or international style.**
+ * - **Type:** ***`Digits-only Mode`.***
+ * - **Can also:**
+ *    - Return only digits string when **digits-only mode** (`takeNumberOnly`).
+ *    - Return boolean when **validity-check mode** (`checkValidOnly`) using a
+ *      regex for international-style phone numbers:
+ *      - ***Valid if:***
+ *          - Only contains digits, optional leading `+`, spaces, parentheses `()`,
+ *            hyphens `-`, or dots `.`.
+ *          - Digits-only length < 16.
+ * - **E.164 compliance:**
+ *    - Optional leading `+` is recommended but **not required**.
+ *    - If Without leading `+`, you must passing `defaultCountry`.
+ * @throws {TypeError} If `value` is not string, number, null or undefined.
+ * @throws {TypeError} If `options` is not an object or contains wrong types.
+ * @param {ValueFormatPhoneNumber} value
+ *   Phone number to format. Accepts:
+ *   - `string` (recommended to preserve leading zeros)
+ *   - `number` (leading zeros will be lost)
+ *   - `null` or `undefined` (returns empty string).
+ * @param {FormatPhoneNumberTakeNumberOnly} [options] Options to customize format output (country code, separator, etc).
+ * @returns {string} Digits-only mode, return string a digits-only.
+ * @example
+ * ```ts
+ * formatPhoneNumber("(0812) 3456-7890", {
+ *   takeNumberOnly: true,
+ *   defaultCountry: "ID"
+ * });
+ * // ➔ "081234567890"
+ * formatPhoneNumber("(0812) 3456-7890", { takeNumberOnly: true });
+ * // ➔ ""
+ * formatPhoneNumber("(63) 917 123 4567", {
+ *   takeNumberOnly: true,
+ *   defaultCountry: "PH"
+ * });
+ * // ➔ "0917 123 4567"
+ * formatPhoneNumber("(63) 4567-8901", {
+ *   takeNumberOnly: true,
+ *   defaultCountry: "PH"
+ * });
+ * // ➔ "" // is not valid number from PH.
+ * formatPhoneNumber("(63) 917 123 4567", { takeNumberOnly: true });
+ * // ➔ ""
+ * formatPhoneNumber("49 (151) 2345 6789", {
+ *   takeNumberOnly: true,
+ *   defaultCountry: "DE"
+ * });
+ * // ➔ "015123456789"
+ * formatPhoneNumber("49 (151) 2345 6789", { takeNumberOnly: true });
+ * // ➔ ""
+ * ```
+ */
+declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatPhoneNumberTakeNumberOnly):string;
+/** -------------------------------------------------------
+ * * ***Utility: `formatPhoneNumber`.***
+ * -------------------------------------------------------
+ * **Formats a phone number into a customizable local or international style.**
+ * - **Type:** ***`Validity-check Mode`.***
+ * - **Can also:**
+ *    - Return only digits string when **digits-only mode** (`takeNumberOnly`).
+ *    - Return boolean when **validity-check mode** (`checkValidOnly`) using a
+ *      regex for international-style phone numbers:
+ *      - ***Valid if:***
+ *          - Only contains digits, optional leading `+`, spaces, parentheses `()`,
+ *            hyphens `-`, or dots `.`.
+ *          - Digits-only length < 16.
+ * - **E.164 compliance:**
+ *    - Optional leading `+` is recommended but **not required**.
+ *    - If Without leading `+`, you must passing `defaultCountry`.
+ * @throws {TypeError} If `value` is not string, number, null or undefined.
+ * @throws {TypeError} If `options` is not an object or contains wrong types.
+ * @param {ValueFormatPhoneNumber} value
+ *  Phone number to format. Accepts:
+ *   - `string` (recommended to preserve leading zeros).
+ *   - `number` (leading zeros will be lost).
+ *   - `null` or `undefined` (returns empty string).
+ * @param {FormatPhoneNumberTakeNumberOnly} [options] Options to customize format output (country code, separator, etc).
+ * @returns {boolean} Validity-check mode, return a boolean.
+ * @example
+ * ```ts
+ * formatPhoneNumber("+6281234567890", { checkValidOnly: true });
+ * // ➔ true
+ * formatPhoneNumber("0812-3456-7890", {
+ *   checkValidOnly: true,
+ *   defaultCountry: "ID"
+ * });
+ * // ➔ true
+ * formatPhoneNumber("0812 3456 7890", { checkValidOnly: true });
+ * // ➔ false
+ * formatPhoneNumber("(0812) 3456-7890", {
+ *   checkValidOnly: true,
+ *   defaultCountry: "ID"
+ * });
+ * // ➔ true
+ * formatPhoneNumber("(0812) 3456-7890", { checkValidOnly: true});
+ * // ➔ false
+ * formatPhoneNumber("+44 20 7946 0958", { checkValidOnly: true });
+ * // ➔ true
+ * formatPhoneNumber("+1 (800) 123-4567", { checkValidOnly: true });
+ * // ➔ true
+ * formatPhoneNumber("+62.812.3456.7890", { checkValidOnly: true });
+ * // ➔ true
+ * formatPhoneNumber("+62(812)3456-7890", { checkValidOnly: true });
+ * // ➔ true
+ * formatPhoneNumber("+62abc123", { checkValidOnly: true });
+ * // ➔ false
+ * formatPhoneNumber("invalid@@@", { checkValidOnly: true });
+ * // ➔ false
+ * formatPhoneNumber("0812-3456-hello", { checkValidOnly: true });
+ * // ➔ false
+ * ```
+ */
+declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatPhoneNumberCheckValidOnly):boolean;
+/** -------------------------------------------------------
+ * * ***Utility: `formatPhoneNumber`.***
+ * -------------------------------------------------------
+ * **Formats a phone number into a customizable local or international style.**
+ * - **Type:** ***Forced to `Validity-check Mode`***, because `checkValidOnly` has set to `true`.
+ * - **Can also:**
+ *    - Return only digits string when **digits-only mode** (`takeNumberOnly`).
+ *    - Return boolean when **validity-check mode** (`checkValidOnly`) using a
+ *      regex for international-style phone numbers:
+ *      - ***Valid if:***
+ *          - Only contains digits, optional leading `+`, spaces, parentheses `()`,
+ *            hyphens `-`, or dots `.`.
+ *          - Digits-only length < 16.
+ * - **E.164 compliance:**
+ *    - Optional leading `+` is recommended but **not required**.
+ *    - If Without leading `+`, you must passing `defaultCountry`.
+ * @throws {TypeError} If `value` is not string, number, null or undefined.
+ * @throws {TypeError} If `options` is not an object or contains wrong types.
+ * @param {ValueFormatPhoneNumber} value
+ *  Phone number to format. Accepts:
+ *   - `string` (recommended to preserve leading zeros).
+ *   - `number` (leading zeros will be lost).
+ *   - `null` or `undefined` (returns empty string).
+ * @param {FormatPhoneNumberTakeNumberOnly} [options] Options to customize format output (country code, separator, etc).
+ * @returns {boolean} Validity-check mode, return a boolean.
+ * @example
+ * ```ts
+ * formatPhoneNumber("+6281234567890", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ * });
+ * // ➔ true
+ * formatPhoneNumber("0812-3456-7890", {
+ *   defaultCountry: "ID",
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ * });
+ * // ➔ true
+ * formatPhoneNumber("0812 3456 7890", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ * });
+ * // ➔ false
+ * formatPhoneNumber("(0812) 3456-7890", {
+ *   defaultCountry: "ID",
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ * });
+ * // ➔ true
+ * formatPhoneNumber("(0812) 3456-7890", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true
+ * });
+ * // ➔ false
+ * formatPhoneNumber("+44 20 7946 0958", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true
+ * });
+ * // ➔ true
+ * formatPhoneNumber("+1 (800) 123-4567", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true
+ * });
+ * // ➔ true
+ * formatPhoneNumber("+62.812.3456.7890", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true
+ * });
+ * // ➔ true
+ * formatPhoneNumber("+62(812)3456-7890", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true
+ * });
+ * // ➔ true
+ * formatPhoneNumber("+62abc123", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true
+ * });
+ * // ➔ false
+ * formatPhoneNumber("invalid@@@", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true
+ * });
+ * // ➔ false
+ * formatPhoneNumber("0812-3456-hello", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true
+ * });
+ * // ➔ false
+ * ```
+ */
+declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatPhoneNumberAllPassingValidOnly):boolean;
+/** -------------------------------------------------------
+ * * ***Utility: `formatPhoneNumber`.***
+ * -------------------------------------------------------
+ * **Formats a phone number into a customizable local or international style.**
+ * - **Type:** ***Forced to `Digits-only Mode`***, because `takeNumberOnly` has set to `true`.
+ * - **Can also:**
+ *    - Return only digits string when **digits-only mode** (`takeNumberOnly`).
+ *    - Return boolean when **validity-check mode** (`checkValidOnly`) using a
+ *      regex for international-style phone numbers:
+ *      - ***Valid if:***
+ *          - Only contains digits, optional leading `+`, spaces, parentheses `()`,
+ *            hyphens `-`, or dots `.`.
+ *          - Digits-only length < 16.
+ * - **E.164 compliance:**
+ *    - Optional leading `+` is recommended but **not required**.
+ *    - If Without leading `+`, you must passing `defaultCountry`.
+ * @throws {TypeError} If `value` is not string, number, null or undefined.
+ * @throws {TypeError} If `options` is not an object or contains wrong types.
+ * @param {ValueFormatPhoneNumber} value
+ *   Phone number to format. Accepts:
+ *   - `string` (recommended to preserve leading zeros)
+ *   - `number` (leading zeros will be lost)
+ *   - `null` or `undefined` (returns empty string).
+ * @param {FormatPhoneNumberTakeNumberOnly} [options] Options to customize format output (country code, separator, etc).
+ * @returns {string} Digits-only mode, return string a digits-only.
+ * @example
+ * ```ts
+ * formatPhoneNumber("(0812) 3456-7890", {
+ *   defaultCountry: "ID",
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ "081234567890"
+ * formatPhoneNumber("(0812) 3456-7890", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ ""
+ * formatPhoneNumber("(63) 917 123 4567", {
+ *   defaultCountry: "PH",
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ "0917 123 4567"
+ * formatPhoneNumber("(63) 4567-8901", {
+ *   defaultCountry: "PH",
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ "" // is not valid number from PH.
+ * formatPhoneNumber("(63) 917 123 4567", { takeNumberOnly: true });
+ * // ➔ ""
+ * formatPhoneNumber("49 (151) 2345 6789", {
+ *   defaultCountry: "DE",
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ "015123456789"
+ * formatPhoneNumber("49 (151) 2345 6789", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ ""
+ * ```
+ */
+declare function formatPhoneNumber(value:ValueFormatPhoneNumber,options?:FormatPhoneNumberAllPassingTakeOnly):string;
+/** -------------------------------------------------------
+ * * ***Utility: `formatPhoneNumber`.***
+ * -------------------------------------------------------
+ * **Formats a phone number into a customizable local or international style.**
+ * - **Type:** ***Forced to `Validity-check Mode`***, because `checkValidOnly` and `takeNumberOnly` has set to `true`,
+ *          but `checkValidOnly` will prioritize one.
+ * - **Can also:**
+ *    - Return only digits string when **digits-only mode** (`takeNumberOnly`).
+ *    - Return boolean when **validity-check mode** (`checkValidOnly`) using a
+ *      regex for international-style phone numbers:
+ *      - ***Valid if:***
+ *          - Only contains digits, optional leading `+`, spaces, parentheses `()`,
+ *            hyphens `-`, or dots `.`.
+ *          - Digits-only length < 16.
+ * - **E.164 compliance:**
+ *    - Optional leading `+` is recommended but **not required**.
+ *    - If Without leading `+`, you must passing `defaultCountry`.
+ * @throws {TypeError} If `value` is not string, number, null or undefined.
+ * @throws {TypeError} If `options` is not an object or contains wrong types.
+ * @param {ValueFormatPhoneNumber} value
+ *  Phone number to format. Accepts:
+ *   - `string` (recommended to preserve leading zeros).
+ *   - `number` (leading zeros will be lost).
+ *   - `null` or `undefined` (returns empty string).
+ * @param {FormatPhoneNumberTakeNumberOnly} [options] Options to customize format output (country code, separator, etc).
+ * @returns {boolean} Validity-check mode, return a boolean.
+ * @example
+ * ```ts
+ * formatPhoneNumber("+6281234567890", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ true
+ * formatPhoneNumber("0812-3456-7890", {
+ *   defaultCountry: "ID",
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ true
+ * formatPhoneNumber("0812 3456 7890", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ false
+ * formatPhoneNumber("(0812) 3456-7890", {
+ *   defaultCountry: "ID",
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ true
+ * formatPhoneNumber("(0812) 3456-7890", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ false
+ * formatPhoneNumber("+44 20 7946 0958", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ true
+ * formatPhoneNumber("+1 (800) 123-4567", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ true
+ * formatPhoneNumber("+62.812.3456.7890", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ true
+ * formatPhoneNumber("+62(812)3456-7890", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ true
+ * formatPhoneNumber("+62abc123", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ false
+ * formatPhoneNumber("invalid@@@", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ false
+ * formatPhoneNumber("0812-3456-hello", {
+ *   // Formatting Phone Number Options
+ *   separator: "-",
+ *   // Validity-check Mode
+ *   checkValidOnly: true,
+ *   // Digits-only Mode
+ *   takeNumberOnly: true,
+ * });
+ * // ➔ 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";};
+/** ----------------------------------------------------------
+ * * ***Utility: `censorEmail`.***
+ * ----------------------------------------------------------
+ * **Censors an email by replacing characters with `"*"` while supporting random or fixed mode.**
+ * - **This function replaces parts of an email with asterisks to protect privacy.**
+ *    - **Modes:**
+ *        - `"fixed"` (default) – Deterministic censorship based on a hash of the email, same input always produces the same output.
+ *        - `"random"` – Each character is randomly replaced every time the function is called.
+ *    - **ℹ️ Note:**
+ *        - Invalid emails or non-string input will return an empty-string (`""`).
+ * @param {string | null | undefined} email - The email address to censor.
+ * @param {CensorEmailOptions} [options={}] - Options object for mode.
+ * @returns {string} The censored email, or an empty string if input is invalid.
+ * @throws {TypeError} If `options` is not a plain object or `mode` is invalid.
+ * @example
+ * // Fixed mode (default, deterministic)
+ * censorEmail("john.doe@gmail.com");
+ * // ➔ "j**n.**e@g***l.com"
+ *
+ * // Fixed mode explicitly
+ * censorEmail("john.doe@gmail.com", { mode: "fixed" });
+ * // ➔ "j**n.**e@g***l.com"
+ *
+ * // Random mode (output may vary each time)
+ * censorEmail("john.doe@gmail.com", { mode: "random" });
+ * // ➔ "j*hn.***e@g***l.com" (random)
+ *
+ * // Invalid email returns empty string
+ * 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;};
+/** ----------------------------------------------
+ * * ***Utility: `chunkString`.***
+ * ----------------------------------------------
+ * **Chunks a string by inserting a separator every `limiter` characters.**
+ * - **This function handles two main behaviors based on `reCountAfterSpace`:**
+ *    1. ***If `reCountAfterSpace` is `false` (default):***
+ *        - The separator is inserted strictly every `limiter` characters throughout the entire string, regardless of spaces, spaces are treated as regular characters in the count.
+ *            - Example: `chunkString("1234567890", 3, "-")` ➔ `"123-456-789-0"`.
+ *            - Example: `chunkString("Hello World", 3, "-")` ➔ `"Hel-lo -Wor-ld"`.
+ *    2. ***If `reCountAfterSpace` is `true`:***
+ *        - The function first processes the input string to replace any multiple consecutive spaces with a
+ *          single space (e.g., "A   B" becomes "A B").
+ *      Then, it treats the string as a sequence of "words" (segments separated by single spaces).
+ *            - Each word is processed independently:
+ *              - if a word's length exceeds the `limiter`, separators are inserted internally within that word.
+ *              - Words are then grouped. Each group will contain `limiter` number of words.
+ *              - Words within the same group are joined by the specified `separator`.
+ *              - Finally, these groups are joined by a single space, preserving the original word separation
+ *                structure between groups.
+ * @param {string} subject - ***The target string to chunk.****
+ * @param {number} limiter
+ *  ***The interval (number of characters) for inserting separators, behavior:***
+ *   - If `reCountAfterSpace = false`, it counts characters.
+ *   - If `reCountAfterSpace = true`, it counts both characters within words and words per group.
+ * @param {ChunkStringOptions} [options={}] - ***Optional settings for separator and counting behavior.***
+ * @returns {string} Return the formatted string with separators.
+ * @example
+ * // Basic usage
+ * chunkString("1234567890", 3);
+ * // ➔ "123 456 789 0"
+ *
+ * // Basic usage `reCountAfterSpace = false` (default)
+ * chunkString("1234567890", 3, { separator: "-");
+ * // ➔ "123-456-789-0"
+ * chunkString("HelloWorld", 2, { separator: "_", reCountAfterSpace: false });
+ * // ➔ "He_ll_oW_or_ld"
+ *
+ * // Usage with reCountAfterSpace = true:
+ * // Multiple spaces are normalized to single spaces before processing.
+ * chunkString("AB  CD   EF GH", 2, { separator: "-", reCountAfterSpace: true });
+ * // ➔ "AB-CD EF-GH" (after normalization to "AB CD EF GH")
+ * // Words "AB" and "CD" form a group and are joined by "-", "EF" and "GH" form another group.
+ * // The groups "AB-CD" and "EF-GH" are then joined by a space.
+ *
+ * // Another usage with reCountAfterSpace = true:
+ * chunkString("ABC DEF GHI JKL", 3, { separator: "-", reCountAfterSpace: true });
+ * // ➔ "ABC-DEF-GHI JKL"
+ * // Words "ABC", "DEF", "GHI" form a group and are joined by "-".
+ * // 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;};
+/** ----------------------------------------------------------
+ * * ***Utility: `truncateString`.***
+ * ----------------------------------------------------------
+ * **Features:**
+ * - Truncates a string to a specified length and optionally appends an ending.
+ * - Supports trimming the input before truncation.
+ * - If truncation occurs, trailing spaces before the ending are removed.
+ * - The `ending` parameter is always trimmed first; if empty, it defaults to `"..."`.
+ * @param {string|null|undefined} text
+ *  ***The input string to truncate, behavior:***
+ *    - If `null`, `undefined`, or empty after trim, returns `""`.
+ * @param {TruncateStringOptions} [options]
+ *  ***Optional settings:***
+ *    - `length` (number, default 10): Maximum length of the truncated string.
+ *    - `ending` (string, default `"..."`): String to append if truncation occurs.
+ *    - `trim` (boolean, default `true`): Whether to trim the input before truncation.
+ * @returns {string} The truncated string with optional trimming and ending.
+ *                   Returns `""` if input is empty or length < 1.
+ * @throws {TypeError} If `options.length` is not a finite number,
+ *                     or if `options.ending` is not a string,
+ *                     or if `options.trim` is not a boolean.
+ * @example
+ * truncateString("hello world", { length: 5 });
+ * // ➔ "hello..."
+ * truncateString("hello world", { length: 5, ending: "---" });
+ * // ➔ "hello---"
+ * truncateString("hello world", { length: 5, ending: "   " });
+ * // ➔ "hello..." (ending trimmed to default)
+ * truncateString("hello world", { length: 5, ending: "   !!!   " });
+ * // ➔ "hello!!!" (ending trimmed)
+ * truncateString("   long data string   ", { length: 8, ending: "...", trim: true });
+ * // ➔ "long dat..."
+ * truncateString("   long data string   ", { length: 8, ending: "...", trim: false });
+ * // ➔ "   long ..."
+ * truncateString(null, { length: 5 });
+ * // ➔ ""
+ */
+declare const truncateString:(text:string|null|undefined,options?:TruncateStringOptions)=>string;
+/** ----------------------------------------------------------------------
+ * * ***Options for formatting dates with `date-fns/format`.***
+ * ----------------------------------------------------------------------
+ *
+ * Extends the base **{@link FormatOptions | *`FormatOptions`*}** (without **`locale`**) with extra options
+ * for handling output formatting, localization, and parsing non-standard inputs.
+ *
+ * @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;}>;
+/** ----------------------------------------------------------
+ * * ***Utility: `formatDateFns`.***
+ * ----------------------------------------------------------
+ * **Formats a date into a human-readable string using `date-fns`.**
+ *  - **Features:**
+ *    - Supports custom output formats using `date-fns/format`.
+ *    - Can parse localized non-ISO strings via `inputFormat` & `inputLocale`.
+ *    - Supports `locale` as `"id"`, `"en"` or `date-fns` `Locale` objects (like `id` or `enUS`).
+ *    - Returns `null` if the date is invalid, not provided, or parsing fails.
+ * @param {string | Date | null | undefined} date
+ *  ***The date input to format, can be:***
+ *   - A `Date` object.
+ *   - An ISO string (e.g. `"2024-01-01T12:00:00Z"`).
+ *   - A localized string (requires `inputFormat` + `inputLocale`).
+ * @param {FormatDateFnsOptions} [options] ***Options for formatting and parsing.***
+ * @param {FormatDateFnsOptions["format"]} [options.format="dd MMM yyyy - HH:mm:ss"]
+ *   ***The output format string (passed to `date-fns/format`), e.g:***
+ *    - `"dd MMMM yyyy, HH:mm:ss" ➔ "14 Juli 2025, 17:25:42"`.
+ * @param {FormatDateFnsOptions["locale"]} [options.locale="id"]
+ *   The output locale. If string, only `"id"` (Indonesian) or `"en"` (English)
+ *   is recognized. Or you can pass a `date-fns` `Locale` object.
+ *   - Example:
+ *   ```ts
+ *     import { ar } from "date-fns/locale";
+ *     formatDateFns(new Date(), { locale: ar, format: "PPPppp" });
+ *   ```
+ * @param {FormatDateFnsOptions["inputLocale"]} [options.inputLocale]
+ *   Required if `date` is a localized non-ISO string. Used with `inputFormat`.
+ *   - Example for Indonesian string:
+ *   ```ts
+ *     formatDateFns("14 Juli 2025 10:25:42", { inputFormat: "dd MMMM yyyy HH:mm:ss", inputLocale: "id" });
+ *   ```
+ * @param {FormatDateFnsOptions["inputFormat"]} [options.inputFormat]
+ *   The format string to parse `date` if it is a non-ISO string.
+ *   Required together with `inputLocale`.
+ * @returns {string | null} A formatted date string or `null` if input is invalid.
+ * @example
+ * formatDateFns(new Date());
+ * // ➔ "14 Jul 2025 - 17:25:42"
+ * formatDateFns("2025-07-14T10:25:42Z", { format: "dd/MM/yyyy", locale: "en" });
+ * // ➔ "14/07/2025"
+ * formatDateFns("14 Juli 2025 10:25:42", {
+ *   inputFormat: "dd MMMM yyyy HH:mm:ss",
+ *   inputLocale: "id",
+ *   format: "yyyy-MM-dd"
+ * });
+ * // ➔ "2025-07-14"
+ * formatDateFns(null);
+ * // ➔ null
+ */
+declare const formatDateFns:(date:string|Date|null|undefined,options?:FormatDateFnsOptions)=>string|null;
+/** -------------------------------------------------------------
+ * * ***Supported IETF BCP-47 locale codes for Intl API.***
+ * -------------------------------------------------------------
+ * **This type ensures proper autocompletion & validation in TS
+ * but does not restrict at runtime (must validate separately).**
+ * - **Includes:**
+ *    - Major global locales (`en-US`, `fr-FR`, `zh-CN`, `etc`)
+ *    - Regional & minor locales (`mi-NZ`, `rw-RW`, `bi-VU`, `etc`)
+ *    - Useful for `Intl.DateTimeFormat`, `Intl.NumberFormat`, `etc`.
+ *    - Still allows fallback via `({} & string)` for arbitrary locales.
+ * @example
+ * 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);
+/** ----------------------------------------------------------------
+ * * ***Options for formatting dates with `Intl.DateTimeFormat`.***
+ * ----------------------------------------------------------------
+ * **Extends the native
+ * **{@link Intl.DateTimeFormatOptions | `Intl.DateTimeFormatOptions`}** with
+ * 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;};
+/** ----------------------------------------------------------
+ * * ***Utility: `formatDateIntl`.***
+ * ----------------------------------------------------------
+ * **Formats a date using the `Intl.DateTimeFormat` API.**
+ *  - **Features:**
+ *    - Supports custom locales (type-safe `SupportedLocales`).
+ *    - Accepts additional `Intl.DateTimeFormatOptions` like `timeZone`, `hour12`, etc.
+ *    - Defaults to `"en-US"` if `locale` is not provided or is an empty string.
+ *    - Returns `null` if the date is invalid, not provided, or options are invalid.
+ * @param {string | Date | null | undefined} date
+ *  ***The date to format.***
+ *    - Can be a `Date` object or an ISO string.
+ *    - If invalid or not provided, returns `null`.
+ * @param {FormatDateIntlOptions} [options] ***Optional formatting options for `Intl.DateTimeFormat`, use `locale` to specify the language & region format.***
+ * @returns {string | null}
+ *   - Formatted date string.
+ *   - Returns `null` if date is invalid or options are of wrong type.
+ * @example
+ * formatDateIntl(new Date());
+ * // ➔ "7/14/2025"
+ * formatDateIntl("2025-07-14T00:00:00Z", { locale: "fr-FR", dateStyle: "long" });
+ * // ➔ "14 juillet 2025"
+ * formatDateIntl(null);
+ * // ➔ null
+ * 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;
+/** ----------------------------------------------------------
+ * * ***Utility: `formatDateTime`.***
+ * ----------------------------------------------------------
+ * **Formats a date and time into a custom string format.**
+ *  - **Features:**
+ *    - Supports only `YYYY`, `MM`, `DD`, `hh`, `mm`, and `ss` as placeholders.
+ *    - Uses a simple string replace (no locale).
+ *    - Returns `null` if the date is invalid or not provided.
+ *    - Defaults to `"YYYY-MM-DD hh:mm:ss"` format if none is specified.
+ * @param {string | Date | null| undefined} date - The date to format.
+ * @param {string} [format="YYYY-MM-DD hh:mm:ss"] - The desired date format, if format is `null` or `undefined` will force to defaultValue, defaultValue is: `"YYYY-MM-DD hh:mm:ss"`.
+ * @returns {string | null} The formatted date string or `null` if invalid.
+ * @example
+ * formatDateTime(new Date());
+ * // ➔ "2024-02-09 14:30:45" (example output with current time)
+ * formatDateTime("2023-07-01T14:30:45");
+ * // ➔ "2023-07-01 14:30:45"
+ * formatDateTime("2023-07-01T14:30:45", "DD/MM/YYYY");
+ * // ➔ "01/07/2023"
+ * formatDateTime("2023-07-01T14:30:45", "YYYY/MM/DD hh-mm-ss");
+ * // ➔ "2023/07/01 14-30-45"
+ * formatDateTime("2023-07-01T14:30:45", "hh:mm");
+ * // ➔ "14:30"
+ * formatDateTime("2023-07-01T14:30:45", "DATE: YYYY.MM.DD");
+ * // ➔ "DATE: 2023.07.01"
+ * formatDateTime("2023-07-01T14:30:45", "Year: YYYY, Time: hh:mm:ss");
+ * // ➔ "Year: 2023, Time: 14:30:45"
+ * formatDateTime("2023-07-01T14:30:45", "YYYY-MM");
+ * // ➔ "2023-07"
+ * formatDateTime("2023-07-01T14:30:45", "YYYYYYYY");
+ * // ➔ "20232023"
+ * formatDateTime("2023-07-01T14:30:45", "hh:mm:ss:ss");
+ * // ➔ "14:30:45:45"
+ * formatDateTime("invalid-date");
+ * // ➔ null
+ * formatDateTime(null);
+ * // ➔ null
+ * formatDateTime(undefined);
+ * // ➔ null
+ */
+declare const formatDateTime:(date:string|Date|null|undefined,format?:string)=>string|null;
+/** ----------------------------------------------------------
+ * * ***Utility: `getGMTOffset`.***
+ * ----------------------------------------------------------
+ * **Returns the formatted GMT offset (e.g., `+0700`, `-0500`) for a given date.**
+ *  - **Features:**
+ *    - If `date` is **not provided** or empty string, it defaults to the current date/time.
+ *    - If `date` is **invalid** or of wrong type (like object or number), it returns `"0"`.
+ *    - The returned string follows the **GMT offset format** (`±HHMM`), where:
+ *      - `±` is `+` if ahead of UTC, `-` if behind.
+ *      - `HH` is two-digit hours.
+ *      - `MM` is two-digit minutes.
+ * @param {string | Date | null} [date]
+ *  ***The date to get the GMT offset from.***
+ *   - Accepts `Date` object or ISO date string (e.g., `"2024-01-01T12:00:00Z"`).
+ *   - If `null`, `undefined`, or empty string, uses current system date.
+ *   - If invalid date or wrong type (like `123` or `{}`), returns `"0"`.
+ * @returns {string} The GMT offset string in format `±HHMM`,
+ *   e.g. `"+0700"`, `"-0530"`, or `"0"` if invalid.
+ * @example
+ * getGMTOffset();
+ * // ➔ "+0700" (depends on your system timezone)
+ * getGMTOffset(new Date("2024-02-09T12:00:00Z"));
+ * // ➔ "+0000"
+ * getGMTOffset("2024-02-09");
+ * // ➔ "+0700" (depends on your system timezone)
+ * getGMTOffset("invalid-date");
+ * // ➔ "0"
+ * getGMTOffset(123);
+ * // ➔ "0"
+ */
+declare const getGMTOffset:(date?:string|Date|null)=>string;export{censorEmail,chunkString,formatCurrency,formatDateFns,formatDateIntl,formatDateTime,formatNumber,formatPhoneNumber,getGMTOffset,truncateString};