@ppabari/strio 1.0.2 → 1.1.0

package/dist/str.cjs

@@ -0,0 +1,623 @@
+'use strict';
+
+// src/str/internal.ts
+function assertString(value, name = "input") {
+  if (typeof value !== "string") {
+    throw new TypeError(`Expected ${name} to be a string, received ${typeof value}.`);
+  }
+}
+function extractWords(str) {
+  return str.replace(/([a-z0-9])([A-Z])/g, "$1 $2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2").replace(/([a-zA-Z])([0-9])/g, "$1 $2").replace(/([0-9])([a-zA-Z])/g, "$1 $2").split(/[^a-zA-Z0-9]+/).filter(Boolean);
+}
+
+// src/str/manipulation.ts
+function capitalize(str, lowerRest = false) {
+  assertString(str);
+  if (str.length === 0) return str;
+  const rest = lowerRest ? str.slice(1).toLowerCase() : str.slice(1);
+  return str.charAt(0).toUpperCase() + rest;
+}
+function capitalizeWords(str) {
+  assertString(str);
+  return str.replace(/(^|\s)(\S)/g, (_m, lead, ch) => lead + ch.toUpperCase());
+}
+function reverse(str) {
+  assertString(str);
+  return [...str].reverse().join("");
+}
+function truncate(str, length, suffix = "\u2026") {
+  assertString(str);
+  if (str.length <= length) return str;
+  if (length <= suffix.length) return suffix.slice(0, length);
+  return str.slice(0, length - suffix.length) + suffix;
+}
+function truncateWords(str, count2, suffix = "\u2026") {
+  assertString(str);
+  const parts = str.trim().split(/\s+/).filter(Boolean);
+  if (count2 <= 0) return suffix;
+  if (parts.length <= count2) return str;
+  return parts.slice(0, count2).join(" ") + suffix;
+}
+function trim(str, chars) {
+  assertString(str);
+  if (chars === void 0) return str.trim();
+  if (chars.length === 0) return str;
+  const set = new Set(chars);
+  let start = 0;
+  let end = str.length;
+  while (start < end && set.has(str[start])) start++;
+  while (end > start && set.has(str[end - 1])) end--;
+  return str.slice(start, end);
+}
+function insert(str, index, substring) {
+  assertString(str);
+  assertString(substring, "substring");
+  let i = index < 0 ? str.length + index : index;
+  if (i < 0) i = 0;
+  if (i > str.length) i = str.length;
+  return str.slice(0, i) + substring + str.slice(i);
+}
+function mask(str, options = {}) {
+  assertString(str);
+  const { maskChar = "*", visibleStart = 0, visibleEnd = 0 } = options;
+  const chars = [...str];
+  const len = chars.length;
+  if (visibleStart + visibleEnd >= len) return str;
+  const head = chars.slice(0, Math.max(0, visibleStart)).join("");
+  const tail = visibleEnd > 0 ? chars.slice(len - visibleEnd).join("") : "";
+  const maskedCount = len - Math.max(0, visibleStart) - Math.max(0, visibleEnd);
+  return head + maskChar.repeat(maskedCount) + tail;
+}
+
+// src/str/case.ts
+function camelize(str) {
+  assertString(str);
+  const words2 = extractWords(str);
+  if (words2.length === 0) return "";
+  return words2.map(
+    (w, i) => i === 0 ? w.toLowerCase() : w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()
+  ).join("");
+}
+function pascalize(str) {
+  assertString(str);
+  return extractWords(str).map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase()).join("");
+}
+function dasherize(str) {
+  assertString(str);
+  return extractWords(str).map((w) => w.toLowerCase()).join("-");
+}
+function underscore(str) {
+  assertString(str);
+  return extractWords(str).map((w) => w.toLowerCase()).join("_");
+}
+
+// src/str/validation.ts
+function isString(value) {
+  return typeof value === "string";
+}
+function isEmpty(value) {
+  return !isString(value) || value.length === 0;
+}
+function isBlank(value) {
+  return !isString(value) || value.trim().length === 0;
+}
+function isAlpha(value) {
+  return isString(value) && /^[A-Za-z]+$/.test(value);
+}
+function isNumeric(value) {
+  return isString(value) && /^[0-9]+$/.test(value);
+}
+function isAlphaNumeric(value) {
+  return isString(value) && /^[A-Za-z0-9]+$/.test(value);
+}
+function isUpperCase(value) {
+  return isString(value) && /[A-Z]/.test(value) && value === value.toUpperCase();
+}
+function isLowerCase(value) {
+  return isString(value) && /[a-z]/.test(value) && value === value.toLowerCase();
+}
+
+// src/str/searching.ts
+function normalize(s, caseSensitive) {
+  return caseSensitive ? s : s.toLowerCase();
+}
+function contains(str, substring, caseSensitive = true) {
+  assertString(str);
+  assertString(substring, "substring");
+  return normalize(str, caseSensitive).includes(normalize(substring, caseSensitive));
+}
+function containsAll(str, substrings, caseSensitive = true) {
+  assertString(str);
+  return substrings.every((s) => contains(str, s, caseSensitive));
+}
+function containsAny(str, substrings, caseSensitive = true) {
+  assertString(str);
+  return substrings.some((s) => contains(str, s, caseSensitive));
+}
+function count(str, substring, overlapping = false) {
+  assertString(str);
+  assertString(substring, "substring");
+  if (substring.length === 0) return 0;
+  let n = 0;
+  let pos = 0;
+  const step = overlapping ? 1 : substring.length;
+  while ((pos = str.indexOf(substring, pos)) !== -1) {
+    n++;
+    pos += step;
+  }
+  return n;
+}
+function between(str, start, end) {
+  assertString(str);
+  const startIdx = str.indexOf(start);
+  if (startIdx === -1) return "";
+  const from = startIdx + start.length;
+  const endIdx = str.indexOf(end, from);
+  if (endIdx === -1) return "";
+  return str.slice(from, endIdx);
+}
+function betweenAll(str, start, end) {
+  assertString(str);
+  const results = [];
+  let pos = 0;
+  while (true) {
+    const startIdx = str.indexOf(start, pos);
+    if (startIdx === -1) break;
+    const from = startIdx + start.length;
+    const endIdx = str.indexOf(end, from);
+    if (endIdx === -1) break;
+    results.push(str.slice(from, endIdx));
+    pos = endIdx + end.length;
+  }
+  return results;
+}
+
+// src/core.ts
+function getRandomChars(charset, count2) {
+  const len = charset.length;
+  const maxValid = 256 - 256 % len;
+  const result = [];
+  const bufSize = Math.ceil(count2 * 1.4) + 32;
+  const buf = new Uint8Array(bufSize);
+  while (result.length < count2) {
+    crypto.getRandomValues(buf);
+    for (let i = 0; i < buf.length && result.length < count2; i++) {
+      const byte = buf[i];
+      if (byte < maxValid) {
+        result.push(charset[byte % len]);
+      }
+    }
+  }
+  return result;
+}
+
+// src/charset-aliases.ts
+var CHARSET_ALIASES = {
+  /**
+   * Base16 — hex digits, lowercase.
+   * Use for: hash representations, color codes, compact binary encoding.
+   */
+  base16: "0123456789abcdef",
+  /** Base16 uppercase variant */
+  base16upper: "0123456789ABCDEF",
+  /**
+   * Base32 — RFC 4648. Uppercase alpha + digits, no padding chars.
+   * Use for: case-insensitive tokens, OTP secrets (Google Authenticator compatible).
+   */
+  base32: "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567",
+  /**
+   * Base32 hex — RFC 4648 §7. Sortable alternative to standard base32.
+   */
+  base32hex: "0123456789ABCDEFGHIJKLMNOPQRSTUV",
+  /**
+   * Base36 — digits + lowercase alpha.
+   * Use for: short URLs, case-insensitive IDs, number system conversions.
+   */
+  base36: "0123456789abcdefghijklmnopqrstuvwxyz",
+  /**
+   * Base58 — Bitcoin alphabet. No 0/O/I/l to avoid visual ambiguity.
+   * Use for: Bitcoin addresses, IPFS CIDs, human-readable tokens.
+   */
+  base58: "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz",
+  /**
+   * Base62 — digits + lowercase + uppercase. Max density for alphanumeric.
+   * Use for: URL shorteners, compact IDs, high-entropy tokens.
+   */
+  base62: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
+  /**
+   * Base64 URL-safe — RFC 4648 §5. No +/= padding; URL and filename safe.
+   * Use for: JWT components, URL tokens, file names.
+   */
+  base64url: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz-_",
+  /**
+   * Alphanumeric — same as base62. Alias for clarity.
+   */
+  alphanumeric: "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
+  /**
+   * Alpha — letters only, mixed case.
+   */
+  alpha: "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz",
+  /**
+   * Numeric — digits only.
+   */
+  numeric: "0123456789",
+  /**
+   * Hex — alias for base16 lowercase.
+   */
+  hex: "0123456789abcdef",
+  /**
+   * Crockford Base32 — human-friendly, case-insensitive, excludes I/L/O/U.
+   * Use for: serial numbers, redemption codes, user-facing IDs.
+   */
+  crockford32: "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+};
+function resolveCharsetAlias(value) {
+  return CHARSET_ALIASES[value] ?? value;
+}
+
+// src/str/utilities.ts
+function words(str) {
+  assertString(str);
+  return str.match(/[A-Za-z0-9]+/g) ?? [];
+}
+function wordCount(str) {
+  return words(str).length;
+}
+function join(values, separator = " ") {
+  return values.filter((v) => v !== null && v !== void 0 && v !== "").join(separator);
+}
+function template(str, data, options = {}) {
+  assertString(str);
+  const { fallback } = options;
+  return str.replace(/\{\{\s*([\w.$-]+)\s*\}\}/g, (match, key) => {
+    const value = data[key];
+    if (value === void 0 || value === null) {
+      return fallback !== void 0 ? fallback : match;
+    }
+    return String(value);
+  });
+}
+function random(length, charset = "alphanumeric") {
+  if (!Number.isInteger(length) || length < 0) {
+    throw new RangeError(`length must be a non-negative integer, received ${length}.`);
+  }
+  const pool = resolveCharsetAlias(charset);
+  if (pool.length < 2) {
+    throw new RangeError("charset must contain at least 2 distinct characters.");
+  }
+  if (length === 0) return "";
+  return getRandomChars(pool, length).join("");
+}
+function randomAlpha(length) {
+  return random(length, CHARSET_ALIASES.alpha);
+}
+function randomNumeric(length) {
+  return random(length, CHARSET_ALIASES.numeric);
+}
+function randomAlphanumeric(length) {
+  return random(length, CHARSET_ALIASES.alphanumeric);
+}
+function similarity(a, b) {
+  assertString(a, "a");
+  assertString(b, "b");
+  if (a === b) return 1;
+  const maxLen = Math.max(a.length, b.length);
+  if (maxLen === 0) return 1;
+  return 1 - levenshtein(a, b) / maxLen;
+}
+function levenshtein(a, b) {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  const curr = new Array(b.length + 1);
+  for (let i = 1; i <= a.length; i++) {
+    curr[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+    }
+    prev = curr.slice();
+  }
+  return prev[b.length];
+}
+var TRANSLITERATION_MAP = {
+  "\xDF": "ss",
+  // ß
+  "\xE6": "ae",
+  // æ
+  "\xC6": "AE",
+  // Æ
+  "\u0153": "oe",
+  // œ
+  "\u0152": "OE",
+  // Œ
+  "\xF8": "o",
+  // ø
+  "\xD8": "O",
+  // Ø
+  "\u0111": "d",
+  // đ
+  "\u0110": "D",
+  // Đ
+  "\xF0": "d",
+  // ð
+  "\xD0": "D",
+  // Ð
+  "\xFE": "th",
+  // þ
+  "\xDE": "Th",
+  // Þ
+  "\u0142": "l",
+  // ł
+  "\u0141": "L"
+  // Ł
+};
+function transliterate(str) {
+  assertString(str);
+  const mapped = [...str].map((ch) => TRANSLITERATION_MAP[ch] ?? ch).join("");
+  return mapped.normalize("NFKD").replace(/[̀-ͯ]/g, "");
+}
+
+// src/str/formatting.ts
+function humanize(str) {
+  assertString(str);
+  const words2 = extractWords(str).map((w) => w.toLowerCase());
+  if (words2.length === 0) return "";
+  const [first, ...rest] = words2;
+  return [first.charAt(0).toUpperCase() + first.slice(1), ...rest].join(" ");
+}
+var TITLE_MINOR_WORDS = /* @__PURE__ */ new Set([
+  "a",
+  "an",
+  "and",
+  "as",
+  "at",
+  "but",
+  "by",
+  "for",
+  "if",
+  "in",
+  "nor",
+  "of",
+  "on",
+  "or",
+  "per",
+  "the",
+  "to",
+  "via",
+  "vs"
+]);
+function titleCase(str) {
+  assertString(str);
+  const words2 = str.trim().split(/\s+/).filter(Boolean);
+  const last = words2.length - 1;
+  return words2.map((word, i) => {
+    const lower = word.toLowerCase();
+    if (i !== 0 && i !== last && TITLE_MINOR_WORDS.has(lower)) return lower;
+    return lower.charAt(0).toUpperCase() + lower.slice(1);
+  }).join(" ");
+}
+function slugify(str, separator = "-") {
+  assertString(str);
+  return transliterate(str).toLowerCase().replace(/[^a-z0-9]+/g, separator).replace(new RegExp(`^${escapeSep(separator)}+|${escapeSep(separator)}+$`, "g"), "");
+}
+function escapeSep(sep) {
+  return sep.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function ordinalize(n) {
+  const num = typeof n === "number" ? n : parseInt(n, 10);
+  if (!Number.isFinite(num)) throw new TypeError(`Expected a finite number, received ${n}.`);
+  const abs = Math.abs(num) % 100;
+  let suffix = "th";
+  if (abs < 11 || abs > 13) {
+    switch (abs % 10) {
+      case 1:
+        suffix = "st";
+        break;
+      case 2:
+        suffix = "nd";
+        break;
+      case 3:
+        suffix = "rd";
+        break;
+    }
+  }
+  return `${num}${suffix}`;
+}
+var IRREGULAR_PLURALS = {
+  child: "children",
+  person: "people",
+  man: "men",
+  woman: "women",
+  tooth: "teeth",
+  foot: "feet",
+  mouse: "mice",
+  goose: "geese",
+  ox: "oxen"
+};
+var UNCOUNTABLE = /* @__PURE__ */ new Set([
+  "sheep",
+  "fish",
+  "series",
+  "species",
+  "deer",
+  "information",
+  "equipment",
+  "money",
+  "rice",
+  "news"
+]);
+function pluralize(word, count2) {
+  assertString(word, "word");
+  if (count2 === 1) return word;
+  if (word.length === 0) return word;
+  const lower = word.toLowerCase();
+  const preserve = (result) => word[0] === word[0].toUpperCase() ? result.charAt(0).toUpperCase() + result.slice(1) : result;
+  if (UNCOUNTABLE.has(lower)) return word;
+  if (IRREGULAR_PLURALS[lower]) return preserve(IRREGULAR_PLURALS[lower]);
+  if (/[^aeiou]y$/.test(lower)) return preserve(lower.slice(0, -1) + "ies");
+  if (/(s|ss|sh|ch|x|z)$/.test(lower)) return preserve(lower + "es");
+  if (/(fe?)$/.test(lower)) return preserve(lower.replace(/fe?$/, "ves"));
+  return preserve(lower + "s");
+}
+
+// src/str/padding.ts
+function padLeft(str, length, char = " ") {
+  assertString(str);
+  if (char.length === 0) return str;
+  return str.length >= length ? str : buildPad(char, length - str.length) + str;
+}
+function padRight(str, length, char = " ") {
+  assertString(str);
+  if (char.length === 0) return str;
+  return str.length >= length ? str : str + buildPad(char, length - str.length);
+}
+function padCenter(str, length, char = " ") {
+  assertString(str);
+  if (char.length === 0 || str.length >= length) return str;
+  const total = length - str.length;
+  const left = Math.floor(total / 2);
+  const right = total - left;
+  return buildPad(char, left) + str + buildPad(char, right);
+}
+function buildPad(char, width) {
+  if (width <= 0) return "";
+  return char.repeat(Math.ceil(width / char.length)).slice(0, width);
+}
+function indent(str, count2 = 2, char = " ", indentEmpty = false) {
+  assertString(str);
+  const prefix = char.repeat(count2);
+  return str.split("\n").map((line) => indentEmpty || line.length > 0 ? prefix + line : line).join("\n");
+}
+function dedent(str) {
+  assertString(str);
+  const lines = str.replace(/^\n/, "").replace(/\n[ \t]*$/, "").split("\n");
+  let min = Infinity;
+  for (const line of lines) {
+    if (line.trim().length === 0) continue;
+    const leading = line.match(/^[ \t]*/)[0].length;
+    if (leading < min) min = leading;
+  }
+  if (!Number.isFinite(min) || min === 0) return lines.join("\n");
+  return lines.map((line) => line.slice(min)).join("\n");
+}
+
+// src/str/security.ts
+var HTML_ESCAPES = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;"
+};
+var HTML_UNESCAPES = {
+  "&amp;": "&",
+  "&lt;": "<",
+  "&gt;": ">",
+  "&quot;": '"',
+  "&#39;": "'",
+  "&#x27;": "'",
+  "&apos;": "'",
+  "&#x2F;": "/",
+  "&#47;": "/"
+};
+function escapeHtml(str) {
+  assertString(str);
+  return str.replace(/[&<>"']/g, (ch) => HTML_ESCAPES[ch]);
+}
+function unescapeHtml(str) {
+  assertString(str);
+  return str.replace(/&(?:amp|lt|gt|quot|#39|#x27|apos|#x2F|#47);/g, (ent) => HTML_UNESCAPES[ent]);
+}
+function escapeRegExp(str) {
+  assertString(str);
+  return str.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function stripTags(str) {
+  assertString(str);
+  return str.replace(/<[^>]*>/g, "");
+}
+function collapseWhitespace(str) {
+  assertString(str);
+  return str.replace(/\s+/g, " ").trim();
+}
+function stripPrefix(str, prefix) {
+  assertString(str);
+  assertString(prefix, "prefix");
+  return prefix.length > 0 && str.startsWith(prefix) ? str.slice(prefix.length) : str;
+}
+function stripSuffix(str, suffix) {
+  assertString(str);
+  assertString(suffix, "suffix");
+  return suffix.length > 0 && str.endsWith(suffix) ? str.slice(0, -suffix.length) : str;
+}
+
+// src/str/ensuring.ts
+function ensureLeft(str, prefix) {
+  assertString(str);
+  assertString(prefix, "prefix");
+  return str.startsWith(prefix) ? str : prefix + str;
+}
+function ensureRight(str, suffix) {
+  assertString(str);
+  assertString(suffix, "suffix");
+  return str.endsWith(suffix) ? str : str + suffix;
+}
+
+exports.between = between;
+exports.betweenAll = betweenAll;
+exports.camelize = camelize;
+exports.capitalize = capitalize;
+exports.capitalizeWords = capitalizeWords;
+exports.collapseWhitespace = collapseWhitespace;
+exports.contains = contains;
+exports.containsAll = containsAll;
+exports.containsAny = containsAny;
+exports.count = count;
+exports.dasherize = dasherize;
+exports.dedent = dedent;
+exports.ensureLeft = ensureLeft;
+exports.ensureRight = ensureRight;
+exports.escapeHtml = escapeHtml;
+exports.escapeRegExp = escapeRegExp;
+exports.humanize = humanize;
+exports.indent = indent;
+exports.insert = insert;
+exports.isAlpha = isAlpha;
+exports.isAlphaNumeric = isAlphaNumeric;
+exports.isBlank = isBlank;
+exports.isEmpty = isEmpty;
+exports.isLowerCase = isLowerCase;
+exports.isNumeric = isNumeric;
+exports.isString = isString;
+exports.isUpperCase = isUpperCase;
+exports.join = join;
+exports.mask = mask;
+exports.ordinalize = ordinalize;
+exports.padCenter = padCenter;
+exports.padLeft = padLeft;
+exports.padRight = padRight;
+exports.pascalize = pascalize;
+exports.pluralize = pluralize;
+exports.random = random;
+exports.randomAlpha = randomAlpha;
+exports.randomAlphanumeric = randomAlphanumeric;
+exports.randomNumeric = randomNumeric;
+exports.reverse = reverse;
+exports.similarity = similarity;
+exports.slugify = slugify;
+exports.stripPrefix = stripPrefix;
+exports.stripSuffix = stripSuffix;
+exports.stripTags = stripTags;
+exports.template = template;
+exports.titleCase = titleCase;
+exports.transliterate = transliterate;
+exports.trim = trim;
+exports.truncate = truncate;
+exports.truncateWords = truncateWords;
+exports.underscore = underscore;
+exports.unescapeHtml = unescapeHtml;
+exports.wordCount = wordCount;
+exports.words = words;
+//# sourceMappingURL=str.cjs.map
+//# sourceMappingURL=str.cjs.map