API Reference

Complete reference for all functions, types, and utilities provided by @visulima/string.

Case Conversion

camelCase

Converts string to camelCase.

function camelCase(input: string, options?: CaseOptions): string;

Parameters:

input: String to convert
options: Optional configuration

Returns: String in camelCase format

Example:

camelCase("hello-world"); // 'helloWorld'

pascalCase

Converts string to PascalCase.

function pascalCase(input: string, options?: CaseOptions): string;

snakeCase

Converts string to snake_case.

function snakeCase(input: string, options?: CaseOptions): string;

kebabCase

Converts string to kebab-case.

function kebabCase(input: string, options?: KebabCaseOptions): string;

constantCase

Converts string to CONSTANT_CASE.

function constantCase(input: string, options?: CaseOptions): string;

dotCase

Converts string to dot.case.

function dotCase(input: string, options?: CaseOptions): string;

pathCase

Converts string to path/case.

function pathCase(input: string, options?: CaseOptions): string;

titleCase

Converts string to Title Case.

function titleCase(input: string, options?: CaseOptions): string;

sentenceCase

Converts string to Sentence case.

function sentenceCase(input: string, options?: CaseOptions): string;

splitByCase

Splits string by case transitions.

function splitByCase(input: string, options?: SplitOptions): string[];

Parameters:

input: String to split
options: Optional configuration

Returns: Array of string segments

Example:

splitByCase("camelCase"); // ['camel', 'Case']

flipCase

Inverts case of each character in a string.

function flipCase(input: string, options?: FlipOptions): string;

Parameters:

input: String to flip case
options: Optional configuration (same as CaseOptions except handleEmoji)

Returns: String with inverted case

Example:

flipCase("Hello World"); // 'hELLO wORLD'
flipCase("XMLHttpRequest"); // 'xmlhTTPrEQUEST'

identifyCase

Identifies the case style of a string.

function identifyCase(input: string): IdentifyCase;

Parameters:

input: String to identify

Returns: Case style identifier: 'camel', 'pascal', 'snake', 'kebab', 'upper_snake', 'lower', 'upper', 'title', 'sentence', 'mixed', or 'unknown'

Example:

identifyCase("helloWorld"); // 'camel'
identifyCase("HELLO_WORLD"); // 'upper_snake'
identifyCase("Hello World"); // 'title'

lowerFirst

Converts first character to lowercase.

function lowerFirst(input: string): string;

Example:

lowerFirst("Hello"); // 'hello'
lowerFirst("HELLO"); // 'hELLO'

upperFirst

Converts first character to uppercase.

function upperFirst(input: string): string;

Example:

upperFirst("hello"); // 'Hello'
upperFirst("hello world"); // 'Hello world'

noCase

Removes all case styling, converting to lowercase with spaces.

function noCase(input: string, options?: CaseOptions): string;

Example:

noCase("camelCase"); // 'camel case'
noCase("PascalCase"); // 'pascal case'
noCase("snake_case"); // 'snake case'

flatCase

Converts string to flatcase (no separators, all lowercase).

function flatCase(input: string, options?: CaseOptions): string;

Example:

flatCase("foo bar"); // 'foobar'
flatCase("foo-bar"); // 'foobar'

capitalCase

Converts string to Capital Case (each word capitalized).

function capitalCase(input: string, options?: CaseOptions): string;

Example:

capitalCase("foo bar"); // 'Foo Bar'
capitalCase("foo-bar"); // 'Foo Bar'

trainCase

Converts string to Train-Case (each word capitalized, hyphen-separated).

function trainCase(input: string, options?: CaseOptions): string;

Example:

trainCase("foo bar"); // 'Foo-Bar'
trainCase("XMLHttpRequest"); // 'Xml-Http-Request'

pascalSnakeCase

Converts string to Pascal_Snake_Case.

function pascalSnakeCase(input: string, options?: CaseOptions): string;

Example:

pascalSnakeCase("foo bar"); // 'Foo_Bar'
pascalSnakeCase("XMLHttpRequest"); // 'Xml_Http_Request'

String Manipulation

truncate

Truncates string to specified length.

function truncate(input: string, length: number, options?: TruncateOptions): string;

Parameters:

input: String to truncate
length: Maximum length
options: Optional configuration

Returns: Truncated string

Example:

truncate("hello world", 8); // 'hello...'

wordWrap

Wraps text to specified width.

function wordWrap(text: string, options?: WordWrapOptions): string;

Parameters:

text: Text to wrap
options: Optional configuration

Returns: Wrapped text

Example:

wordWrap("Long text...", { width: 40 });

alignText

Aligns text to left, center, or right.

function alignText(text: string | string[], options?: AlignTextOptions): string | string[];

Parameters:

text: Text to align (string or array of strings)
options: Optional configuration

Returns: Aligned text in same format as input

Example:

