@jarenjs/core 0.9.2

package/src/object.js

@@ -0,0 +1,240 @@
+//@ts-check
+
+import {
+  isFn,
+  isScalarType,
+  isBooleanType,
+  isTypedArray,
+} from './index.js';
+
+const hasOwn = Object.hasOwn;
+
+/**
+ * Deep equality comparison for arbitrary values.
+ *
+ * Generic JavaScript equality: understands Maps, Sets, RegExps,
+ * functions, typed arrays and class instances (constructors must
+ * match). Not the same as `equalsJson`, which compares JSON values
+ * only and is the hot-path variant — keep both.
+ * @param {any} target
+ * @param {any} source
+ * @returns {boolean}
+ */
+export function equalsDeep(target, source) {
+  if (target === source) return true;
+  if (target == null) return false;
+  if (source == null) return false;
+  if (isBooleanType(target)) return false;
+  if (isBooleanType(source)) return false;
+
+  if (isFn(target))
+    return target.toString() === source.toString();
+
+  if (isScalarType(target))
+    return false;
+
+  if (target.constructor !== source.constructor)
+    return false;
+
+  if (target.constructor === Object) {
+    const tks = Object.keys(target);
+    const sks = Object.keys(source);
+    if (tks.length !== sks.length)
+      return false;
+    for (let i = 0; i < tks.length; ++i) {
+      const key = tks[i];
+      if (!equalsDeep(target[key], source[key]))
+        return false;
+    }
+    return true;
+  }
+
+  if (target.constructor === Map) {
+    if (target.size !== source.size)
+      return false;
+    for (const [key, value] of target) {
+      if (source.has(key) === false)
+        return false;
+      if (!equalsDeep(value, source.get(key)))
+        return false;
+    }
+    return true;
+  }
+
+  if (target.constructor === Array) {
+    if (target.length !== source.length)
+      return false;
+    for (let i = 0; i < target.length; ++i) {
+      if (!equalsDeep(target[i], source[i]))
+        return false;
+    }
+    return true;
+  }
+
+  if (target.constructor === Set) {
+    if (target.size !== source.size)
+      return false;
+    for (const value of target) {
+      if (source.has(value) === false)
+        return false;
+    }
+    return true;
+  }
+
+  if (target.constructor === RegExp) {
+    return target.toString() === source.toString();
+  }
+
+  if (isTypedArray(target)) {
+    if (target.length !== source.length)
+      return false;
+    for (let i = 0; i < target.length; ++i) {
+      if (target[i] !== source[i])
+        return false;
+    }
+    return true;
+  }
+
+  // we could test for instance of Array, Map and Set in order
+  // to differentiate between types of equality.. but we dont.
+  const tkeys = Object.keys(target);
+  const skeys = Object.keys(source);
+  if (tkeys.length !== skeys.length) return false;
+  if (tkeys.length === 0) return true;
+  for (let i = 0; i < tkeys.length; ++i) {
+    const key = tkeys[i];
+    if (!equalsDeep(target[key], source[key]))
+      return false;
+  }
+  return true;
+}
+
+/**
+ * Structural equality of two JSON values per RFC 9535 section 2.3.5.2.2.
+ *
+ * JSON-only equality: objects compare by own enumerable keys, arrays by
+ * index, primitives by `===` (so `1 === 1.0`, and `NaN` is never equal).
+ * Anything a JSON value cannot be — Map, Set, RegExp, function, class
+ * instance — compares by identity only. Deliberately not the same as
+ * `equalsDeep`, the generic JavaScript variant: this is the hot-path
+ * comparator of the JSONPath engine — do not merge the two.
+ * @param {any} a
+ * @param {any} b
+ * @returns {boolean}
+ */
+export function equalsJson(a, b) {
+  if (a === b)
+    return true;
+  if (typeof a !== 'object' || typeof b !== 'object' || a === null || b === null)
+    return false;
+  const aIsArray = Array.isArray(a);
+  if (aIsArray !== Array.isArray(b))
+    return false;
+  if (aIsArray) {
+    const alen = a.length;
+    if (alen !== b.length)
+      return false;
+    for (let i = 0; i < alen; i++) {
+      if (!equalsJson(a[i], b[i]))
+        return false;
+    }
+    return true;
+  }
+  let count = 0;
+  for (const key in a) {
+    if (!hasOwn(a, key))
+      continue;
+    if (!hasOwn(b, key) || !equalsJson(a[key], b[key]))
+      return false;
+    count++;
+  }
+  for (const key in b) {
+    if (hasOwn(b, key))
+      count--;
+  }
+  return count === 0;
+}
+
+/**
+ * Check if all items in an array are unique using deep equality
+ * @param {any[]} arr - The array to check
+ * @returns {boolean} True if all items are unique
+ */
+export function isUniqueDeepArray(arr) {
+  if (!Array.isArray(arr) || arr.length < 2) return true;
+
+  // Small all-scalar arrays: pairwise === beats allocating a Set.
+  if (arr.length <= 8) {
+    let allScalar = true;
+    for (let i = 0; i < arr.length; i++) {
+      const item = arr[i];
+      if ((typeof item === 'object' && item !== null) || typeof item === 'function') {
+        allScalar = false;
+        break;
+      }
+    }
+    if (allScalar) {
+      for (let i = 0; i < arr.length; i++) {
+        for (let j = i + 1; j < arr.length; j++) {
+          if (arr[i] === arr[j]) return false;
+        }
+      }
+      return true;
+    }
+  }
+
+  // Primitives are compared with === by equalsDeep and can never deep-equal
+  // an object, so they dedupe in O(n) through a Set (SameValueZero); only
+  // objects, arrays and functions need the pairwise deep comparison.
+  let seen = null;
+  let complex = null;
+  for (let i = 0; i < arr.length; i++) {
+    const item = arr[i];
+    if ((typeof item === 'object' && item !== null) || typeof item === 'function') {
+      if (complex === null) complex = [item];
+      else complex.push(item);
+    }
+    else {
+      // NaN !== NaN under equalsDeep; keep NaN values always unique
+      if (typeof item === 'number' && item !== item) continue;
+      if (seen === null) seen = new Set();
+      else if (seen.has(item)) return false;
+      seen.add(item);
+    }
+  }
+
+  if (complex !== null && complex.length > 1) {
+    for (let i = 0; i < complex.length; i++) {
+      for (let j = i + 1; j < complex.length; j++) {
+        if (equalsDeep(complex[i], complex[j])) return false;
+      }
+    }
+  }
+  return true;
+}
+
+/**
+ *
+ * @param {Map<any, any>} map
+ * @param {...Map<any, any>} iterables
+ */
+export function mergeMap(map, ...iterables) {
+  for (const iterable of iterables) {
+    for (const item of iterable) {
+      map.set(...item);
+    }
+  }
+}
+
+/**
+ *
+ * @param {Set<any>} set
+ * @param  {...Array<Set<any>>} iterables
+ */
+export function mergeSet(set, ...iterables) {
+  for (const iterable of iterables) {
+    for (const item of iterable) {
+      set.add(item);
+    }
+  }
+}

