@synstack/str 1.1.3 → 1.2.0

package/dist/str.index.cjs

@@ -53,6 +53,8 @@ __export(str_index_exports, {
   pascalCase: () => import_change_case.pascalCase,
   pascalSnakeCase: () => import_change_case.pascalSnakeCase,
   pathCase: () => import_change_case.pathCase,
+  replace: () => replace,
+  replaceAll: () => replaceAll,
   sentenceCase: () => import_change_case.sentenceCase,
   snakeCase: () => import_change_case.snakeCase,
   split: () => split,
@@ -154,245 +156,502 @@ var leadingSpacesCount = (text) => {
 var isEmpty = (text) => {
   return text.trim() === "";
 };
+var replace = (text, searchValue, replaceValue) => {
+  return text.replace(searchValue, replaceValue);
+};
+var replaceAll = (text, searchValue, replaceValue) => {
+  if (typeof searchValue === "string") {
+    return text.replaceAll(searchValue, replaceValue);
+  }
+  const flags = searchValue.flags.includes("g") ? searchValue.flags : searchValue.flags + "g";
+  const globalRegex = new RegExp(searchValue.source, flags);
+  return text.replace(globalRegex, replaceValue);
+};
 
 // src/str.chainable.ts
 var Str = class _Str extends import_pipe.Pipeable {
   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) {
     super();
     this.text = text;
   }
+  /**
+   * Get the underlying string value
+   * @returns The wrapped string value
+   */
   valueOf() {
     return this.text;
   }
+  /**
+   * Convert the Str instance to a string
+   * @returns The wrapped string value
+   */
   toString() {
     return this.text;
   }
+  /**
+   * Get the current Str instance
+   * @returns The current Str instance
+   * @internal Used by Pipeable
+   */
   instanceOf() {
     return this;
   }
   /**
-   * 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() {
     return new _Str(chopEmptyLinesStart(this.text));
   }
   /**
-   * 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() {
     return new _Str(chopEmptyLinesEnd(this.text));
   }
   /**
-   * 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() {
     return new _Str(trimEmptyLines(this.text));
   }
   /**
-   * 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() {
     return new _Str(trimLinesTrailingSpaces(this.text));
   }
   /**
-   * 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() {
     return new _Str(trim(this.text));
   }
   /**
-   * 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() {
     return new _Str(trimStart(this.text));
   }
   /**
-   * 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() {
     return new _Str(trimEnd(this.text));
   }
   /**
-   * 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, limit) {
     return split(this.text, separator, limit).map((v) => new _Str(v));
   }
   /**
-   * 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 = ":") {
     return new _Str(addLineNumbers(this.text, separator));
   }
   /**
-   * 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) {
     return this.text.at(index);
   }
   /**
-   * 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() {
     return this.text.length;
   }
   /**
-   * 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, char = " ") {
     return new _Str(indent(this.text, size, char));
   }
   /**
-   * 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(indentation2) {
     return new _Str(dedent(this.text, indentation2));
   }
   /**
-   * 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) {
     return new _Str(chopStart(this.text, count));
   }
   /**
-   * 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) {
     if (count === 0) return this;
     return new _Str(chopEnd(this.text, count));
   }
   /**
-   * 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) {
     if (maxRepeat === 0) return this;
     return new _Str(chopRepeatNewlines(this.text, maxRepeat));
   }
   /**
-   * 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) {
     return new _Str(takeStart(this.text, count));
   }
   /**
-   * 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) {
     return new _Str(takeEnd(this.text, count));
   }
   /**
-   * 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() {
     return new _Str(lastLine(this.text));
   }
   /**
-   * 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() {
     return new _Str(firstLine(this.text));
   }
   /**
-   * 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() {
     return leadingSpacesCount(this.text);
   }
   /**
-   * 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() {
     return indentation(this.text);
   }
   /**
-   * 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() {
     return isEmpty(this.text);
   }
   /**
-   * 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, replaceValue) {
+    return new _Str(replace(this.text, searchValue, replaceValue));
+  }
+  /**
+   * 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, replaceValue) {
+    return new _Str(replaceAll(this.text, searchValue, replaceValue));
+  }
+  /**
+   * Convert string to camelCase
+   * @returns A new Str instance in camelCase
+   * @example
+   * ```typescript
+   * str('hello-world').camelCase().$  // 'helloWorld'
+   * ```
    */
   camelCase() {
     return new _Str(changeCase.camelCase(this.text));
   }
   /**
-   * 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() {
     return new _Str(changeCase.capitalCase(this.text));
   }
   /**
-   * 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() {
     return new _Str(changeCase.constantCase(this.text));
   }
   /**
-   * 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() {
     return new _Str(changeCase.dotCase(this.text));
   }
   /**
-   * 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() {
     return new _Str(changeCase.kebabCase(this.text));
   }
   /**
-   * 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() {
     return new _Str(changeCase.noCase(this.text));
   }
   /**
-   * 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() {
     return new _Str(changeCase.pascalCase(this.text));
   }
   /**
-   * 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() {
     return new _Str(changeCase.pascalSnakeCase(this.text));
   }
   /**
-   * 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() {
     return new _Str(changeCase.pathCase(this.text));
   }
   /**
-   * 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() {
     return new _Str(changeCase.sentenceCase(this.text));
   }
   /**
-   * 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() {
     return new _Str(changeCase.snakeCase(this.text));
   }
   /**
-   * 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() {
     return new _Str(changeCase.trainCase(this.text));
   }
   /**
-   * Shorthand for `.toString()`
+   * Get the underlying string value
+   * @returns The wrapped string value
+   * @example
+   * ```typescript
+   * str('hello').str  // 'hello'
+   * ```
    */
   get str() {
     return this.toString();
@@ -426,6 +685,8 @@ var str = (text) => {
   pascalCase,
   pascalSnakeCase,
   pathCase,
+  replace,
+  replaceAll,
   sentenceCase,
   snakeCase,
   split,