nhb-toolbox/dist/dts/string/case.d.ts

A versatile collection of smart, efficient, and reusable utility functions, classes and types for everyday development needs.

import type { $WidenEmpty, CamelCase, CapitalizeOptions, CaseFormat, ConstantCase, DotCase, KebabCase, PascalCase, PascalSnakeCase, PathCase, SentenceCase, SnakeCase, StringCaseOptions, TitleCase, TrainCase } from './types';
/**
 * * Converts a string to a specified case format with advanced handling for word boundaries, punctuation, acronyms, and Unicode characters.
 *
 * @remarks
 * - This function is Unicode-aware, treats non-alphanumeric characters (spaces, underscores, dots, slashes, etc.) as word boundaries, and optionally preserves internal acronyms.
 * - `Title Case` formatting respects small words such as prepositions, articles, conjunctions, and auxiliary verbs (defined in `LOWERCASE`) — these are not capitalized unless they appear at the start or end of the string.
 * - Leading and trailing punctuation (non-letter/number characters) is preserved in the result.
 *
 * @param value - The input string to convert. Can contain letters, numbers, punctuation,
 *   spaces, underscores, dashes, etc.
 * @param format - The target case format:
 *   - `'camelCase'` → camelCase (e.g., `myVariableName`)
 *   - `'PascalCase'` → PascalCase (e.g., `MyVariableName`)
 *   - `'snake_case'` → snake_case (e.g., `my_variable_name`)
 *   - `'kebab-case'` → kebab-case (e.g., `my-variable-name`)
 *   - `'Title Case'` → Title Case (e.g., `My Variable Name`)
 *   - `'Sentence case'` → Sentence case (e.g., `My variable name`)
 *   - `'lowercase'` → all lowercase [ It is recommended to use built-in string method `string.toLowerCase()` ]
 *   - `'UPPERCASE'` → all uppercase [ It is recommended to use built-in string method `string.toUpperCase()` ]
 * @param options - Optional configuration options for more control.
 *
 * @returns The converted string, with leading/trailing punctuation preserved.
 *
 * @example
 * // Basic usage
 * convertStringCase('my-example_string', 'camelCase');
 * // Returns: 'myExampleString'
 *
 * convertStringCase('my-example_string', 'snake_case');
 * // Returns: 'my_example_string'
 *
 * convertStringCase('my-example_string', 'kebab-case');
 * // Returns: 'my-example-string'
 *
 * convertStringCase('my example string', 'Title Case');
 * // Returns: 'My Example String'
 *
 * convertStringCase('my example string', 'Sentence case');
 * // Returns: 'My example string'
 *
 * convertStringCase('My example String', 'lowercase');
 * // Returns: 'my example string'
 *
 * convertStringCase('my example string', 'UPPERCASE');
 * // Returns: 'MY EXAMPLE STRING'
 *
 * @example
 * // Preserve acronyms
 * convertStringCase('get API response', 'camelCase', { preserveAcronyms: true });
 * // Returns: 'getAPIResponse'
 *
 * convertStringCase('get API response', 'PascalCase', { preserveAcronyms: true });
 * // Returns: 'GetAPIResponse'
 *
 * convertStringCase('the API of things', 'Title Case', { preserveAcronyms: true });
 * // Returns: 'The API of Things'
 *
 * @example
 * // Leading/trailing punctuation is preserved
 * convertStringCase('++hello_world++', 'PascalCase');
 * // Returns: '++HelloWorld++'
 *
 * @example
 * // Dashes are preserved in Title Case
 * convertStringCase('xml-http_request', 'Title Case');
 * // Returns: 'Xml-http Request'
 *
 * @example
 * // Empty string returns empty
 * convertStringCase('', 'camelCase');
 * // Returns: ''
 *
 * @example
 * // Single token is capitalized properly
 * convertStringCase('api', 'PascalCase');
 * // Returns: 'Api'
 */
export declare function convertStringCase(value: string, format: CaseFormat, options?: StringCaseOptions): string;
/**
 * * Utility to convert the first letter of any string to uppercase and the rest lowercase (unless specified).
 * * Handles surrounding symbols like quotes or parentheses.
 *
 * @param string String to be capitalized.
 * @param options Options to customize the capitalization.
 * @returns Capitalized string or fully upper-cased string depending on `capitalizeAll` option.
 */
export declare function capitalizeString(string: string, options?: CapitalizeOptions): string;
/**
 * * Converts a string into `camelCase`, using the optional custom delimiters in addition to the default delimiters.
 *
 * @remarks
 * - This utility returns appropriate type IntelliSense with string literal. For general purpose use {@link convertStringCase}.
 * - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
 *   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
 * - Use it for short literal strings (`up to 45 characters`) for best performance.
 * - It does not handle ACRONYMS properly, so be cautious when the string has ACRONYMS or use {@link convertStringCase}.
 * - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
 *
 * @example
 * toCamelCase("hello world")            // "helloWorld"
 * toCamelCase("my-awesome_string")      // "myAwesomeString"
 * toCamelCase("value*with+custom", "*+") // "valueWithCustom"
 *
 * @param str The input string to convert.
 * @param del Additional delimiter characters to recognize.
 * @returns The `camelCase` formatted string.
 */