package/src/scan.js

@@ -0,0 +1,96 @@
+//@ts-check
+
+// Scanner primitives shared by the char-code-level recursive-descent
+// parsers (JSONPath in json/path.js, I-Regexp in text/iregexp.js).
+// Constants and pure predicates only — stateful token readers belong
+// to the parser that owns the cursor.
+
+//#region char codes
+
+export const CC_TAB = 0x09;
+export const CC_LF = 0x0A;
+export const CC_CR = 0x0D;
+export const CC_SPACE = 0x20;
+export const CC_BANG = 0x21;
+export const CC_DQUOTE = 0x22;
+export const CC_HASH = 0x23;
+export const CC_DOLLAR = 0x24;
+export const CC_PERCENT = 0x25;
+export const CC_AMP = 0x26;
+export const CC_SQUOTE = 0x27;
+export const CC_LPAREN = 0x28;
+export const CC_RPAREN = 0x29;
+export const CC_STAR = 0x2A;
+export const CC_COMMA = 0x2C;
+export const CC_MINUS = 0x2D;
+export const CC_DOT = 0x2E;
+export const CC_SLASH = 0x2F;
+export const CC_0 = 0x30;
+export const CC_1 = 0x31;
+export const CC_9 = 0x39;
+export const CC_COLON = 0x3A;
+export const CC_LT = 0x3C;
+export const CC_EQ = 0x3D;
+export const CC_GT = 0x3E;
+export const CC_QUESTION = 0x3F;
+export const CC_AT = 0x40;
+export const CC_LBRACKET = 0x5B;
+export const CC_BACKSLASH = 0x5C;
+export const CC_RBRACKET = 0x5D;
+export const CC_UNDERSCORE = 0x5F;
+export const CC_PIPE = 0x7C;
+export const CC_TILDE = 0x7E;
+
+//#endregion
+
+//#region predicates
+
+/**
+ * Checks if a char code is an ASCII digit (0-9).
+ * @param {number} c - The char code
+ * @returns {boolean}
+ */
+export function isDigitCode(c) {
+  return c >= CC_0 && c <= CC_9;
+}
+
+/**
+ * Checks if a char code is an ASCII hexadecimal digit (0-9, A-F, a-f).
+ * @param {number} c - The char code
+ * @returns {boolean}
+ */
+export function isHexDigitCode(c) {
+  return (c >= CC_0 && c <= CC_9)
+    || (c >= 0x41 && c <= 0x46) // A-F
+    || (c >= 0x61 && c <= 0x66); // a-f
+}
+
+/**
+ * Checks if a char code is blank space per RFC 9535 (space, tab,
+ * line feed or carriage return).
+ * @param {number} c - The char code
+ * @returns {boolean}
+ */
+export function isWhitespaceCode(c) {
+  return c === CC_SPACE || c === CC_TAB || c === CC_LF || c === CC_CR;
+}
+
+/**
+ * Checks if a char code is an ASCII lowercase letter (a-z).
+ * @param {number} c - The char code
+ * @returns {boolean}
+ */
+export function isAsciiLowerCode(c) {
+  return c >= 0x61 && c <= 0x7A;
+}
+
+/**
+ * Checks if a char code is an ASCII uppercase letter (A-Z).
+ * @param {number} c - The char code
+ * @returns {boolean}
+ */
+export function isAsciiUpperCode(c) {
+  return c >= 0x41 && c <= 0x5A;
+}
+
+//#endregion

