@zinaid/str 0.0.6 → 0.0.7

package/dist/stringable/index.d.ts

@@ -4,75 +4,138 @@ export type ConditionableClosure = ((instance: Stringable, value: ConditionableV
 /**
  * Get a new stringable object from the given string.
  *
+ * @param value - The string value to wrap in a Stringable instance.
+ * @returns A new Stringable instance.
+ *
  * @example
  *
  * of('foo').append('bar'); -> 'foobar'
  */
 export declare function of(value: string): Stringable;
+/**
+ * Get a new stringable object from the given string.
+ *
+ * @param value - The string value to wrap in a Stringable instance.
+ * @returns A new Stringable instance.
+ *
+ * @example
+ *
+ * str('foo').append('bar'); -> 'foobar'
+ */
+export declare function str(value: string): Stringable;
 export declare class Stringable {
     private readonly _value;
     /**
      * Create a new instance of the class.
+     *
+     * @param _value - The initial string value. Defaults to an empty string.
      */
     constructor(_value?: string);
     /**
      * Return the remainder of a string after the first occurrence of a given value.
+     *
+     * @param search - The substring to search for.
+     * @returns The portion of the string after the first occurrence of the search value.
      */
     after(search: string | number): Stringable;
     /**
      * Return the remainder of a string after the last occurrence of a given value
+     *
+     * @param search - The substring to search for.
+     * @returns The portion of the string after the last occurrence of the search value.
      */
     afterLast(search: string | number): Stringable;
     /**
      * Append the given values to the string.
+     *
+     * @param values - The values to append to the string.
+     * @returns The updated Stringable instance.
      */
     append(...values: Array<string | number>): Stringable;
     /**
      * Append a new line to the string.
+     *
+     * @param count - The number of new lines to append. Defaults to 1.
+     * @returns The updated Stringable instance.
      */
     newLine(count?: number): Stringable;
     /**
      * Transliterate a UTF-8 value to ASCII.
+     *
+     * @returns The transliterated string as a new Stringable instance.
      */
     ascii(): Stringable;
     /**
      * Get the portion of a string before the first occurrence of a given value.
+     *
+     * @param search - The substring to search for.
+     * @returns The portion of the string before the first occurrence of the search value.
      */
     before(search: string | number): Stringable;
     /**
      * Get the portion of a string before the last occurrence of a given value.
+     *
+     * @param search - The substring to search for.
+     * @returns The portion of the string before the last occurrence of the search value.
      */
     beforeLast(search: string | number): Stringable;
     /**
      * Get the portion of a string between two given values.
+     *
+     * @param from - The starting substring.
+     * @param to - The ending substring.
+     * @returns The portion of the string between the two given values.
      */
     between(from: string | number, to: string | number): Stringable;
     /**
      * Get the smallest possible portion of a string between two given values.
+     *
+     * @param from - The starting substring.
+     * @param to - The ending substring.
+     * @returns The smallest possible portion of the string between the two given values.
      */
     betweenFirst(from: string | number, to: string | number): Stringable;
     /**
      * Convert a value to camel case.
+     *
+     * @returns The camel-cased string as a new Stringable instance.
      */
     camel(): Stringable;
     /**
      * Get the character at the specified index.
+     *
+     * @param index - The index of the character to retrieve.
+     * @returns The character at the specified index, or false if the index is out of bounds.
      */
     charAt(index: number): string | false;
     /**
      * Remove the given string if it exists at the start of the current string.
+     *
+     * @param needle - The string or array of strings to remove from the start.
+     * @returns The updated Stringable instance.
      */
     chopStart(needle: string | string[]): Stringable;
     /**
      * Remove the given string if it exists at the end of the current string.
+     *
+     * @param needle - The string or array of strings to remove from the end.
+     * @returns The updated Stringable instance.
      */
     chopEnd(needle: string | string[]): Stringable;
     /**
      * Determine if a given string contains a given substring.
+     *
+     * @param needles - The substring(s) to search for
+     * @param ignoreCase - Whether the search should be case-insensitive
+     * @returns boolean - True if the substring(s) are found, false otherwise
      */
     contains(needles: string | Iterable<string>, ignoreCase?: boolean): boolean;
     /**
      * Determine if a given string contains all array values.
+     *
+     * @param needles - The substring(s) to search for
+     * @param ignoreCase - Whether the search should be case-insensitive
+     * @returns boolean - True if all substring(s) are found, false otherwise
      */
     containsAll(needles: Iterable<string>, ignoreCase?: boolean): boolean;
     /**
@@ -85,26 +148,45 @@ export declare class Stringable {
     doesntContain(needles: string | Iterable<string>, ignoreCase?: boolean): boolean;
     /**
      * Convert the case of a string.
+     *
+     * @param mode - The case conversion mode to apply.
+     * @returns The converted string as a new Stringable instance.
      */
     convertCase(mode: ConvertCaseMode): Stringable;
     /**
      * Replace consecutive instances of a given character with a single character.
+     *
+     * @param character - The character or array of characters to deduplicate. Defaults to a space.
+     * @returns The updated Stringable instance.
      */
     deduplicate(character?: string | string[]): Stringable;
     /**
      * Determine if a given string ends with a given substring.
+     *
+     * @param needles - The substring(s) to search for
+     * @returns boolean - True if the substring(s) are found, false otherwise
      */
     endsWith(needles: string | number | Iterable<string>): boolean;
     /**
      * Determine if a given string doesn't end with a given substring.
+     *
+     * @param needles - The substring(s) to search for
+     * @returns boolean - True if the substring(s) are not found, false otherwise
      */
     doesntEndWith(needles: string | number | Iterable<string>): boolean;
     /**
      * Determine if the string is an exact match with the given value.
+     *
+     * @param value - The value to compare against.
+     * @returns True if the strings are exactly the same, false otherwise.
      */
     exactly(value: Stringable | string): boolean;
     /**
      * Extracts an excerpt from text that matches the first instance of a phrase.
+     *
+     * @param phrase - The phrase to search for within the text.
+     * @param options - Options to customize the excerpt extraction, including radius and omission string.
+     * @returns The extracted excerpt or null if the phrase is not found.
      */
     excerpt(phrase?: string | null, options?: {
         radius?: number;
@@ -112,170 +194,309 @@ export declare class Stringable {
     }): string | null;
     /**
      * Explode the string into an array
+     *
+     * @param delimiter - The delimiter string to split the string by.
+     * @param limit - The maximum number of elements to return. Defaults to Number.MAX_SAFE_INTEGER.
+     * @returns An array of strings obtained by splitting the original string.
      */
     explode(delimiter: string, limit?: number): string[];
     /**
      * Split a string using a regular expression or by length.
+     *
+     * @param pattern - The regex pattern or length to split the string by.
+     * @param limit - The maximum number of splits to perform. Defaults to null (no limit).
+     * @returns An array of strings obtained by splitting the original string.
      */
     split(pattern: string | number, limit?: number | null): string[];
     /**
      * Cap a string with a single instance of a given value.
+     *
+     * @param cap - The string to cap the original string with.
+     * @returns The updated Stringable instance.
      */
     finish(cap: string): Stringable;
     /**
      * Determine if a given string matches a given pattern.
+     *
+     * @param pattern - The pattern(s) to match against
+     * @returns boolean - True if the pattern(s) match, false otherwise
      */
     is(pattern: string | Iterable<string>, ignoreCase?: boolean): boolean;
     /**
      * Determine if a given string is 7 bit ASCII.
+     *
+     * @returns True if the string is ASCII, false otherwise.
      */
     isAscii(): boolean;
     /**
      * Determine if a given string is valid JSON.
+     *
+     * @returns True if the string is valid JSON, false otherwise.
      */
     isJson(): boolean;
     /**
      * Determine if a given value is a valid URL.
+     *
+     * @param protocols - An array of allowed protocols (e.g., ['http', 'https']).
+     * @returns True if the string is a valid URL, false otherwise.
      */
     isUrl(protocols?: string[]): boolean;
     /**
      * Determine if a given string is a valid UUID.
+     *
+     * @param version - The UUID version to validate against (1-5), "nil", "max", or null for any version.
+     * @returns True if the string is a valid UUID, false otherwise.
      */
     isUuid(version?: number | "nil" | "max" | null): boolean;
     /**
      * Determine if a given string is a valid ULID.
+     *
+     * @return True if the string is a valid ULID, false otherwise.
      */
     isUlid(): boolean;
     /**
      * Determine if the given string is empty.
+     *
+     * @return True if the string is empty, false otherwise.
      */
     isEmpty(): boolean;
     /**
      * Determine if the given string is not empty.
+     *
+     * @return True if the string is not empty, false otherwise.
      */
     isNotEmpty(): boolean;
     /**
      * Convert a string to kebab case.
+     *
+     * @returns The kebab-cased string as a new Stringable instance.
      */
     kebab(): Stringable;
     /**
      * Return the length of the given string.
+     *
+     * @returns The length of the string.
      */
     length(): number;
     /**
      * Limit the number of characters in a string.
+     *
+     * @param limitValue - The maximum number of characters allowed.
+     * @param end - The string to append if the original string exceeds the limit.
+     * @param preserveWords - Whether to avoid cutting off in the middle of a word.
+     * @returns A new Stringable instance with the limited string.
      */
     limit(limitValue?: number, end?: string, preserveWords?: boolean): Stringable;
     /**
      * Convert the given string to lower-case.
+     *
+     * @returns The lower-cased string as a new Stringable instance.
      */
     lower(): Stringable;
     /**
      * Convert GitHub flavored Markdown into HTML.
+     *
+     * @param options - Options to customize the markdown rendering. Defaults to GFM enabled and no anchors.
+     * @param extensions - An array of markdown-it extensions to apply during rendering.
+     * @returns The resulting HTML string as a new Stringable instance.
      */
     markdown(options?: MarkDownOptions, extensions?: MarkDownExtensions): Stringable;
     /**
      * Convert inline Markdown into HTML.
+     *
+     * @param options - Options to customize the markdown rendering. Defaults to GFM enabled.
+     * @param extensions - An array of markdown-it extensions to apply during rendering.
+     * @returns The resulting HTML string as a new Stringable instance.
      */
     inlineMarkdown(options?: MarkDownOptions, extensions?: MarkDownExtensions): Stringable;
     /**
      * Masks a portion of a string with a repeated character.
+     *
+     * @param character - The character to use for masking.
+     * @param index - The starting index to begin masking.
+     * @param length - The number of characters to mask. If null, masks to the end of the string.
+     * @returns The masked string as a new Stringable instance.
      */
     mask(character: string, index: number, length?: number | null): Stringable;
     /**
      * Get the string matching the given pattern.
+     *
+     * @param pattern - The pattern to match against.
+     * @returns A new Stringable instance containing the matched string.
      */
     match(pattern: string): Stringable;
     /**
      * Determine if a given string matches a given pattern.
+     *
+     * @param pattern - The pattern(s) to match against
+     * @returns boolean - True if the pattern(s) match, false otherwise
      */
     isMatch(pattern: string | Iterable<string>): boolean;
     /**
      * Get the string matching the given pattern.
+     *
+     * @param pattern - The pattern to match against.
+     * @returns An array of all matched strings.
      */
     matchAll(pattern: string): string[];
     /**
      * Determine if the string matches the given pattern.
+     *
+     * @param pattern - The pattern(s) to match against
+     * @returns boolean - True if the pattern(s) match, false otherwise
      */
     test(pattern: string): boolean;
     /**
      * Remove all non-numeric characters from a string.
+     *
+     * @returns The numeric string as a new Stringable instance.
      */
     numbers(): Stringable;
     /**
      * Pad both sides of the string with another.
+     *
+     * @param length - The desired total length of the string after padding.
+     * @param pad - The string to use for padding. Defaults to a space.
+     * @returns The padded string as a new Stringable instance.
      */
     padBoth(length: number, pad?: string): Stringable;
     /**
      * Pad the left side of the string with another.
+     *
+     * @param length - The desired total length of the string after padding.
+     * @param pad - The string to use for padding. Defaults to a space.
+     * @returns The padded string as a new Stringable instance.
      */
     padLeft(length: number, pad?: string): Stringable;
     /**
      * Pad the right side of the string with another.
+     *
+     * @param length - The desired total length of the string after padding.
+     * @param pad - The string to use for padding. Defaults to a space.
+     * @returns The padded string as a new Stringable instance.
      */
     padRight(length: number, pad?: string): Stringable;
     /**
      * Call the given callback and return a new string.
+     *
+     * @param callback - The callback function to process the string.
+     * @returns The processed string as a new Stringable instance.
      */
     pipe<T = Stringable | string>(callback: (s: Stringable) => T): Stringable;
     /**
      * Get the plural form of an English word.
+     *
+     * @param count - The count to determine singular or plural form. Defaults to 2.
+     * @param prependCount - Whether to prepend the count to the result. Defaults to false.
+     * @returns The pluralized string as a new Stringable instance.
      */
     plural(count?: number, prependCount?: boolean): Stringable;
     /**
      * Pluralize the last word of an English, studly caps case string.
+     *
+     * @param count - The count to determine singular or plural form. Defaults to 2.
+     * @returns The pluralized string as a new Stringable instance.
      */
     pluralStudly(count?: number): Stringable;
     /**
      * Pluralize the last word of an English, Pascal caps case string.
+     *
+     * @param count - The count to determine singular or plural form. Defaults to 2.
+     * @returns The pluralized string as a new Stringable instance.
      */
     pluralPascal(count?: number): Stringable;
     /**
      * Find the multi-byte safe position of the first occurrence of the given substring.
+     *
+     * @param needle - The substring to search for.
+     * @param offset - The offset from which to start the search. Defaults to 0.
+     * @returns The position of the first occurrence of the substring, or false if not found.
      */
     position(needle: string, offset?: number): number | false;
     /**
      * Prepend the given values to the string.
+     *
+     * @param values - The values to prepend to the string.
+     * @returns The updated Stringable instance.
      */
     prepend(...values: Array<string | number>): Stringable;
     /**
      * Remove any occurrence of the given string in the subject.
+     *
+     * @param search - The string or iterable of strings to remove.
+     * @param caseSensitive - Whether the search should be case-sensitive. Defaults to true.
+     * @returns The updated Stringable instance.
      */
     remove(search: string | Iterable<string>, caseSensitive?: boolean): Stringable;
     /**
      * Reverse the string.
+     *
+     * @returns The reversed string as a new Stringable instance.
      */
     reverse(): Stringable;
     /**
      * Repeat the string.
+     *
+     * @param times - The number of times to repeat the string.
+     * @returns The repeated string as a new Stringable instance.
      */
     repeat(times: number): Stringable;
     /**
      * Replace the given value in the given string.
+     *
+     * @param search - The value or iterable of values to search for.
+     * @param replacement - The replacement value or iterable of values.
+     * @param caseSensitive - Whether the search should be case-sensitive. Defaults to true.
+     * @returns The updated Stringable instance.
      */
     replace(search: string | Iterable<string>, replacement: string | Iterable<string>, caseSensitive?: boolean): Stringable;
     /**
      * Replace a given value in the string sequentially with an array.
+     *
+     * @param search - The value to search for.
+     * @param replace - The array or record of replacements.
+     * @returns The updated Stringable instance.
      */
     replaceArray(search: string, replace: Record<string, string> | Iterable<string>): Stringable;
     /**
      * Replace the first occurrence of a given value in the string.
+     *
+     * @param search - The value to search for.
+     * @param replace - The replacement value.
+     * @returns The updated Stringable instance.
      */
     replaceFirst(search: string | number, replace: string): Stringable;
     /**
      * Replace the first occurrence of the given value if it appears at the start of the string.
+     *
+     * @param search - The value to search for.
+     * @param replace - The replacement value.
+     * @returns The updated Stringable instance.
      */
     replaceStart(search: string | number, replace: string): Stringable;
     /**
      * Replace the last occurrence of a given value in the string.
+     *
+     * @param search - The value to search for.
+     * @param replace - The replacement value.
+     * @returns The updated Stringable instance.
      */
     replaceLast(search: string | number, replace: string): Stringable;
     /**
      * Replace the last occurrence of a given value if it appears at the end of the string.
+     *
+     * @param search - The value to search for.
+     * @param replace - The replacement value.
+     * @returns The updated Stringable instance.
      */
     replaceEnd(search: string | number, replace: string): Stringable;
     /**
      * Replace the patterns matching the given regular expression.
+     *
+     * @param pattern - The pattern(s) to search for.
+     * @param replace - The replacement string(s) or a callback function.
+     * @param limit - The maximum number of replacements to perform. Defaults to -1 (no limit).
+     * @returns The updated Stringable instance.
      */
     replaceMatches(pattern: string | string[] | RegExp | RegExp[], replace: string | string[] | ((match: string[]) => string), limit?: number): Stringable;
     /**
@@ -293,110 +514,183 @@ export declare class Stringable {
     scan(format: string): string[];
     /**
      * Remove all "extra" blank space from the given string.
+     *
+     * @returns The updated Stringable instance.
      */
     squish(): Stringable;
     /**
      * Begin a string with a single instance of a given value.
+     *
+     * @param prefix - The string to start the original string with.
+     * @returns The updated Stringable instance.
      */
     start(prefix: string): Stringable;
     /**
      * Strip HTML and PHP tags from the given string.
+     *
+     * @returns The updated Stringable instance.
      */
     stripTags(): Stringable;
     /**
      * Convert the given string to upper-case.
+     *
+     * @returns The upper-cased string as a new Stringable instance.
      */
     upper(): Stringable;
     /**
      * Convert the given string to proper case.
+     *
+     * @returns The title-cased string as a new Stringable instance.
      */
     title(): Stringable;
     /**
      * Convert the given string to proper case for each word.
+     *
+     * @returns The headline-cased string as a new Stringable instance.
      */
     headline(): Stringable;
     /**
      * Convert the given string to APA-style title case.
+     *
+     * @returns The APA title-cased string as a new Stringable instance.
      */
     apa(): Stringable;
     /**
      * Transliterate a string to its closest ASCII representation.
+     *
+     * @returns The transliterated string as a new Stringable instance.
      */
     transliterate(): Stringable;
     /**
      * Get the singular form of an English word.
+     *
+     * @returns The singularized string as a new Stringable instance.
      */
     singular(): Stringable;
     /**
      * Generate a URL friendly "slug" from a given string.
+     *
+     * @param separator - The separator to use in the slug. Defaults to "-".
+     * @param dictionary - A dictionary of characters to replace. Defaults to { "@": "at" }.
+     * @returns The slugified string as a new Stringable instance.
      */
     slug(separator?: string, dictionary?: Record<string, string>): Stringable;
     /**
      * Convert a string to snake case.
+     *
+     * @param delimiter - The delimiter to use in the snake case. Defaults to "_".
+     * @returns The snake-cased string as a new Stringable instance.
      */
     snake(delimiter?: string): Stringable;
     /**
      * Determine if a given string starts with a given substring.
+     *
+     * @param needles - The substring(s) to search for
+     * @returns boolean - True if the substring(s) are found, false otherwise
      */
     startsWith(needles: string | number | null | Iterable<string | number | null>): boolean;
     /**
      * Determine if a given string doesn't start with a given substring.
+     *
+     * @param needles - The substring(s) to search for
+     * @returns boolean - True if the substring(s) are not found, false otherwise
      */
     doesntStartWith(needles: string | number | null | Iterable<string | number | null>): boolean;
     /**
      * Convert a value to studly caps case.
+     *
+     * @returns The studly-cased string as a new Stringable instance.
      */
     studly(): Stringable;
     /**
      * Convert the string to Pascal case.
+     *
+     * @returns The pascal-cased string as a new Stringable instance.
      */
     pascal(): Stringable;
     /**
      * Returns the portion of the string specified by the start and length parameters.
+     *
+     * @param start - The starting position of the substring.
+     * @param length - The length of the substring. If null, extracts to the end of the string.
+     * @returns The extracted substring as a new Stringable instance.
      */
     substr(start: number, length?: number | null): Stringable;
     /**
      * Returns the number of substring occurrences.
+     *
+     * @param needle - The substring to search for.
+     * @param offset - The offset to start searching from. Defaults to 0.
+     * @param length - The length of the string to search within. If null, searches to the end of the string.
+     * @returns The number of occurrences of the substring.
      */
     substrCount(needle: string, offset?: number, length?: number | null): number;
     /**
      * Replace text within a portion of a string.
+     *
+     * @param replace - The replacement string.
+     * @param offset - The starting position to begin replacing.
+     * @param length - The number of characters to replace. If null, replaces to the end of the string.
+     * @returns The updated Stringable instance.
      */
     substrReplace(replace: string, offset?: number | number[], length?: number | number[] | null): Stringable;
     /**
      * Swap multiple keywords in a string with other keywords.
+     *
+     * @param map - A record of keywords to swap (key: search, value: replacement).
+     * @returns The updated Stringable instance.
      */
     swap(map: Record<string, string>): Stringable;
     /**
      * Take the first or last {$limit} characters.
+     *
+     * @param limit - The number of characters to take. Positive for start, negative for end.
+     * @returns The resulting substring as a new Stringable instance.
      */
     take(limit: number): Stringable;
     /**
      * Trim the string of the given characters.
+     *
+     * @param charlist - The characters to trim from the string. If null, trims whitespace.
+     * @returns The trimmed string as a new Stringable instance.
      */
     trim(charlist?: string | null): Stringable;
     /**
      * Left trim the string of the given characters.
+     *
+     * @param charlist - The characters to trim from the start of the string. If null, trims whitespace.
+     * @returns The left-trimmed string as a new Stringable instance.
      */
     ltrim(charlist?: string | null): Stringable;
     /**
      * Right trim the string of the given characters.
+     *
+     * @param charlist - The characters to trim from the end of the string. If null, trims whitespace.
+     * @returns The right-trimmed string as a new Stringable instance.
      */
     rtrim(charlist?: string | null): Stringable;
     /**
      * Make a string's first character lowercase.
+     *
+     * @returns The updated Stringable instance.
      */
     lcfirst(): Stringable;
     /**
      * Make a string's first character uppercase.
+     *
+     * @returns The updated Stringable instance.
      */
     ucfirst(): Stringable;
     /**
      * Split a string by uppercase characters.
+     *
+     * @returns An array of substrings split at uppercase characters.
      */
     ucsplit(): string[];
     /**
      * Uppercase the first character of each word in a string.
+     *
+     * @returns The updated Stringable instance.
      */
     ucwords(): Stringable;
     /**
@@ -439,116 +733,219 @@ export declare class Stringable {
     unless<TUnlessParameter, TUnlessReturnType>(value: ((instance: this) => TUnlessParameter) | TUnlessParameter | null, callback?: ((instance: this, value: TUnlessParameter) => TUnlessReturnType) | null, defaultCallback?: ((instance: this, value: TUnlessParameter) => TUnlessReturnType) | null): Stringable;
     /**
      * Execute the given callback if the string contains a given substring.
+     *
+     * @param needles - The substring(s) to search for
+     * @param callback - The callback to execute if the substring(s) are found
+     * @param defaultCallback - The callback to execute if the substring(s) are not found
+     * @returns Stringable - The current instance or the result of the callback
      */
     whenContains(needles: string | Iterable<string>, callback: ConditionableClosure, defaultCallback?: ConditionableClosure): Stringable;
     /**
      * Execute the given callback if the string contains all array values.
+     *
+     * @param needles - The substring(s) to search for
+     * @param callback - The callback to execute if all substring(s) are found
+     * @param defaultCallback - The callback to execute if not all substring(s) are found
+     * @returns Stringable - The current instance or the result of the callback
      */
     whenContainsAll(needles: string | Iterable<string>, callback: ConditionableClosure, defaultCallback?: ConditionableClosure): Stringable;
     /**
      * Execute the given callback if the string is empty.
+     *
+     * @param callback - The callback to execute if the string is empty
+     * @param defaultCallback - The callback to execute if the string is not empty
+     * @returns Stringable - The current instance or the result of the callback
      */
     whenEmpty(callback: ConditionableClosure, defaultCallback?: ConditionableClosure): Stringable;
     /**
      * Execute the given callback if the string is not empty.
+     *
+     * @param callback - The callback to execute if the string is not empty
+     * @param defaultCallback - The callback to execute if the string is empty
+     * @returns Stringable - The current instance or the result of the callback
      */
     whenNotEmpty(callback: ConditionableClosure, defaultCallback?: ConditionableClosure): Stringable;
     /**
      * Execute the given callback if the string ends with a given substring.
+     *
+     * @param needles - The substring(s) to search for
+     * @param callback - The callback to execute if the substring(s) are found
+     * @param defaultCallback - The callback to execute if the substring(s) are not found
+     * @returns Stringable - The current instance or the result of the callback
      */
     whenEndsWith(needles: string | Iterable<string>, callback: ConditionableClosure, defaultCallback?: ConditionableClosure): Stringable;
     /**
      * Execute the given callback if the string doesn't end with a given substring.
+     *
+     * @param needles - The substring(s) to search for
+     * @param callback - The callback to execute if the substring(s) are not found
+     * @param defaultCallback - The callback to execute if the substring(s) are found
+     * @returns Stringable - The current instance or the result of the callback
      */
     whenDoesntEndWith(needles: string | Iterable<string>, callback: ConditionableClosure, defaultCallback?: ConditionableClosure): Stringable;
     /**
      * Execute the given callback if the string is an exact match with the given value.
+     *
+     * @param value - The value to compare against
+     * @param callback - The callback to execute if the string matches the value
+     * @param defaultCallback - The callback to execute if the string does not match the value
+     * @returns Stringable - The current instance or the result of the callback
      */
     whenExactly(value: string, callback: ConditionableClosure, defaultCallback?: ConditionableClosure): Stringable;
     /**
      * Execute the given callback if the string is not an exact match with the given value.
+     *
+     * @param value - The value to compare against
+     * @param callback - The callback to execute if the string does not match the value
+     * @param defaultCallback - The callback to execute if the string matches the value
+     * @returns Stringable - The current instance or the result of the callback
      */
     whenNotExactly(value: string, callback: ConditionableClosure, defaultCallback?: ConditionableClosure): Stringable;
     /**
      * Execute the given callback if the string matches a given pattern.
+     *
+     * @param pattern - The pattern(s) to match against
+     * @param callback - The callback to execute if the pattern(s) match
+     * @param defaultCallback - The callback to execute if the pattern(s) do not match
+     * @returns Stringable - The current instance or the result of the callback
      */
     whenIs(pattern: string | Iterable<string>, callback: ConditionableClosure, defaultCallback?: ConditionableClosure): Stringable;
     /**
      * Execute the given callback if the string is 7 bit ASCII.
+     *
+     * @param callback - The callback to execute if the string is ASCII
+     * @param defaultCallback - The callback to execute if the string is not ASCII
+     * @returns Stringable - The current instance or the result of the callback
      */
     whenIsAscii(callback: ConditionableClosure, defaultCallback?: ConditionableClosure): Stringable;
     /**
      * Execute the given callback if the string is a valid UUID.
+     *
+     * @param callback - The callback to execute if the string is a UUID
+     * @param defaultCallback - The callback to execute if the string is not a UUID
+     * @returns Stringable - The current instance or the result of the callback
      */
     whenIsUuid(callback: ConditionableClosure, defaultCallback?: ConditionableClosure): Stringable;
     /**
      * Execute the given callback if the string is a valid ULID.
+     *
+     * @param callback - The callback to execute if the string is a ULID
+     * @param defaultCallback - The callback to execute if the string is not a ULID
+     * @returns Stringable - The current instance or the result of the callback
      */
     whenIsUlid(callback: ConditionableClosure, defaultCallback?: ConditionableClosure): Stringable;
     /**
      * Execute the given callback if the string starts with a given substring.
+     *
+     * @param needles - The substring(s) to search for
+     * @param callback - The callback to execute if the substring(s) are found
+     * @param defaultCallback - The callback to execute if the substring(s) are not found
+     * @returns Stringable - The current instance or the result of the callback
      */
     whenStartsWith(needles: string | Iterable<string>, callback: ConditionableClosure, defaultCallback?: ConditionableClosure): Stringable;
     /**
      * Execute the given callback if the string matches the given pattern.
+     *
+     * @param pattern - The pattern(s) to match against
+     * @param callback - The callback to execute if the pattern(s) match
+     * @param defaultCallback - The callback to execute if the pattern(s) do not match
+     * @returns Stringable - The current instance or the result of the callback
      */
     whenTest(pattern: string, callback: ConditionableClosure, defaultCallback?: ConditionableClosure): Stringable;
     /**
      * Limit the number of words in a string.
+     *
+     * @param wordsValue - The maximum number of words allowed. Defaults to 100.
+     * @param end - The string to append if the string is truncated. Defaults to "...".
+     * @returns The truncated string as a new Stringable instance.
      */
     words(wordsValue?: number, end?: string): Stringable;
     /**
      * Get the number of words a string contains.
+     *
+     * @param characters - The characters to consider as word boundaries. If null, defaults to standard word boundaries.
+     * @returns The number of words in the string.
      */
     wordCount(characters?: string | null): number;
     /**
      * Wrap a string to a given number of characters.
+     *
+     * @param characters - The number of characters at which to wrap the string. Defaults to 75.
+     * @param breakStr - The string to insert as a break. Defaults to "\n".
+     * @param cutLongWords - Whether to cut words longer than the specified length. Defaults to false.
+     * @returns The wrapped string as a new Stringable instance.
      */
     wordWrap(characters?: number, breakStr?: string, cutLongWords?: boolean): Stringable;
     /**
      * Wrap the string with the given strings.
+     *
+     * @param before - The string to prepend
+     * @param after - The string to append. Defaults to the value of `before`
+     * @returns The wrapped string as a new Stringable instance.
      */
     wrap(before: string, after?: string | null): Stringable;
     /**
      * Unwrap the string with the given strings.
+     *
+     * @param before - The string to remove from the start
+     * @param after - The string to remove from the end. Defaults to the value of `before`
+     * @returns The unwrapped string as a new Stringable instance.
      */
     unwrap(before: string, after?: string | null): Stringable;
     /**
      * Convert the string to Base64 encoding.
+     *
+     * @returns The Base64 encoded string as a new Stringable instance.
      */
     toBase64(): Stringable;
     /**
      * Decode the Base64 encoded string.
+     *
+     * @param strict - Whether to use strict decoding. Defaults to false.
+     * @returns The decoded string as a new Stringable instance, or false on failure.
      */
     fromBase64(strict?: boolean): Stringable | false;
     /**
      * Get the underlying string value.
+     *
+     * @returns The string representation of the object.
      */
     toString(): string;
     /**
      * Get the underlying string value.
+     *
+     * @returns The string value.
      */
     value(): string;
     /**
      * Get the underlying string value as an integer.
+     *
+     * @param base - The base to use for conversion. Defaults to 10.
+     * @returns The integer value.
      */
     toInteger(base?: number): number;
     /**
      * Get the underlying string value as a float.
+     *
+     * @returns The float value.
      */
     toFloat(): number;
     /**
      * Get the underlying string value as a boolean.
      *
-     * Returns true when value is "1", "true", "on", and "yes". Otherwise, returns false.
+     * @returns true when value is "1", "true", "on", and "yes". Otherwise, returns false.
      */
     toBoolean(): boolean;
     /**
      * Get the underlying string value as a Carbon instance.
+     *
+     * @returns The Date instance or null if parsing fails.
      */
     toDate(): Date | null;
     /**
      * Convert the object to a string when JSON encoded.
+     *
+     * @returns The string representation of the object.
      */
     jsonSerialize(): string;
 }