export declare function toCamelCase<Str extends string, Del extends string = ''>(str: Str, ...del: Del[]): $WidenEmpty<CamelCase<Str, Del>>;
/**
 * * Converts a string into `PascalCase`, using the optional custom delimiters in addition to the default delimiters.
 *
 * @remarks
 * - This utility returns appropriate type IntelliSense with string literal. For general purpose use {@link convertStringCase}.
 * - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
 *   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
 * - Use it for short literal strings (`up to 45 characters`) for best performance.
 * - It does not handle ACRONYMS properly, so be cautious when the string has ACRONYMS or use {@link convertStringCase}.
 * - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
 *
 * @example
 * toPascalCase("hello world")            // "HelloWorld"
 * toPascalCase("my-awesome_string")      // "MyAwesomeString"
 * toPascalCase("value*with+custom", "*+") // "ValueWithCustom"
 *
 * @param str The input string to convert.
 * @param del Additional delimiter characters to recognize.
 * @returns The `PascalCase` formatted string.
 */
export declare function toPascalCase<Str extends string, Del extends string = ''>(str: Str, ...del: Del[]): $WidenEmpty<PascalCase<Str, Del>>;
/**
 * * Converts a string into `snake_case`, using the optional custom delimiters in addition to the default delimiters.
 *
 * @remarks
 * - This utility returns appropriate type IntelliSense with string literal. For general purpose use {@link convertStringCase}.
 * - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
 *   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
 * - Use it for short literal strings (`up to 45 characters`) for best performance.
 * - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
 *
 * @example
 * toSnakeCase("hello world")            // "hello_world"
 * toSnakeCase("my-awesome_string")      // "my_awesome_string"
 * toSnakeCase("value*with+custom", "*+") // "value_with_custom"
 *
 * @param str The input string to convert.
 * @param del Additional delimiter characters to recognize.
 * @returns The `snake_case` formatted string.
 */
export declare function toSnakeCase<Str extends string, Del extends string = ''>(str: Str, ...del: Del[]): $WidenEmpty<SnakeCase<Str, Del>>;
/**
 * * Converts a string into `kebab-case`, using the optional custom delimiters in addition to the default delimiters.
 *
 * @remarks
 * - This utility returns appropriate type IntelliSense with string literal. For general purpose use {@link convertStringCase}.
 * - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
 *   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
 * - Use it for short literal strings (`up to 45 characters`) for best performance.
 * - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
 *
 * @example
 * toKebabCase("hello world")            // "hello-world"
 * toKebabCase("my-awesome_string")      // "my-awesome-string"
 * toKebabCase("value*with+custom", "*+") // "value-with-custom"
 *
 * @param str The input string to convert.
 * @param del Additional delimiter characters to recognize.
 * @returns The `kebab-case` formatted string.
 */
export declare function toKebabCase<Str extends string, Del extends string = ''>(str: Str, ...del: Del[]): $WidenEmpty<KebabCase<Str, Del>>;
/**
 * * Converts a string into `Train-Case`, using the optional custom delimiters in addition to the default delimiters.
 *
 * @remarks
 * - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
 *   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
 * - Use it for short literal strings (`up to 45 characters`) for best performance.
 * - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
 *
 * @example
 * toTrainCase("hello world")            // "Hello-World"
 * toTrainCase("my-awesome_string")      // "My-Awesome-String"
 * toTrainCase("value*with+custom", "*+") // "Value-With-Custom"
 *
 * @param str The input string to convert.
 * @param del Additional delimiter characters to recognize.
 * @returns The `Train-Case` formatted string.
 */
export declare function toTrainCase<Str extends string, Del extends string = ''>(str: Str, ...del: Del[]): $WidenEmpty<TrainCase<Str, Del>>;
/**
 * * Converts a string into `dot.case`, using the optional custom delimiters in addition to the default delimiters.
 *
 * @remarks
 * - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
 *   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
 * - Use it for short literal strings (`up to 45 characters`) for best performance.
 * - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
 *
 * @example
 * toDotCase("hello world")            // "hello.world"
 * toDotCase("my-awesome_string")      // "my.awesome.string"
 * toDotCase("value*with+custom", "*+") // "value.with.custom"
 *
 * @param str The input string to convert.
 * @param del Additional delimiter characters to recognize.
 * @returns The `dot.case` formatted string.
 */