alignText("Hello", { align: "center" });

outdent

Removes leading indentation.

function outdent(strings: TemplateStringsArray, ...values: any[]): string;

function outdent(options: OutdentOptions): typeof outdent;

namespace outdent {
    function string(input: string): string;
}

Usage:

// Template literal
outdent`
  Hello
  World
`;

// String input
outdent.string("  Hello\n  World");

// With options
const custom = outdent({ trimLeadingNewline: false });
custom`Hello`;

slice

Unicode-aware string slicing.

function slice(input: string, start: number, end?: number, options?: SliceOptions): string;

Parameters:

input: String to slice
start: Start index
end: End index (optional)
options: Optional configuration

Returns: Sliced string

Example:

slice("hello world", 0, 5); // 'hello'

replaceString

Advanced string replacement with ignore ranges.

function replaceString(source: string, searches: OptionReplaceArray, ignoreRanges?: IntervalArray): string;

Parameters:

source: Source string
searches: Array of [search, replace] tuples
ignoreRanges: Optional ranges to ignore

Returns: String with replacements applied

Example:

replaceString("hello", [["h", "H"]], []); // 'Hello'

excerpt

Strips HTML tags and truncates text to a specified limit.

function excerpt(html: string, limit: number, options?: ExcerptOptions): string;

Parameters:

html: HTML string to process
limit: Maximum character limit
options: Optional configuration

Returns: Plain text string with HTML removed and truncated

Example:

excerpt("<p>Hello <strong>world</strong>!</p>", 10);
// 'Hello wor…'

excerpt("<div>Content</div>", 7);
// 'Content'

countOccurrences

Counts occurrences of a substring in a string.

function countOccurrences(value: string, substring: string): number;

Parameters:

value: Content to search in
substring: Substring to look for (must be non-empty)

Returns: Count of substrings in value

Throws: TypeError when substring is not a string or is empty

Example:

countOccurrences("foo", "o"); // 2
countOccurrences("fo fooo fo", "o"); // 5
countOccurrences("a🤔b🤔c", "🤔"); // 2

direction

Detects the direction of text: left-to-right, right-to-left, or neutral.

function direction(value: string): "rtl" | "ltr" | "neutral";

Parameters:

value: The string to analyze

Returns: The text direction: 'rtl' for right-to-left, 'ltr' for left-to-right, or 'neutral' for neutral

Example:

direction("english"); // 'ltr'
direction("الجملة"); // 'rtl'
direction("123"); // 'neutral'
direction(""); // 'neutral'

String Width

getStringWidth

Calculates visual width of string.

function getStringWidth(input: string, options?: StringWidthOptions): number;

Parameters:

input: String to measure
options: Optional configuration

Returns: Visual width in columns

Example:

getStringWidth("hello"); // 5
getStringWidth("你好"); // 4

getStringTruncatedWidth

Calculates width with truncation support.

function getStringTruncatedWidth(input: string, options?: StringTruncatedWidthOptions): StringTruncatedWidthResult;

Parameters:

input: String to measure
options: Optional configuration

Returns: Object with width, truncation info, and index

Example:

getStringTruncatedWidth("hello", { limit: 3 });
// { width: 3, truncated: true, ellipsed: false, index: 3 }

Slugification

slugify

Creates URL-friendly slug.

function slugify(input: string, options?: SlugifyOptions): string;

Parameters:

input: String to slugify
options: Optional configuration

Returns: URL-friendly slug

Example:

slugify("Hello World!"); // 'hello-world'

transliterate

Transliterates Unicode to ASCII.

function transliterate(source: string, options?: OptionsTransliterate): string;

Parameters:

source: String to transliterate
options: Optional configuration

Returns: Transliterated string

Example:

transliterate("Café"); // 'Cafe'

String Similarity

distance

Calculates Levenshtein distance.

function distance(a: string, b: string): number;

Parameters:

a: First string
b: Second string

Returns: Edit distance

Example:

distance("hello", "hallo"); // 1

closest

Finds closest matching string.

function closest(target: string, options: string[]): string | null;

Parameters:

target: Target string
options: Array of candidate strings

Returns: Closest match or null

Example:

closest("aple", ["apple", "banana"]); // 'apple'

closestN

Finds N closest matches.

function closestN(target: string, options: string[], count: number): string[];

Parameters:

target: Target string
options: Array of candidate strings
count: Number of matches to return

Returns: Array of closest matches

closestString

Finds closest string with options.

function closestString(target: string, options: string[], config?: ClosestStringOptions): ClosestStringResult | null;

Returns: Object with value, distance, and similarity

compareSimilarity

Compares two strings.

function compareSimilarity(
    a: string,
    b: string,
    options?: CompareSimilarityOptions,
): {
    distance: number;
    similarity: number;
    equal: boolean;
};

wordSimilaritySort

Sorts strings by similarity.

