@zinaid/str 0.0.6 → 0.0.8

package/dist/stringable/index.js

@@ -1,35 +1,52 @@
-import { after as p, afterLast as d, ascii as f, before as m, beforeLast as _, between as E, betweenFirst as y, camel as A, charAt as W, chopStart as x, chopEnd as N, contains as k, containsAll as U, doesntContain as C, convertCase as L, deduplicate as M, endsWith as F, doesntEndWith as I, excerpt as B, finish as R, is as j, isAscii as D, isJson as T, isUrl as P, isUuid as q, isUlid as J, kebab as V, length as $, limit as z, lower as a, markdown as G, inlineMarkdown as X, mask as H, match as K, isMatch as O, matchAll as Q, numbers as Y, padBoth as Z, padLeft as g, padRight as b, plural as S, pluralStudly as ee, pluralPascal as te, position as se, remove as re, reverse as ne, repeat as ue, replace as he, replaceArray as ie, replaceFirst as le, replaceStart as ae, replaceLast as we, replaceEnd as oe, replaceMatches as ve, squish as ce, start as pe, stripTags as de, upper as fe, title as me, headline as _e, apa as Ee, transliterate as ye, singular as Ae, slug as We, snake as xe, startsWith as Ne, doesntStartWith as ke, studly as Ue, pascal as Ce, substr as Le, substrCount as Me, substrReplace as Fe, swap as Ie, take as Be, trim as w, ltrim as Re, rtrim as je, lcfirst as De, ucfirst as Te, ucsplit as Pe, ucwords as qe, words as Je, wordCount as Ve, wordWrap as $e, wrap as ze, unwrap as Ge, toBase64 as Xe, fromBase64 as He } from "@zinaid/str";
-import { isInteger as Ke, isArray as o, isFunction as v } from "@zinaid/utils";
-function Ye(c) {
-  return new s(c);
+import { after as p, afterLast as d, ascii as f, before as m, beforeLast as _, between as E, betweenFirst as y, camel as A, charAt as W, chopStart as x, chopEnd as N, contains as k, containsAll as U, doesntContain as C, convertCase as L, deduplicate as M, endsWith as F, doesntEndWith as I, excerpt as B, finish as R, is as j, isAscii as D, isJson as T, isUrl as P, isUuid as q, isUlid as J, kebab as V, length as $, limit as z, lower as w, markdown as G, inlineMarkdown as X, mask as H, match as K, isMatch as O, matchAll as Q, numbers as Y, padBoth as Z, padLeft as g, padRight as b, plural as S, pluralStudly as ee, pluralPascal as te, position as se, remove as re, reverse as ne, repeat as ue, replace as he, replaceArray as ie, replaceFirst as le, replaceStart as ae, replaceLast as we, replaceEnd as oe, replaceMatches as ve, squish as ce, start as pe, stripTags as de, upper as fe, title as me, headline as _e, apa as Ee, transliterate as ye, singular as Ae, slug as We, snake as xe, startsWith as Ne, doesntStartWith as ke, studly as Ue, pascal as Ce, substr as Le, substrCount as Me, substrReplace as Fe, swap as Ie, take as Be, trim as o, ltrim as Re, rtrim as je, lcfirst as De, ucfirst as Te, ucsplit as Pe, ucwords as qe, words as Je, wordCount as Ve, wordWrap as $e, wrap as ze, unwrap as Ge, toBase64 as Xe, fromBase64 as He } from "@zinaid/str";
+import { isInteger as Ke, isArray as v, isFunction as c } from "@zinaid/utils";
+function Ye(a) {
+  return new s(a);
+}
+function Ze(a) {
+  return new s(a);
 }
 class s {
   /**
    * Create a new instance of the class.
+   *
+   * @param _value - The initial string value. Defaults to an empty string.
    */
   constructor(e = "") {
     this._value = e;
   }
   /**
    * 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(e) {
     return new s(p(this._value, e));
   }
   /**
    * 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(e) {
     return new s(d(this._value, e));
   }
   /**
    * Append the given values to the string.
+   *
+   * @param values - The values to append to the string.
+   * @returns The updated Stringable instance.
    */
   append(...e) {
     return new s(this._value + e.map(String).join(""));
   }
   /**
    * 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(e = 1) {
     return this.append(`
@@ -37,66 +54,101 @@ class s {
   }
   /**
    * Transliterate a UTF-8 value to ASCII.
+   *
+   * @returns The transliterated string as a new Stringable instance.
    */
   ascii() {
     return new s(f(this._value));
   }
   /**
    * 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(e) {
     return new s(m(this._value, e));
   }
   /**
    * 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(e) {
     return new s(_(this._value, e));
   }
   /**
    * 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(e, t) {
     return new s(E(this._value, e, t));
   }
   /**
    * 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(e, t) {
     return new s(y(this._value, e, t));
   }
   /**
    * Convert a value to camel case.
+   *
+   * @returns The camel-cased string as a new Stringable instance.
    */
   camel() {
     return new s(A(this._value));
   }
   /**
    * 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(e) {
     return W(this._value, e);
   }
   /**
    * 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(e) {
     return new s(x(this._value, e));
   }
   /**
    * 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(e) {
     return new s(N(this._value, e));
   }
   /**
    * 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(e, t = !1) {
     return k(this._value, e, t);
   }
   /**
    * 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(e, t = !1) {
     return U(this._value, e, t);
@@ -113,30 +165,45 @@ class s {
   }
   /**
    * Convert the case of a string.
+   *
+   * @param mode - The case conversion mode to apply.
+   * @returns The converted string as a new Stringable instance.
    */
   convertCase(e) {
     return new s(L(this._value, e));
   }
   /**
    * 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(e = " ") {
     return new s(M(this._value, e));
   }
   /**
    * 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(e) {
     return F(this._value, e);
   }
   /**
    * 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(e) {
     return I(this._value, e);
   }
   /**
    * 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(e) {
     const t = e instanceof s ? e.toString() : String(e);
@@ -144,12 +211,20 @@ class s {
   }
   /**
    * 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(e = "", t = {}) {
     return B(this._value, e, t);
   }
   /**
    * 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(e, t = Number.MAX_SAFE_INTEGER) {
     const r = this._value.split(e);
@@ -162,6 +237,10 @@ class s {
   }
   /**
    * 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(e, t = null) {
     if (Ke(e)) {
@@ -177,72 +256,103 @@ class s {
   }
   /**
    * 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(e) {
     return new s(R(this._value, e));
   }
   /**
    * 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(e, t = !1) {
     return j(e, this._value, t);
   }
   /**
    * Determine if a given string is 7 bit ASCII.
+   *
+   * @returns True if the string is ASCII, false otherwise.
    */
   isAscii() {
     return D(this._value);
   }
   /**
    * Determine if a given string is valid JSON.
+   *
+   * @returns True if the string is valid JSON, false otherwise.
    */
   isJson() {
     return T(this._value);
   }
   /**
    * 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(e = []) {
     return P(this._value, e);
   }
   /**
    * 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(e = null) {
     return q(this._value, e);
   }
   /**
    * Determine if a given string is a valid ULID.
+   *
+   * @return True if the string is a valid ULID, false otherwise.
    */
   isUlid() {
     return J(this._value);
   }
   /**
    * Determine if the given string is empty.
+   *
+   * @return True if the string is empty, false otherwise.
    */
   isEmpty() {
     return this._value === "";
   }
   /**
    * Determine if the given string is not empty.
+   *
+   * @return True if the string is not empty, false otherwise.
    */
   isNotEmpty() {
     return !this.isEmpty();
   }
   /**
    * Convert a string to kebab case.
+   *
+   * @returns The kebab-cased string as a new Stringable instance.
    */
   kebab() {
     return new s(V(this._value));
   }
   /**
    * Return the length of the given string.
+   *
+   * @returns The length of the string.
    */
   length() {
     return $(this._value);
   }
   /**
    * 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(e = 100, t = "...", r = !1) {
     return new s(
@@ -251,78 +361,122 @@ class s {
   }
   /**
    * Convert the given string to lower-case.
+   *
+   * @returns The lower-cased string as a new Stringable instance.
    */
   lower() {
-    return new s(a(this._value));
+    return new s(w(this._value));
   }
   /**
    * 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(e = { gfm: !0, anchors: !1 }, t = []) {
     return new s(G(this._value, e, t));
   }
   /**
    * 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(e = { gfm: !0 }, t = []) {
     return new s(X(this._value, e, t));
   }
   /**
    * 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(e, t, r = null) {
     return new s(H(this._value, e, t, r));
   }
   /**
    * Get the string matching the given pattern.
+   *
+   * @param pattern - The pattern to match against.
+   * @returns A new Stringable instance containing the matched string.
    */
   match(e) {
     return new s(K(e, this._value));
   }
   /**
    * 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(e) {
     return O(e, this._value);
   }
   /**
    * Get the string matching the given pattern.
+   *
+   * @param pattern - The pattern to match against.
+   * @returns An array of all matched strings.
    */
   matchAll(e) {
     return Q(e, this._value);
   }
   /**
    * 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(e) {
     return this.isMatch(e);
   }
   /**
    * Remove all non-numeric characters from a string.
+   *
+   * @returns The numeric string as a new Stringable instance.
    */
   numbers() {
     return new s(Y(this._value));
   }
   /**
    * 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(e, t = " ") {
     return new s(Z(this._value, e, t));
   }
   /**
    * 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(e, t = " ") {
     return new s(g(this._value, e, t));
   }
   /**
    * 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(e, t = " ") {
     return new s(b(this._value, e, t));
   }
   /**
    * 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(e) {
     const t = e(this);
@@ -330,38 +484,59 @@ class s {
   }
   /**
    * 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(e = 2, t = !1) {
     return new s(S(this._value, e, t));
   }
   /**
    * 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(e = 2) {
-    const t = o(e) ? e.length : Number(e);
+    const t = v(e) ? e.length : Number(e);
     return new s(ee(this._value, t));
   }
   /**
    * 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(e = 2) {
-    const t = o(e) ? e.length : Number(e);
+    const t = v(e) ? e.length : Number(e);
     return new s(te(this._value, t));
   }
   /**
    * 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(e, t = 0) {
     return se(this._value, e, t);
   }
   /**
    * Prepend the given values to the string.
+   *
+   * @param values - The values to prepend to the string.
+   * @returns The updated Stringable instance.
    */
   prepend(...e) {
     return new s(e.map(String).join("") + this._value);
   }
   /**
    * 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(e, t = !0) {
     return new s(
@@ -370,18 +545,28 @@ class s {
   }
   /**
    * Reverse the string.
+   *
+   * @returns The reversed string as a new Stringable instance.
    */
   reverse() {
     return new s(ne(this._value));
   }
   /**
    * Repeat the string.
+   *
+   * @param times - The number of times to repeat the string.
+   * @returns The repeated string as a new Stringable instance.
    */
   repeat(e) {
     return new s(ue(this._value, e));
   }
   /**
    * 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(e, t, r = !0) {
     return new s(
@@ -390,36 +575,61 @@ class s {
   }
   /**
    * 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(e, t) {
     return new s(ie(e, t, this._value));
   }
   /**
    * 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(e, t) {
     return new s(le(e, t, this._value));
   }
   /**
    * 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(e, t) {
     return new s(ae(e, t, this._value));
   }
   /**
    * 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(e, t) {
     return new s(we(e, t, this._value));
   }
   /**
    * 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(e, t) {
     return new s(oe(e, t, this._value));
   }
   /**
    * 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(e, t, r = -1) {
     const n = ve(e, t, this._value, r);
@@ -464,108 +674,158 @@ class s {
   }
   /**
    * Remove all "extra" blank space from the given string.
+   *
+   * @returns The updated Stringable instance.
    */
   squish() {
     return new s(ce(this._value));
   }
   /**
    * 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(e) {
     return new s(pe(this._value, e));
   }
   /**
    * Strip HTML and PHP tags from the given string.
+   *
+   * @returns The updated Stringable instance.
    */
   stripTags() {
     return new s(de(this._value));
   }
   /**
    * Convert the given string to upper-case.
+   *
+   * @returns The upper-cased string as a new Stringable instance.
    */
   upper() {
     return new s(fe(this._value));
   }
   /**
    * Convert the given string to proper case.
+   *
+   * @returns The title-cased string as a new Stringable instance.
    */
   title() {
     return new s(me(this._value));
   }
   /**
    * Convert the given string to proper case for each word.
+   *
+   * @returns The headline-cased string as a new Stringable instance.
    */
   headline() {
     return new s(_e(this._value));
   }
   /**
    * Convert the given string to APA-style title case.
+   *
+   * @returns The APA title-cased string as a new Stringable instance.
    */
   apa() {
     return new s(Ee(this._value));
   }
   /**
    * Transliterate a string to its closest ASCII representation.
+   *
+   * @returns The transliterated string as a new Stringable instance.
    */
   transliterate() {
     return new s(ye(this._value));
   }
   /**
    * Get the singular form of an English word.
+   *
+   * @returns The singularized string as a new Stringable instance.
    */
   singular() {
     return new s(Ae(this._value));
   }
   /**
    * 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(e = "-", t = { "@": "at" }) {
     return new s(We(this._value, e, t));
   }
   /**
    * 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(e = "_") {
     return new s(xe(this._value, e));
   }
   /**
    * 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(e) {
     return Ne(this._value, e);
   }
   /**
    * 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(e) {
     return ke(this._value, e);
   }
   /**
    * Convert a value to studly caps case.
+   *
+   * @returns The studly-cased string as a new Stringable instance.
    */
   studly() {
     return new s(Ue(this._value));
   }
   /**
    * Convert the string to Pascal case.
+   *
+   * @returns The pascal-cased string as a new Stringable instance.
    */
   pascal() {
     return new s(Ce(this._value));
   }
   /**
    * 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(e, t = null) {
     return new s(Le(this._value, e, t));
   }
   /**
    * 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(e, t = 0, r = null) {
     return Me(this._value, e, t, r);
   }
   /**
    * 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(e, t = 0, r = null) {
     return new s(
@@ -574,54 +834,77 @@ class s {
   }
   /**
    * 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(e) {
     return new s(Ie(e, this._value));
   }
   /**
    * 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(e) {
     return new s(Be(this._value, e));
   }
   /**
    * 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(e = null) {
-    return new s(w(this._value, e));
+    return new s(o(this._value, e));
   }
   /**
    * 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(e = null) {
     return new s(Re(this._value, e));
   }
   /**
    * 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(e = null) {
     return new s(je(this._value, e));
   }
   /**
    * Make a string's first character lowercase.
+   *
+   * @returns The updated Stringable instance.
    */
   lcfirst() {
     return new s(De(this._value));
   }
   /**
    * Make a string's first character uppercase.
+   *
+   * @returns The updated Stringable instance.
    */
   ucfirst() {
     return new s(Te(this._value));
   }
   /**
    * Split a string by uppercase characters.
+   *
+   * @returns An array of substrings split at uppercase characters.
    */
   ucsplit() {
     return Pe(this._value);
   }
   /**
    * Uppercase the first character of each word in a string.
+   *
+   * @returns The updated Stringable instance.
    */
   ucwords() {
     return new s(qe(this._value));
@@ -649,7 +932,7 @@ class s {
    * ```
    */
   when(e, t = null, r = null) {
-    const n = v(e) ? e(this) : e;
+    const n = c(e) ? e(this) : e;
     return n ? t?.(this, n) ?? this : r ? r(this, n) ?? this : this;
   }
   /**
@@ -667,7 +950,7 @@ class s {
    * str.unless(false, s => s.upper(), s => s.lower()); // Returns 'HELLO WORLD'
    */
   unless(e, t = null, r = null) {
-    const n = v(e) ? e(this) : e;
+    const n = c(e) ? e(this) : e;
     if (n) {
       if (r)
         return r(this, n) ?? this;
@@ -676,36 +959,64 @@ class s {
   }
   /**
    * 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(e, t, r = null) {
     return this.when(this.contains(e), t, r);
   }
   /**
    * 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(e, t, r = null) {
     return this.when(this.containsAll(e), t, r);
   }
   /**
    * 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(e, t = null) {
     return this.when(this.isEmpty(), e, t);
   }
   /**
    * 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(e, t = null) {
     return this.when(this.isNotEmpty(), e, t);
   }
   /**
    * 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(e, t, r = null) {
     return this.when(this.endsWith(e), t, r);
   }
   /**
    * 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(e, t, r = null) {
     return this.when(
@@ -716,66 +1027,115 @@ class s {
   }
   /**
    * 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(e, t, r = null) {
     return this.when(this.exactly(e), t, r);
   }
   /**
    * 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(e, t, r = null) {
     return this.when(!this.exactly(e), t, r);
   }
   /**
    * 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(e, t, r = null) {
     return this.when(this.is(e), t, r);
   }
   /**
    * 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(e, t = null) {
     return this.when(this.isAscii(), e, t);
   }
   /**
    * 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(e, t = null) {
     return this.when(this.isUuid(), e, t);
   }
   /**
    * 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(e, t = null) {
     return this.when(this.isUlid(), e, t);
   }
   /**
    * 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(e, t, r = null) {
     return this.when(this.startsWith(e), t, r);
   }
   /**
    * 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(e, t, r = null) {
     return this.when(this.test(e), t, r);
   }
   /**
    * 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(e = 100, t = "...") {
     return new s(Je(this._value, e, t));
   }
   /**
    * 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(e = null) {
     return Ve(this._value, e);
   }
   /**
    * 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(e = 75, t = `
 `, r = !1) {
@@ -785,24 +1145,37 @@ class s {
   }
   /**
    * 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(e, t = null) {
     return new s(ze(this._value, e, t));
   }
   /**
    * 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(e, t = null) {
     return new s(Ge(this._value, e, t));
   }
   /**
    * Convert the string to Base64 encoding.
+   *
+   * @returns The Base64 encoded string as a new Stringable instance.
    */
   toBase64() {
     return new s(Xe(this._value));
   }
   /**
    * 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(e = !1) {
     const t = He(this._value, e);
@@ -810,18 +1183,25 @@ class s {
   }
   /**
    * Get the underlying string value.
+   *
+   * @returns The string representation of the object.
    */
   toString() {
     return this.value();
   }
   /**
    * Get the underlying string value.
+   *
+   * @returns The string value.
    */
   value() {
     return String(this._value);
   }
   /**
    * Get the underlying string value as an integer.
+   *
+   * @param base - The base to use for conversion. Defaults to 10.
+   * @returns The integer value.
    */
   toInteger(e = 10) {
     const t = Number(e) || 10;
@@ -829,6 +1209,8 @@ class s {
   }
   /**
    * Get the underlying string value as a float.
+   *
+   * @returns The float value.
    */
   toFloat() {
     return parseFloat(this._value);
@@ -836,14 +1218,16 @@ class s {
   /**
    * 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() {
-    const e = a(w(this._value));
+    const e = w(o(this._value));
     return e === "1" || e === "true" || e === "on" || e === "yes";
   }
   /**
    * Get the underlying string value as a Carbon instance.
+   *
+   * @returns The Date instance or null if parsing fails.
    */
   toDate() {
     const e = Date.parse(this._value);
@@ -851,6 +1235,8 @@ class s {
   }
   /**
    * Convert the object to a string when JSON encoded.
+   *
+   * @returns The string representation of the object.
    */
   jsonSerialize() {
     return this.toString();
@@ -858,5 +1244,6 @@ class s {
 }
 export {
   s as Stringable,
-  Ye as of
+  Ye as of,
+  Ze as str
 };