funtool/dist/string/index.d.ts

A modern, efficient, and modular JavaScript utility library designed to enhance developer productivity.

/**
 * Capitalizes the first letter of a string.
 *
 * @param {string} str - The input string.
 * @returns {string} The string with the first character in uppercase.
 *
 * @example
 * capitalizeFirstLetter('hello'); // ✅ 'Hello'
 */
declare function capitalizeFirstLetter(str: string): string;

/**
 * Counts the number of occurrences of a substring in a string.
 *
 * @param {string} str - The input string.
 * @param {string} substr - The substring to count.
 * @returns {number} The number of times the substring appears in the string.
 *
 * @example
 * count('hello world, hello universe', 'hello'); // 2
 */
declare function count(str: string, substr: string): number;

/**
 * Finds the first index of a substring in a string.
 *
 * @param {string} str - The input string.
 * @param {string} substr - The substring to find.
 * @returns {number} The index of the first occurrence of the substring, or -1 if not found.
 *
 * @example
 * findIndex('hello world', 'world'); // 6
 */
declare function findIndex(str: string, substr: string): number;

/**
 * Inserts a string after the specified character or index.
 *
 * @param input The input string
 * @param insertText The string to insert
 * @param target The character or index after which to insert
 * @returns The updated string
 * @example
 * insertAfter('hello', 'X', 1) // ✅ 'heXllo'
 * insertAfter('foo-bar', '_', '-') // ✅ 'foo-_bar'
 */
declare function insertAfter(input: string, insertText: string, target: string | number): string;

/**
 * Inserts a string before the specified character or index.
 *
 * @param input The input string
 * @param insertText The string to insert
 * @param target The character or index before which to insert
 * @returns The updated string
 * @example
 * insertBefore('hello', 'X', 1) // ✅ 'hXello'
 * insertBefore('foo-bar', '_', '-') // ✅ 'foo_-bar'
 */
declare function insertBefore(input: string, insertText: string, target: string | number): string;

/**
 * Lowercases the first letter of a string.
 *
 * @param {string} str - The input string.
 * @returns {string} The string with the first character in lowercase.
 *
 * @example
 * lowercaseFirstLetter('Hello'); // ✅ 'hello'
 */
declare function lowercaseFirstLetter(str: string): string;

/**
 * Pads the string from the end to a specified length with a given character.
 *
 * @param {string} str - The input string.
 * @param {number} length - The target length of the string.
 * @param {string} padChar - The character to pad with.
 * @returns {string} The padded string.
 *
 * @example
 * padEnd('hello', 10, '*'); // 'hello*****'
 */
declare function padEnd(str: string, length: number, padChar?: string): string;

/**
 * Pads the string from the start to a specified length with a given character.
 *
 * @param {string} str - The input string.
 * @param {number} length - The target length of the string.
 * @param {string} padChar - The character to pad with.
 * @returns {string} The padded string.
 *
 * @example
 * padStart('hello', 10, '*'); // '*****hello'
 */
declare function padStart(str: string, length: number, padChar?: string): string;

/**
 * Removes all characters after the specified character or index.
 *
 * @param input The input string
 * @param target Character or index after which content is removed
 * @returns The sliced string
 * @example
 * removeAfter('foo-bar', '-') // ✅ 'foo-'
 * removeAfter('hello', 3) // ✅ 'hel'
 */
declare function removeAfter(input: string, target: string | number): string;

/**
 * Removes the character at a specific index or matching a character.
 *
 * @param input The input string
 * @param target A character or index to remove
 * @returns The updated string
 * @example
 * removeAt('hello', 1) // ✅ 'hllo'
 * removeAt('abc-def', '-') // ✅ 'abcdef'
 */
declare function removeAt(input: string, target: string | number): string;

/**
 * Removes all characters before the specified character or index.
 *
 * @param input The input string
 * @param target Character or index before which content is removed
 * @returns The sliced string
 * @example
 * removeBefore('foo-bar', '-') // ✅ 'bar'
 * removeBefore('hello', 3) // ✅ 'lo'
 */
declare function removeBefore(input: string, target: string | number): string;

