@zinaid/str 0.0.5 → 0.0.7

package/dist/stringable/index.d.ts

@@ -0,0 +1,952 @@
+import { ConvertCaseMode, MarkDownExtensions, MarkDownOptions } from '../index.ts';
+export type ConditionableValue = string | number | boolean | ((instance: Stringable) => string | number | boolean);
+export type ConditionableClosure = ((instance: Stringable, value: ConditionableValue) => unknown) | null;
+/**
+ * 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;
+    /**
+     * Determine if a given string doesn't contain 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 not found, false otherwise
+     */
+    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;
+        omission?: string;
+    }): 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;
+    /**
+     * Parse input from a string to an array, according to a format.
+     *
+     * @param format - A format string like "%d", "%s", "%[^,],%s", etc.
+     * @returns Array of parsed values according to the format
+     *
+     * @example
+     *
+     * Str.of("SN/123456").scan("SN/%d") -> ["123456"]
+     * Str.of("Otwell, Taylor").scan("%[^,],%s") -> ["Otwell", "Taylor"]
+     * Str.of("filename.jpg").scan("%[^.].%s") -> ["filename", "jpg"]
+     */
+    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;
+    /**
+     * Apply the callback if the given "value" is (or resolves to) truthy.
+     *
+     * @param value - The value to evaluate or a closure that returns the value
+     * @param callback - The callback to execute if the value is truthy
+     * @param defaultCallback - The callback to execute if the value is falsy
+     * @returns Stringable - The current instance or the result of the callback
+     *
+     * @example
+     *
+     * ```typescript
+     * const str = new Stringable('hello world');
+     *
+     * Using a direct value
+     * str.when(true, s => s.upper()); // Returns 'HELLO WORLD'
+     * str.when(false, s => s.upper(), s => s.lower()); // Returns 'hello world'
+     *
+     * Using a closure to determine the value
+     * str.when(s => s.contains('world'), s => s.upper()); // Returns 'HELLO WORLD'
+     * str.when(s => s.contains('foo'), s => s.upper(), s => s.lower()); // Returns 'hello world'
+     * ```
+     */
+    when<TWhenParameter, TWhenReturnType>(value: ((instance: this) => TWhenParameter) | TWhenParameter | null, callback?: ((instance: this, value: TWhenParameter) => TWhenReturnType) | null, defaultCallback?: ((instance: this, value: TWhenParameter) => TWhenReturnType) | null): Stringable;
+    /**
+     * Apply the callback if the given "value" is (or resolves to) falsy.
+     *
+     * @param value - The value to evaluate or a closure that returns the value
+     * @param callback - The callback to execute if the value is falsy
+     * @param defaultCallback - The callback to execute if the value is truthy
+     * @returns Stringable - The current instance or the result of the callback
+     *
+     * @example
+     *
+     * const str = new Stringable('hello world');
+     * str.unless(true, s => s.upper()); // Returns 'hello world'
+     * str.unless(false, s => s.upper(), s => s.lower()); // Returns 'HELLO WORLD'
+     */
+    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.
+     */
+    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;
+}
+//# sourceMappingURL=index.d.ts.map