@zinaid/str 0.0.1

package/dist/stringable.js

@@ -0,0 +1,862 @@
+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);
+}
+class s {
+  /**
+   * Create a new instance of the class.
+   */
+  constructor(e = "") {
+    this._value = e;
+  }
+  /**
+   * Return the remainder of a string after the first occurrence of a given value.
+   */
+  after(e) {
+    return new s(p(this._value, e));
+  }
+  /**
+   * Return the remainder of a string after the last occurrence of a given value
+   */
+  afterLast(e) {
+    return new s(d(this._value, e));
+  }
+  /**
+   * Append the given values to the string.
+   */
+  append(...e) {
+    return new s(this._value + e.map(String).join(""));
+  }
+  /**
+   * Append a new line to the string.
+   */
+  newLine(e = 1) {
+    return this.append(`
+`.repeat(Math.max(0, e)));
+  }
+  /**
+   * Transliterate a UTF-8 value to ASCII.
+   */
+  ascii() {
+    return new s(f(this._value));
+  }
+  /**
+   * Get the portion of a string before the first occurrence of a given value.
+   */
+  before(e) {
+    return new s(m(this._value, e));
+  }
+  /**
+   * Get the portion of a string before the last occurrence of a given value.
+   */
+  beforeLast(e) {
+    return new s(_(this._value, e));
+  }
+  /**
+   * Get the portion of a string between 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.
+   */
+  betweenFirst(e, t) {
+    return new s(y(this._value, e, t));
+  }
+  /**
+   * Convert a value to camel case.
+   */
+  camel() {
+    return new s(A(this._value));
+  }
+  /**
+   * Get the character at the specified index.
+   */
+  charAt(e) {
+    return W(this._value, e);
+  }
+  /**
+   * Remove the given string if it exists at the start of the current string.
+   */
+  chopStart(e) {
+    return new s(x(this._value, e));
+  }
+  /**
+   * Remove the given string if it exists at the end of the current string.
+   */
+  chopEnd(e) {
+    return new s(N(this._value, e));
+  }
+  /**
+   * Determine if a given string contains a given substring.
+   */
+  contains(e, t = !1) {
+    return k(this._value, e, t);
+  }
+  /**
+   * Determine if a given string contains all array values.
+   */
+  containsAll(e, t = !1) {
+    return U(this._value, e, t);
+  }
+  /**
+   * 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(e, t = !1) {
+    return C(this._value, e, t);
+  }
+  /**
+   * Convert the case of a string.
+   */
+  convertCase(e) {
+    return new s(L(this._value, e));
+  }
+  /**
+   * Replace consecutive instances of a given character with a single character.
+   */
+  deduplicate(e = " ") {
+    return new s(M(this._value, e));
+  }
+  /**
+   * Determine if a given string ends with a given substring.
+   */
+  endsWith(e) {
+    return F(this._value, e);
+  }
+  /**
+   * Determine if a given string doesn't end with a given substring.
+   */
+  doesntEndWith(e) {
+    return I(this._value, e);
+  }
+  /**
+   * Determine if the string is an exact match with the given value.
+   */
+  exactly(e) {
+    const t = e instanceof s ? e.toString() : String(e);
+    return this._value === t;
+  }
+  /**
+   * Extracts an excerpt from text that matches the first instance of a phrase.
+   */
+  excerpt(e = "", t = {}) {
+    return B(this._value, e, t);
+  }
+  /**
+   * Explode the string into an array
+   */
+  explode(e, t = Number.MAX_SAFE_INTEGER) {
+    const r = this._value.split(e);
+    if (t > 0 && r.length > t) {
+      const n = r.slice(0, t - 1);
+      return n.push(r.slice(t - 1).join(e)), n;
+    } else if (t < 0)
+      return r.slice(0, t);
+    return r;
+  }
+  /**
+   * Split a string using a regular expression or by length.
+   */
+  split(e, t = null) {
+    if (Ke(e)) {
+      const n = Number(e), h = [];
+      for (let i = 0; i < this._value.length; i += n)
+        h.push(this._value.substr(i, n));
+      return h;
+    }
+    return this._value.split(
+      new RegExp(String(e)),
+      t ?? void 0
+    );
+  }
+  /**
+   * Cap a string with a single instance of a given value.
+   */
+  finish(e) {
+    return new s(R(this._value, e));
+  }
+  /**
+   * Determine if a given string matches a given pattern.
+   */
+  is(e, t = !1) {
+    return j(e, this._value, t);
+  }
+  /**
+   * Determine if a given string is 7 bit ASCII.
+   */
+  isAscii() {
+    return D(this._value);
+  }
+  /**
+   * Determine if a given string is valid JSON.
+   */
+  isJson() {
+    return T(this._value);
+  }
+  /**
+   * Determine if a given value is a valid URL.
+   */
+  isUrl(e = []) {
+    return P(this._value, e);
+  }
+  /**
+   * Determine if a given string is a valid UUID.
+   */
+  isUuid(e = null) {
+    return q(this._value, e);
+  }
+  /**
+   * Determine if a given string is a valid ULID.
+   */
+  isUlid() {
+    return J(this._value);
+  }
+  /**
+   * Determine if the given string is empty.
+   */
+  isEmpty() {
+    return this._value === "";
+  }
+  /**
+   * Determine if the given string is not empty.
+   */
+  isNotEmpty() {
+    return !this.isEmpty();
+  }
+  /**
+   * Convert a string to kebab case.
+   */
+  kebab() {
+    return new s(V(this._value));
+  }
+  /**
+   * Return the length of the given string.
+   */
+  length() {
+    return $(this._value);
+  }
+  /**
+   * Limit the number of characters in a string.
+   */
+  limit(e = 100, t = "...", r = !1) {
+    return new s(
+      z(this._value, e, t, r)
+    );
+  }
+  /**
+   * Convert the given string to lower-case.
+   */
+  lower() {
+    return new s(a(this._value));
+  }
+  /**
+   * Convert GitHub flavored Markdown into HTML.
+   */
+  markdown(e = { gfm: !0, anchors: !1 }, t = []) {
+    return new s(G(this._value, e, t));
+  }
+  /**
+   * Convert inline Markdown into HTML.
+   */
+  inlineMarkdown(e = { gfm: !0 }, t = []) {
+    return new s(X(this._value, e, t));
+  }
+  /**
+   * Masks a portion of a string with a repeated character.
+   */
+  mask(e, t, r = null) {
+    return new s(H(this._value, e, t, r));
+  }
+  /**
+   * Get the string matching the given pattern.
+   */
+  match(e) {
+    return new s(K(e, this._value));
+  }
+  /**
+   * Determine if a given string matches a given pattern.
+   */
+  isMatch(e) {
+    return O(e, this._value);
+  }
+  /**
+   * Get the string matching the given pattern.
+   */
+  matchAll(e) {
+    return Q(e, this._value);
+  }
+  /**
+   * Determine if the string matches the given pattern.
+   */
+  test(e) {
+    return this.isMatch(e);
+  }
+  /**
+   * Remove all non-numeric characters from a string.
+   */
+  numbers() {
+    return new s(Y(this._value));
+  }
+  /**
+   * Pad both sides of the string with another.
+   */
+  padBoth(e, t = " ") {
+    return new s(Z(this._value, e, t));
+  }
+  /**
+   * Pad the left side of the string with another.
+   */
+  padLeft(e, t = " ") {
+    return new s(g(this._value, e, t));
+  }
+  /**
+   * Pad the right side of the string with another.
+   */
+  padRight(e, t = " ") {
+    return new s(b(this._value, e, t));
+  }
+  /**
+   * Call the given callback and return a new string.
+   */
+  pipe(e) {
+    const t = e(this);
+    return t instanceof s ? t : new s(String(t));
+  }
+  /**
+   * Get the plural form of an English word.
+   */
+  plural(e = 2, t = !1) {
+    return new s(S(this._value, e, t));
+  }
+  /**
+   * Pluralize the last word of an English, studly caps case string.
+   */
+  pluralStudly(e = 2) {
+    const t = o(e) ? e.length : Number(e);
+    return new s(ee(this._value, t));
+  }
+  /**
+   * Pluralize the last word of an English, Pascal caps case string.
+   */
+  pluralPascal(e = 2) {
+    const t = o(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.
+   */
+  position(e, t = 0) {
+    return se(this._value, e, t);
+  }
+  /**
+   * Prepend the given values to the string.
+   */
+  prepend(...e) {
+    return new s(e.map(String).join("") + this._value);
+  }
+  /**
+   * Remove any occurrence of the given string in the subject.
+   */
+  remove(e, t = !0) {
+    return new s(
+      re(e, this._value, t)
+    );
+  }
+  /**
+   * Reverse the string.
+   */
+  reverse() {
+    return new s(ne(this._value));
+  }
+  /**
+   * Repeat the string.
+   */
+  repeat(e) {
+    return new s(ue(this._value, e));
+  }
+  /**
+   * Replace the given value in the given string.
+   */
+  replace(e, t, r = !0) {
+    return new s(
+      he(e, t, this._value, r)
+    );
+  }
+  /**
+   * Replace a given value in the string sequentially with an array.
+   */
+  replaceArray(e, t) {
+    return new s(ie(e, t, this._value));
+  }
+  /**
+   * Replace the first occurrence of a given value in the string.
+   */
+  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.
+   */
+  replaceStart(e, t) {
+    return new s(ae(e, t, this._value));
+  }
+  /**
+   * Replace the last occurrence of a given value in the string.
+   */
+  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.
+   */
+  replaceEnd(e, t) {
+    return new s(oe(e, t, this._value));
+  }
+  /**
+   * Replace the patterns matching the given regular expression.
+   */
+  replaceMatches(e, t, r = -1) {
+    const n = ve(e, t, this._value, r);
+    return new s(n);
+  }
+  /**
+   * 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(e) {
+    let t = "", r = 0;
+    for (; r < e.length; )
+      if (e[r] === "%")
+        if (e[r + 1] === "[") {
+          let u = r + 2;
+          for (; u < e.length && e[u] !== "]"; )
+            u++;
+          const l = e.substring(r + 2, u);
+          t += "([" + l + "]+)", r = u + 1;
+        } else e[r + 1] === "d" ? (t += "\\s*(-?\\d+)", r += 2) : e[r + 1] === "s" ? (t += "\\s*(\\S+)", r += 2) : (t += e[r], r++);
+      else {
+        const u = e[r];
+        u && /[.+?^${}()|\\]/.test(u) ? t += "\\" + u : t += u, r++;
+      }
+    const n = new RegExp("^" + t + "$"), h = this._value.match(n);
+    if (!h)
+      return [];
+    const i = [];
+    for (let u = 1; u < h.length; u++) {
+      const l = h[u];
+      l && i.push(l);
+    }
+    return i;
+  }
+  /**
+   * Remove all "extra" blank space from the given string.
+   */
+  squish() {
+    return new s(ce(this._value));
+  }
+  /**
+   * Begin a string with a single instance of a given value.
+   */
+  start(e) {
+    return new s(pe(this._value, e));
+  }
+  /**
+   * Strip HTML and PHP tags from the given string.
+   */
+  stripTags() {
+    return new s(de(this._value));
+  }
+  /**
+   * Convert the given string to upper-case.
+   */
+  upper() {
+    return new s(fe(this._value));
+  }
+  /**
+   * Convert the given string to proper case.
+   */
+  title() {
+    return new s(me(this._value));
+  }
+  /**
+   * Convert the given string to proper case for each word.
+   */
+  headline() {
+    return new s(_e(this._value));
+  }
+  /**
+   * Convert the given string to APA-style title case.
+   */
+  apa() {
+    return new s(Ee(this._value));
+  }
+  /**
+   * Transliterate a string to its closest ASCII representation.
+   */
+  transliterate() {
+    return new s(ye(this._value));
+  }
+  /**
+   * Get the singular form of an English word.
+   */
+  singular() {
+    return new s(Ae(this._value));
+  }
+  /**
+   * Generate a URL friendly "slug" from a given string.
+   */
+  slug(e = "-", t = { "@": "at" }) {
+    return new s(We(this._value, e, t));
+  }
+  /**
+   * Convert a string to snake case.
+   */
+  snake(e = "_") {
+    return new s(xe(this._value, e));
+  }
+  /**
+   * Determine if a given string starts with a given substring.
+   */
+  startsWith(e) {
+    return Ne(this._value, e);
+  }
+  /**
+   * Determine if a given string doesn't start with a given substring.
+   */
+  doesntStartWith(e) {
+    return ke(this._value, e);
+  }
+  /**
+   * Convert a value to studly caps case.
+   */
+  studly() {
+    return new s(Ue(this._value));
+  }
+  /**
+   * Convert the string to Pascal case.
+   */
+  pascal() {
+    return new s(Ce(this._value));
+  }
+  /**
+   * Returns the portion of the string specified by the start and length parameters.
+   */
+  substr(e, t = null) {
+    return new s(Le(this._value, e, t));
+  }
+  /**
+   * Returns the number of substring occurrences.
+   */
+  substrCount(e, t = 0, r = null) {
+    return Me(this._value, e, t, r);
+  }
+  /**
+   * Replace text within a portion of a string.
+   */
+  substrReplace(e, t = 0, r = null) {
+    return new s(
+      Fe(this._value, e, t, r)
+    );
+  }
+  /**
+   * Swap multiple keywords in a string with other keywords.
+   */
+  swap(e) {
+    return new s(Ie(e, this._value));
+  }
+  /**
+   * Take the first or last {$limit} characters.
+   */
+  take(e) {
+    return new s(Be(this._value, e));
+  }
+  /**
+   * Trim the string of the given characters.
+   */
+  trim(e = null) {
+    return new s(w(this._value, e));
+  }
+  /**
+   * Left trim the string of the given characters.
+   */
+  ltrim(e = null) {
+    return new s(Re(this._value, e));
+  }
+  /**
+   * Right trim the string of the given characters.
+   */
+  rtrim(e = null) {
+    return new s(je(this._value, e));
+  }
+  /**
+   * Make a string's first character lowercase.
+   */
+  lcfirst() {
+    return new s(De(this._value));
+  }
+  /**
+   * Make a string's first character uppercase.
+   */
+  ucfirst() {
+    return new s(Te(this._value));
+  }
+  /**
+   * Split a string by uppercase characters.
+   */
+  ucsplit() {
+    return Pe(this._value);
+  }
+  /**
+   * Uppercase the first character of each word in a string.
+   */
+  ucwords() {
+    return new s(qe(this._value));
+  }
+  /**
+   * 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(e, t = null, r = null) {
+    const n = v(e) ? e(this) : e;
+    return n ? t?.(this, n) ?? this : r ? r(this, n) ?? this : this;
+  }
+  /**
+   * 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(e, t = null, r = null) {
+    const n = v(e) ? e(this) : e;
+    if (n) {
+      if (r)
+        return r(this, n) ?? this;
+    } else return t?.(this, n) ?? this;
+    return this;
+  }
+  /**
+   * Execute the given callback if the string contains a given substring.
+   */
+  whenContains(e, t, r = null) {
+    return this.when(this.contains(e), t, r);
+  }
+  /**
+   * Execute the given callback if the string contains all array values.
+   */
+  whenContainsAll(e, t, r = null) {
+    return this.when(this.containsAll(e), t, r);
+  }
+  /**
+   * Execute the given callback if the string is empty.
+   */
+  whenEmpty(e, t = null) {
+    return this.when(this.isEmpty(), e, t);
+  }
+  /**
+   * Execute the given callback if the string is not empty.
+   */
+  whenNotEmpty(e, t = null) {
+    return this.when(this.isNotEmpty(), e, t);
+  }
+  /**
+   * Execute the given callback if the string ends with a given substring.
+   */
+  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.
+   */
+  whenDoesntEndWith(e, t, r = null) {
+    return this.when(
+      this.doesntEndWith(e),
+      t,
+      r
+    );
+  }
+  /**
+   * Execute the given callback if the string is an exact match with the given value.
+   */
+  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.
+   */
+  whenNotExactly(e, t, r = null) {
+    return this.when(!this.exactly(e), t, r);
+  }
+  /**
+   * Execute the given callback if the string matches a given pattern.
+   */
+  whenIs(e, t, r = null) {
+    return this.when(this.is(e), t, r);
+  }
+  /**
+   * Execute the given callback if the string is 7 bit ASCII.
+   */
+  whenIsAscii(e, t = null) {
+    return this.when(this.isAscii(), e, t);
+  }
+  /**
+   * Execute the given callback if the string is a valid UUID.
+   */
+  whenIsUuid(e, t = null) {
+    return this.when(this.isUuid(), e, t);
+  }
+  /**
+   * Execute the given callback if the string is a valid ULID.
+   */
+  whenIsUlid(e, t = null) {
+    return this.when(this.isUlid(), e, t);
+  }
+  /**
+   * Execute the given callback if the string starts with a given substring.
+   */
+  whenStartsWith(e, t, r = null) {
+    return this.when(this.startsWith(e), t, r);
+  }
+  /**
+   * Execute the given callback if the string matches the given pattern.
+   */
+  whenTest(e, t, r = null) {
+    return this.when(this.test(e), t, r);
+  }
+  /**
+   * Limit the number of words in a string.
+   */
+  words(e = 100, t = "...") {
+    return new s(Je(this._value, e, t));
+  }
+  /**
+   * Get the number of words a string contains.
+   */
+  wordCount(e = null) {
+    return Ve(this._value, e);
+  }
+  /**
+   * Wrap a string to a given number of characters.
+   */
+  wordWrap(e = 75, t = `
+`, r = !1) {
+    return new s(
+      $e(this._value, e, t, r)
+    );
+  }
+  /**
+   * Wrap the string with the given strings.
+   */
+  wrap(e, t = null) {
+    return new s(ze(this._value, e, t));
+  }
+  /**
+   * Unwrap the string with the given strings.
+   */
+  unwrap(e, t = null) {
+    return new s(Ge(this._value, e, t));
+  }
+  /**
+   * Convert the string to Base64 encoding.
+   */
+  toBase64() {
+    return new s(Xe(this._value));
+  }
+  /**
+   * Decode the Base64 encoded string.
+   */
+  fromBase64(e = !1) {
+    const t = He(this._value, e);
+    return t === !1 ? !1 : new s(t);
+  }
+  /**
+   * Get the underlying string value.
+   */
+  toString() {
+    return this.value();
+  }
+  /**
+   * Get the underlying string value.
+   */
+  value() {
+    return String(this._value);
+  }
+  /**
+   * Get the underlying string value as an integer.
+   */
+  toInteger(e = 10) {
+    const t = Number(e) || 10;
+    return parseInt(this._value, t);
+  }
+  /**
+   * Get the underlying string value as a float.
+   */
+  toFloat() {
+    return parseFloat(this._value);
+  }
+  /**
+   * Get the underlying string value as a boolean.
+   *
+   * Returns true when value is "1", "true", "on", and "yes". Otherwise, returns false.
+   */
+  toBoolean() {
+    const e = a(w(this._value));
+    return e === "1" || e === "true" || e === "on" || e === "yes";
+  }
+  /**
+   * Get the underlying string value as a Carbon instance.
+   */
+  toDate() {
+    const e = Date.parse(this._value);
+    return isNaN(e) ? null : new Date(e);
+  }
+  /**
+   * Convert the object to a string when JSON encoded.
+   */
+  jsonSerialize() {
+    return this.toString();
+  }
+}
+export {
+  s as Stringable,
+  Ye as of
+};