@jarenjs/core 0.9.2 → 0.34.0

package/src/message.js

@@ -0,0 +1,119 @@
+//@ts-check
+
+/**
+ * Human-message templating: the shared half of every message catalog in
+ * the suite.
+ *
+ * A catalog is a plain flat object keyed by a stable message id, whose
+ * entries are either render closures or template strings. Compiling one
+ * turns every template string into a closure, so the consumer only ever
+ * calls `catalog[msgid](params)` — the two-stage house rule applied to
+ * messages: parse the template once, render many times.
+ *
+ * This lives in `@jarenjs/core` so that packages which must not depend on
+ * each other can still speak the identical catalog contract. That is what
+ * lets one locale pack service both the validator's document voice ("must
+ * have required property 'x'") and the form layer's field voice ("This
+ * field is required") without either package importing the other.
+ */
+
+/**
+ * Render one interpolated parameter: `String(v)` for primitives,
+ * `JSON.stringify(v)` for objects and arrays.
+ *
+ * @param {unknown} value - The parameter value
+ * @returns {string} The rendered value
+ */
+export function formatTemplateParam(value) {
+  return (value !== null && typeof value === 'object')
+    ? JSON.stringify(value)
+    : String(value);
+}
+
+/**
+ * Render a JSON value for quotation inside a message: strings keep their
+ * quotes so an empty or space-padded value is visible, everything else is
+ * JSON.
+ *
+ * @param {unknown} value - The value to render
+ * @returns {string}
+ */
+export function formatMessageValue(value) {
+  return typeof value === 'string' ? `"${value}"` : JSON.stringify(value);
+}
+
+/**
+ * Compile a message template into a render closure. Template syntax:
+ * `{name}` substitutes the params member `name`; an unknown name leaves
+ * the placeholder literally (so a catalog typo shows up in the output
+ * instead of rendering as `undefined`); `{{` escapes a literal `{`.
+ *
+ * @param {string} template - The template text
+ * @returns {(params: object, error?: object) => string} The compiled render closure
+ */
+export function compileMessageTemplate(template) {
+  /** @type {string[]} literal parts between placeholders */
+  const parts = [];
+  /** @type {string[]} placeholder names, one per gap between parts */
+  const names = [];
+  let literal = '';
+  for (let i = 0; i < template.length; ++i) {
+    if (template.charCodeAt(i) === 0x7b /* { */) {
+      if (template.charCodeAt(i + 1) === 0x7b) {
+        literal += '{';
+        i += 1;
+        continue;
+      }
+      const end = template.indexOf('}', i + 1);
+      if (end === -1) {
+        literal += template.slice(i);
+        break;
+      }
+      parts.push(literal);
+      literal = '';
+      names.push(template.slice(i + 1, end));
+      i = end;
+      continue;
+    }
+    literal += template[i];
+  }
+  parts.push(literal);
+
+  if (names.length === 0) {
+    const text = parts[0];
+    return function renderLiteralTemplate() { return text; };
+  }
+
+  return function renderMessageTemplate(params) {
+    let out = parts[0];
+    for (let i = 0; i < names.length; ++i) {
+      const name = names[i];
+      out += (params != null && name in params)
+        ? formatTemplateParam(params[name])
+        : `{${name}}`;
+      out += parts[i + 1];
+    }
+    return out;
+  };
+}
+
+/**
+ * Compile a catalog-like object into a functions-only frozen catalog.
+ * Entries may be render closures (kept as-is) or template strings
+ * (compiled through {@link compileMessageTemplate}).
+ *
+ * @param {Record<string, string | ((params: object, error?: object) => string)>} catalogLike - The catalog to compile
+ * @returns {Readonly<Record<string, (params: object, error?: object) => string>>} The compiled catalog
+ */
+export function compileMessageCatalog(catalogLike) {
+  /** @type {Record<string, (params: object, error?: object) => string>} */
+  const compiled = {};
+  const keys = Object.keys(catalogLike);
+  for (let i = 0; i < keys.length; ++i) {
+    const entry = catalogLike[keys[i]];
+    compiled[keys[i]] = typeof entry === 'function'
+      ? entry
+      : compileMessageTemplate(String(entry));
+  }
+  return Object.freeze(compiled);
+}

package/src/object.js

@@ -6,6 +6,7 @@ import {
   isBooleanType,
   isTypedArray,
 } from './index.js';
+import { compareCodePoints, hashContent } from './string.js';
 
 const hasOwn = Object.hasOwn;
 
