@rzl-zone/utils-js 2.0.1 → 3.0.0-beta.0

package/dist/formatting/index.d.ts

@@ -0,0 +1,912 @@
+import{O as OmitStrict}from'../omit-VvmIsZmX.js';import{Locale}from'date-fns/locale';import{FormatOptions}from'date-fns';import'../prettify-C4xLcYOP.js';import'../if-CvT4R7Kh.js';import'../type-data-DDs-u2kq.js';import'../never-BfayMBF9.js';type ValueFormatPhoneNumber=string|number|null;type FormatPhoneNumberProps={
+/** @default " " */
+separator?:string;
+/** @default "" */
+plusNumberCountry?:string;
+/** @default "" */
+openingNumberCountry?:string;
+/** @default "" */
+closingNumberCountry?:string;
+/** @default false */
+checkValidOnly?:boolean;
+/** @default false */
+takeNumberOnly?:boolean;};type FormatPhoneNumberPropsString=OmitStrict<FormatPhoneNumberProps,"checkValidOnly"|"takeNumberOnly">&{
+/** @default false */
+checkValidOnly?:false;
+/** @default false */
+takeNumberOnly?:false;};type FormatPhoneNumberPropsBoolean=OmitStrict<FormatPhoneNumberProps,"separator"|"plusNumberCountry"|"closingNumberCountry"|"openingNumberCountry"|"takeNumberOnly">;type FormatPhoneNumberPropsTransform=OmitStrict<FormatPhoneNumberProps,"separator"|"plusNumberCountry"|"closingNumberCountry"|"openingNumberCountry"|"checkValidOnly">;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;
+/** ---------------------------------------------------------------------------
+* * ***Options for `formatCurrency()`***
+* ---------------------------------------------------------------------------
+*/
+type FormatCurrencyOptions={
+/** ---------------------------------------------------------------------------
+* * ***Prefix currency string.***
+* ---------------------------------------------------------------------------
+*
+* Does not auto-keep input symbols.
+*
+* Example: `"Rp "` ➔ `Rp 1.000`.
+*
+* *DefaultValue: `""`.*
+*
+* @default ""
+*/
+suffixCurrency?:string;
+/** ---------------------------------------------------------------------------
+* * ***Thousands separator.***
+* ---------------------------------------------------------------------------
+*
+* Example: `"."` ➔ `1.000.000`.
+*
+* *DefaultValue: `"."`.*
+*
+* @default "."
+*/
+separator?:string;
+/** ---------------------------------------------------------------------------
+* * ***Prefix currency string.***
+* ---------------------------------------------------------------------------
+*
+* If `false`, rounds to integer.
+*
+* *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.***
+* ---------------------------------------------------------------------------
+*
+* E.g: (`".-"`, `" USD"`).
+*
+* *Example 1: `".-"` ➔ `1.000,00.-`.*
+*
+* *Example 2: `" USD"` ➔ `1.000,00 USD`.*
+*
+* *DefaultValue: `""`.*
+*
+*  @default ""
+*/
+suffixDecimal?:string;
+/** ---------------------------------------------------------------------------
+* * ***Rounding mode for decimals.***
+* ---------------------------------------------------------------------------
+*
+*  - `"round"` ➔ nearest
+*  - `"ceil"` ➔ always up
+*  - `"floor"` ➔ always down
+*  - `false` ➔ truncate
+*
+* *DefaultValue: `"round"`.*
+*
+*  @default "round"
+*/
+roundedDecimal?:"round"|"ceil"|"floor"|false;
+/** ---------------------------------------------------------------------------
+* * ***Decimal separator.***
+* ---------------------------------------------------------------------------
+*
+*  Example: `","` ➔ `1.000,10`
+*
+* *DefaultValue: `","`.*
+*
+*  @default ","
+*/
+separatorDecimals?:string;
+/** ---------------------------------------------------------------------------
+* * ***Negative formatting option.***
+* ---------------------------------------------------------------------------
+*
+*  Can be string ("dash" | "brackets" | "abs") or object with custom formatter.
+*
+*  - `"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.***
+* ---------------------------------------------------------------------------
+*
+*  If `true`, formats as Indian: `12,34,567`.
+*
+*  Also forces `separator: ","`, `separatorDecimals: "."`.
+*
+* *DefaultValue: `false`.*
+*
+*  @default false
+*/
+indianFormat?:boolean;};
+/** -------------------------------------------------------
+* * ***Formats a number or messy currency string into a
+*   beautifully formatted currency string, with highly
+*   customizable separators, decimal control, rounding,
+*   currency symbols, and negative styling.***
+* -------------------------------------------------------
+*
+* ✅ Highlights:
+* - Accepts:
+*    - Pure numbers: `15300.95`
+*    - Messy currency strings from **any locale**:
+*      - `"Rp 15.000,21"` (Indonesian / Euro)
+*      - `"$12,345.60"` (US)
+*      - `"CHF 12'345.60"` (Swiss)
+*      - `"1,23,456.78"` (Indian)
+* - Auto extracts numeric value with smart multi-locale parsing
+*   via `parseCurrencyString`.
+* - Handles:
+*    - Thousands separators: `.`, `,`, `'`, ` `
+*    - Decimal separators: `,`, `.`
+*    - Decimal suffix (eg. `".-"`, `" USD"`)
+*    - Currency prefix (eg. `"Rp "`, `"$ "`)
+*    - Rounding: `"round"`, `"ceil"`, `"floor"`, or truncate
+*    - Negative styling: dash `-`, brackets `( )`, absolute, or custom
+* - Strong type checks & clear errors for misconfigured options.
+*
+* ✅ How input is parsed:
+* - Removes all non-digit except `.`, `,`, `'` and spaces.
+* - Detects bracket negatives: `"(15.000,10)"` ➔ `-15000.10`
+* - Uses last `,` or `.` as decimal separator (others are thousands).
+* - Ignores currency symbols like `Rp`, `$` (must re-apply with `suffixCurrency`).
+*
+* ✅ Options:
+* @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 {string} [options.separator] Thousands separator:
+*    - `{ separator: "." }` ➔ `1.000.000`.
+*    - ***DefaultValue: `"."`***.
+*
+* @param {string} [options.separatorDecimals] Decimal separator:
+*    - `{ separatorDecimals: "," }` ➔ `1.000,10`.
+*    - ***DefaultValue: `","`***.
+*
+* @param {string} [options.suffixCurrency] Prefix currency string:
+*    - Does **not auto-keep input symbols**.
+*    - Must set manually e.g: `{ suffixCurrency: "Rp " }`.
+*        - `{ suffixCurrency: "Rp " }` ➔ `Rp 1.000`.
+*    - ***DefaultValue: `""`***.
+*
+* @param {boolean} [options.decimal] Show decimals:
+*    - If `false`, rounds to integer.
+*    - ***DefaultValue: `false`***.
+*
+* @param {number} [options.totalDecimal] Total decimal digits:
+*    - If `decimal: true` & `roundedDecimal: false`, simply cuts.
+*    - ***DefaultValue: `2`***.
+*
+* @param {string} [options.suffixDecimal] Text appended after decimals:
+*    - E.g: (`".-"`, `" USD"`).
+*    - Example 1: `".-"` ➔ `1.000,00.-`.
+*    - Example 2: `" USD"` ➔ `1.000,00 USD`.
+*    - ***DefaultValue: `""`***.
+*
+* @param {boolean} [options.endDecimal] Actually append `suffixDecimal`:
+*    - ***DefaultValue: `true`***.
+*
+* @param {"round"|"ceil"|"floor"|false} [options.roundedDecimal] Rounding mode:
+*    - `"round"` ➔ nearest
+*    - `"ceil"` ➔ always up
+*    - `"floor"` ➔ always down
+*    - `false` ➔ truncate
+*    - ***DefaultValue: `"round"`***.
+*
+* @param {"dash"|"brackets"|"abs"|{style?, space?, custom?}} [options.negativeFormat] How to format negatives:
+*    - `"dash"` ➔ `-15.000`
+*    - `"brackets"` ➔ `(15.000)`
+*    - `"abs"` ➔ `15.000` (always positive)
+*    - Or object:
+*         `{
+*            style: "dash"|"brackets"|"abs",
+*            space: true|false,
+*            custom: (formatted) => string
+*         }`.
+*    - ***DefaultValue: `"dash"`.***
+*
+* @param {boolean} [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:
+*    - `value` is not string or number
+*    - cannot parse to valid number
+*    - options have invalid types
+*
+* ---
+*
+* ***✅ Notes:***
+* - Always re-apply symbols via `suffixCurrency`.
+* - `parseCurrencyString` smartly detects last decimal,
+*   so `"1.121.234,56"` and `"1,121,234.56"` both parsed correctly.
+*/
+declare const formatCurrency:(value:string|number,options?:FormatCurrencyOptions)=>string;
+/** ----------------------------------------------------------
+* * ***Formats a number or numeric string by adding a custom separator
+* every three digits (thousands separator), and intelligently
+* flips the decimal separator according to the chosen separator.***
+* ----------------------------------------------------------
+*
+* - 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;
+/** -------------------------------------------------------
+* * ***Formats a phone number into a customizable local or international style.***
+* -------------------------------------------------------
+*
+* Can also:
+* - Return only digits (`takeNumberOnly`).
+* - Check validity (`checkValidOnly`) using a regex for international-style phone numbers.
+*
+* Validation (`checkValidOnly: true`)
+* Valid if:
+* - Only contains digits, optional leading `+`, spaces, parentheses `()`, hyphens `-`, or dots `.`.
+* - Digits-only length < 24.
+*
+* Example:
+* ```js
+* formatPhoneNumber("081234567890")
+* // => "0812 3456 7890"
+* ```
+*
+* Example:
+* ```js
+* formatPhoneNumber("(0812) 3456-7890", { takeNumberOnly: true })
+* // => "081234567890"
+* ```
+*
+* Example:
+* ```js
+* formatPhoneNumber("(0812) 3456-7890", { checkValidOnly: true })
+* // => true
+* ```
+*
+* Example:
+* ```js
+* formatPhoneNumber("+6281234567890", { checkValidOnly: true })
+* // => true
+* ```
+*
+* Example:
+* ```js
+* formatPhoneNumber("+1 (800) 123-4567", { checkValidOnly: true })
+* // => true
+* formatPhoneNumber("+44 20 7946 0958", { checkValidOnly: true })
+* // => true
+* ```
+*
+* Example:
+* ```js
+* formatPhoneNumber("0812-3456-7890", { checkValidOnly: true })
+* // => true
+* formatPhoneNumber("(0812) 3456 7890", { checkValidOnly: true })
+* // => true
+* formatPhoneNumber("0812 3456 7890", { checkValidOnly: true })
+* // => true
+* ```
+*
+* Example:
+* ```js
+* formatPhoneNumber("+62abc123", { checkValidOnly: true })
+* // => false
+* formatPhoneNumber("0812-3456-hello", { checkValidOnly: true })
+* // => false
+* formatPhoneNumber("+62 123456789012345678901234", { checkValidOnly: true })
+* // => false
+* formatPhoneNumber("++6281234567890", { checkValidOnly: true })
+* // => false
+* formatPhoneNumber("invalid@@@", { checkValidOnly: true })
+* // => false
+* ```
+*
+* Example:
+* ```js
+* formatPhoneNumber("+62.812.3456.7890", { checkValidOnly: true })
+* // => true
+* formatPhoneNumber("+62(812)3456-7890", { checkValidOnly: true })
+* // => true
+* ```
+*
+* Example:
+* ```js
+* formatPhoneNumber("081234567890", {
+*   separator: "-",
+*   plusNumberCountry: "+44",
+*   openingNumberCountry: "(",
+*   closingNumberCountry: ")",
+* })
+* // => "(+44) 8123-4567-890"
+* ```
+*
+* @throws {TypeError} If `value` is not string, number, null or undefined.
+* @throws {TypeError} If `options` is not an object or contains wrong types.
+*
+* @overload
+* @param value The phone number input (string or number).
+* @param options With `checkValidOnly: true`.
+* @returns A boolean indicating whether the input is a valid phone number.
+*
+* @overload
+* @param value The phone number input (string or number).
+* @param options With `takeNumberOnly: true`.
+* @returns A string of digits only.
+*
+* @overload
+* @param value The phone number input (string or number).
+* @param options Options to customize format output (country code, separator, etc).
+* @returns A formatted phone number string.
+*/
+declare function formatPhoneNumber(value?:ValueFormatPhoneNumber,options?:FormatPhoneNumberPropsString):string;declare function formatPhoneNumber(value?:ValueFormatPhoneNumber,options?:FormatPhoneNumberPropsBoolean):boolean;declare function formatPhoneNumber(value?:ValueFormatPhoneNumber,options?:FormatPhoneNumberPropsTransform):string;
+/**
+* -------------------------------------------------------------
+* * ***Supported IETF BCP-47 locale codes for Intl API.***
+* -------------------------------------------------------------
+*
+* 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.
+*
+* This type ensures proper autocompletion & validation in TS
+* but does not restrict at runtime (must validate separately).
+*
+* @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);
+/** ----------------------------------------------------------
+* * ***Formats a date and time into a custom string format.***
+* ----------------------------------------------------------
+*
+* - 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} [date] - The date to format.
+* @param {string} [format="YYYY-MM-DD hh:mm:ss"] - The desired date format.
+* @returns {string | null} The formatted date string or `null` if invalid.
+*
+* @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,
+/** @default "YYYY-MM-DD hh:mm:ss" */
+format?:string)=>string|null;
+/** ----------------------------------------------------------
+* * ***Formats a date using the `Intl.DateTimeFormat` API.***
+* ----------------------------------------------------------
+*
+* - Supports custom locales (type-safe `SupportedLocales`).
+* - Accepts additional `Intl.DateTimeFormatOptions` like `timeZone`, `hour12`, etc.
+* - Defaults to `"en-US"` if `locale` is not provided or is an empty string.
+* - Returns `null` if the date is invalid, not provided, or options are invalid.
+*
+* @param {string | Date | null | undefined} [date] - The date to format.
+*   Can be a `Date` object or an ISO string. If invalid or not provided, returns `null`.
+*
+* @param {Intl.DateTimeFormatOptions & { locale?: SupportedLocales | SupportedLocales[] }} [options]
+*   - 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,options?:Intl.DateTimeFormatOptions &{locale?:SupportedLocales|SupportedLocales[];})=>string|null;
+/** ----------------------------------------------------------
+* * ***Formats a date into a human-readable string using `date-fns`.***
+* ----------------------------------------------------------
+*
+* - Supports custom output formats using `date-fns/format`.
+* - Can parse localized non-ISO strings via `inputFormat` & `inputLocale`.
+* - Supports `locale` as `"id"`, `"en"` or `date-fns` `Locale` objects (like `id` or `enUS`).
+* - Returns `null` if the date is invalid, not provided, or parsing fails.
+*
+* @param {string | Date | null} [date] - The date input to format. Can be:
+*   - A `Date` object
+*   - An ISO string (e.g. `"2024-01-01T12:00:00Z"`)
+*   - A localized string (requires `inputFormat` + `inputLocale`)
+*
+* @param {object} [options] - Options for formatting and parsing.
+*
+* @param {string} [options.format="dd MMM yyyy - HH:mm:ss"]
+*   The output format string (passed to `date-fns/format`).
+*   E.g. `"dd MMMM yyyy, HH:mm:ss" => "14 Juli 2025, 17:25:42"`
+*
+* @param {"id" | "en" | (string & {}) | Locale} [options.locale="id"]
+*   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 {"id" | "en" | (string & {}) | Locale} [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 {string} [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,
+/**
+* Options for formatting and parsing a date using `date-fns`.
+*/
+options?:OmitStrict<FormatOptions,"locale",true,false>&{
+/**
+* Output format string using `date-fns/format`.
+* @default "dd MMM yyyy - HH:mm:ss"
+* @example "dd MMMM yyyy, HH:mm:ss"
+*/
+format?:string;
+/**
+* The locale to be used for formatting.
+* If `string` Only Accepts "id" for Indonesian or "en" for English.
+* Or you can put props `Locale` from `date-fns/locale`, e.g :
+*
+* ```ts
+*    import { ar } from "date-fns/locale";
+*
+*    // then passing `ar` to this props.
+*    formatDateFns(
+*    // your date input...,
+*    {
+*       locale: ar,
+*       //.... other options.
+*    });
+*
+* ```
+* @default "id"
+*/
+locale?:"id"|"en"|(string &{})|Locale;
+/**
+* The Input locale to be used for parsing `inputFormat`.
+* If `string` Only Accepts "id" for Indonesian or "en" for English.
+* Required if `date` is a non-standard string like "03 Mei 2025 10:25:42").
+*
+*  Or you can put props `Locale` from `date-fns/locale`, e.g :
+*
+* ```ts
+*    import { ar } from "date-fns/locale";
+*
+*    // then passing `ar` to this props.
+*    formatDateFns(
+*    // your date input...,
+*    {
+*        inputLocale: ar,
+*        //.... other options.
+*    });
+*```
+
+* @default undefined
+*/
+inputLocale?:"id"|"en"|(string &{})|Locale;
+/**
+* Input format string for parsing non-ISO string dates
+* (e.g., localized strings like "03 Mei 2025 10:25:42").
+* Required if `date` is a non-standard string.
+* @example "dd MMMM yyyy HH:mm:ss"
+*/
+inputFormat?:string;})=>string|null;
+/** ----------------------------------------------------------
+* * ***Returns the formatted GMT offset (e.g., `+0700`, `-0500`) for a given date.***
+* ----------------------------------------------------------
+*
+* - If `date` is **not provided** or empty string, it defaults to the current date/time.
+* - If `date` is **invalid** or of wrong type (like object or number), it returns `"0"`.
+* - The returned string follows the **GMT offset format** (`±HHMM`), where:
+*   - `±` is `+` if ahead of UTC, `-` if behind.
+*   - `HH` is two-digit hours.
+*   - `MM` is two-digit minutes.
+*
+* @param {string | Date | null} [date] - The date to get the GMT offset from.
+*   - Accepts `Date` object or ISO date string (e.g., `"2024-01-01T12:00:00Z"`).
+*   - If `null`, `undefined`, or empty string, uses current system date.
+*   - If invalid date or wrong type (like `123` or `{}`), returns `"0"`.
+*
+* @returns {string} The GMT offset string in format `±HHMM`,
+*   e.g. `"+0700"`, `"-0530"`, or `"0"` if invalid.
+*
+* @example
+* getGMTOffset();
+* // => "+0700" (depends on system timezone)
+*
+* getGMTOffset(new Date("2024-02-09T12:00:00Z"));
+* // => "+0000"
+*
+* getGMTOffset("2024-02-09");
+* // => "+0700" (depends on your timezone)
+*
+* getGMTOffset("invalid-date");
+* // => "0"
+*
+* getGMTOffset(123);
+* // => "0"
+*/
+declare const getGMTOffset:(date?:string|Date|null)=>string;type CensorEmailOptions={
+/** ----------------------------------------------------------
+* * ***Censorship Mode.***
+* ----------------------------------------------------------
+*
+* **Valid value:**
+* - `"fixed"` (default) – Deterministic censorship based on a hash of the email.
+*   The same input always produces the same output.
+* - `"random"` – Each character is randomly replaced every time the function is called.
+*/
+mode?:"random"|"fixed";};
+/** ----------------------------------------------------------
+* * ***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.
+*
+* 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,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`, counting is continuous across the whole string,
+*   treating spaces as normal characters.
+*
+* @default false
+*/
+reCountAfterSpace?:boolean;};
+/** ----------------------------------------------
+* * ***Chunks a string by inserting a separator every `limiter` characters.***
+* ----------------------------------------------
+*
+* This function handles two main behaviors based on `reCountAfterSpace`:
+*
+* 1. If `reCountAfterSpace` is `false` (default):
+* The separator is inserted strictly every `limiter` characters throughout the entire string,
+* regardless of spaces. Spaces are treated as regular characters in the count.
+* Example: `chunkString("1234567890", 3, "-")` returns `"123-456-789-0"`.
+* Example: `chunkString("Hello World", 3, "-")` returns `"Hel-lo -Wor-ld"`.
+*
+* 2. If `reCountAfterSpace` is `true`:
+* The function first processes the input string to replace any multiple consecutive spaces
+* with a single space (e.g., "A   B" becomes "A B").
+* Then, it treats the string as a sequence of "words" (segments separated by single spaces).
+* - Each word is processed independently: if a word's length exceeds the `limiter`,
+* separators are inserted internally within that word.
+* - Words are then grouped. Each group will contain `limiter` number of words.
+* Words within the same group are joined by the specified `separator`.
+* - Finally, these groups are joined by a single space, preserving the original word separation structure
+* between groups.
+*
+* @param {string} subject - The target string to chunk.
+* @param {number} limiter - The interval (number of characters) for inserting separators.
+*   - If `reCountAfterSpace = false`, it counts characters.
+*   - If `reCountAfterSpace = true`, it counts both characters within words and words per group.
+* @param {ChunkStringOptions} [options={}] - Optional settings for separator and counting behavior.
+* @returns {string} - The formatted string with separators.
+*
+* @example
+* // Basic usage
+* chunkString("1234567890", 3);
+* // ➔ "123 456 789 0"
+*
+* @example
+* // Basic usage `reCountAfterSpace = false` (default)
+* chunkString("1234567890", 3, { separator: "-");
+* // ➔ "123-456-789-0"
+* chunkString("HelloWorld", 2, { separator: "_", reCountAfterSpace: false });
+* // ➔ "He_ll_oW_or_ld"
+*
+* @example
+* // Usage with reCountAfterSpace = true:
+* // Multiple spaces are normalized to single spaces before processing.
+* chunkString("AB  CD   EF GH", 2, { separator: "-", reCountAfterSpace: true });
+* // ➔ "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.
+*
+* @example
+* // 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;};
+/** ----------------------------------------------------------
+* * ***Truncates a string to a specified length and optionally appends an ending.***
+* * ***Supports trimming the input before truncation.***
+* * ***If truncation occurs, trailing spaces before the ending are removed.***
+* * ***The `ending` parameter is always trimmed first; if empty, it defaults to `"..."`.***
+* ----------------------------------------------------------
+*
+* @param {string|null|undefined} text - The input string to truncate.
+*        If `null`, `undefined`, or empty after trim, returns `""`.
+* @param {TruncateStringOptions} [options] - Optional settings:
+*        - `length` (number, default 10): Maximum length of the truncated string.
+*        - `ending` (string, default `"..."`): String to append if truncation occurs.
+*        - `trim` (boolean, default true): Whether to trim the input before truncation.
+*
+* @returns {string} The truncated string with optional trimming and ending.
+*                   Returns `""` if input is empty or length < 1.
+*
+* @throws {TypeError} If `options.length` is not a finite number,
+*                     or if `options.ending` is not a string,
+*                     or if `options.trim` is not a boolean.
+*
+* @example
+* truncateString("hello world", { length: 5 });
+* // ➔ "hello..."
+*
+* truncateString("hello world", { length: 5, ending: "---" });
+* // ➔ "hello---"
+*
+* truncateString("hello world", { length: 5, ending: "   " });
+* // ➔ "hello..." (ending trimmed to default)
+*
+* truncateString("hello world", { length: 5, ending: "   !!!   " });
+* // ➔ "hello!!!" (ending trimmed)
+*
+* truncateString("   long data string   ", { length: 8, ending: "...", trim: true });
+* // ➔ "long dat..."
+*
+* truncateString("   long data string   ", { length: 8, ending: "...", trim: false });
+* // ➔ "   long ..."
+*
+* truncateString(null, { length: 5 });
+* // ➔ ""
+*
+*/
+declare const truncateString:(text?:string|null,options?:TruncateStringOptions)=>string;export{censorEmail,chunkString,formatCurrency,formatDateFns,formatDateIntl,formatDateTime,formatNumber,formatPhoneNumber,getGMTOffset,truncateString};