package/src/string.js

@@ -0,0 +1,194 @@
+//@ts-check
+
+import {
+  isStringType,
+  isObjectOfClass,
+} from './index.js';
+
+/**
+ * @param {string | null | undefined} data
+ * @returns {boolean}
+ */
+export function isStringEmpty(data) {
+  return typeof data === 'string' && !data;
+}
+
+/**
+ * @param {string | null | undefined} data
+ * @returns {boolean}
+ */
+export function isStringWhiteSpace(data) {
+  return data == null || /^\s*$/.test(data);
+}
+
+/**
+ * @param {string} str
+ * @returns {boolean}
+ */
+export function isStringUpperCase(str) {
+  return str === str.toUpperCase();
+}
+
+/**
+ * @param {string} str
+ * @returns {boolean}
+ */
+export function isStringLowerCase(str) {
+  return str === str.toLowerCase();
+}
+
+/**
+ * @param {unknown} data
+ * @returns {data is RegExp}
+ */
+export function isRegExpType(data) {
+  return isObjectOfClass(data, RegExp);
+}
+
+
+/**
+ * @param {string | RegExp | null | undefined } data
+ * @returns {boolean}
+ */
+export function isStringRegExp(data) {
+  try {
+    return createRegExp(data) != null;
+  }
+  // eslint-disable-next-line no-unused-vars
+  catch (e) {
+    return false;
+  }
+}
+
+/**
+ * @param {string | RegExp | null | undefined } pattern
+ * @returns {RegExp | undefined}
+ */
+export function createRegExp(pattern) {
+  if (pattern == null)
+    return undefined;
+
+  if (isRegExpType(pattern))
+    return pattern;
+
+  if (isStringType(pattern)) {
+    if (pattern[0] === '/') {
+      const e = pattern.lastIndexOf('/');
+      if (e >= 0) {
+        const r = pattern.substring(1, e);
+        const g = pattern.substring(e + 1);
+        // Add unicode flag if not already present
+        return g.includes('u') ? new RegExp(r, g) : new RegExp(r, g + 'u');
+      }
+    }
+    else
+      return new RegExp(pattern, 'u');
+  }
+  // TODO: should we return false instead?
+  throw new Error(`Unknown Regular Expression Pattern Type: ${pattern}`);
+}
+
+/**
+ * @type {Intl.Segmenter | null}
+ */
+let segmenterCache = null;
+export function getSegmenter() {
+  if (segmenterCache === null) {
+    segmenterCache = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+  }
+  return segmenterCache;
+}
+
+/**
+ * @param {string} str
+ * @returns {boolean}
+ */
+export function isAsciiString(str) {
+  const len = str.length;
+  for (let i = 0; i < len; i++) {
+    if (str.charCodeAt(i) > 127) return false;
+  }
+  return true;
+}
+
+// Characters that can merge with neighbours into a multi-codepoint grapheme
+// cluster: CR (CRLF), combining marks, ZWJ/ZWNJ, variation selectors,
+// emoji modifiers, regional indicators (flags), conjoining Hangul jamo,
+// prepended concatenation marks and tag characters. When none of these are
+// present, grapheme count equals code point count and the (expensive)
+// 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{...})
+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;
+
+/**
+ * @param {string} str
+ * @param {boolean} [useGrapheme=false]
+ * @returns {number}
+ */
+export function getStringLength(str, useGrapheme = false) {
+  if (!useGrapheme) {
+    return str.length;
+  }
+  // Fast-path: check ASCII inline to avoid function call overhead
+  const len = str.length;
+  for (let i = 0; i < len; i++) {
+    if (str.charCodeAt(i) > 127) {
+      // Non-ASCII found - use grapheme counting.
+      // Segment the whole string: a cluster may span the ASCII boundary
+      // (e.g. 'e' followed by a combining accent).
+      if (COMPLEX_GRAPHEME_REGEX.test(str)) {
+        let count = 0;
+        for (const _ of getSegmenter().segment(str)) count++;
+        return count;
+      }
+      // No cluster-forming characters: count code points (surrogate aware)
+      return countCodePoints(str);
+    }
+  }
+  return len;
+}
+
+/**
+ * Count the Unicode code points of a string (surrogate-pair aware;
+ * a lone surrogate counts as one code point).
+ * @param {string} str
+ * @returns {number}
+ */
+export function countCodePoints(str) {
+  const slen = str.length;
+  let count = 0;
+  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)
+        i++;
+    }
+    count++;
+  }
+  return count;
+}
+
+/**
+ * Compare two strings by Unicode scalar values (code points), per
+ * RFC 9535 section 2.3.5.2.2. This differs from JavaScript's native
+ * `<`, which compares UTF-16 code units and orders surrogate pairs
+ * (U+10000 and up) below unpaired BMP characters in U+E000-U+FFFF.
+ * When one string is a prefix of the other, the shorter sorts first.
+ * @param {string} a
+ * @param {string} b
+ * @returns {number} -1 when a < b, 0 when equal, 1 when a > b
+ */
+export function compareCodePoints(a, b) {
+  const alen = a.length;
+  const blen = b.length;
+  const m = alen < blen ? alen : blen;
+  let i = 0;
+  while (i < m && a.charCodeAt(i) === b.charCodeAt(i))
+    i++;
+  if (i === m)
+    return alen === blen ? 0 : (alen < blen ? -1 : 1);
+  // differing code units at i can never decode to equal code points
+  return a.codePointAt(i) < b.codePointAt(i) ? -1 : 1;
+}