@@ -155,6 +156,31 @@ export function equalsJson(a, b) {
   return count === 0;
 }
 
+/**
+ * Ordering of two JSON values per RFC 9535 section 2.3.5.2.2 — the
+ * ordering half of the comparison family whose equality half is
+ * `equalsJson`.
+ *
+ * Only two numbers or two strings order at all: numbers by value,
+ * strings by Unicode scalar values (`compareCodePoints`, not the native
+ * `<`). Every other pair — mismatched types, objects, arrays, booleans,
+ * null — is simply `false` in both directions, never an error.
+ *
+ * @param {any} a
+ * @param {any} b
+ * @param {boolean} [orEqual] when true test `<=` instead of `<`
+ * @returns {boolean}
+ */
+export function compareJsonScalarLt(a, b, orEqual = false) {
+  if (typeof a === 'number')
+    return typeof b === 'number' && (orEqual ? a <= b : a < b);
+  if (typeof a === 'string')
+    return typeof b === 'string' && (orEqual
+      ? compareCodePoints(a, b) <= 0
+      : compareCodePoints(a, b) < 0);
+  return false;
+}
+
 /**
  * Check if all items in an array are unique using deep equality
  * @param {any[]} arr - The array to check
@@ -213,6 +239,309 @@ export function isUniqueDeepArray(arr) {
   return true;
 }
 
+/**
+ * Deterministic JSON text for plain data: like `JSON.stringify`, but
+ * object keys are emitted in sorted order at every depth, so two
+ * structurally equal values always produce the same string (a stable
+ * cache/memo/fingerprint key regardless of key insertion order).
+ * Non-JSON values follow `JSON.stringify` semantics (undefined members
+ * are dropped, undefined roots return undefined).
+ *
+ * That leniency is what makes it a memo key and not an interchange
+ * format: dropping a member changes the document. For output that is
+ * hashed or signed, use `canonicalizeJson` (`@jarenjs/json/canonical`,
+ * RFC 8785), which rejects every non-JSON input instead of coercing it.
+ * @param {*} value - The value to serialize
+ * @returns {string|undefined} Deterministic JSON text
+ */
+export function stableStringify(value) {
+  if (value === null || typeof value !== 'object')
+    return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    let out = '[';
+    for (let i = 0; i < value.length; ++i)
+      out += (i === 0 ? '' : ',') + (stableStringify(value[i]) ?? 'null');
+    return out + ']';
+  }
+  const keys = Object.keys(value).sort();
+  let out = '{';
+  let first = true;
+  for (const key of keys) {
+    const sv = stableStringify(value[key]);
+    if (sv === undefined)
+      continue;
+    out += (first ? '' : ',') + JSON.stringify(key) + ':' + sv;
+    first = false;
+  }
+  return out + '}';
+}
+
+/**
+ * The suite's one MEMO-GRADE content key: `hashContent(stableStringify
+ * (value) ?? '')`. Two structurally equal plain-JSON values produce the
+ * same key regardless of property insertion order — which is exactly
+ * what a reconciliation key wants and exactly what `JSON.stringify`-based
+ * keys get wrong.
+ *
+ * **This is a 32-bit FINGERPRINT, never an identity.** Distinct values
+ * DO share a key — the birthday bound puts the first collision around
+ * 65k documents, and one turns up after ~113k trivially different query
+ * documents in practice. So it is sound for a vnode `key`, a DOM id, a
+ * bucket index or a diagnostic label, and WRONG as the sole identity of
+ * anything whose reuse changes a result: a compiled query, a query plan,
+ * a registered SQL function body, a memoized render. For those use
+ * {@link semanticKey}, which compares the whole serialization.
+ *
+ * Two further properties a caller must know, inherited from
+ * `stableStringify`: **`undefined` members are dropped** (two values
+ * differing only in an `undefined` member share a key) and there is
+ * **no cycle guard** (a cyclic value overflows the stack). Both are fine
+ * for a fingerprint and wrong for a checksum — for anything hashed,
+ * signed or recorded, use `canonicalizeJson`
+ * (`@jarenjs/json/canonical`, RFC 8785) instead. Do not conflate the
+ * three.
+ * @param {*} value - The value to derive a fingerprint for
+ * @returns {string} base-36 content hash of the stable serialization
+ */
+export function contentKey(value) {
+  return hashContent(stableStringify(value) ?? '');
+}
+
+/**
+ * The raw tokens {@link semanticKey} uses for the values JSON text cannot
+ * tell apart. Each is emitted UNQUOTED, which alone is enough that no
+ * string can forge one — `JSON.stringify` always puts quotes around a
+ * string. The leading NUL is belt and braces: `JSON.stringify` escapes it
+ * to `\u0000` inside a string, so a token cannot occur in serialized text
+ * at all.
+ *
+ * Written as `\u0000` escapes on purpose. The same character as a literal
+ * byte is invisible in every editor and diff and makes tooling treat the
+ * file as binary, so a test pins that it stays an escape.
+ */
+const SEMANTIC_TOKENS = {
+  undefined: '\u0000undef',
+  nan: '\u0000nan',
+  posInfinity: '\u0000+inf',
+  negInfinity: '\u0000-inf',
+  // -0 needs no sentinel: JSON text for the NUMBER -0 is `0`, so this
+  // two-character form is already unreachable as a number's key
+  negZero: '-0',
+};
+
+/**
+ * Serialize one node of a semantic key, or throw when the value cannot
+ * be keyed injectively.
+ * @param {*} value
+ * @param {string} path - JSON-Pointer-ish trail, for the error message
+ * @param {Set<object>} open - Ancestors on the current path (cycle guard)
+ * @returns {string}
+ */
+function semanticToken(value, path, open) {
+  const refuse = (what) => {
+    throw new TypeError(
+      `semanticKey: ${what} at ${path === '' ? 'the root' : path} cannot be a cache identity`);
+  };
+  if (value === null) return 'null';
+  switch (typeof value) {
+    case 'boolean': return value ? 'true' : 'false';
+    case 'string': return JSON.stringify(value);
+    case 'number':
+      if (Number.isNaN(value)) return SEMANTIC_TOKENS.nan;
+      if (value === Infinity) return SEMANTIC_TOKENS.posInfinity;
+      if (value === -Infinity) return SEMANTIC_TOKENS.negInfinity;
+      // -0 and 0 are one token in JSON text and two values to every
+      // arithmetic the engine performs (1/-0 is -Infinity)
+      return Object.is(value, -0) ? SEMANTIC_TOKENS.negZero : String(value);
+    case 'undefined': return SEMANTIC_TOKENS.undefined;
+    case 'bigint': return `\u0000big${value}`;
+    case 'function': return refuse('a function');
+    case 'symbol': return refuse('a symbol');
+    default: break;
+  }
+  const object = /** @type {object} */ (value);
+  if (open.has(object)) refuse('a cycle');
+  const proto = Object.getPrototypeOf(object);
+  // a symbol-keyed member is data the serialization cannot show, so two
+  // values differing only there would share an identity
+  if (Object.getOwnPropertySymbols(object).length > 0)
+    refuse('a symbol-keyed member');
+  open.add(object);
+  let out;
+  if (Array.isArray(object)) {
+    // a subclass carries behavior the key cannot see
+    if (proto !== Array.prototype) refuse('an Array subclass instance');
+    const items = /** @type {any[]} */ (object);
+    // an own property beyond the elements would vanish positionally
+    for (const key of Object.keys(items)) {
+      const index = Number(key);
+      if (!Number.isInteger(index) || index < 0 || index >= items.length)
+        refuse(`the extra array property ${JSON.stringify(key)}`);
+    }
+    out = '[';
+    for (let i = 0; i < items.length; i++)
+      out += (i === 0 ? '' : ',') + semanticToken(items[i], `${path}/${i}`, open);
+    out += ']';
+  }
+  else {
+    // Date, Map, Set, RegExp and every class instance stringify to `{}`
+    // through `Object.keys` — a whole family collapsing onto one key
+    if (proto !== Object.prototype && proto !== null)
+      refuse(`a ${object.constructor?.name ?? 'non-plain'} instance`);
+    const keys = Object.keys(object).sort(compareCodePoints);
+    out = '{';
+    for (let i = 0; i < keys.length; i++) {
+      const key = keys[i];
+      out += (i === 0 ? '' : ',') + JSON.stringify(key) + ':'
+        + semanticToken(/** @type {any} */ (object)[key], `${path}/${key}`, open);
+    }
+    out += '}';
+  }
+  open.delete(object);
+  return out;
+}
+
+/**
+ * The suite's one COLLISION-FREE semantic key: the COMPLETE
+ * deterministic serialization of a plain-data value. Two values share a
+ * key exactly when they are structurally equal, so a cache keyed by it
+ * can never serve one document's compiled semantics for another —
+ * which a hash-only key inevitably does (see {@link contentKey}).
+ *
+ * Use it wherever reuse changes a RESULT: compiled queries, query
+ * plans, load specifications, safe profiles, registered SQL function
+ * bodies, memoized renders. The key is longer than a fingerprint; for a
+ * bounded cache of a few hundred entries that cost is a few kilobytes
+ * and the alternative is wrong data.
+ *
+ * Injective over plain data, and STRICT about the rest: it distinguishes
+ * `-0` from `0`, `NaN`/`±Infinity` from `null` and from each other, and
+ * a present-but-`undefined` member from an absent one — every case
+ * `stableStringify` silently folds together. Values that cannot be
+ * keyed injectively are REFUSED with a `TypeError` rather than folded:
+ * functions, symbols, cycles, and non-plain objects (a `Date`, `Map`,
+ * `RegExp` or class instance, all of which serialize to `{}`), plus the
+ * two members a serialization cannot show — a symbol key, and an own
+ * array property past the last element. A caller that may hold such a
+ * value must treat the refusal as "not cacheable" and compute afresh —
+ * never as "reuse whatever shares the key".
+ *
+ * The identity covers OWN ENUMERABLE string-keyed properties, the same
+ * surface JSON reads. Two values differing only in a non-enumerable
+ * member are one value to this key, as they are to `JSON.stringify`.
+ * @param {*} value - The value to derive an identity for
+ * @returns {string} the complete deterministic serialization
+ * @throws {TypeError} When the value cannot be keyed injectively
+ */
+export function semanticKey(value) {
+  return semanticToken(value, '', new Set());
+}
+
+/**
+ * True for a JSON object — a non-null object that is not an array.
+ *
+ * This is the JSON data-model predicate, deliberately distinct from
+ * `isObjectType`: it treats `Map`, `Set`, `Date` and every other class
+ * instance as an object too, because at the JSON layer such a value has
+ * already been rejected or serialized before it gets here, and the only
+ * distinction that matters is object-vs-array.
+ *
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isJsonObject(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Assign a member so that a key named `__proto__` becomes an own data
+ * property instead of reassigning the object's prototype. Every builder
+ * that turns untrusted names into members must go through this — a plain
+ * `out[name] = value` is a prototype-pollution hole for that one name.
+ *
+ * @param {Object} out target object
+ * @param {string} name member name, possibly attacker-controlled
+ * @param {any} value
+ */
+export function setObjectMember(out, name, value) {
+  if (name === '__proto__') {
+    Object.defineProperty(out, name, {
+      value,
+      enumerable: true,
+      configurable: true,
+      writable: true,
+    });
+  }
+  else {
+    out[name] = value;
+  }
+}
+
+/**
+ * Whether a value can hold JSON members: an object or an array, not null.
+ * The complement of a JSON scalar.
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isJsonContainer(value) {
+  return typeof value === 'object' && value !== null;
+}
+
+/**
+ * Copy one JSON container one level deep, preserving member order. Object
+ * spread copies an own `__proto__` data property as an own property
+ * (CreateDataProperty semantics), so this is pollution-safe.
+ * @template T
+ * @param {T} value - The container to copy
+ * @returns {T} A shallow copy; scalars are returned unchanged
+ */
+export function shallowCloneJson(value) {
+  return Array.isArray(value) ? value.slice() : { ...value };
+}
+
+/**
+ * Deep-copy a JSON value. Scalars are returned as-is; containers are
+ * rebuilt so no part of the result is shared with the input.
+ * @template T
+ * @param {T} value - The JSON value to copy
+ * @returns {T} A deep copy sharing no container with the input
+ */
+export function cloneJson(value) {
+  if (!isJsonContainer(value))
+    return value;
+  if (Array.isArray(value)) {
+    const len = value.length;
+    const out = new Array(len);
+    for (let i = 0; i < len; i++)
+      out[i] = cloneJson(value[i]);
+    return out;
+  }
+  const out = {};
+  for (const key in value) {
+    if (Object.hasOwn(value, key))
+      setObjectMember(out, key, cloneJson(value[key]));
+  }
+  return out;
+}
+
+/**
+ * Recursively `Object.freeze` a value and everything reachable from it,
+ * returning the value. Scalars pass through untouched. Assumes an acyclic
+ * structure (a JSON value); a cycle would recurse forever.
+ *
+ * @template T
+ * @param {T} value
+ * @returns {T} the same value, deeply frozen
+ */
+export function deepFreeze(value) {
+  if (typeof value !== 'object' || value === null)
+    return value;
+  const keys = Object.keys(value);
+  for (let i = 0; i < keys.length; i++)
+    deepFreeze(value[keys[i]]);
+  return Object.freeze(value);
+}
+
 /**
  *
  * @param {Map<any, any>} map

package/src/scan.js

@@ -21,6 +21,7 @@ export const CC_SQUOTE = 0x27;
 export const CC_LPAREN = 0x28;
 export const CC_RPAREN = 0x29;
 export const CC_STAR = 0x2A;
+export const CC_PLUS = 0x2B;
 export const CC_COMMA = 0x2C;
 export const CC_MINUS = 0x2D;
 export const CC_DOT = 0x2E;
@@ -38,8 +39,14 @@ export const CC_LBRACKET = 0x5B;
 export const CC_BACKSLASH = 0x5C;
 export const CC_RBRACKET = 0x5D;
 export const CC_UNDERSCORE = 0x5F;
+export const CC_LOWER_B = 0x62;
+export const CC_LOWER_O = 0x6F;
+export const CC_LOWER_X = 0x78;
+export const CC_LBRACE = 0x7B;
 export const CC_PIPE = 0x7C;
+export const CC_RBRACE = 0x7D;
 export const CC_TILDE = 0x7E;
+export const CC_DEL = 0x7F;
 
 //#endregion
 
@@ -65,6 +72,32 @@ export function isHexDigitCode(c) {
     || (c >= 0x61 && c <= 0x66); // a-f
 }
 
+/**
+ * Checks if a char code may start an unquoted name: an ASCII letter,
+ * `_`, or any non-ASCII code unit. Non-ASCII is admitted wholesale rather
+ * than by Unicode category, which is what the RFC 9535 shorthand member
+ * name and the XML Name productions both settle for in practice.
+ * @param {number} c - The char code
+ * @returns {boolean}
+ */
+export function isNameStartCode(c) {
+  return (c >= 0x41 && c <= 0x5A) // A-Z
+    || (c >= 0x61 && c <= 0x7A) // a-z
+    || c === CC_UNDERSCORE
+    || c >= 0x80; // any non-ASCII code unit
+}
+
+/**
+ * Checks if a char code may continue an unquoted name: a name start or an
+ * ASCII digit. Grammars that also admit `-`/`.` inside names (XML Name,
+ * for one) test those separately on top of this.
+ * @param {number} c - The char code
+ * @returns {boolean}
+ */
+export function isNameCharCode(c) {
+  return isNameStartCode(c) || isDigitCode(c);
+}
+
 /**
  * Checks if a char code is blank space per RFC 9535 (space, tab,
  * line feed or carriage return).
@@ -93,4 +126,13 @@ export function isAsciiUpperCode(c) {
   return c >= 0x41 && c <= 0x5A;
 }
 
+/**
+ * Checks if a char code is an ASCII letter (A-Z or a-z).
+ * @param {number} c - The char code
+ * @returns {boolean}
+ */
+export function isAsciiLetterCode(c) {
+  return isAsciiUpperCode(c) || isAsciiLowerCode(c);
+}
+
 //#endregion

