@catbee/utils/string/index.d.ts

A modular, production-grade utility toolkit for Node.js and TypeScript, designed for robust, scalable applications (including Express-based services). All utilities are tree-shakable and can be imported independently.

/*
 * The MIT License
 * 
 * Copyright (c) 2026 Catbee Technologies. https://catbee.in/license
 * 
 * Permission is hereby granted, free of charge, to any person obtaining a copy
 * of this software and associated documentation files (the "Software"), to deal
 * in the Software without restriction, including without limitation the rights
 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 * copies of the Software, and to permit persons to whom the Software is
 * furnished to do so, subject to the following conditions:
 * 
 * The above copyright notice and this permission notice shall be included in all
 * copies or substantial portions of the Software.
 * 
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 * SOFTWARE.
 */

/**
 * Capitalizes the first character of a string.
 *
 * @param {string} str - The input string.
 * @returns {string} The string with the first character in uppercase.
 */
declare function capitalize(str: string): string;
/**
 * Converts a string to kebab-case (e.g., "FooBar test" -> "foo-bar-test").
 *
 * @param {string} str - The input string.
 * @returns {string} The kebab-cased string.
 */
declare function toKebabCase(str: string): string;
/**
 * Converts a kebab-case or snake_case string to camelCase.
 *
 * @param {string} str - The input string.
 * @returns {string} The camelCased string.
 */
declare function toCamelCase(str: string): string;
/**
 * Converts a string to a URL-friendly slug (lowercase, dashes, alphanumeric).
 *
 * @param {string} str - The input string.
 * @returns {string} The slugified string.
 */
declare function slugify(str: string): string;
/**
 * Truncates a string to a specific length, appending '...' if truncated.
 *
 * @param {string} str - The input string.
 * @param {number} len - The maximum length.
 * @returns {string} The truncated string.
 */
declare function truncate(str: string, len: number): string;
/**
 * Converts a string to PascalCase (e.g., "foo-bar" -> "FooBar").
 *
 * @param {string} str - The input string.
 * @returns {string} The PascalCased string.
 */
declare function toPascalCase(str: string): string;
/**
 * Converts a string to snake_case (e.g., "FooBar test" -> "foo_bar_test").
 *
 * @param {string} str - The input string.
 * @returns {string} The snake_cased string.
 */
declare function toSnakeCase(str: string): string;
/**
 * Masks a string by replacing characters with a mask character.
 * Useful for hiding sensitive information like credit cards or passwords.
 *
 * @param {string} str - The string to mask.
 * @param {number} [visibleStart=0] - Number of characters to show at start.
 * @param {number} [visibleEnd=0] - Number of characters to show at end.
 * @param {string} [maskChar="*"] - Character to use for masking.
 * @returns {string} The masked string.
 */
declare function mask(str: string, visibleStart?: number, visibleEnd?: number, maskChar?: string): string;
/**
 * Removes all HTML tags from a string.
 *
 * @param {string} str - The HTML string to process.
 * @returns {string} The string with HTML tags removed.
 */
declare function stripHtml(str: string): string;
/**
 * Performs case-insensitive string comparison.
 *
 * @param {string} a - First string.
 * @param {string} b - Second string.
 * @returns {boolean} True if the strings are equal ignoring case.
 */
declare function equalsIgnoreCase(a: string, b: string): boolean;
/**
 * Reverses a string.
 *
 * @param {string} str - The string to reverse.
 * @returns {string} The reversed string.
 */
declare function reverse(str: string): string;
/**
 * Counts occurrences of a substring within a string.
 *
 * @param {string} str - The source string.
 * @param {string} substring - The substring to count.
 * @param {boolean} [caseSensitive=true] - Whether to perform case-sensitive counting.
 * @returns {number} Number of occurrences.
 */
declare function countOccurrences(str: string, substring: string, caseSensitive?: boolean): number;
/**
 * Convert a string to Title Case (each word capitalized).
 * Preserves existing spacing and punctuation between words.
 *
 * @param str - Input string
 * @returns Title-cased string
 */
declare function toTitleCase(str: string): string;
/**
 * Escapes special regex characters in a string.
 *
 * @param {string} str - The input string.
 * @returns {string} String with regex characters escaped.
 *
 * @example
 * escapeRegex('Hello (world)'); // 'Hello \\(world\\)'
 */
declare function escapeRegex(str: string): string;
/**
 * Unescapes HTML entities in a string.
 *
 * @param {string} str - The HTML string.
 * @returns {string} String with HTML entities unescaped.
 *
 * @example
 * unescapeHtml('&lt;div&gt;Hello&lt;/div&gt;'); // '<div>Hello</div>'
 */
declare function unescapeHtml(str: string): string;
/**
 * Checks if a string is blank (empty or only whitespace).
 *
 * @param {string} str - The input string.
 * @returns {boolean} True if blank.
 *
 * @example
 * isBlank('   '); // true
 * isBlank('hello'); // false
 */
declare function isBlank(str: string): boolean;
/**
 * Truncates a string with an ellipsis, ensuring word boundaries.
 *
 * @param {string} str - The input string.
 * @param {number} maxLength - Maximum length.
 * @param {string} [suffix='...'] - Suffix to append.
 * @returns {string} Truncated string.
 *
 * @example
 * ellipsis('The quick brown fox', 10); // 'The quick...'
 */
declare function ellipsis(str: string, maxLength: number, suffix?: string): string;

export { capitalize, countOccurrences, ellipsis, equalsIgnoreCase, escapeRegex, isBlank, mask, reverse, slugify, stripHtml, toCamelCase, toKebabCase, toPascalCase, toSnakeCase, toTitleCase, truncate, unescapeHtml };