package/src/text/base64.js

@@ -0,0 +1,54 @@
+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})?$/;
+
+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;
+}
+

package/src/text/basic.js

@@ -0,0 +1,23 @@
+const CONST_REGEXP_ALPHA = /^[a-zA-Z]+$/;
+export function isValidAlpha(str) {
+  return CONST_REGEXP_ALPHA.test(str);
+}
+const CONST_REGEXP_ALPHANUMERIC = /^[a-zA-Z0-9]+$/;
+export function isValidAlphaNumeric(str) {
+  return CONST_REGEXP_ALPHANUMERIC.test(str);
+}
+
+const CONST_REGEXP_NUMERIC = /^[0-9]+$/;
+export function isValidNumeric(str) {
+  return CONST_REGEXP_NUMERIC.test(str);
+}
+
+const CONST_REGEXP_HEXADECIMAL = /^[a-fA-F0-9]+$/;
+export function isValidHexaDecimal(str) {
+  return CONST_REGEXP_HEXADECIMAL.test(str);
+}
+
+const CONST_REGEXP_HEXCOLOR = /^#(?:[0-9a-f]{3}){1,2}\b$/i;
+export function isValidHexColor(str) {
+  return CONST_REGEXP_HEXCOLOR.test(str);
+}

package/src/text/email.js

