@rzl-zone/utils-js 3.12.0 → 3.12.1-beta.0

package/dist/index-DPs1_p5G.d.cts

@@ -0,0 +1,760 @@
+/*!
+* ========================================================================
+*  @rzl-zone/utils-js
+* ------------------------------------------------------------------------
+*  Version: `3.12.1-beta.0`
+*  Author: `Rizalvin Dwiky <rizalvindwiky@gmail.com>`
+*  Repository: `https://github.com/rzl-zone/rzl-zone/tree/main/packages/utils-js`
+* ========================================================================
+*/
+
+import { Extends, Nilable } from "@rzl-zone/ts-types-plus";
+type CapitalizeFirstOptions = {
+  /** If true **(default)**, the rest of the string will be converted to lowercase after capitalizing the first letter.
+   *
+   * @default true
+   */
+  lowerCaseNextRest?: boolean;
+  /** If true, the string will trimmed, default: `false`.
+   *
+   * @default false
+   */
+  trim?: boolean;
+};
+/** ----------------------------------------------------------
+ * * ***Utility: `capitalizeFirst`.***
+ * ----------------------------------------------------------
+ * **Capitalizes the first letter of a string, with optionally lowercases the rest and trims whitespace.**
+ * @param {string | null | undefined} string - The string to be processed.
+ * @param {CapitalizeFirstOptions} [options] - Options to control behavior.
+ * @param {CapitalizeFirstOptions["lowerCaseNextRest"]} [options.lowerCaseNextRest=true] - If true, lowercases the rest (next first letter), default: `true`.
+ * @param {CapitalizeFirstOptions["trim"]} [options.trim=false] - If true, trims the string before processing, default: `false`.
+ * @returns {string} The processed string, returns `""` if input is `null`, `undefined`, or `not a valid string`.
+ * @example
+ * ```ts
+ * capitalizeFirst(" hello WORLD ");
+ * // ➔ " Hello world"
+ * capitalizeFirst(" hello WORLD ", { trim: true });
+ * // ➔ "Hello world"
+ * capitalizeFirst("FOO", { lowerCaseNextRest: false });
+ * // ➔ "FOO"
+ * capitalizeFirst("   foo BAR   ", { trim: true, lowerCaseNextRest: false });
+ * // ➔ "Foo BAR"
+ * ```
+ * #### ℹ️ If null, undefined, or not a valid string input, return `""`.
+ * ```ts
+ * capitalizeFirst(123);
+ * capitalizeFirst(null);
+ * capitalizeFirst(undefined);
+ * // ➔ ""
+ * ```
+ */
+declare const capitalizeFirst: (string: string | null | undefined, options?: CapitalizeFirstOptions) => string;
+type CapitalizeWordsOptions = {
+  /** If `true`, removes leading and trailing spaces, default `false`.
+   *
+   * @default false
+   */
+  trim?: boolean;
+  /** If `true`, collapses multiple spaces **between words** into a single space (while preserving leading/trailing spaces), default `false`.
+   *
+   * @default false
+   */
+  collapseSpaces?: boolean;
+};
+/** ----------------------------------------------------------
+ * * ***Utility: `capitalizeWords`.***
+ * ----------------------------------------------------------
+ * **Capitalizes the first letter of each word in a string while converting the rest to lowercase.**
+ * @param {string | null | undefined} value
+ *  ***The input string to be processed.***
+ *   - If `null` or `undefined`, returns an empty-string (`""`).
+ * @param {CapitalizeWordsOptions} [options]
+ *  ***Optional settings to control the output:***
+ *   - `trim`: If `true`, removes leading and trailing spaces, defaultValue: `false`.
+ *   - `collapseSpaces`: If `true`, collapses multiple spaces **between words** into a single space (while preserving leading/trailing spaces), defaultValue: `false`.
+ * @returns {string} A new string where each word starts with an uppercase letter
+ * and the remaining letters are lowercase.
+ *  - If `value` is `empty`, `null`, or `undefined`, returns an `empty-string`.
+ * @example
+ * ```ts
+ * capitalizeWords("  hello   world  ");
+ * // ➔ "  Hello   World  "
+ * capitalizeWords("  hello   world  ", { trim: true });
+ * // ➔ "Hello   World"
+ * capitalizeWords("  hello   world  ", { collapseSpaces: true });
+ * // ➔ "  Hello World  "
+ * capitalizeWords("  hello   world  ", { trim: true, collapseSpaces: true });
+ * // ➔ "Hello World"
+ * ```
+ * #### ℹ️ If null, undefined, or not a valid string input, return "".
+ * ```ts
+ * capitalizeWords(123);
+ * capitalizeWords(null);
+ * capitalizeWords(undefined);
+ * // ➔ ""
+ * ```
+ */
+declare const capitalizeWords: (value: string | null | undefined, options?: CapitalizeWordsOptions) => string;
+/** --------------------------------------------------
+ * * ***Represents a string input.***
+ * --------------------------------------------------
+ * - **Can be one of:**
+ *    - A single `string`
+ *    - An array of strings (`string[]`)
+ *    - A readonly array of strings (`readonly string[]`)
+ *    - `null` or `undefined`
+ * @template T - A string or array of strings.
+ * @private ***types input for {@link toCamelCase}, {@link toPascalCaseSpace}, {@link toPascalCase}, {@link toLowerCase}, {@link toKebabCase}, {@link toSnakeCase}, {@link toDotCase} and {@link slugify}.***
+ */
+type StringLike = Nilable<string | string[] | ReadonlyArray<string>>;
+/** --------------------------------------------------
+ * * ***Represents a collection of strings.***
+ * --------------------------------------------------
+ * - **Can be one of:**
+ *    - A single `string`
+ *    - An array of strings (`string[]`)
+ *    - A readonly array of strings (`readonly string[]`)
+ *    - A `Set<string>`
+ *    - A `ReadonlySet<string>`
+ * @private ***types options for {@link toCamelCase}, {@link toPascalCaseSpace}, {@link toPascalCase}, {@link toLowerCase}, {@link toKebabCase}, {@link toSnakeCase}, {@link toDotCase} and {@link slugify}.***
+ */
+type StringCollection = string | string[] | ReadonlyArray<string> | Set<string> | ReadonlySet<string>;
+/** ----------------------------------------------------------
+ * * ***Utility: `slugify`.***
+ * ----------------------------------------------------------
+ * **Slugifies a string (or array of strings) for safe use in URLs, with optionally leaving specific words unchanged.**
+ * - **Behavior:**
+ *    - Accepts a `string` or an `array of strings`:
+ *      - If an array is provided, elements are trimmed, empty ones removed,
+ *        then joined with `"-"` before conversion.
+ *    - Splits the input by non-alphanumeric characters
+ *      (spaces, punctuation, symbols, hyphens, underscores, emojis, etc.).
+ *    - The first word is fully lowercase; subsequent words are capitalized.
+ *    - Words listed in `ignoreWord` remain unchanged in the output.
+ *    - `ignoreWord` is normalized (trimmed, delimiters removed), empty values ignored.
+ *    - `ignoreWord` accepts:
+ *      - a single string,
+ *      - an array of strings, or
+ *      - a `Set` of strings.
+ *    - Multiple delimiters collapse into one; empty segments ignored.
+ *    - Returns `""` if the input is `null`, `undefined`, or empty.
+ * @param {StringLike} input - The string or array to convert. Returns `""` if empty, `null`, or `undefined`.
+ * @param {StringCollection} [ignoreWord] - Optional word(s) to leave unchanged in the output.
+ * @returns {string} The slugified string.
+ * @example
+ * // Basic usage
+ * slugify("Hello World!");
+ * // ➔ "hello-world"
+ *
+ * // Array input is joined before conversion
+ * slugify(["Join", "Words", "Here"]);
+ * // ➔ "join-words-here"
+ *
+ * // Trims and cleans input
+ * slugify(" --- Convert to Slug? --- ");
+ * // ➔ "convert-to-slug"
+ *
+ * // Ignore single word
+ * slugify("This URL path", "URL");
+ * // ➔ "this-URL-path"
+ *
+ * // Ignore multiple words
+ * slugify("ignore API and URL", ["API", "URL"]);
+ * // ➔ "ignore-API-and-URL"
+ *
+ * // Ignore using Set
+ * slugify("ignore API and URL", new Set(["API", "URL"]));
+ * // ➔ "ignore-API-and-URL"
+ *
+ * // Supports emojis and symbols
+ * slugify("🔥 Fire_and_ice ❄️");
+ * // ➔ "fire-and-ice"
+ *
+ * // Null, Undefined or empty (string or array) input returns empty string
+ * slugify(undefined);
+ * // ➔ ""
+ */
+declare const slugify: (input: StringLike, ignoreWord?: StringCollection) => string;
+/** ----------------------------------------------------------
+ * * ***Utility: `toCamelCase`.***
+ * ----------------------------------------------------------
+ * **Converts a string (or array of strings) into `camelCase`, with optionally leaving specific words unchanged.**
+ * - **Behavior:**
+ *    - Accepts a `string` or an `array of strings`:
+ *      - If an array is provided, elements are trimmed, empty ones removed,
+ *        then joined with `"-"` before conversion.
+ *    - Splits the input by non-alphanumeric characters
+ *      (spaces, punctuation, symbols, hyphens, underscores, emojis, etc.).
+ *    - The first word is fully lowercase; subsequent words are capitalized.
+ *    - Words listed in `ignoreWord` remain unchanged in the output.
+ *    - `ignoreWord` is normalized (trimmed, delimiters removed), empty values ignored.
+ *    - `ignoreWord` accepts:
+ *      - a single string,
+ *      - an array of strings, or
+ *      - a `Set` of strings.
+ *    - Multiple delimiters collapse into one; empty segments ignored.
+ *    - Returns `""` if the input is `null`, `undefined`, or empty.
+ * @param {StringLike} input - The string or array to convert. Returns `""` if empty, `null`, or `undefined`.
+ * @param {StringCollection} [ignoreWord] - Optional word(s) to leave unchanged in the output.
+ * @returns {string} The camelCase formatted string.
+ * @example
+ * // Basic usage
+ * toCamelCase("hello world");
+ * // ➔ "helloWorld"
+ *
+ * // Array input is joined before conversion
+ * toCamelCase(["Join", "Words", "Here"]);
+ * // ➔ "joinWordsHere"
+ *
+ * // Supports mixed delimiters
+ * toCamelCase("convert_to-camel case");
+ * // ➔ "convertToCamelCase"
+ *
+ * // Words in ignoreWord stay unchanged
+ * toCamelCase("this URL path will ignore", "URL");
+ * // ➔ "thisURLPathWillIgnore"
+ *
+ * // Multiple ignored words
+ * toCamelCase("ignore API and URL", ["API", "URL"]);
+ * // ➔ "ignoreAPIAndURL"
+ *
+ * // Set can also be used
+ * toCamelCase("ignore API and URL", new Set(["API", "URL"]));
+ * // ➔ "ignoreAPIAndURL"
+ *
+ * // Null, Undefined or empty (string or array) input returns empty string
+ * toCamelCase(null);
+ * // ➔ ""
+ */
+declare const toCamelCase: (input: StringLike, ignoreWord?: StringCollection) => string;
+/** ----------------------------------------------------------
+ * * ***Utility: `toDotCase`.***
+ * ----------------------------------------------------------
+ * **Converts a string (or array of strings) into `dot.case`, with optionally leaving specific words unchanged.**
+ * - **Behavior:**
+ *    - Accepts a `string` or an `array of strings`:
+ *      - If an array is provided, elements are trimmed, empty ones removed,
+ *        then joined with `"-"` before conversion.
+ *    - Splits the input by non-alphanumeric characters
+ *      (spaces, punctuation, symbols, hyphens, underscores, emojis, etc.).
+ *    - The first word is fully lowercase; subsequent words are capitalized.
+ *    - Words listed in `ignoreWord` remain unchanged in the output.
+ *    - `ignoreWord` is normalized (trimmed, delimiters removed), empty values ignored.
+ *    - `ignoreWord` accepts:
+ *      - a single string,
+ *      - an array of strings, or
+ *      - a `Set` of strings.
+ *    - Multiple delimiters collapse into one; empty segments ignored.
+ *    - Returns `""` if the input is `null`, `undefined`, or empty.
+ * @param {StringLike} input - The string or array to convert. Returns `""` if empty, `null`, or `undefined`.
+ * @param {StringCollection} [ignoreWord] - Optional word(s) to leave unchanged in the output.
+ * @returns {string} The dot.case formatted string.
+ * @example
+ * // Basic usage
+ * toDotCase("Hello World");
+ * // ➔ "hello.world"
+ *
+ * // Array input is joined before conversion
+ * toDotCase(["Join", "Words", "Here"]);
+ * // ➔ "join.words.here"
+ *
+ * // Handles underscores and hyphens
+ * toDotCase("convert-to_dot case");
+ * // ➔ "convert.to.dot.case"
+ *
+ * // Multiple delimiters and trimming
+ * toDotCase("___Hello--World__ again!!");
+ * // ➔ "hello.world.again"
+ *
+ * // Supports emojis and symbols
+ * toDotCase("🔥Fire_and-ice❄️");
+ * // ➔ "fire.and.ice"
+ *
+ * // Ignore single word
+ * toDotCase("this URL path", "URL");
+ * // ➔ "this.URL.path"
+ *
+ * // Ignore multiple words
+ * toDotCase("ignore API and URL", ["API", "URL"]);
+ * // ➔ "ignore.API.and.URL"
+ *
+ * // Ignore using Set
+ * toDotCase("ignore API and URL", new Set(["API", "URL"]));
+ * // ➔ "ignore.API.and.URL"
+ *
+ * // Null, Undefined or empty (string or array) input returns empty string
+ * toDotCase(undefined);
+ * // ➔ ""
+ */
+declare const toDotCase: (input: StringLike, ignoreWord?: StringCollection) => string;
+/** ----------------------------------------------------------
+ * * ***Utility: `toKebabCase`.***
+ * ----------------------------------------------------------
+ * **Converts a string (or array of strings) into `kebab-case`, with optionally leaving specific words unchanged.**
+ * - **Behavior:**
+ *    - Accepts a `string` or an `array of strings`:
+ *      - If an array is provided, elements are trimmed, empty ones removed,
+ *        then joined with `"-"` before conversion.
+ *    - Splits the input by non-alphanumeric characters
+ *      (spaces, punctuation, symbols, hyphens, underscores, emojis, etc.).
+ *    - The first word is fully lowercase; subsequent words are capitalized.
+ *    - Words listed in `ignoreWord` remain unchanged in the output.
+ *    - `ignoreWord` is normalized (trimmed, delimiters removed), empty values ignored.
+ *    - `ignoreWord` accepts:
+ *      - a single string,
+ *      - an array of strings, or
+ *      - a `Set` of strings.
+ *    - Multiple delimiters collapse into one; empty segments ignored.
+ *    - Returns `""` if the input is `null`, `undefined`, or empty.
+ * @param {StringLike} input - The string or array to convert. Returns `""` if empty, `null`, or `undefined`.
+ * @param {StringCollection} [ignoreWord] - Optional word(s) to leave unchanged in the output.
+ * @returns {string} The kebab-case formatted string.
+ * @example
+ * // Basic usage
+ * toKebabCase("Hello World");
+ * // ➔ "hello-world"
+ *
+ * // Array input is joined before conversion
+ * toKebabCase(["Join", "Words", "Here"]);
+ * // ➔ "join-words-here"
+ *
+ * // Handles underscores and hyphens
+ * toKebabCase("convert_to-kebab case");
+ * // ➔ "convert-to-kebab-case"
+ *
+ * // Handles emojis and symbols
+ * toKebabCase("🔥fire___and--ice❄️");
+ * // ➔ "fire-and-ice"
+ *
+ * // Ignore specific word
+ * toKebabCase("ignore URL case", "URL");
+ * // ➔ "ignore-URL-case"
+ *
+ * // Ignore multiple words
+ * toKebabCase("ignore API and URL", ["API", "URL"]);
+ * // ➔ "ignore-API-and-URL"
+ *
+ * // Ignore with Set
+ * toKebabCase("ignore API and URL", new Set(["API", "URL"]));
+ * // ➔ "ignore-API-and-URL"
+ *
+ * // Null, Undefined or empty (string or array) input returns empty string
+ * toKebabCase(null);
+ * // ➔ ""
+ */
+declare const toKebabCase: (input: StringLike, ignoreWord?: StringCollection) => string;
+/** ----------------------------------------------------------
+ * * ***Utility: `toLowerCase`.***
+ * ----------------------------------------------------------
+ * **Converts a string (or array of strings) into `lower case`, with optionally leaving specific words unchanged.**
+ * - **Behavior:**
+ *    - Accepts a `string` or an `array of strings`:
+ *      - If an array is provided, elements are trimmed, empty ones removed,
+ *        then joined with `"-"` before conversion.
+ *    - Splits the input by non-alphanumeric characters
+ *      (spaces, punctuation, symbols, hyphens, underscores, emojis, etc.).
+ *    - The first word is fully lowercase; subsequent words are capitalized.
+ *    - Words listed in `ignoreWord` remain unchanged in the output.
+ *    - `ignoreWord` is normalized (trimmed, delimiters removed), empty values ignored.
+ *    - `ignoreWord` accepts:
+ *      - a single string,
+ *      - an array of strings, or
+ *      - a `Set` of strings.
+ *    - Multiple delimiters collapse into one; empty segments ignored.
+ *    - Returns `""` if the input is `null`, `undefined`, or empty.
+ * @param {StringLike} input - The string or array to convert. Returns `""` if empty, `null`, or `undefined`.
+ * @param {StringCollection} [ignoreWord] - Optional word(s) to leave unchanged in the output.
+ * @returns {string} The LowerCase formatted string.
+ * @example
+ * // Basic usage
+ * toLowerCase("Hello World");
+ * // ➔ "hello world"
+ *
+ * // Array input is joined before conversion
+ * toLowerCase(["Join", "WORLD", "Here"]);
+ * // ➔ "join words here"
+ *
+ * // Handles underscores and hyphens
+ * toLowerCase("convert_to-pascal case");
+ * // ➔ "convert to lower case"
+ *
+ * // Trims extra delimiters
+ * toLowerCase("___hello--world__ again!!");
+ * // ➔ "hello world again"
+ *
+ * // Supports emojis and symbols
+ * toLowerCase("🔥fire_and-ice❄️");
+ * // ➔ "fire and ice"
+ *
+ * // Ignore single word
+ * toLowerCase("this URL path will ignore", "URL");
+ * // ➔ "this URL path will ignore"
+ *
+ * // Ignore multiple words
+ * toLowerCase("ignore API and URL", ["API", "URL"]);
+ * // ➔ "ignore API and URL"
+ *
+ * // Ignore using Set
+ * toLowerCase("ignore API and URL", new Set(["API", "URL"]));
+ * // ➔ "ignore API and URL"
+ *
+ * // Null, Undefined or empty (string or array) input returns empty string
+ * toLowerCase(undefined);
+ * // ➔ ""
+ */
+declare const toLowerCase: (input: StringLike, ignoreWord?: StringCollection) => string;
+/** ----------------------------------------------------------
+ * * ***Utility: `toPascalCase`.***
+ * ----------------------------------------------------------
+ * **Converts a string (or array of strings) into `PascalCase`, with optionally leaving specific words unchanged.**
+ * - **Behavior:**
+ *    - Accepts a `string` or an `array of strings`:
+ *      - If an array is provided, elements are trimmed, empty ones removed,
+ *        then joined with `"-"` before conversion.
+ *    - Splits the input by non-alphanumeric characters
+ *      (spaces, punctuation, symbols, hyphens, underscores, emojis, etc.).
+ *    - The first word is fully lowercase; subsequent words are capitalized.
+ *    - Words listed in `ignoreWord` remain unchanged in the output.
+ *    - `ignoreWord` is normalized (trimmed, delimiters removed), empty values ignored.
+ *    - `ignoreWord` accepts:
+ *      - a single string,
+ *      - an array of strings, or
+ *      - a `Set` of strings.
+ *    - Multiple delimiters collapse into one; empty segments ignored.
+ *    - Returns `""` if the input is `null`, `undefined`, or empty.
+ * @param {StringLike} input - The string or array to convert. Returns `""` if empty, `null`, or `undefined`.
+ * @param {StringCollection} [ignoreWord] - Optional word(s) to leave unchanged in the output.
+ * @returns {string} The PascalCase formatted string.
+ * @example
+ * // Basic usage
+ * toPascalCase("hello world");
+ * // ➔ "HelloWorld"
+ *
+ * // Array input is joined before conversion
+ * toPascalCase(["Join", "Words", "Here"]);
+ * // ➔ "JoinWordsHere"
+ *
+ * // Handles underscores and hyphens
+ * toPascalCase("convert_to-pascal case");
+ * // ➔ "ConvertToPascalCase"
+ *
+ * // Trims extra delimiters
+ * toPascalCase("___hello--world__ again!!");
+ * // ➔ "HelloWorldAgain"
+ *
+ * // Supports emojis and symbols
+ * toPascalCase("🔥fire_and-ice❄️");
+ * // ➔ "FireAndIce"
+ *
+ * // Ignore single word
+ * toPascalCase("this URL path will ignore", "URL");
+ * // ➔ "ThisURLPathWillIgnore"
+ *
+ * // Ignore multiple words
+ * toPascalCase("ignore API and URL", ["API", "URL"]);
+ * // ➔ "IgnoreAPIAndURL"
+ *
+ * // Ignore using Set
+ * toPascalCase("ignore API and URL", new Set(["API", "URL"]));
+ * // ➔ "IgnoreAPIAndURL"
+ *
+ * // Null, Undefined or empty (string or array) input returns empty string
+ * toPascalCase(undefined);
+ * // ➔ ""
+ */
+declare const toPascalCase: (input: StringLike, ignoreWord?: StringCollection) => string;
+/** ----------------------------------------------------------
+ * * ***Utility: `toPascalCaseSpace`.***
+ * ----------------------------------------------------------
+ * **Converts a string (or array of strings) into `PascalCaseSpace`, with optionally leaving specific words unchanged.**
+ * - **Behavior:**
+ *    - Accepts a `string` or an `array of strings`:
+ *      - If an array is provided, elements are trimmed, empty ones removed,
+ *        then joined with `"-"` before conversion.
+ *    - Splits the input by non-alphanumeric characters
+ *      (spaces, punctuation, symbols, hyphens, underscores, emojis, etc.).
+ *    - The first word is fully lowercase; subsequent words are capitalized.
+ *    - Words listed in `ignoreWord` remain unchanged in the output.
+ *    - `ignoreWord` is normalized (trimmed, delimiters removed), empty values ignored.
+ *    - `ignoreWord` accepts:
+ *      - a single string,
+ *      - an array of strings, or
+ *      - a `Set` of strings.
+ *    - Multiple delimiters collapse into one; empty segments ignored.
+ *    - Returns `""` if the input is `null`, `undefined`, or empty.
+ * @param {StringLike} input - The string or array to convert. Returns `""` if empty, `null`, or `undefined`.
+ * @param {StringCollection} [ignoreWord] - Optional word(s) to leave unchanged in the output.
+ * @returns {string} The PascalCaseSpace formatted string.
+ * @example
+ * // Basic usage
+ * toPascalCaseSpace("hello world");
+ * // ➔ "Hello World"
+ *
+ * // Array input is joined before conversion
+ * toPascalCaseSpace(["Join", "Words", "Here"]);
+ * // ➔ "Join Words Here"
+ *
+ * // Handles underscores and hyphens
+ * toPascalCaseSpace("convert_to-pascal case");
+ * // ➔ "Convert To Pascal Case Space"
+ *
+ * // Trims extra delimiters
+ * toPascalCaseSpace("___hello--world__ again!!");
+ * // ➔ "Hello World Again"
+ *
+ * // Supports emojis and symbols
+ * toPascalCaseSpace("🔥fire_and-ice❄️");
+ * // ➔ "Fire And Ice"
+ *
+ * // Ignore single word
+ * toPascalCaseSpace("this URL path will ignore", "URL");
+ * // ➔ "This URL Path Will Ignore"
+ *
+ * // Ignore multiple words
+ * toPascalCaseSpace("ignore API and URL", ["API", "URL"]);
+ * // ➔ "Ignore API And URL"
+ *
+ * // Ignore using Set
+ * toPascalCaseSpace("ignore API and URL", new Set(["API", "URL"]));
+ * // ➔ "Ignore API And URL"
+ *
+ * // Null, Undefined or empty (string or array) input returns empty string
+ * toPascalCaseSpace(undefined);
+ * // ➔ ""
+ */
+declare const toPascalCaseSpace: (input: StringLike, ignoreWord?: StringCollection) => string;
+/** ----------------------------------------------------------
+ * * ***Utility: `toSnakeCase`.***
+ * ----------------------------------------------------------
+ * **Converts a string (or array of strings) into `snake_case`, with optionally leaving specific words unchanged.**
+ * - **Behavior:**
+ *    - Accepts a `string` or an `array of strings`:
+ *      - If an array is provided, elements are trimmed, empty ones removed,
+ *        then joined with `"-"` before conversion.
+ *    - Splits the input by non-alphanumeric characters
+ *      (spaces, punctuation, symbols, hyphens, underscores, emojis, etc.).
+ *    - The first word is fully lowercase; subsequent words are capitalized.
+ *    - Words listed in `ignoreWord` remain unchanged in the output.
+ *    - `ignoreWord` is normalized (trimmed, delimiters removed), empty values ignored.
+ *    - `ignoreWord` accepts:
+ *      - a single string,
+ *      - an array of strings, or
+ *      - a `Set` of strings.
+ *    - Multiple delimiters collapse into one; empty segments ignored.
+ *    - Returns `""` if the input is `null`, `undefined`, or empty.
+ * @param {StringLike} input - The string or array to convert. Returns `""` if empty, `null`, or `undefined`.
+ * @param {StringCollection} [ignoreWord] - Optional word(s) to leave unchanged in the output.
+ * @returns {string} The snake_case formatted string.
+ * @example
+ * // Basic usage
+ * toSnakeCase("Hello World");
+ * // ➔ "hello_world"
+ *
+ * // Array input is joined before conversion
+ * toSnakeCase(["Join", "Words", "Here"]);
+ * // ➔ "join_words_here"
+ *
+ * // Handles underscores, hyphens, spaces
+ * toSnakeCase("convert-to_snake case");
+ * // ➔ "convert_to_snake_case"
+ *
+ * // Handles emojis and symbols
+ * toSnakeCase("🔥fire___and--ice❄️");
+ * // ➔ "fire_and_ice"
+ *
+ * // Ignore specific word
+ * toSnakeCase("ignore URL case", "URL");
+ * // ➔ "ignore_URL_case"
+ *
+ * // Ignore multiple words
+ * toSnakeCase("ignore API and URL", ["API", "URL"]);
+ * // ➔ "ignore_API_and_URL"
+ *
+ * // Ignore with Set
+ * toSnakeCase("ignore API and URL", new Set(["API", "URL"]));
+ * // ➔ "ignore_API_and_URL"
+ *
+ * // Null, Undefined or empty (string or array) input returns empty string
+ * toSnakeCase(null);
+ * // ➔ ""
+ */
+declare const toSnakeCase: (input: StringLike, ignoreWord?: StringCollection) => string;
+type NormalizeSpacesOptions = {
+  /** If `true`, skips normalization and only trims whitespace from start & end, defaultValue: `false`.
+   *
+   * @default false
+   */
+  trimOnly?: boolean;
+  /** If `false`, skips trimming value, defaultValue: `true`.
+   *
+   * @default true
+   */
+  withTrim?: boolean;
+};
+/** ----------------------------------------------------------
+ * * ***Utility: `normalizeSpaces`.***
+ * ----------------------------------------------------------
+ * **Normalizes whitespace in a string by reducing multiple spaces
+ * to a single space, optionally trims, or only trims based on options.**
+ * - **Behavior:**
+ *    - Collapses all consecutive whitespace (spaces, tabs, newlines) into a single space.
+ *    - Can trim leading/trailing spaces (default behavior), or preserve them with `withTrim: false`.
+ *    - Can skip normalization entirely and only trim using `trimOnly: true`.
+ *    - Returns an empty string if input is `null` or `undefined`.
+ * @param {string | null | undefined} value - The input string to be processed. If `null` or `undefined`, returns an empty string.
+ * @param {NormalizeSpacesOptions} [options] - Configuration options.
+ * @param {NormalizeSpacesOptions["trimOnly"]} [options.trimOnly=false] - If `true`, skips normalization and only trims the string.
+ * @param {NormalizeSpacesOptions["withTrim"]} [options.withTrim=true] - If `false`, preserves leading/trailing whitespace.
+ * @returns {string} The processed string.
+ * @example
+ * normalizeSpaces("   Hello    World\tthis   is\n\nok ");
+ * // ➔ "Hello World this is ok"
+ * normalizeSpaces("   Hello    World\tthis   is\n\nok ", { trimOnly: true });
+ * // ➔ "Hello    World	this   is\n\nok"
+ * normalizeSpaces("   Hello    World   ", { withTrim: false });
+ * // ➔ " Hello World "
+ * normalizeSpaces(null);
+ * // ➔ ""
+ */
+declare const normalizeSpaces: (value: string | null | undefined, options?: NormalizeSpacesOptions) => string;
+/** ----------------------------------------------------------
+ * * ***Utility: `normalizeString`.***
+ * ----------------------------------------------------------
+ * **Normalizes a string by ensuring it is a valid string and trimming whitespace.**
+ * - **Behavior:**
+ *    - If the input is `undefined`, `null`, or an `empty string` after trimming,
+ *      it returns an empty string `("")`.
+ * @param {string | undefined | null} input - The input string to be normalize. If `null` or `undefined`, returns an empty string.
+ * @returns {string} A trimmed string or an empty string if the input is invalid.
+ * @example
+ * normalizeString("   Hello World   ");
+ * // ➔ "Hello World"
+ * normalizeString("   Hello    World   ");
+ * // ➔ "Hello    World"
+ * normalizeString("");
+ * // ➔ ""
+ * normalizeString(null);
+ * // ➔ ""
+ * normalizeString(undefined);
+ * // ➔ ""
+ */
+declare const normalizeString: (input: string | null | undefined) => string;
+type RemoveSpacesOptions = {
+  /** If `true`, only trims the string, defaultValue: `false`.
+   *
+   * @default false */
+  trimOnly?: boolean;
+};
+/** ----------------------------------------------------------
+ * * ***Utility: `removeSpaces`.***
+ * ----------------------------------------------------------
+ * **Removes all spaces from a string or trims only, based on the options provided.**
+ * - **Behavior:**
+ *    - If `trimOnly` is `true`, the string is simply trimmed.
+ *    - Otherwise, removes **all spaces**, tabs, newlines, etc.
+ *    - If the input is `null` or `undefined`, returns an empty string `("")`.
+ * @param {string | null | undefined} value - The input string to be processed. If `null` or `undefined`, returns an empty string.
+ * @param {RemoveSpacesOptions} [options] - The options object.
+ * @param {RemoveSpacesOptions["trimOnly"]} [options.trimOnly=false] - If `true`, only trims the string without removing spaces inside.
+ * @returns {string} The processed string.
+ * @example
+ * removeSpaces("  Hello   World  ");
+ * // ➔ "HelloWorld"
+ * removeSpaces("  Hello   World  ", { trimOnly: true });
+ * // ➔ "Hello   World"
+ * removeSpaces(null);
+ * // ➔ ""
+ */
+declare const removeSpaces: (value: string | null | undefined, options?: RemoveSpacesOptions) => string;
+/** ----------------------------------------------------------
+ * * ***Utility: `stripHtmlTags`.***
+ * ----------------------------------------------------------
+ * **This function removes valid HTML tags (including nested and self-closing ones)
+ * by replacing them with spaces, then collapses multiple whitespaces into a single space.**
+ * - **It handles the following cases:**
+ *    - If the input is not a string (`null`, `undefined`, or any non-string), it is returned as undefined.
+ *    - If the input is an empty or whitespace-only string, it returns an empty string (`""`).
+ *    - Otherwise, it returns the cleaned string with tags removed and normalized whitespace.
+ * @template T - Input string type (string | null | undefined).
+ * @param {string | null | undefined} input - A string potentially containing HTML tags.
+ * @returns {string | undefined} Cleaned string if input is string, or original input otherwise.
+ * @example
+ * stripHtmlTags("<p>Hello</p>");
+ * // ➔ "Hello"
+ * stripHtmlTags("<div><b>Bold</b> text</div>");
+ * // ➔ "Bold text"
+ * stripHtmlTags("Line<br/>Break");
+ * // ➔ "Line Break"
+ * stripHtmlTags("2 < 5 and 5 > 2");
+ * // ➔ "2 < 5 and 5 > 2"
+ * stripHtmlTags("");
+ * // ➔ ""
+ * stripHtmlTags("   ");
+ * // ➔ ""
+ * stripHtmlTags(null);
+ * // ➔ undefined
+ * stripHtmlTags(undefined);
+ * // ➔ undefined
+ */
+declare function stripHtmlTags(input: string): string;
+declare function stripHtmlTags<T>(input: T): Extends<string, T> extends true ? string | undefined : undefined;
+/** ----------------------------------------------------------
+ * * ***Utility: `getInitialsName`.***
+ * ----------------------------------------------------------
+ * **Extracts initials from the given name string.**
+ * - **Behavior:**
+ *    - For names with two or more words, returns the first letter of the first and second words.
+ *    - For a single word with 2+ characters, returns the first two letters.
+ *    - For a single character, returns that character.
+ *    - For `empty`, `null`, `undefined` or `whitespace-only input`, returns an empty string (`""`).
+ * @param {string | null | undefined} name - The name to extract initials from.
+ * @returns {string} The extracted initials (e.g., "JD" for "John Doe").
+ * @example
+ * getInitialsName("Alice");             // ➔ "AL"
+ * getInitialsName("John Doe");          // ➔ "JD"
+ * getInitialsName(" Bob Marley ");      // ➔ "BM"
+ * getInitialsName("John Ronald Donal"); // ➔ "JR"
+ * getInitialsName("Lord John Doe Moe"); // ➔ "LJ"
+ * getInitialsName("X");                 // ➔ "X"
+ * getInitialsName("");                  // ➔ "" (empty string)
+ * getInitialsName("  ");                // ➔ "" (empty string)
+ * getInitialsName(null);                // ➔ "" (null input)
+ * getInitialsName(undefined);           // ➔ "" (undefined input)
+ */
+declare const getInitialsName: (name: string | null | undefined) => string;
+/** ----------------------------------------------------------
+ *  * ***Utility: `replaceAt`.***
+ * ----------------------------------------------------------
+ * **Replaces exactly one character at the specified index in the original string
+ * with the provided `replaceTo` string.**
+ * - **Behavior:**
+ *    - If `replaceTo` has more than one character,
+ * the result will expand accordingly.
+ * @param {number} index - The starting index where the replacement should occur.
+ * @param {string} originalString - The original string to modify.
+ * @param {string} replaceTo - The string to insert at the specified index.
+ * @returns {string} The modified string with the replacement applied.
+ * @example
+ * replaceAt(3, "hello", "X");
+ * // ➔ "helXo"
+ * replaceAt(1, "world", "AB");
+ * // ➔ "wABrld"
+ * replaceAt(0, "cat", "br");
+ * // ➔ "brat"
+ * replaceAt(2, "12345", "-");
+ * // ➔ "12-45"
+ * replaceAt(4, "ABCDE", "Z");
+ * // ➔ "ABCDZ"
+ * // ❌ Examples that throw:
+ * replaceAt(10, "short", "X");
+ * // ➔ ❌ RangeError: First parameter (`index`) is out of range from second parameter `originalString`.
+ * replaceAt(-1, "test", "X");
+ * // ➔ ❌ RangeError: First parameter (`index`) is out of range from second parameter `originalString`.
+ * replaceAt("1", "test", "X");
+ * // ➔ ❌ TypeError: First parameter `index` must be of type `number`, second parameter `originalString` and third parameter `replaceTo` must be of type `string`, but received: "['index': `string`,...]."
+ * replaceAt(2, null, "X");
+ * // ➔ ❌ TypeError: First parameter `index` must be of type `number`, second parameter `originalString` and third parameter `replaceTo` must be of type `string`, but received: "['index': `string`,...]."
+ */
+declare const replaceAt: (index: number, originalString: string, replaceTo: string) => string;
+export { normalizeString as a, toPascalCaseSpace as c, toKebabCase as d, toDotCase as f, capitalizeFirst as g, capitalizeWords as h, removeSpaces as i, toPascalCase as l, slugify as m, getInitialsName as n, normalizeSpaces as o, toCamelCase as p, stripHtmlTags as r, toSnakeCase as s, replaceAt as t, toLowerCase as u };