export declare function toDotCase<Str extends string, Del extends string = ''>(str: Str, ...del: Del[]): $WidenEmpty<DotCase<Str, Del>>;
/**
 * * Converts a string into `path/case`, using the optional custom delimiters in addition to the default delimiters.
 *
 * @remarks
 * - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
 *   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
 * - Use it for short literal strings (`up to 45 characters`) for best performance.
 * - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
 *
 * @example
 * toPathCase("hello world")            // "hello/world"
 * toPathCase("my-awesome_string")      // "my/awesome/string"
 * toPathCase("value*with+custom", "*+") // "value/with/custom"
 *
 * @param str The input string to convert.
 * @param del Additional delimiter characters to recognize.
 * @returns The `path/case` formatted string.
 */
export declare function toPathCase<Str extends string, Del extends string = ''>(str: Str, ...del: Del[]): $WidenEmpty<PathCase<Str, Del>>;
/**
 * * Converts a string into `CONSTANT_CASE`, using the optional custom delimiters in addition to the default delimiters.
 *
 * @remarks
 * - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
 *   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
 * - Use it for short literal strings (`up to 45 characters`) for best performance.
 * - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
 *
 * @example
 * toConstantCase("hello world")            // "HELLO_WORLD"
 * toConstantCase("my-awesome_string")      // "MY_AWESOME_STRING"
 * toConstantCase("value*with+custom", "*+") // "VALUE_WITH_CUSTOM"
 *
 * @param str The input string to convert.
 * @param del Additional delimiter characters to recognize.
 * @returns The `CONSTANT_CASE` formatted string.
 */
export declare function toConstantCase<Str extends string, Del extends string = ''>(str: Str, ...del: Del[]): $WidenEmpty<ConstantCase<Str, Del>>;
/**
 * * Converts a string into `Pascal_Snake_Case`, using the optional custom delimiters in addition to the default delimiters.
 *
 * @remarks
 * - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
 *   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
 * - Use it for short literal strings (`up to 45 characters`) for best performance.
 * - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
 *
 * @example
 * toPascalSnakeCase("hello world")            // "Hello_World"
 * toPascalSnakeCase("my-awesome_string")      // "My_Awesome_String"
 * toPascalSnakeCase("value*with+custom", "*+") // "Value_With_Custom"
 *
 * @param str The input string to convert.
 * @param del Additional delimiter characters to recognize.
 * @returns The `Pascal_Snake_Case` formatted string.
 */
export declare function toPascalSnakeCase<Str extends string, Del extends string = ''>(str: Str, ...del: Del[]): $WidenEmpty<PascalSnakeCase<Str, Del>>;
/**
 * * Converts a string into `Title Case`, using the optional custom delimiters in addition to the default delimiters.
 *
 * @remarks
 * - This utility returns appropriate type IntelliSense with string literal. For general purpose use {@link convertStringCase}.
 * - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
 *   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
 * - Use it for short literal strings (`up to 45 characters`) for best performance.
 * - It does not handle ACRONYMS properly, so be cautious when the string has ACRONYMS or use {@link convertStringCase}.
 * - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
 *
 * @example
 * toTitleCase("hello world")            // "Hello World"
 * toTitleCase("my-awesome_string")      // "My Awesome String"
 * toTitleCase("value*with+custom", "*+") // "Value with Custom"
 *
 * @param str The input string to convert.
 * @param del Additional delimiter characters to recognize.
 * @returns The `Title Case` formatted string.
 */
export declare function toTitleCase<Str extends string, Del extends string = ''>(str: Str, ...del: Del[]): $WidenEmpty<TitleCase<Str, Del>>;
/**
 * * Converts a string into `Sentence case`, using the optional custom delimiters in addition to the default delimiters.
 *
 * @remarks
 * - This utility returns appropriate type IntelliSense with string literal. For general purpose use {@link convertStringCase}.
 * - At the type level, TypeScript supports `up to 45 characters` for reliable literal inference.
 *   - This limitation does not affect runtime behavior but shows TypeScript compiler error.
 * - Use it for short literal strings (`up to 45 characters`) for best performance.
 * - It does not handle ACRONYMS properly, so be cautious when the string has ACRONYMS or use {@link convertStringCase}.
 * - Custom delimiters are merged with the default set: `space`, `.`, `-`, `_`, `/`.
 *
 * @example
 * toSentenceCase("hello world")            // "Hello world"
 * toSentenceCase("my-awesome_string")      // "My awesome string"
 * toSentenceCase("value*with+custom", "*+") // "Value with custom"
 *
 * @param str The input string to convert.
 * @param del Additional delimiter characters to recognize.
 * @returns The `Sentence case` formatted string.
 */
export declare function toSentenceCase<Str extends string, Del extends string = ''>(str: Str, ...del: Del[]): $WidenEmpty<SentenceCase<Str, Del>>;