@@ -0,0 +1,61 @@
+import {
+  isValidIPv4,
+  isValidIPv6,
+} from './host.js';
+
+// email (sources from json validator):
+// http://stackoverflow.com/questions/201323/using-a-regular-expression-to-validate-an-email-address#answer-8829363
+// http://www.w3.org/TR/html5/forms.html#valid-e-mail-address (search for 'willful violation')
+const CONST_REGEXP_EMAIL_FAST = /^[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*@[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/i;
+
+// RFC 5321 slow-path pieces: quoted-string local part (qtext / quoted-pair),
+// dot-atom local part and dot-atom domain.
+const CONST_REGEXP_EMAIL_QUOTED_LOCAL = /^"(?:[\x20-\x21\x23-\x5b\x5d-\x7e]|\\[\x20-\x7e])*"$/;
+const CONST_REGEXP_EMAIL_LOCAL = /^[a-z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-z0-9!#$%&'*+/=?^_`{|}~-]+)*$/i;
+const CONST_REGEXP_EMAIL_DOMAIN = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)+$/i;
+
+function isValidEmailDomain(domain) {
+  // RFC 5321 address literal: [IPv4] or [IPv6:...]
+  if (domain.charCodeAt(0) === 0x5b /* [ */) {
+    if (domain.charCodeAt(domain.length - 1) !== 0x5d /* ] */) return false;
+    const literal = domain.slice(1, -1);
+    if (literal.slice(0, 5).toLowerCase() === 'ipv6:')
+      return isValidIPv6(literal.slice(5));
+    return isValidIPv4(literal);
+  }
+  return CONST_REGEXP_EMAIL_DOMAIN.test(domain);
+}
+
+export function isValidEmail(str) {
+  // Fast path: dot-atom local part with a regular domain
+  if (CONST_REGEXP_EMAIL_FAST.test(str)) return true;
+
+  // Slow path (RFC 5321): quoted-string local part and/or address literal
+  if (str.charCodeAt(0) === 0x22 /* " */) {
+    // Find the end of the quoted string, honoring quoted-pairs
+    let i = 1;
+    for (; i < str.length; ++i) {
+      const c = str.charCodeAt(i);
+      if (c === 0x5c /* \ */) { i++; continue; }
+      if (c === 0x22 /* " */) break;
+    }
+    if (i >= str.length || str.charCodeAt(i + 1) !== 0x40 /* @ */) return false;
+    return CONST_REGEXP_EMAIL_QUOTED_LOCAL.test(str.slice(0, i + 1))
+      && isValidEmailDomain(str.slice(i + 2));
+  }
+
+  const at = str.lastIndexOf('@');
+  if (at <= 0) return false;
+  return CONST_REGEXP_EMAIL_LOCAL.test(str.slice(0, at))
+    && 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);
+}