@synstack/str 1.1.2 → 1.2.0

package/dist/str.index.d.cts

@@ -8,258 +8,714 @@ type Stringable = {
     toString(): string;
 };
 
+/**
+ * A chainable string manipulation class that extends Pipeable
+ * Provides a fluent interface for string operations with full TypeScript support
+ *
+ * @example
+ * ```typescript
+ * import { str } from '@synstack/str'
+ *
+ * // Basic chaining
+ * const result = str('Hello World')
+ *   .trim()
+ *   .split(' ')
+ *   .at(0)
+ *   .$
+ *
+ * // Advanced chaining with Pipeable methods
+ * const modified = str('hello-world')
+ *   ._((s) => s.camelCase())
+ *   ._$((value) => value.toUpperCase())
+ *   .$
+ * ```
+ */
 declare class Str extends Pipeable<Str, string> {
     private readonly text;
+    /**
+     * Create a new Str instance
+     * @param text - The input string to wrap
+     * @example
+     * ```typescript
+     * const s = new Str('Hello World')
+     * // or use the convenience function
+     * const s = str('Hello World')
+     * ```
+     */
     constructor(text: string);
+    /**
+     * Get the underlying string value
+     * @returns The wrapped string value
+     */
     valueOf(): string;
+    /**
+     * Convert the Str instance to a string
+     * @returns The wrapped string value
+     */
     toString(): string;
+    /**
+     * Get the current Str instance
+     * @returns The current Str instance
+     * @internal Used by Pipeable
+     */
     instanceOf(): Str;
     /**
-     * Remove empty lines at the start of the text but leave whitespace on the first line with content
+     * Remove empty lines at the start of the text
+     * @returns A new Str instance with empty lines removed from the start
+     * @example
+     * ```typescript
+     * str('\n\n  Hello').chopEmptyLinesStart().$  // '  Hello'
+     * ```
      */
     chopEmptyLinesStart(): Str;
     /**
-     * Remove empty lines at the end of the text but leave whitespace on the last line with content
+     * Remove empty lines at the end of the text
+     * @returns A new Str instance with empty lines removed from the end
+     * @example
+     * ```typescript
+     * str('Hello\n\n').chopEmptyLinesEnd().$  // 'Hello'
+     * ```
      */
     chopEmptyLinesEnd(): Str;
     /**
-     * Remove all space (\s) characters in lines without content
+     * Remove whitespace from empty lines
+     * @returns A new Str instance with whitespace removed from empty lines
+     * @example
+     * ```typescript
+     * str('Hello\n   \nWorld').trimEmptyLines().$  // 'Hello\n\nWorld'
+     * ```
      */
     trimEmptyLines(): Str;
     /**
-     * Remove all spaces (\s) characters at the end of lines
+     * Remove trailing spaces from all lines
+     * @returns A new Str instance with trailing spaces removed from all lines
+     * @example
+     * ```typescript
+     * str('Hello  \nWorld  ').trimLinesTrailingSpaces().$  // 'Hello\nWorld'
+     * ```
      */
     trimLinesTrailingSpaces(): Str;
     /**
-     * Removes the leading and trailing white space and line terminator characters
+     * Remove leading and trailing whitespace
+     * @returns A new Str instance with whitespace removed from both ends
+     * @example
+     * ```typescript
+     * str('  Hello  ').trim().$  // 'Hello'
+     * ```
      */
     trim(): Str;
     /**
-     * Removes the leading white space and line terminator characters
+     * Remove leading whitespace
+     * @returns A new Str instance with leading whitespace removed
+     * @example
+     * ```typescript
+     * str('  Hello  ').trimStart().$  // 'Hello  '
+     * ```
      */
     trimStart(): Str;
     /**
-     * Removes the trailing white space and line terminator characters
+     * Remove trailing whitespace
+     * @returns A new Str instance with trailing whitespace removed
+     * @example
+     * ```typescript
+     * str('  Hello  ').trimEnd().$  // '  Hello'
+     * ```
      */
     trimEnd(): Str;
     /**
-     * Split a string into substrings using the specified separator and return them as an array
+     * Split the string into an array of Str instances
+     * @param separator - String or RegExp to split on
+     * @param limit - Maximum number of splits to perform
+     * @returns Array of Str instances
+     * @example
+     * ```typescript
+     * str('a,b,c').split(',')  // [Str('a'), Str('b'), Str('c')]
+     * str('a b c').split(' ', 2)  // [Str('a'), Str('b')]
+     * ```
      */
     split(separator: string | RegExp, limit?: number): Str[];
     /**
-     * Add line numbers to a string
-     * @param separator The separator to use between the line number and the line content.
-     * Defaults to ":"
+     * Add line numbers to each line
+     * @param separator - String to separate line numbers from content
+     * @returns A new Str instance with line numbers added
+     * @example
+     * ```typescript
+     * str('A\nB').addLineNumbers().$  // '0:A\n1:B'
+     * str('A\nB').addLineNumbers(' -> ').$  // '0 -> A\n1 -> B'
+     * ```
      */
     addLineNumbers(separator?: string): Str;
     /**
-     * Returns the character at the specified index
-     * @return string or undefined if the index is out of bounds
+     * Get the character at a specific index
+     * @param index - Zero-based position in the string
+     * @returns The character at the index, or undefined if out of bounds
+     * @example
+     * ```typescript
+     * str('Hello').at(0)   // 'H'
+     * str('Hello').at(-1)  // 'o'
+     * ```
      */
     at(index: number): string | undefined;
     /**
-     * Returns the length of the string
+     * Get the length of the string
+     * @returns The number of characters in the string
+     * @example
+     * ```typescript
+     * str('Hello').length()  // 5
+     * str('').length()       // 0
+     * ```
      */
     length(): number;
     /**
-     * Indent the string by the specified number of spaces
-     * @param size The number of spaces to indent by
-     * @param char The character to use for indentation. Defaults to " "
+     * Indent each line by a specified number of spaces
+     * @param size - Number of spaces to add
+     * @param char - Character to use for indentation
+     * @returns A new Str instance with added indentation
+     * @example
+     * ```typescript
+     * str('Hello\nWorld').indent(2).$  // '  Hello\n  World'
+     * str('A\nB').indent(2, '-').$     // '--A\n--B'
+     * ```
      */
     indent(size: number, char?: string): Str;
     /**
-     * Dedent the string by the specified number of spaces
-     * @param indentation The number of spaces to dedent by.
-     * If not provided, it will be calculated automatically based on the maximum indentation in the string.
+     * Remove indentation from each line
+     * @param indentation - Optional number of spaces to remove
+     * @returns A new Str instance with indentation removed
+     * @example
+     * ```typescript
+     * str('  Hello\n    World').dedent().$  // 'Hello\n  World'
+     * str('    A\n  B').dedent(2).$         // '  A\nB'
+     * ```
      */
     dedent(indentation?: number): Str;
     /**
-     * Chop the string at the start by the specified number of characters
+     * Remove characters from the start of the string
+     * @param count - Number of characters to remove
+     * @returns A new Str instance with characters removed from the start
+     * @example
+     * ```typescript
+     * str('Hello').chopStart(2).$  // 'llo'
+     * ```
      */
     chopStart(count: number): Str;
     /**
-     * Chop the string at the end by the specified number of characters
+     * Remove characters from the end of the string
+     * @param count - Number of characters to remove
+     * @returns A new Str instance with characters removed from the end
+     * @example
+     * ```typescript
+     * str('Hello').chopEnd(2).$  // 'Hel'
+     * ```
      */
     chopEnd(count: number): Str;
     /**
-     * Remove successive newlines of the specified repetition or more
-     * @param maxRepeat the maximum number of newlines to allow
+     * Limit consecutive newlines to a maximum count
+     * @param maxRepeat - Maximum number of consecutive newlines to allow
+     * @returns A new Str instance with limited consecutive newlines
+     * @example
+     * ```typescript
+     * str('A\n\n\nB').chopRepeatNewlines(1).$  // 'A\nB'
+     * str('A\n\n\nB').chopRepeatNewlines(2).$  // 'A\n\nB'
+     * ```
      */
     chopRepeatNewlines(maxRepeat: number): Str;
     /**
-     * Take the first n characters of the string
+     * Take characters from the start of the string
+     * @param count - Number of characters to take
+     * @returns A new Str instance with the first n characters
+     * @example
+     * ```typescript
+     * str('Hello').takeStart(2).$  // 'He'
+     * ```
      */
     takeStart(count: number): Str;
     /**
-     * Take the last n characters of the string
+     * Take characters from the end of the string
+     * @param count - Number of characters to take
+     * @returns A new Str instance with the last n characters
+     * @example
+     * ```typescript
+     * str('Hello').takeEnd(2).$  // 'lo'
+     * ```
      */
     takeEnd(count: number): Str;
     /**
-     * Returns the last line of the string
+     * Get the last line of the string
+     * @returns A new Str instance containing the last line
+     * @example
+     * ```typescript
+     * str('Hello\nWorld').lastLine().$  // 'World'
+     * ```
      */
     lastLine(): Str;
     /**
-     * Returns the first line of the string
+     * Get the first line of the string
+     * @returns A new Str instance containing the first line
+     * @example
+     * ```typescript
+     * str('Hello\nWorld').firstLine().$  // 'Hello'
+     * ```
      */
     firstLine(): Str;
     /**
-     * Returns the number of leading spaces in the string
+     * Count leading space characters
+     * @returns The number of leading space characters
+     * @example
+     * ```typescript
+     * str('  Hello').leadingSpacesCount()  // 2
+     * str('Hello').leadingSpacesCount()    // 0
+     * ```
      */
     leadingSpacesCount(): number;
     /**
-     * Returns the indentation level of the string skipping empty lines in the process
+     * Get the minimum indentation level of non-empty lines
+     * @returns The number of spaces in the minimum indentation
+     * @example
+     * ```typescript
+     * str('  Hello\n    World').indentation()  // 2
+     * str('Hello\n  World').indentation()      // 0
+     * ```
      */
     indentation(): number;
     /**
-     * Returns true if the string is empty or contains only whitespace
+     * Check if the string is empty or contains only whitespace
+     * @returns True if empty or whitespace-only, false otherwise
+     * @example
+     * ```typescript
+     * str('').isEmpty()      // true
+     * str('  \n').isEmpty()  // true
+     * str('Hello').isEmpty() // false
+     * ```
      */
     isEmpty(): boolean;
     /**
-     * Converts the string to camel case
+     * Replace the first occurrence of a substring or pattern
+     * @param searchValue - The string or pattern to search for
+     * @param replaceValue - The string to replace the match with
+     * @returns A new Str instance with the first match replaced
+     * @example
+     * ```typescript
+     * str('Hello World').replace('o', '0').$     // 'Hell0 World'
+     * str('abc abc').replace(/[a-z]/, 'X').$     // 'Xbc abc'
+     * ```
+     */
+    replace(searchValue: string | RegExp, replaceValue: string): Str;
+    /**
+     * Replace all occurrences of a substring or pattern
+     * @param searchValue - The string or pattern to search for
+     * @param replaceValue - The string to replace the matches with
+     * @returns A new Str instance with all matches replaced
+     * @example
+     * ```typescript
+     * str('Hello World').replaceAll('o', '0').$     // 'Hell0 W0rld'
+     * str('abc abc').replaceAll(/[a-z]/g, 'X').$    // 'XXX XXX'
+     * ```
+     */
+    replaceAll(searchValue: string | RegExp, replaceValue: string): Str;
+    /**
+     * Convert string to camelCase
+     * @returns A new Str instance in camelCase
+     * @example
+     * ```typescript
+     * str('hello-world').camelCase().$  // 'helloWorld'
+     * ```
      */
     camelCase(): Str;
     /**
-     * Converts the string to capital case
+     * Convert string to Capital Case
+     * @returns A new Str instance in Capital Case
+     * @example
+     * ```typescript
+     * str('hello-world').capitalCase().$  // 'Hello World'
+     * ```
      */
     capitalCase(): Str;
     /**
-     * Converts the string to constant case
+     * Convert string to CONSTANT_CASE
+     * @returns A new Str instance in CONSTANT_CASE
+     * @example
+     * ```typescript
+     * str('hello-world').constantCase().$  // 'HELLO_WORLD'
+     * ```
      */
     constantCase(): Str;
     /**
-     * Converts the string to dot case
+     * Convert string to dot.case
+     * @returns A new Str instance in dot.case
+     * @example
+     * ```typescript
+     * str('hello-world').dotCase().$  // 'hello.world'
+     * ```
      */
     dotCase(): Str;
     /**
-     * Converts the string to kebab case
+     * Convert string to kebab-case
+     * @returns A new Str instance in kebab-case
+     * @example
+     * ```typescript
+     * str('helloWorld').kebabCase().$  // 'hello-world'
+     * ```
      */
     kebabCase(): Str;
     /**
-     * Converts the string to no case
+     * Convert string to no case
+     * @returns A new Str instance with no case
+     * @example
+     * ```typescript
+     * str('helloWorld').noCase().$  // 'hello world'
+     * ```
      */
     noCase(): Str;
     /**
-     * Converts the string to pascal case
+     * Convert string to PascalCase
+     * @returns A new Str instance in PascalCase
+     * @example
+     * ```typescript
+     * str('hello-world').pascalCase().$  // 'HelloWorld'
+     * ```
      */
     pascalCase(): Str;
     /**
-     * Converts the string to pascal snake case
+     * Convert string to Pascal_Snake_Case
+     * @returns A new Str instance in Pascal_Snake_Case
+     * @example
+     * ```typescript
+     * str('hello-world').pascalSnakeCase().$  // 'Hello_World'
+     * ```
      */
     pascalSnakeCase(): Str;
     /**
-     * Converts the string to path case
+     * Convert string to path/case
+     * @returns A new Str instance in path/case
+     * @example
+     * ```typescript
+     * str('hello-world').pathCase().$  // 'hello/world'
+     * ```
      */
     pathCase(): Str;
     /**
-     * Converts the string to sentence case
+     * Convert string to Sentence case
+     * @returns A new Str instance in Sentence case
+     * @example
+     * ```typescript
+     * str('hello-world').sentenceCase().$  // 'Hello world'
+     * ```
      */
     sentenceCase(): Str;
     /**
-     * Converts the string to snake case
+     * Convert string to snake_case
+     * @returns A new Str instance in snake_case
+     * @example
+     * ```typescript
+     * str('helloWorld').snakeCase().$  // 'hello_world'
+     * ```
      */
     snakeCase(): Str;
     /**
-     * Converts the string to train case
+     * Convert string to Train-Case
+     * @returns A new Str instance in Train-Case
+     * @example
+     * ```typescript
+     * str('hello-world').trainCase().$  // 'Hello-World'
+     * ```
      */
     trainCase(): Str;
     /**
-     * Shorthand for `.toString()`
+     * Get the underlying string value
+     * @returns The wrapped string value
+     * @example
+     * ```typescript
+     * str('hello').str  // 'hello'
+     * ```
      */
     get str(): string;
 }
