@jarenjs/core 0.9.2 → 0.34.0

package/src/string.js

@@ -119,6 +119,7 @@ export function isAsciiString(str) {
 // Intl.Segmenter can be skipped.
 // (U+0600-0605, 06DD, 070F, 0890, 0891, 08E2, 110BD, 110CD are the
 // Prepended_Concatenation_Mark set, which V8 does not expose as \p{...})
+// eslint-disable-next-line no-misleading-character-class -- intentional grapheme-cluster detector: this char class deliberately mixes combining marks, join-controls, emoji modifiers, regional indicators and prepended concatenation marks to fast-path the Intl.Segmenter skip.
 const COMPLEX_GRAPHEME_REGEX = /[\r\p{M}\p{Join_Control}\p{Emoji_Modifier}\p{Regional_Indicator}\u0600-\u0605\u06DD\u070F\u0890\u0891\u08E2\uFE00-\uFE0F\u1100-\u11FF\uA960-\uA97F\uD7B0-\uD7FF\u{110BD}\u{110CD}\u{E0000}-\u{E007F}]/u;
 
 /**
@@ -149,6 +150,22 @@ export function getStringLength(str, useGrapheme = false) {
   return len;
 }
 
+/**
+ * Count occurrences of a UTF-16 code unit in a slice of a string.
+ * @param {string} str - The string to scan
+ * @param {number} code - The char code to count
+ * @param {number} [start] - Inclusive start offset (defaults to 0)
+ * @param {number} [end] - Exclusive end offset (defaults to full length)
+ * @returns {number} Number of occurrences in [start, end)
+ */
+export function countCharCode(str, code, start = 0, end = str.length) {
+  let n = 0;
+  for (let i = start; i < end; ++i)
+    if (str.charCodeAt(i) === code)
+      n++;
+  return n;
+}
+
 /**
  * Count the Unicode code points of a string (surrogate-pair aware;
  * a lone surrogate counts as one code point).
@@ -170,6 +187,72 @@ export function countCodePoints(str) {
   return count;
 }
 
+/**
+ * Decode a string into its Unicode code points (surrogate-pair aware).
+ *
+ * `Array.from(str).map(c => c.codePointAt(0))` computes the same thing
+ * but allocates a string per character on the way; this reads the code
+ * units directly. An unpaired surrogate is kept as its own code point
+ * rather than replaced, so the result round-trips through
+ * {@link fromCodePoints} and a caller validating text can see the lone
+ * surrogate and reject it.
+ *
+ * @param {string} str - The string to decode
+ * @returns {number[]} The code points, in order
+ */
+export function toCodePoints(str) {
+  const slen = str.length;
+  const out = [];
+  for (let i = 0; i < slen; i++) {
+    const c = str.charCodeAt(i);
+    if (c >= 0xD800 && c <= 0xDBFF && i + 1 < slen) {
+      const d = str.charCodeAt(i + 1);
+      if (d >= 0xDC00 && d <= 0xDFFF) {
+        out.push((c - 0xD800) * 0x400 + (d - 0xDC00) + 0x10000);
+        i++;
+        continue;
+      }
+    }
+    out.push(c);
+  }
+  return out;
+}
+
+/**
+ * Fewer code points than this and appending one at a time beats
+ * spreading the array into `String.fromCodePoint`, whose argument-list
+ * setup then costs more than the concatenations it saves. Measured
+ * crossover; the two are within a few percent either side of it.
+ */
+const CODE_POINT_SPREAD_MIN = 8;
+
+/** Code points per spread, so a large array cannot overflow the stack. */
+const CODE_POINT_SPREAD_CHUNK = 4096;
+
+/**
+ * Build a string from Unicode code points - the inverse of
+ * {@link toCodePoints}.
+ *
+ * @param {number[]} codePoints - The code points to encode
+ * @returns {string} The resulting string
+ */
+export function fromCodePoints(codePoints) {
+  const len = codePoints.length;
+  if (len < CODE_POINT_SPREAD_MIN) {
+    let out = '';
+    for (let i = 0; i < len; i++)
+      out += String.fromCodePoint(codePoints[i]);
+    return out;
+  }
+  if (len <= CODE_POINT_SPREAD_CHUNK)
+    return String.fromCodePoint(...codePoints);
+
+  let out = '';
+  for (let i = 0; i < len; i += CODE_POINT_SPREAD_CHUNK)
+    out += String.fromCodePoint(...codePoints.slice(i, i + CODE_POINT_SPREAD_CHUNK));
+  return out;
+}
+
 /**
  * Compare two strings by Unicode scalar values (code points), per
  * RFC 9535 section 2.3.5.2.2. This differs from JavaScript's native
@@ -192,3 +275,109 @@ export function compareCodePoints(a, b) {
   // differing code units at i can never decode to equal code points
   return a.codePointAt(i) < b.codePointAt(i) ? -1 : 1;
 }
+
+/** FNV-1a 32-bit offset basis — the seed a fresh hash starts from. */
+export const FNV1A_OFFSET_BASIS = 0x811c9dc5;
+
+/**
+ * FNV-1a 32-bit hash of a string, as an unsigned 32-bit number. Not
+ * cryptographic — a stable, fast content fingerprint.
+ *
+ * Pass `seed` to continue an existing hash, which is what lets a caller
+ * fold a chunk stream or walk a tree without concatenating the pieces
+ * first: `fnv1a(b, fnv1a(a))` equals `fnv1a(a + b)`. Callers that just want
+ * a fingerprint string should use {@link hashContent} instead, so the whole
+ * suite agrees on one encoding.
+ *
+ * @param {string} str
+ * @param {number} [seed] running hash to continue, unsigned 32-bit
+ * @returns {number} unsigned 32-bit hash
+ */
+export function fnv1a(str, seed = FNV1A_OFFSET_BASIS) {
+  let hash = seed;
+  for (let i = 0; i < str.length; i++) {
+    hash ^= str.charCodeAt(i);
+    hash = (hash * 0x01000193) >>> 0;
+  }
+  return hash;
+}
+
+/**
+ * FNV-1a 32-bit hash of a string, returned as an unsigned base-36 string
+ * (at most 7 chars). Not cryptographic — a stable, fast content
+ * fingerprint for cache keys and reconciliation keys. The suite's single
+ * content-hash primitive: equal content produces the same fingerprint
+ * (and therefore the same vnode `key`/memo key) everywhere downstream, so
+ * do NOT invent a second hash — {@link fnv1a} is the one mixing step.
+ *
+ * @param {string} str
+ * @returns {string}
+ */
+export function hashContent(str) {
+  return fnv1a(str).toString(36);
+}
+
+/**
+ * Convert a camelCase identifier to kebab-case by inserting a hyphen
+ * before each ASCII uppercase letter and lower-casing it
+ * (`fontFamily` → `font-family`). Leaves already-hyphenated or
+ * all-lowercase input unchanged.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+export function kebabCase(s) {
+  return s.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
+}
+
+/** One code point that a slug keeps: a letter, a digit, or a combining
+ * mark (which belongs to the letter in front of it). Everything else
+ * outside ASCII is punctuation, a symbol or an emoji, and is dropped. */
+const SLUG_KEEP = /[\p{L}\p{N}\p{M}]/u;
+
+/**
+ * Convert heading text into a URL fragment the way GitHub does, so one
+ * committed document anchors identically on GitHub, in an editor preview
+ * and in a renderer that uses this: lower-case, drop punctuation and
+ * symbols, and turn each whitespace character into a hyphen.
+ *
+ * `-` and `_` survive, as do non-ASCII letters and digits
+ * (`Ünicode Wörks` → `ünicode-wörks`); a `§` or an em dash does not,
+ * because it is a symbol rather than a letter. Text that reduces to
+ * nothing (`***`) yields `''` — what an empty slug means is the caller's
+ * decision, not this function's.
+ *
+ * This is the suite's ONLY slug implementation: a second one would drift
+ * from the first and break the promise above. Whitespace is converted one
+ * character at a time, not per run, because that is what GitHub does and
+ * the resulting `--` is part of the fragment a reader may already have
+ * bookmarked.
+ *
+ * @example
+ * slugify('Hello, World!');   // 'hello-world'
+ * slugify('§ 3.1 — Setup');   // '-31--setup'
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function slugify(text) {
+  let out = '';
+  for (let i = 0; i < text.length; i++) {
+    const code = text.charCodeAt(i);
+    if (code < 0x80) {
+      if (code >= 0x61 && code <= 0x7a) out += text[i]; // a-z
+      else if (code >= 0x41 && code <= 0x5a) out += String.fromCharCode(code + 32); // A-Z
+      else if (code >= 0x30 && code <= 0x39) out += text[i]; // 0-9
+      else if (code === 0x2d || code === 0x5f) out += text[i]; // - _
+      else if (code === 0x20 || (code >= 0x09 && code <= 0x0d)) out += '-';
+      continue;
+    }
+    // Outside ASCII a slug decision needs the whole code point, so an
+    // astral pair is read (and skipped over) as one character.
+    const point = /** @type {number} */ (text.codePointAt(i));
+    const char = String.fromCodePoint(point);
+    if (point > 0xffff) i++;
+    if (SLUG_KEEP.test(char)) out += char.toLowerCase();
+  }
+  return out;
+}