package/src/schema.js

@@ -0,0 +1,37 @@
+//@ts-check
+/**
+ * @file The JSON Schema constraint-keyword vocabulary, grouped by the
+ * value family each keyword constrains. Before this file the same
+ * keyword lists were spelled four times (forms' constraint extraction,
+ * emit's dropped-constraint table, the validator's `$data` dispatch
+ * order and its `$ref`-sibling detection) — and a keyword added to one
+ * list silently missed the others. Each site composes the list it wants
+ * from these groups and appends its own extras; the loops stay where
+ * they are, because the drift risk was always in the data, not the
+ * code.
+ *
+ * ORDER IS PART OF THE CONTRACT: the validator's `$data` dispatch
+ * applies keywords in list order and its error order is observable
+ * behaviour, so the internal order of each group is fixed. Membership
+ * consumers are order-insensitive by construction.
+ */
+
+/** Keywords constraining numeric values, in dispatch order. */
+export const NUMERIC_CONSTRAINTS = Object.freeze([
+  'minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf',
+]);
+
+/** Keywords constraining string values, in dispatch order. */
+export const STRING_CONSTRAINTS = Object.freeze([
+  'minLength', 'maxLength', 'pattern', 'format',
+]);
+
+/** Keywords constraining array values, in dispatch order. */
+export const ARRAY_CONSTRAINTS = Object.freeze([
+  'minItems', 'maxItems', 'uniqueItems',
+]);
+
+/** Keywords constraining object values, in dispatch order. */
+export const OBJECT_CONSTRAINTS = Object.freeze([
+  'minProperties', 'maxProperties',
+]);