@hichchi/utils 0.0.1-alpha.1 → 0.0.1-beta.1

package/utils/string.utils.d.ts

@@ -0,0 +1,932 @@
+/**
+ * Breaks a string into an array of words based on common separator patterns.
+ *
+ * This function intelligently splits strings into individual words by detecting various
+ * word boundary patterns, including:
+ * - Camel case boundaries ("helloWorld" → ["hello", "world"])
+ * - Snake case boundaries ("hello_world" → ["hello", "world"])
+ * - Kebab case boundaries ("hello-world" → ["hello", "world"])
+ * - Space-separated words ("hello world" → ["hello", "world"])
+ * - Uppercase acronyms ("APIClient" → ["api", "client"])
+ *
+ * The returned words are all converted to lowercase.
+ *
+ * @param {string} str - The string to split into words
+ * @returns {string[]} - An array of lowercase words
+ *
+ * @example
+ * ```typescript
+ * breakToWords("helloWorld"); // ['hello', 'world']
+ * breakToWords("hello_world"); // ['hello', 'world']
+ * breakToWords("hello-world"); // ['hello', 'world']
+ * breakToWords("hello world"); // ['hello', 'world']
+ * breakToWords("APIConfig"); // ['api', 'config']
+ * breakToWords("123Test456"); // ['123', 'test', '456']
+ * ```
+ *
+ * @remarks
+ * - Returns an empty array for empty, null, or undefined input
+ * - Preserves numbers as separate words
+ * - Handles consecutive uppercase letters as acronyms (preserving them as a single word)
+ */
+export declare function breakToWords(str: string): string[];
+/**
+ * Breaks a string into words and formats them using a provided function.
+ *
+ * This overload splits a string into words using the same logic as the array version,
+ * but additionally applies a formatting function to each word and joins them with spaces.
+ *
+ * Common use cases include:
+ * - Converting camelCase to Title Case
+ * - Formatting identifiers for display
+ * - Normalizing different string formats
+ *
+ * @param {string} str - The string to split and format
+ * @param {(str: string) => string} format - A function to apply to each word
+ * @returns {string} - A space-joined string of formatted words
+ *
+ * @example
+ * ```typescript
+ * // Convert camelCase to Sentence case
+ * breakToWords("helloWorld", toFirstCase); // "Hello world"
+ *
+ * // Convert snake_case to Title Case
+ * breakToWords("user_profile_data", toFirstCase); // "User profile data"
+ *
+ * // Format with a custom function
+ * breakToWords("SYSTEM_ERROR", word => word.toLowerCase()); // "system error"
+ * ```
+ */
+export declare function breakToWords(str: string, format: (str: string) => string): string;
+/**
+ * Converts a string to lowercase with safe handling of undefined or null values.
+ *
+ * This utility function provides a safe way to convert strings to lowercase, automatically
+ * handling edge cases where the input might be undefined, null, or empty. Unlike the native
+ * String.prototype.toLowerCase() method, this function won't throw an error when called
+ * with undefined or null values, instead returning an empty string.
+ *
+ * This is particularly useful when working with user input, API responses, or any scenario
+ * where string values might be optional or potentially undefined. It's commonly used for
+ * case-insensitive comparisons, search functionality, or normalizing text data.
+ *
+ * @param {string} [str] - The string to convert to lowercase. Can be undefined or null.
+ * @returns {string} The lowercase version of the input string, or an empty string if input is falsy
+ *
+ * @example
+ * ```typescript
+ * // Basic string conversion
+ * const result1 = toLowerCase("Hello World");
+ * // Returns: "hello world"
+ *
+ * const result2 = toLowerCase("JAVASCRIPT");
+ * // Returns: "javascript"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Safe handling of undefined/null values
+ * const result1 = toLowerCase(undefined);
+ * // Returns: ""
+ *
+ * const result2 = toLowerCase(null);
+ * // Returns: ""
+ *
+ * const result3 = toLowerCase("");
+ * // Returns: ""
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in case-insensitive search
+ * function searchUsers(users: User[], searchTerm: string): User[] {
+ *   const normalizedSearch = toLowerCase(searchTerm);
+ *   return users.filter(user =>
+ *     toLowerCase(user.name).includes(normalizedSearch) ||
+ *     toLowerCase(user.email).includes(normalizedSearch)
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in form validation
+ * function validateEmail(email?: string): boolean {
+ *   const normalizedEmail = toLowerCase(email);
+ *   const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+ *   return emailRegex.test(normalizedEmail);
+ * }
+ * ```
+ *
+ * @remarks
+ * - Returns an empty string for any falsy input (undefined, null, empty string)
+ * - Uses the native String.prototype.toLowerCase() method for actual conversion
+ * - Does not modify the original string (strings are immutable in JavaScript)
+ * - Handles all Unicode characters correctly, following locale-independent rules
+ * - More robust than direct .toLowerCase() calls when input might be undefined
+ *
+ * @see {@link toUpperCase} Function for converting strings to uppercase
+ * @see {@link toLowerCaseBreak} Function for converting to lowercase and breaking into words
+ */
+export declare function toLowerCase(str?: string): string;
+/**
+ * Converts a string to lowercase and breaks it into words, joining them with a specified separator.
+ *
+ * This utility function combines word breaking and case conversion in a single operation.
+ * It first breaks the input string into individual words using intelligent pattern recognition
+ * (handling camelCase, snake_case, kebab-case, etc.), converts each word to lowercase,
+ * and then joins them with the specified separator or a space by default.
+ *
+ * This is particularly useful for converting various naming conventions to a consistent
+ * lowercase format, creating readable labels from variable names, generating search-friendly
+ * text, or preparing strings for further processing where consistent word separation is needed.
+ *
+ * @param {string} [str] - The string to convert and break into words. Can be undefined or null.
+ * @param {string} [join=" "] - The separator to use when joining the words. Defaults to a single space.
+ * @returns {string} A lowercase string with words separated by the specified join character,
+ *                   or an empty string if input is falsy
+ *
+ * @example
+ * ```typescript
+ * // Basic camelCase conversion
+ * const result1 = toLowerCaseBreak("HelloWorld");
+ * // Returns: "hello world"
+ *
+ * const result2 = toLowerCaseBreak("getUserProfile");
+ * // Returns: "get user profile"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Custom separators
+ * const result1 = toLowerCaseBreak("HelloWorld", "-");
+ * // Returns: "hello-world"
+ *
+ * const result2 = toLowerCaseBreak("APIResponseHandler", "_");
+ * // Returns: "api_response_handler"
+ *
+ * const result3 = toLowerCaseBreak("userAccountSettings", " | ");
+ * // Returns: "user | account | settings"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Various input formats
+ * const result1 = toLowerCaseBreak("snake_case_example");
+ * // Returns: "snake case example"
+ *
+ * const result2 = toLowerCaseBreak("kebab-case-example");
+ * // Returns: "kebab case example"
+ *
+ * const result3 = toLowerCaseBreak("CONSTANT_VALUE");
+ * // Returns: "constant value"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Creating user-friendly labels
+ * function createLabel(fieldName: string): string {
+ *   return toLowerCaseBreak(fieldName)
+ *     .split(' ')
+ *     .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+ *     .join(' ');
+ * }
+ *
+ * createLabel("firstName"); // "First Name"
+ * createLabel("emailAddress"); // "Email Address"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Safe handling of edge cases
+ * const result1 = toLowerCaseBreak(undefined);
+ * // Returns: ""
+ *
+ * const result2 = toLowerCaseBreak("", "-");
+ * // Returns: ""
+ *
+ * const result3 = toLowerCaseBreak("singleword");
+ * // Returns: "singleword"
+ * ```
+ *
+ * @remarks
+ * - Returns an empty string for any falsy input (undefined, null, empty string)
+ * - Uses the same intelligent word-breaking algorithm as the breakToWords function
+ * - Handles camelCase, PascalCase, snake_case, kebab-case, and mixed formats
+ * - Preserves numbers as separate words when they appear in the string
+ * - The join parameter can be any string, including empty string for concatenation
+ * - More efficient than calling breakToWords and toLowerCase separately
+ *
+ * @see {@link breakToWords} Function for breaking strings into word arrays
+ * @see {@link toLowerCase} Function for simple lowercase conversion
+ * @see {@link toUpperCaseBreak} Function for uppercase word breaking
+ */
+export declare function toLowerCaseBreak(str?: string, join?: string): string;
+/**
+ * Converts a string to uppercase with safe handling of undefined or null values.
+ *
+ * This utility function provides a safe way to convert strings to uppercase, automatically
+ * handling edge cases where the input might be undefined, null, or empty. Unlike the native
+ * String.prototype.toUpperCase() method, this function won't throw an error when called
+ * with undefined or null values, instead returning an empty string.
+ *
+ * This is particularly useful when working with user input, API responses, or any scenario
+ * where string values might be optional or potentially undefined. It's commonly used for
+ * creating constants, formatting display text, generating identifiers, or normalizing text
+ * data that needs to be in uppercase format.
+ *
+ * @param {string} [str] - The string to convert to uppercase. Can be undefined or null.
+ * @returns {string} The uppercase version of the input string, or an empty string if input is falsy
+ *
+ * @example
+ * ```typescript
+ * // Basic string conversion
+ * const result1 = toUpperCase("hello world");
+ * // Returns: "HELLO WORLD"
+ *
+ * const result2 = toUpperCase("javascript");
+ * // Returns: "JAVASCRIPT"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Safe handling of undefined/null values
+ * const result1 = toUpperCase(undefined);
+ * // Returns: ""
+ *
+ * const result2 = toUpperCase(null);
+ * // Returns: ""
+ *
+ * const result3 = toUpperCase("");
+ * // Returns: ""
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Creating constants or identifiers
+ * function generateConstantName(variableName: string): string {
+ *   return toUpperCase(variableName.replace(/[^a-zA-Z0-9]/g, '_'));
+ * }
+ *
+ * generateConstantName("user-profile"); // "USER_PROFILE"
+ * generateConstantName("api.endpoint"); // "API_ENDPOINT"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in text formatting
+ * function formatTitle(title?: string): string {
+ *   if (!title) return "UNTITLED";
+ *   return toUpperCase(title.trim());
+ * }
+ *
+ * formatTitle("my document"); // "MY DOCUMENT"
+ * formatTitle(undefined);     // "UNTITLED"
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in case-insensitive comparisons
+ * function compareIgnoreCase(str1?: string, str2?: string): boolean {
+ *   return toUpperCase(str1) === toUpperCase(str2);
+ * }
+ *
+ * compareIgnoreCase("Hello", "HELLO"); // true
+ * compareIgnoreCase("Test", "test");   // true
+ * ```
+ *
+ * @remarks
+ * - Returns an empty string for any falsy input (undefined, null, empty string)
+ * - Uses the native String.prototype.toUpperCase() method for actual conversion
+ * - Does not modify the original string (strings are immutable in JavaScript)
+ * - Handles all Unicode characters correctly, following locale-independent rules
+ * - More robust than direct .toUpperCase() calls when input might be undefined
+ * - Particularly useful for creating constants, headers, or display text
+ *
+ * @see {@link toLowerCase} Function for converting strings to lowercase
+ * @see {@link toUpperCaseBreak} Function for converting to uppercase and breaking into words
+ */
+export declare function toUpperCase(str?: string): string;
+/**
+ * Compares two strings for similarity using Levenshtein distance algorithm.
+ *
+ * The Levenshtein distance is a measure of the difference between two strings
+ * by counting the minimum number of single-character edits (insertions, deletions,
+ * or substitutions) required to change one string into another.
+ *
+ * @param {string} str1 - First string to compare
+ * @param {string} str2 - Second string to compare
+ * @returns {number} - A value between 0 and 1, where 1 means identical strings
+ *
+ * @example
+ * ```typescript
+ * stringSimilarity("hello", "hallo");       // 0.8 (4/5 characters match)
+ * stringSimilarity("kitten", "sitting");    // ~0.57 (higher distance)
+ * stringSimilarity("same", "same");         // 1.0 (identical)
+ * ```
+ */
+export declare function stringSimilarity(str1: string, str2: string): number;
+/**
+ * Generates a slug from a string, suitable for URLs or file names.
+ *
+ * @param {string} str - The string to convert to a slug
+ * @param {string} [separator="-"] - The character to use as separator
+ * @returns {string} - The slug string
+ *
+ * @example
+ * ```typescript
+ * slugify("Hello World");                // "hello-world"
+ * slugify("10 Tips & Tricks!");          // "10-tips-tricks"
+ * slugify("My Product (2023 Edition)");   // "my-product-2023-edition"
+ * slugify("Über résumé");                // "uber-resume"
+ * slugify("Blog Post", "_");             // "blog_post"
+ * ```
+ */
+export declare function slugify(str: string, separator?: string): string;
+/**
+ * Extracts all email addresses from a string.
+ *
+ * @param {string} str - The string to extract emails from
+ * @returns {string[]} - Array of found email addresses
+ *
+ * @example
+ * ```typescript
+ * extractEmails("Contact us at support@example.com or sales@example.com");
+ * // ["support@example.com", "sales@example.com"]
+ * ```
+ */
+export declare function extractEmails(str: string): string[];
+/**
+ * Extracts all URLs from a string.
+ *
+ * @param {string} str - The string to extract URLs from
+ * @returns {string[]} - Array of found URLs
+ *
+ * @example
+ * ```typescript
+ * extractUrls("Visit https://example.com or http://test.org/page?id=5");
+ * // ["https://example.com", "http://test.org/page?id=5"]
+ * ```
+ */
+export declare function extractUrls(str: string): string[];
+/**
+ * Converts a string to a secure hash using SHA-256.
+ *
+ * Note: This is a browser-compatible implementation using the Web Crypto API.
+ * For Node.js environments, you might want to use the crypto module instead.
+ *
+ * @param {string} str - The string to hash
+ * @returns {Promise<string>} - Promise resolving to the hex hash string
+ *
+ * @example
+ * ```typescript
+ * // Browser usage
+ * await hashString("password123");
+ * // "ef92b778bafe771e89245b89ecbc08a44a4e166c06659911881f383d4473e94f"
+ * ```
+ */
+export declare function hashString(str: string): Promise<string>;
+/**
+ * Generates a random string with specified length and character set.
+ *
+ * @param {number} length - The length of the random string
+ * @param {string} [charset] - The characters to use (defaults to alphanumeric)
+ * @returns {string} - The generated random string
+ *
+ * @example
+ * ```typescript
+ * // Default alphanumeric string
+ * randomString(8);
+ * // e.g. "A7bC9Df3"
+ *
+ * // Hex string
+ * randomString(6, "0123456789abcdef");
+ * // e.g. "a3f9d2"
+ *
+ * // PIN code
+ * randomString(4, "0123456789");
+ * // e.g. "8302"
+ * ```
+ */
+export declare function randomString(length: number, charset?: string): string;
+/**
+ * Masks a portion of a string, useful for displaying sensitive information.
+ *
+ * @param {string} str - The string to mask
+ * @param {number} [visibleStart=0] - Number of characters to show at the beginning
+ * @param {number} [visibleEnd=0] - Number of characters to show at the end
+ * @param {string} [maskChar="*"] - Character to use for masking
+ * @returns {string} - The masked string
+ *
+ * @example
+ * ```typescript
+ * // Mask credit card
+ * maskString("4111111111111111", 4, 4);
+ * // "4111********1111"
+ *
+ * // Mask email
+ * maskString("user@example.com", 2, 4, "x");
+ * // "usxxxxxx.com"
+ *
+ * // Mask phone number
+ * maskString("+1-555-123-4567", 0, 4);
+ * // "*********4567"
+ * ```
+ */
+export declare function maskString(str: string, visibleStart?: number, visibleEnd?: number, maskChar?: string): string;
+/**
+ * Convert a string to first case (Capitalize first letter of the string).
+ * @param {string} [str] Optional string to join the words with.
+ * @returns {string} String in first case.
+ *
+ * @example
+ * ```TypeScript
+ * toFirstCase("hello world"); // "Hello world"
+ * ```
+ */
+export declare function toFirstCase(str?: string): string;
+/**
+ * Converts a string to a camelCase or PascalCase variable name.
+ *
+ * @param {string} str - The string to convert
+ * @param {boolean} [pascalCase=false] - Whether to use PascalCase (true) or camelCase (false)
+ * @returns {string} - The variable name
+ *
+ * @example
+ * ```typescript
+ * toVariableName("Hello World");      // "helloWorld"
+ * toVariableName("API Response");     // "apiResponse"
+ * toVariableName("first-name");       // "firstName"
+ * toVariableName("user_id", true);    // "UserId"
+ * ```
+ */
+export declare function toVariableName(str: string, pascalCase?: boolean): string;
+/**
+ * Wraps words in a string to ensure each line is no longer than a specified length.
+ *
+ * @param {string} str - The string to wrap
+ * @param {number} [lineLength=80] - Maximum length of each line
+ * @param {string} [breakChar="\n"] - Character(s) to insert at line breaks
+ * @returns {string} - The wrapped string
+ *
+ * @example
+ * ```typescript
+ * const text = "This is a long sentence that needs to be wrapped to fit within a certain width.";
+ *
+ * wordWrap(text, 20);
+ * // "This is a long\nsentence that needs\nto be wrapped to\nfit within a\ncertain width."
+ *
+ * wordWrap(text, 30, "<br>");
+ * // "This is a long sentence that<br>needs to be wrapped to fit<br>within a certain width."
+ * ```
+ */
+export declare function wordWrap(str: string, lineLength?: number, breakChar?: string): string;
+/**
+ * Creates an excerpt from a longer text by extracting a portion around a search term.
+ * Useful for search result highlighting or previews.
+ *
+ * @param {string} text - The full text to create an excerpt from
+ * @param {string} searchTerm - The search term to find in the text
+ * @param {number} [contextLength=40] - Number of characters to include before and after the search term
+ * @param {string} [ellipsis="..."] - Characters to use for indicating truncated text
+ * @returns {string} - The excerpt with the search term in context
+ *
+ * @example
+ * ```typescript
+ * const article = "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nullam in dui mauris.";
+ *
+ * createExcerpt(article, "dolor", 10);
+ * // "...ipsum dolor sit amet..."
+ *
+ * createExcerpt(article, "consectetur", 15, "[...]");
+ * // "[...]sit amet, consectetur adipiscing[...]"
+ * ```
+ */
+export declare function createExcerpt(text: string, searchTerm: string, contextLength?: number, ellipsis?: string): string;
+/**
+ * Normalizes a string by removing accents, diacritics, and converting to lowercase.
+ *
+ * @param {string} str - The string to normalize
+ * @returns {string} - The normalized string
+ *
+ * @example
+ * ```typescript
+ * normalizeString("Café");          // "cafe"
+ * normalizeString("Über");          // "uber"
+ * normalizeString("résumé");        // "resume"
+ * normalizeString("ESPAÑA");        // "espana"
+ * ```
+ */
+export declare function normalizeString(str: string): string;
+/**
+ * Convert a string to upper cases and break into words with optional join or space.
+ * @param {string} [str] String to convert to upper cases and break into words.
+ * @param {string} [join] Optional string to join the words with.
+ * @returns {string} String in upper cases and broken into words.
+ *
+ * @example
+ * ```TypeScript
+ * toUpperCaseBreak("HelloWorld"); // "HELLO WORLD"
+ * ```
+ *
+ * @example
+ * ```TypeScript
+ * toUpperCaseBreak("HelloWorld", "! "); // "HELLO! WORLD"
+ */
+export declare function toUpperCaseBreak(str?: string, join?: string): string;
+/**
+ * Converts a string to Sentence case (first word capitalized, rest lowercase) with customizable word separators.
+ *
+ * This function breaks a string into words, capitalizes the first word, converts remaining
+ * words to lowercase, and then joins them using a custom separator (or space by default).
+ *
+ * Unlike `toFirstCase()` which works on a single word, this function processes multi-word
+ * strings from various formats (camelCase, snake_case, etc.) and gives control over how
+ * the words are joined back together.
+ *
+ * @param {string} [str] - The input string to convert
+ * @param {string} [join] - Optional separator to join words (defaults to space)
+ * @returns {string} - The formatted string with first word capitalized and custom separators,
+ *                    or empty string if input is falsy
+ *
+ * @example
+ * ```typescript
+ * // With default space separator
+ * toFirstCaseBreak("helloWorld");       // "Hello world"
+ * toFirstCaseBreak("SYSTEM_ERROR");     // "System error"
+ * toFirstCaseBreak("api-request-log");  // "Api request log"
+ *
+ * // With custom separators
+ * toFirstCaseBreak("hello_world", "-");    // "Hello-world"
+ * toFirstCaseBreak("userAuthConfig", "."); // "User.auth.config"
+ * toFirstCaseBreak("GET_USER_DATA", "/");  // "Get/user/data"
+ * ```
+ *
+ * @see {@link toFirstCase} For capitalizing a single word
+ * @see {@link toTitleCase} For capitalizing the first letter of every word
+ * @see {@link breakToWords} The underlying function used to split input into words
+ */
+export declare function toFirstCaseBreak(str?: string, join?: string): string;
+/**
+ * Convert a string to title case (Capitalize first letter of each word).
+ * @param {string} [str] String to convert to title case.
+ * @returns {string} String in title case.
+ *
+ * @example
+ * ```TypeScript
+ * toTitleCase("hello world"); // "Hello World"
+ * ```
+ */
+export declare function toTitleCase(str?: string): string;
+/**
+ * Convert a string to camel case.
+ * @param {string} [str] String to convert to camel case.
+ * @returns {string} String in camel case.
+ *
+ * @example
+ * ```TypeScript
+ * toCamelCase("hello world"); // "helloWorld"
+ * ```
+ */
+export declare function toCamelCase(str?: string): string;
+/**
+ * Convert a string to pascal case.
+ * @param {string} [str] String to convert to pascal case.
+ * @returns {string} String in pascal case.
+ *
+ * @example
+ * ```TypeScript
+ * toPascalCase("hello world"); // "HelloWorld"
+ * ```
+ */
+export declare function toPascalCase(str?: string): string;
+/**
+ * Convert a string to sentence case. (Capitalize first letter of every sentence).
+ * @param {string} [str] String to convert to sentence case.
+ * @returns {string} String in sentence case.
+ *
+ * @example
+ * ```TypeScript
+ * toSentenceCase("hello world. how are you?"); // "Hello world. How are you?"
+ * ```
+ */
+export declare function toSentenceCase(str: string): string;
+/**
+ * Converts a string to snake_case format.
+ *
+ * This function transforms a string from any common case format (camel, pascal, kebab, etc.)
+ * into snake_case, where words are lowercase and separated by underscores.
+ *
+ * When the optional `caps` parameter is set to true, the result will be UPPER_SNAKE_CASE
+ * (also known as SCREAMING_SNAKE_CASE or CONSTANT_CASE).
+ *
+ * @param {string} [str] - The input string to convert
+ * @param {boolean} [caps=false] - When true, converts to UPPER_SNAKE_CASE
+ * @returns {string} - The converted snake_case string, or empty string if input is falsy
+ *
+ * @example
+ * ```typescript
+ * // From various formats to snake_case
+ * toSnakeCase("hello world");    // "hello_world"
+ * toSnakeCase("HelloWorld");     // "hello_world"
+ * toSnakeCase("hello-world");    // "hello_world"
+ * toSnakeCase("HELLO WORLD");    // "hello_world"
+ *
+ * // To UPPER_SNAKE_CASE (CONSTANT_CASE)
+ * toSnakeCase("hello world", true);  // "HELLO_WORLD"
+ * toSnakeCase("helloWorld", true);   // "HELLO_WORLD"
+ * ```
+ *
+ * @remarks
+ * This function first splits the string into words using `breakToWords()`,
+ * then joins them with underscores, applying the requested case transformation.
+ */
+export declare function toSnakeCase(str?: string, caps?: boolean): string;
+/**
+ * Convert a string to kebab case.
+ * @param {string} [str] String to convert to kebab case.
+ * @param {boolean} [caps] Whether to convert to upper case.
+ * @returns {string} String in kebab case.
+ *
+ * @example
+ * ```TypeScript
+ * toKebabCase("hello world"); // "hello-world"
+ * ```
+ *
+ * @example
+ * ```TypeScript
+ * toKebabCase("hello world", true); // "HELLO-WORLD"
+ * ```
+ */
+export declare function toKebabCase(str?: string, caps?: boolean): string;
+/**
+ * Converts a string to a number.
+ * @param {number|string} str String to convert to a number.
+ * @returns {number|undefined} Number or undefined.
+ *
+ * @example
+ * ```TypeScript
+ * toNumber("123"); // 123
+ * ```
+ */
+export declare function toNumber(str: number | string): number | undefined;
+/**
+ * Remove HTML tags from a string and return plain text.
+ * @param {string} str String to remove HTML tags from.
+ * @returns {string} Plain text.
+ *
+ * @example
+ * ```TypeScript
+ * htmlToText("<h1>Hello World</h1>"); // "Hello World"
+ * ```
+ */
+export declare function htmlToText(str: string): string;
+/**
+ * Converts a singular English word to its plural form.
+ *
+ * This function applies common English pluralization rules to transform
+ * singular words into their plural equivalents. It handles regular patterns
+ * as well as many irregular cases and special rules for different word endings.
+ *
+ * @param {string} str - The singular word to convert to plural form
+ * @returns {string} - The plural form of the word, or the original string if:
+ *   - Input is empty/falsy
+ *   - The word is already plural
+ *
+ * @example
+ * ```typescript
+ * // Regular plurals
+ * plural("cat");      // "cats"
+ * plural("dog");      // "dogs"
+ *
+ * // Words ending in -y
+ * plural("party");    // "parties"
+ * plural("day");      // "days"
+ *
+ * // Words ending in -f or -fe
+ * plural("wolf");     // "wolves"
+ * plural("knife");    // "knives"
+ *
+ * // Words ending in -o
+ * plural("potato");   // "potatoes"
+ * plural("photo");    // "photos"
+ *
+ * // Irregular plurals
+ * plural("child");    // "children"
+ * plural("man");      // "men"
+ * plural("foot");     // "feet"
+ *
+ * // Latin/Greek words
+ * plural("cactus");   // "cacti"
+ * plural("analysis"); // "analyses"
+ * ```
+ *
+ * @remarks
+ * - This function is designed for English language words only
+ * - It pairs well with the `singular()` function for round-trip conversion
+ */
+export declare function plural(str: string): string;
+/**
+ * Truncates a string to a specified length and adds an ellipsis if needed.
+ *
+ * @param {string} str - The string to truncate
+ * @param {number} length - Maximum length of the truncated string (excluding ellipsis)
+ * @param {string} [ellipsis="..."] - The ellipsis to add to truncated strings
+ * @returns {string} - The truncated string with ellipsis if needed
+ *
+ * @example
+ * ```typescript
+ * truncate("This is a long sentence", 10);  // "This is a..."
+ * truncate("Short", 10);                   // "Short"
+ * truncate("Custom ellipsis", 6, " [more]"); // "Custom [more]"
+ * ```
+ */
+export declare function truncate(str: string, length: number, ellipsis?: string): string;
+/**
+ * Pads a string to a specified length with a specified character.
+ *
+ * @param {string} str - The string to pad
+ * @param {number} length - The target length of the resulting string
+ * @param {string} [char=" "] - The character to pad with (defaults to space)
+ * @param {boolean} [padEnd=true] - Whether to pad at the end (true) or beginning (false)
+ * @returns {string} - The padded string
+ *
+ * @example
+ * ```typescript
+ * padString("Hello", 10);           // "Hello     "
+ * padString("Hello", 10, "*");      // "Hello*****"
+ * padString("Hello", 10, "0", false); // "00000Hello"
+ * ```
+ */
+export declare function padString(str: string, length: number, char?: string, padEnd?: boolean): string;
+/**
+ * Escapes special characters in a string for use in regular expressions.
+ *
+ * @param {string} str - The string to escape
+ * @returns {string} - The escaped string safe for use in RegExp
+ *
+ * @example
+ * ```typescript
+ * escapeRegExp("hello.world*");  // "hello\.world\*"
+ *
+ * // Usage in RegExp:
+ * const userInput = "hello.world*";
+ * const regex = new RegExp(escapeRegExp(userInput));
+ * ```
+ */
+export declare function escapeRegExp(str: string): string;
+/**
+ * Capitalizes each word in a string according to title case rules.
+ *
+ * This function implements proper title case rules, where:
+ * - The first and last words are always capitalized
+ * - All other major words are capitalized
+ * - Minor words (articles, conjunctions, short prepositions) are not capitalized
+ *   unless they are the first or last word
+ *
+ * @param {string} str - The string to convert to title case
+ * @returns {string} - The string in proper title case format
+ *
+ * @example
+ * ```typescript
+ * toProperTitleCase("the quick brown fox jumps over the lazy dog");
+ * // "The Quick Brown Fox Jumps over the Lazy Dog"
+ *
+ * toProperTitleCase("a tale of two cities");
+ * // "A Tale of Two Cities"
+ * ```
+ */
+export declare function toProperTitleCase(str: string): string;
+/**
+ * Formats a string by replacing indexed placeholders with provided values.
+ *
+ * This implementation uses {n} syntax for indexed placeholders where n is the
+ * position of the value in the arguments list (0-based).
+ *
+ * @param {string} template - The template string with {0}, {1}, etc. placeholders
+ * @param {...(string|number|boolean|null|undefined)} values - Values to insert into the template
+ * @returns {string} - The formatted string
+ *
+ * @example
+ * ```typescript
+ * format("Hello, {0}!", "World");  // "Hello, World!"
+ *
+ * format("User {0} has {1} points", "John", 100);
+ * // "User John has 100 points"
+ * ```
+ */
+export declare function format(template: string, ...values: (string | number | boolean | null | undefined)[]): string;
+/**
+ * Formats a string by replacing named placeholders with values from an object.
+ *
+ * This implementation uses {name} syntax for named placeholders where 'name'
+ * corresponds to a property in the provided values object.
+ *
+ * @param {string} template - The template string with {propertyName} placeholders
+ * @param {Record<string, string|number|boolean|null|undefined>} values - Object with values to insert
+ * @returns {string} - The formatted string
+ *
+ * @example
+ * ```typescript
+ * // Named placeholders with object
+ * format("Hello, {name}! You have {count} messages.", { name: "Alice", count: 5 });
+ * // "Hello, Alice! You have 5 messages."
+ * ```
+ */
+export declare function format(template: string, values: Record<string, string | number | boolean | null | undefined>): string;
+/**
+ * Counts the occurrences of a substring within a string.
+ *
+ * @param {string} str - The string to search within
+ * @param {string} searchValue - The substring to search for
+ * @param {boolean} [caseSensitive=true] - Whether the search should be case-sensitive
+ * @returns {number} - The number of occurrences
+ *
+ * @example
+ * ```typescript
+ * countOccurrences("hello hello world", "hello");  // 2
+ * countOccurrences("Hello hello", "hello", false); // 2
+ * countOccurrences("Hello hello", "hello", true);  // 1
+ * ```
+ */
+export declare function countOccurrences(str: string, searchValue: string, caseSensitive?: boolean): number;
+/**
+ * Reverses a string.
+ *
+ * @param {string} str - The string to reverse
+ * @returns {string} - The reversed string
+ *
+ * @example
+ * ```typescript
+ * reverse("hello");  // "olleh"
+ * reverse("12345");  // "54321"
+ * ```
+ */
+export declare function reverse(str: string): string;
+/**
+ * Checks if a string contains only alphanumeric characters.
+ *
+ * @param {string} str - The string to check
+ * @returns {boolean} - True if the string contains only alphanumeric characters
+ *
+ * @example
+ * ```typescript
+ * isAlphanumeric("abc123");  // true
+ * isAlphanumeric("abc-123"); // false
+ * ```
+ */
+export declare function isAlphanumeric(str: string): boolean;
+/**
+ * Removes all whitespace from a string.
+ *
+ * @param {string} str - The string to process
+ * @returns {string} - The string with all whitespace removed
+ *
+ * @example
+ * ```typescript
+ * removeWhitespace("hello world");       // "helloworld"
+ * removeWhitespace("  spaces   tabs  "); // "spacestabs"
+ * ```
+ */
+export declare function removeWhitespace(str: string): string;
+/**
+ * Converts plural English words to their singular form.
+ *
+ * This function applies a series of linguistic rules and exceptions to transform
+ * plural English words into their singular equivalents. It handles irregular plurals
+ * (e.g., "children" → "child"), common suffix patterns (e.g., "parties" → "party"),
+ * and Latin-derived words (e.g., "cacti" → "cactus").
+ *
+ * The function applies rules in priority order, from most specific to most general,
+ * to ensure correct handling of special cases.
+ *
+ * @param {string} str - The plural word to convert to singular form
+ * @returns {string} - The singular form of the word, or the original string if:
+ *   - Input is empty/falsy
+ *   - No singular form is recognized
+ *   - The word is already singular
+ *
+ * @example
+ * ```typescript
+ * // Irregular plurals
+ * singular("children"); // "child"
+ * singular("men");     // "man"
+ * singular("feet");    // "foot"
+ *
+ * // Common patterns
+ * singular("cats");    // "cat"
+ * singular("boxes");   // "box"
+ * singular("parties"); // "party"
+ * singular("wolves"); // "wolf"
+ *
+ * // Latin-derived words
+ * singular("cacti");      // "cactus"
+ * singular("phenomena");  // "phenomenon"
+ * ```
+ *
+ * @remarks
+ * - This function is designed for English language words only
+ * - It handles many common cases but isn't exhaustive for all English plurals
+ * - Words that are identical in singular and plural form (e.g., "sheep") are returned unchanged
+ */
+export declare function singular(str: string): string;