+/**
+ * Create a new Str instance from any stringable value
+ * @param text - Any value that can be converted to a string
+ * @returns A new Str instance wrapping the string value
+ * @example
+ * ```typescript
+ * str('hello')          // from string
+ * str(123)              // from number
+ * str({ toString() })   // from object with toString
+ * ```
+ */
 declare const str: (text: Stringable) => Str;
 
 /**
  * Remove empty lines at the start of the text but leave whitespace on the first line with content
+ * @param text - The input string to process
+ * @returns The string with empty lines removed from the start
+ * @example
+ * ```typescript
+ * chopEmptyLinesStart("\n\n  \n  Hello")  // "  Hello"
+ * chopEmptyLinesStart("  Hello")          // "  Hello"
+ * ```
  */
 declare const chopEmptyLinesStart: (text: string) => string;
 /**
  * Remove empty lines at the end of the text but leave whitespace on the last line with content
+ * @param text - The input string to process
+ * @returns The string with empty lines removed from the end
+ * @example
+ * ```typescript
+ * chopEmptyLinesEnd("Hello\n\n  \n")  // "Hello"
+ * chopEmptyLinesEnd("Hello  ")        // "Hello  "
+ * ```
  */
 declare const chopEmptyLinesEnd: (text: string) => string;
 /**
- * Remove all space (\s) characters in lines without content
+ * Remove all space characters in lines that contain no content
+ * @param text - The input string to process
+ * @returns The string with whitespace removed from empty lines
+ * @example
+ * ```typescript
+ * trimEmptyLines("Hello\n   \nWorld")  // "Hello\n\nWorld"
+ * trimEmptyLines("  \n  \n  ")        // "\n\n"
+ * ```
  */
 declare const trimEmptyLines: (text: string) => string;
 /**
- * Remove all space (\s) characters at the end of lines
+ * Remove all space characters at the end of each line
+ * @param text - The input string to process
+ * @returns The string with trailing spaces removed from all lines
+ * @example
+ * ```typescript
+ * trimLinesTrailingSpaces("Hello  \nWorld   ")  // "Hello\nWorld"
+ * trimLinesTrailingSpaces("Hello   ")          // "Hello"
+ * ```
  */
 declare const trimLinesTrailingSpaces: (text: string) => string;
 /**
- * Removes the leading and trailing white space and line terminator characters
+ * Remove leading and trailing whitespace and line terminator characters
+ * @param text - The input string to process
+ * @returns The trimmed string
+ * @example
+ * ```typescript
+ * trim("  Hello World  ")  // "Hello World"
+ * trim("\n  Hello  \n")   // "Hello"
+ * ```
  */
 declare const trim: (text: string) => string;
 /**
- * Removes the leading white space and line terminator characters
+ * Remove leading whitespace and line terminator characters
+ * @param text - The input string to process
+ * @returns The string with leading whitespace removed
+ * @example
+ * ```typescript
+ * trimStart("  Hello World  ")  // "Hello World  "
+ * trimStart("\n  Hello")       // "Hello"
+ * ```
  */
 declare const trimStart: (text: string) => string;
 /**
- * Removes the trailing white space and line terminator characters
+ * Remove trailing whitespace and line terminator characters
+ * @param text - The input string to process
+ * @returns The string with trailing whitespace removed
+ * @example
+ * ```typescript
+ * trimEnd("  Hello World  ")  // "  Hello World"
+ * trimEnd("Hello  \n")       // "Hello"
+ * ```
  */
 declare const trimEnd: (text: string) => string;
 /**
- * Split a string into substrings using the specified separator and return them as an array
+ * Split a string into substrings using the specified separator
+ * @param text - The input string to split
+ * @param separator - The string or regular expression to use for splitting
+ * @param limit - Optional limit on the number of splits to perform
+ * @returns An array of substrings
+ * @example
+ * ```typescript
+ * split("Hello World", " ")      // ["Hello", "World"]
+ * split("a,b,c", ",", 2)        // ["a", "b"]
+ * split("a.b-c", /[.-]/)        // ["a", "b", "c"]
+ * ```
  */
 declare const split: (text: string, separator: string | RegExp, limit?: number) => string[];
 /**
- * Add line numbers to a string
- * @param text The string to add line numbers to
- * @param separator The separator to use between the line number and the line content.
- * Defaults to ":"
+ * Add line numbers to each line in a string
+ * @param text - The string to add line numbers to
+ * @param separator - The separator between line number and content (defaults to ":")
+ * @returns The string with line numbers added
+ * @example
+ * ```typescript
+ * addLineNumbers("Hello\nWorld")           // "0:Hello\n1:World"
+ * addLineNumbers("A\nB\nC", " -> ")       // "0 -> A\n1 -> B\n2 -> C"
+ * ```
  */
 declare const addLineNumbers: (text: string, separator?: string) => string;
 /**
- * Returns the indentation level of the string skipping empty lines in the process
+ * Calculate the minimum indentation level of non-empty lines in the string
+ * @param text - The input string to analyze
+ * @returns The number of spaces in the minimum indentation level, or 0 if no indentation found
+ * @example
+ * ```typescript
+ * indentation("  Hello\n    World")  // 2
+ * indentation("Hello\n  World")      // 0
+ * indentation("  \n    Hello")       // 4
+ * ```
  */
 declare const indentation: (text: string) => number;
 /**
- * Indent the string by the specified number of spaces
- * @param size The number of spaces to indent by
- * @param char The character to use for indentation. Defaults to " "
+ * Indent each line of the string by a specified number of spaces
+ * @param text - The input string to indent
+ * @param size - The number of spaces to add at the start of each line
+ * @param char - The character to use for indentation (defaults to space)
+ * @returns The indented string
+ * @example
+ * ```typescript
+ * indent("Hello\nWorld", 2)        // "  Hello\n  World"
+ * indent("A\nB", 3, "-")          // "---A\n---B"
+ * ```
  */
 declare const indent: (text: string, size: number, char?: string) => string;
 /**
- * Dedent the string by the specified number of spaces
- * @param indentation The number of spaces to dedent by.
- * If not provided, it will be calculated automatically based on the maximum indentation in the string.
+ * Remove indentation from each line of the string
+ * @param text - The input string to dedent
+ * @param size - Optional number of spaces to remove. If not provided, removes the minimum common indentation
+ * @returns The dedented string
+ * @example
+ * ```typescript
+ * dedent("  Hello\n    World")     // "Hello\n  World"
+ * dedent("    A\n  B", 2)         // "  A\nB"
+ * ```
  */
 declare const dedent: (text: string, size?: number) => string;
 /**
- * Chop the string at the end by the specified number of characters
+ * Remove a specified number of characters from the end of the string
+ * @param text - The input string to process
+ * @param count - The number of characters to remove
+ * @returns The string with characters removed from the end
+ * @example
+ * ```typescript
+ * chopEnd("Hello World", 6)  // "Hello"
+ * chopEnd("Hello", 0)        // "Hello"
+ * ```
  */
 declare const chopEnd: (text: string, count: number) => string;
 /**
- * Chop the string at the start by the specified number of characters
+ * Remove a specified number of characters from the start of the string
+ * @param text - The input string to process
+ * @param count - The number of characters to remove
+ * @returns The string with characters removed from the start
+ * @example
+ * ```typescript
+ * chopStart("Hello World", 6)  // "World"
+ * chopStart("Hello", 0)        // "Hello"
+ * ```
  */
 declare const chopStart: (text: string, count: number) => string;
 /**
- * Remove successive newlines of the specified repetition or more
- * @param maxRepeat the maximum number of newlines to allow
+ * Limit the number of consecutive newlines in the string
+ * @param text - The input string to process
+ * @param maxRepeat - The maximum number of consecutive newlines to allow
+ * @returns The string with consecutive newlines limited
+ * @example
+ * ```typescript
+ * chopRepeatNewlines("A\n\n\n\nB", 2)  // "A\n\nB"
+ * chopRepeatNewlines("A\n\nB", 1)      // "A\nB"
+ * ```
  */
 declare const chopRepeatNewlines: (text: string, maxRepeat: number) => string;
 /**
- * Take the first n characters of the string
+ * Extract a specified number of characters from the start of the string
+ * @param text - The input string to process
+ * @param count - The number of characters to take
+ * @returns The extracted substring from the start
+ * @example
+ * ```typescript
+ * takeStart("Hello World", 5)  // "Hello"
+ * takeStart("Hi", 5)           // "Hi"
+ * ```
  */
 declare const takeStart: (text: string, count: number) => string;
 /**
- * Take the last n characters of the string
+ * Extract a specified number of characters from the end of the string
+ * @param text - The input string to process
+ * @param count - The number of characters to take
+ * @returns The extracted substring from the end
+ * @example
+ * ```typescript
+ * takeEnd("Hello World", 5)  // "World"
+ * takeEnd("Hi", 5)           // "Hi"
+ * ```
  */
 declare const takeEnd: (text: string, count: number) => string;
 /**
- * Returns the last line of the string
+ * Get the last line of a multi-line string
+ * @param text - The input string to process
+ * @returns The last line of the string, or empty string if input is empty
+ * @example
+ * ```typescript
+ * lastLine("Hello\nWorld")  // "World"
+ * lastLine("Hello")         // "Hello"
+ * lastLine("")             // ""
+ * ```
  */
 declare const lastLine: (text: string) => string;
 /**
- * Returns the first line of the string
+ * Get the first line of a multi-line string
+ * @param text - The input string to process
+ * @returns The first line of the string, or empty string if input is empty
+ * @example
+ * ```typescript
+ * firstLine("Hello\nWorld")  // "Hello"
+ * firstLine("Hello")         // "Hello"
+ * firstLine("")             // ""
+ * ```
  */
 declare const firstLine: (text: string) => string;
 /**
- * Returns the number of leading spaces in the string
+ * Count the number of leading space characters in a string
+ * @param text - The input string to analyze
+ * @returns The number of leading space characters
+ * @example
+ * ```typescript
+ * leadingSpacesCount("  Hello")  // 2
+ * leadingSpacesCount("Hello")    // 0
+ * ```
  */
 declare const leadingSpacesCount: (text: string) => number;
 /**
- * Returns true if the string is empty or contains only whitespace
+ * Check if a string is empty or contains only whitespace
+ * @param text - The input string to check
+ * @returns True if the string is empty or contains only whitespace, false otherwise
+ * @example
+ * ```typescript
+ * isEmpty("")         // true
+ * isEmpty("  \n  ")  // true
+ * isEmpty("Hello")   // false
+ * ```
  */
 declare const isEmpty: (text: string) => boolean;