/**
 * Repeats the string a specified number of times.
 *
 * @param {string} str - The input string.
 * @param {number} count - The number of times to repeat the string.
 * @returns {string} The repeated string.
 *
 * @example
 * repeat('hello', 3); // 'hellohellohello'
 */
declare function repeat(str: string, count: number): string;

/**
 * Replaces all occurrences of a substring with a new string.
 *
 * @param {string} str - The input string.
 * @param {string} target - The substring to replace.
 * @param {string} replacement - The string to replace with.
 * @returns {string} The modified string with replacements.
 *
 * @example
 * replaceAll('hello world', 'world', 'everyone'); // 'hello everyone'
 */
declare function replaceAll(str: string, target: string, replacement: string): string;

/**
 * Reverses the string.
 *
 * @param {string} str - The input string.
 * @returns {string} The reversed string.
 *
 * @example
 * reverse('hello'); // 'olleh'
 */
declare function reverse(str: string): string;

/**
 * Extracts a substring from the string.
 *
 * @param {string} str - The input string.
 * @param {number} start - The starting index.
 * @param {number} end - The ending index.
 * @returns {string} The extracted substring.
 *
 * @example
 * substring('hello world', 0, 5); // 'hello'
 */
declare function substring(str: string, start: number, end: number): string;

/**
 * Converts a string to camelCase.
 *
 * @param {string} str - The input string (e.g., "hello_world").
 * @returns {string} The camelCase version of the string.
 *
 * @example
 * toCamelCase('hello_world'); // ✅ 'helloWorld'
 * toCamelCase('hello-world'); // ✅ 'helloWorld'
 * toCamelCase('api_version'); // ✅ 'apiVersion'
 * toCamelCase('API_version'); // ✅ 'apiVersion'
 * toCamelCase('my-xml-parser'); // ✅ 'myXmlParser'
 */
declare function toCamelCase(str: string): string;

/**
 * Converts a string to kebab-case.
 *
 * @param {string} str - The input string (e.g., "helloWorld").
 * @returns {string} The kebab-case version of the string.
 *
 * @example
 * toKebabCase('helloWorld'); // ✅ 'hello-world'
 * toKebabCase('HelloWorld'); // ✅ 'hello-world'
 * toKebabCase('myXMLParser'); // ✅ 'my-xml-parser'
 * toKebabCase('MyXMLParser'); // ✅ 'my-xml-parser'
 * toKebabCase('hello_world'); // ✅ 'hello-world'
 * toKebabCase('APIversion'); // ✅ 'ap-iversion'
 * toKebabCase('userID_token'); // ✅ 'user-id-token'
 * toKebabCase('JSONData'); // ✅ 'json-data'
 */
declare function toKebabCase(str: string): string;

/**
 * Converts the character at a specific index or matching a character to lowercase.
 *
 * @param input The input string
 * @param target A character or index to transform
 * @returns The transformed string
 * @example
 * toLowerAt('Hello', 0) // ✅ 'hello'
 * toLowerAt('Foo-Bar', 'B') // ✅ 'Foo-bar'
 */
declare function toLowerAt(input: string, target: string | number): string;

/**
 * Convert string to lowercase
 * @param str - Input string
 * @returns Lowercase string
 * @example
 * toLowerCase('HELLO') // => 'hello' ✅
 * toLowerCase(123) // => '123' ✅
 */
declare function toLowerCase(str: string): string;

/**
 * Converts a string to PascalCase.
 *
 * @param {string} str - The input string (e.g., "hello_world").
 * @returns {string} The PascalCase version of the string.
 *
 * @example
 * toPascalCase('hello_world'); // ✅ 'HelloWorld'
 * toPascalCase('api_version'); // ✅ 'ApiVersion'
 * toPascalCase('API_version'); // ✅ 'APIVersion'
 * toPascalCase('my-xml-parser'); // ✅ 'MyXmlParser'
 */
declare function toPascalCase(str: string): string;