function wordSimilaritySort(target: string, words: string[], options?: WordSimilaritySortOptions): string[];

Utilities

escapeRegExp

Escapes special regex characters for safe use in regular expressions.

function escapeRegExp(string: string): string;

Parameters:

string: String to escape

Returns: Escaped string safe for use in regex

Example:

escapeRegExp("hello.world"); // 'hello\\.world'
escapeRegExp("(test)"); // '\\(test\\)'

inRange

Checks if a number falls within any of the specified intervals.

function inRange(value: number, ranges: IntervalArray): boolean;

Parameters:

value: Number to check
ranges: Array of [start, end] intervals

Returns: True if number is within any interval

Example:

inRange(5, [
    [0, 10],
    [20, 30],
]); // true
inRange(15, [
    [0, 10],
    [20, 30],
]); // false

hasChinese

Checks if string contains Chinese characters (Han script).

function hasChinese(text: string): boolean;

Parameters:

text: String to check

Returns: True if string contains Chinese characters

Example:

hasChinese("你好"); // true
hasChinese("hello"); // false
hasChinese("hello 世界"); // true

hasPunctuationOrSpace

Checks if string contains punctuation or space characters.

function hasPunctuationOrSpace(text: string): boolean;

Parameters:

text: String to check

Returns: True if string contains punctuation or space

Example:

hasPunctuationOrSpace("hello world"); // true
hasPunctuationOrSpace("hello,world"); // true
hasPunctuationOrSpace("helloworld"); // false

findStringOccurrences

Finds all occurrences of multiple substrings and returns their positions.

function findStringOccurrences(source: string, targets: string[]): IntervalArray;

Parameters:

source: String to search within
targets: Array of strings to search for

Returns: Array of [start, end] intervals for each occurrence

Example:

findStringOccurrences("hello world hello", ["hello", "world"]);
// [[0, 4], [6, 10], [12, 16]]

findStringOccurrences("abc def abc", ["abc"]);
// [[0, 2], [8, 10]]

Testing

toEqualAnsi

Vitest matcher for ANSI strings.

function toEqualAnsi(received: string, expected: string): { pass: boolean; message: () => string };

Usage:

expect.extend({ toEqualAnsi });
expect(actual).toEqualAnsi(expected);

formatAnsiString

Formats ANSI string for display.

function formatAnsiString(input: string): {
    ansi: string;
    stripped: string;
    visible: string;
    json: string;
    lengthDifference: number;
};

compareAnsiStrings

Compares two ANSI strings.

function compareAnsiStrings(
    actual: string,
    expected: string,
): {
    ansiEqual: boolean;
    strippedEqual: boolean;
    summary: string;
    actual: FormattedAnsiString;
    expected: FormattedAnsiString;
};

Type Definitions

CaseOptions

interface CaseOptions {
    cache?: boolean;
    cacheMaxSize?: number;
    cacheStore?: Map<string, string>;
    knownAcronyms?: ReadonlyArray<string>;
    locale?: string;
}

TruncateOptions

interface TruncateOptions {
    ellipsis?: string;
    ellipsisWidth?: number;
    position?: "end" | "middle" | "start";
    preferTruncationOnSpace?: boolean;
    width?: StringWidthOptions;
}

StringWidthOptions

interface StringWidthOptions {
    ambiguousIsNarrow?: boolean;
    ansiWidth?: number;
    controlWidth?: number;
    countAnsiEscapeCodes?: boolean;
    emojiWidth?: number;
    fullWidth?: number;
    regularWidth?: number;
    tabWidth?: number;
    wideWidth?: number;
}

SlugifyOptions

interface SlugifyOptions {
    allowedChars?: string;
    fixChineseSpacing?: boolean;
    ignore?: string[];
    lowercase?: boolean;
    replaceAfter?: OptionReplaceCombined;
    replaceBefore?: OptionReplaceCombined;
    separator?: string;
    transliterate?: boolean;
    trim?: boolean;
    unknown?: string;
    uppercase?: boolean;
}

ExcerptOptions

interface ExcerptOptions {
    // String to append when truncation occurs
    ellipsis?: string; // default: '…'

    // All other TruncateOptions except 'position' (always 'end')
    // See TruncateOptions for full details
}

FlipOptions

interface FlipOptions extends Omit<CaseOptions, "handleEmoji"> {
    // Same as CaseOptions but handleEmoji is not available
    // (emojis are preserved by default in flipCase)
}

IdentifyCase

type IdentifyCase = "camel" | "pascal" | "snake" | "kebab" | "upper_snake" | "lower" | "upper" | "title" | "sentence" | "mixed" | "unknown";

Next Steps

Case Conversion - Case conversion guide
String Manipulation - String manipulation guide
TypeScript - TypeScript support

API Reference

On this page

Contribute to our work and keep us going

Ready to help us out?

Submit a pull request

Good first issues