+/**
+ * Replace the first occurrence of a substring or pattern in the string
+ * @param text - The input string to process
+ * @param searchValue - The string or pattern to search for
+ * @param replaceValue - The string to replace the match with
+ * @returns The string with the first match replaced
+ * @example
+ * ```typescript
+ * replace("Hello World", "o", "0")     // "Hell0 World"
+ * replace("abc abc", /[a-z]/, "X")     // "Xbc abc"
+ * ```
+ */
+declare const replace: (text: string, searchValue: string | RegExp, replaceValue: string) => string;
+/**
+ * Replace all occurrences of a substring or pattern in the string
+ * @param text - The input string to process
+ * @param searchValue - The string or pattern to search for
+ * @param replaceValue - The string to replace the matches with
+ * @returns The string with all matches replaced
+ * @example
+ * ```typescript
+ * replaceAll("Hello World", "o", "0")     // "Hell0 W0rld"
+ * replaceAll("abc abc", /[a-z]/g, "X")    // "XXX XXX"
+ * ```
+ */
+declare const replaceAll: (text: string, searchValue: string | RegExp, replaceValue: string) => string;
 
-export { Str, addLineNumbers, chopEmptyLinesEnd, chopEmptyLinesStart, chopEnd, chopRepeatNewlines, chopStart, dedent, firstLine, indent, indentation, isEmpty, lastLine, leadingSpacesCount, split, str, takeEnd, takeStart, trim, trimEmptyLines, trimEnd, trimLinesTrailingSpaces, trimStart };
+export { Str, addLineNumbers, chopEmptyLinesEnd, chopEmptyLinesStart, chopEnd, chopRepeatNewlines, chopStart, dedent, firstLine, indent, indentation, isEmpty, lastLine, leadingSpacesCount, replace, replaceAll, split, str, takeEnd, takeStart, trim, trimEmptyLines, trimEnd, trimLinesTrailingSpaces, trimStart };