/**
 * Converts a string into snake_case.
 *
 * This function transforms camelCase, PascalCase, kebab-case, and space-separated strings
 * into snake_case format by:
 * - Inserting underscores between lowercase and uppercase letter transitions
 * - Replacing spaces and hyphens with underscores
 * - Converting all letters to lowercase
 *
 * @param {string} str - The input string to convert.
 * @returns {string} A snake_case formatted string.
 *
 * @example
 * toSnakeCase('helloWorld'); // ✅ 'hello_world'
 * toSnakeCase('HelloWorld'); // ✅ 'hello_world'
 * toSnakeCase('hello-world'); // ✅ 'hello_world'
 * toSnakeCase('hello world'); // ✅ 'hello_world'
 * toSnakeCase('APIVersion');  // ✅ 'api_version'
 * toSnakeCase('MyXMLParser'); // ✅ 'my_xml_parser
 */
declare function toSnakeCase(str: string): string;

/**
 * Converts a string into Title Case (each word capitalized, separated by spaces).
 *
 * - Converts the entire string to lowercase first
 * - Capitalizes the first letter of each word (detected via space, hyphen, or underscore)
 * - Replaces underscores and hyphens with spaces
 *
 * Note: Acronyms or all-caps words will be normalized to capitalized first-letter only.
 *
 * @param {string} str - The input string to convert.
 * @returns {string} A string in Title Case format.
 *
 * @example
 * toTitleCase('hello_world');   // ✅ 'Hello World'
 * toTitleCase('hello-world');   // ✅ 'Hello World'
 * toTitleCase('hello world');   // ✅ 'Hello World'
 * toTitleCase('user_id');       // ✅ 'User Id'
 * toTitleCase('API_version');   // ✅ 'Api Version'
 */
declare function toTitleCase(str: string): string;

/**
 * Converts the character at a specific index or matching a character to uppercase.
 *
 * @param input The input string
 * @param target A character or index to transform
 * @returns The transformed string
 * @example
 * toUpperAt('hello', 0) // ✅ 'Hello'
 * toUpperAt('foo-bar', 'b') // ✅ 'foo-Bar'
 */
declare function toUpperAt(input: string, target: string | number): string;

/**
 * Convert string to uppercase
 * @param str - Input string
 * @returns Uppercase string
 * @example
 * toUpperCase('hello') // => 'HELLO' ✅
 * toUpperCase(123) // => '123' ✅
 */
declare function toUpperCase(str: string): string;

/**
 * Remove whitespace from both ends of a string
 * @param str - Input string
 * @returns Trimmed string
 * @example
 * trim('  hello  ') // => 'hello' ✅
 * trim(123) // => '123' ✅
 */
declare function trim(str: string): string;

/**
 * Remove whitespace from the right end of a string
 * @param str - Input string
 * @returns Right-trimmed string
 * @example
 * trimEnd('hello  ') // => 'hello' ✅
 * trimEnd(123) // => '123' ✅
 */
declare function trimEnd(str: string): string;

/**
 * Remove whitespace from the left end of a string
 * @param str - Input string
 * @returns Left-trimmed string
 * @example
 * trimStart('  hello') // => 'hello' ✅
 * trimStart(123) // => '123' ✅
 */
declare function trimStart(str: string): string;

/**
 * Splits a string into word segments.
 * This function is purely responsible for splitting the string into words and not for any formatting.
 *
 * It handles:
 * - camelCase / PascalCase
 * - snake_case / kebab-case / space-separated
 * - digits mixed with text (e.g. 'userID2Token' → ['user', 'ID', '2', 'Token'])
 *
 * @param {string} str - The input string to be split.
 * @returns {string[]} Array of word segments.
 *
 * @example
 * words('helloWorld'); // ['hello', 'World']
 * words('APIversion'); // ['API', 'version']
 * words('userID2Token'); // ['user', 'ID', '2', 'Token']
 * words('hello_world-test Value') //['hello', 'world', 'test', 'Value']
 */
declare function words(str: string): string[];

export { capitalizeFirstLetter, count, findIndex, insertAfter, insertBefore, lowercaseFirstLetter, padEnd, padStart, removeAfter, removeAt, removeBefore, repeat, replaceAll, reverse, substring, toCamelCase, toKebabCase, toLowerAt, toLowerCase, toPascalCase, toSnakeCase, toTitleCase, toUpperAt, toUpperCase, trim, trimEnd, trimStart, words };