package/src/text/base64.js

@@ -1,54 +1,17 @@
-const CONST_REGEXP_BASE64 = /^(?:[a-zA-Z0-9+\/]{4})*(?:|(?:[a-zA-Z0-9+\/]{3}=)|(?:[a-zA-Z0-9+\/]{2}==)|(?:[a-zA-Z0-9+\/]{1}===))$/;
-export function isValidBase64Full(str) {
-  return CONST_REGEXP_BASE64.test(str);
-}
-
-// Base64 validation regex (RFC 4648)
-const BASE64_REGEX_SHORT = /^[A-Za-z0-9+/]*={0,2}$/;
-
-export function isValidBase64Old(str) {
-  // Check length is valid for base64 (multiple of 4)
-  if (str.length % 4 !== 0) return false;
-  // Check characters are valid base64
-  if (!BASE64_REGEX_SHORT.test(str)) return false;
-  return true;
-}
-
-const BASE64_REGEX = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})?$/;
-
+//@ts-check
+
+// Base64 (RFC 4648 section 4): groups of four characters from the
+// standard alphabet, with the final group optionally padded to four by
+// one or two "=". Three padding characters, or padding anywhere but at
+// the end, are not Base64 - which is what separates this from the
+// length-and-charset approximations it is easy to reach for.
+const CONST_REGEXP_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=|[A-Za-z0-9+/]{4})?$/;
+
+/**
+ * Validate a Base64-encoded string (RFC 4648).
+ * @param {string} str - The candidate encoding
+ * @returns {boolean} True when the string is well-formed Base64
+ */
 export function isValidBase64(str) {
-  return BASE64_REGEX.test(str);
-}
-
-// Fast base64 validation - inline for performance
-// Valid base64 chars: A-Z (65-90), a-z (97-122), 0-9 (48-57), + (43), / (47)
-export function isValidBase64Fast(str) {
-  const len = str.length;
-  if (len === 0) return true;
-
-  // Check length is valid for base64 (must be multiple of 4)
-  if (len % 4 !== 0) return false;
-
-  // Check all characters are valid base64 (A-Z, a-z, 0-9, +, /, =)
-  for (let i = 0; i < len; i++) {
-    const code = str.charCodeAt(i);
-    // A-Z, a-z, 0-9, +, /, =
-    if (!((code >= 65 && code <= 90) ||
-          (code >= 97 && code <= 122) ||
-          (code >= 48 && code <= 57) ||
-          code === 43 || code === 47 || code === 61)) {
-      return false;
-    }
-  }
-
-  // Check padding rules
-  // Valid endings: xxxx (no padding), xxx= (1 padding), xx== (2 padding)
-  const c1 = str.charCodeAt(len - 2);
-  const c2 = str.charCodeAt(len - 1);
-  
-  // If second to last is =, last must also be =
-  if (c1 === 61 && c2 !== 61) return false;
-
-  return true;
+  return CONST_REGEXP_BASE64.test(str);
 }
-

package/src/text/email.js

@@ -50,11 +50,6 @@ export function isValidEmail(str) {
     && isValidEmailDomain(str.slice(at + 1));
 }
 
-const CONST_REGEXP_EMAIL_FULL = /^[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/i;
-export function isValidEmailFull(str) {
-  return CONST_REGEXP_EMAIL_FULL.test(str);
-}
-
 const CONST_REGEXP_IDNEMAIL = /^[^@]+@[^@]+\.[^@]+$/;
 export function isValidIdnEmail(str) {
   return CONST_REGEXP_IDNEMAIL.test(str);