@jarenjs/core 0.72.0 → 0.72.3

package/ARCHITECTURE.md

@@ -83,7 +83,7 @@ flowchart TB
             Integer["integer.js<br/>Int8/16/32/64 validation"]
             Float["float.js<br/>Float16/32/64 validation"]
             BigIntModule["bigint.js<br/>BigInt utilities"]
-            NumberModule["number.js<br/>Number coercion"]
+            NumberModule["number.js<br/>Coercion and JSON number grammar"]
         end
 
         subgraph CollectionModules["Collection Modules"]
@@ -445,6 +445,7 @@ flowchart TB
         RegExpUtils --> IsRegExp["isRegExpType()"]
         RegExpUtils --> IsStringRegExp["isStringRegExp()<br/>(tests if valid pattern)"]
         RegExpUtils --> CreateRegExp["createRegExp()<br/>(handles /pattern/flags syntax)"]
+        RegExpUtils --> TestRegExp["createRegExpTester()<br/>(repeatable, isolated global/sticky state)"]
 
         Unicode["Unicode Support"]
         Unicode --> Ascii["isAsciiString()"]

package/README.md

@@ -11,8 +11,8 @@ None of it depends on JSON Schema: every module can be used standalone in any Ja
 | `@jarenjs/core` | type guards and getters (`isStringType`, `isObjectClass`, `getIntegerType`, ...) |
 | `@jarenjs/core/array` | array helpers (`isUniqueArray`, `getUniqueArray`, `includesAll`, ...) |
 | `@jarenjs/core/object` | deep equality (`equalsDeep`, JSON-only `equalsJson`), the `isJsonObject` and deep `isJsonValue` predicates, `__proto__`-safe `setObjectMember`, `deepFreeze`, map/set merging |
-| `@jarenjs/core/string` | Unicode string helpers (`countCodePoints`, `compareCodePoints`, ...), cached regex compilation, the suite's one content hash (`fnv1a` and the `hashContent` fingerprint over it) and `kebabCase` |
-| `@jarenjs/core/cache` | the bounded LRU (`createBoundedCache`), the reference-keyed `createWeakCache`, and `createSemanticCache` — keyed by what a value IS, for caches whose entries decide a result |
+| `@jarenjs/core/string` | Unicode string helpers (`countCodePoints`, `compareCodePoints`, ...), regex compilation and repeatable `createRegExpTester` predicates, the suite's one content hash (`fnv1a` and the `hashContent` fingerprint over it) and `kebabCase` |
+| `@jarenjs/core/cache` | the bounded LRU with key deletion (`createBoundedCache`), the reference-keyed `createWeakCache`, and `createSemanticCache` — keyed by what a value IS, for caches whose entries decide a result |
 | `@jarenjs/core/random` | the suite's one seeded generator (`mulberry32`, pinned sequence, ToUint32 seed) and the draws built on it: `randomInt` over a half-open range, in-place Fisher–Yates `shuffle`, and `drawDistinct` — `k` distinct indices from one stream |
 | `@jarenjs/core/runtime` | the runtime record — `createRuntime({ now, uuid, random, zoneProvider })`, frozen, defaulting member for member to the platform's own (`Date.now`, `crypto.randomUUID`, `Math.random`, no zone provider) — that the store (its query deadlines included), the jobs engine, the migration runner, every contract binding and the contract memory ledger take as `runtime`, so a deterministic run is configured once; a subsystem's own explicit option wins over the record, and the record reaches hosts, never query compilation |
 | `@jarenjs/core/stats` | descriptive statistics over a sample: `mean`, sample `variance`/`stddev`, the midpoint `median`, and `quantile(values, p, { method })` — `p` on 0..1 under a NAMED rule, `'nearest-rank'` or `'linear'`, because a default would decide silently; an empty sample answers `undefined`, never `0` |
@@ -21,7 +21,7 @@ None of it depends on JSON Schema: every module can be used standalone in any Ja
 | `@jarenjs/core/scan` | char-code constants and predicates for recursive-descent parsers |
 | `@jarenjs/core/message` | the message template/catalog compiler shared by the validator and the form layer |
 | `@jarenjs/core/color` | pure color math (`lerpColor` — hex `#rrggbb` interpolation) |
-| `@jarenjs/core/number` | boolean/number/integer coercion helpers (`isIntishType`, ...) |
+| `@jarenjs/core/number` | boolean/number/integer coercion helpers (`isIntishType`, ...) and `isJsonNumberString`, the strict lexical JSON-number predicate shared by query casts and schema normalization; conversion and overflow policy stay with each caller |
 | `@jarenjs/core/integer` | `int8` ... `uint64` ranges and validators |
 | `@jarenjs/core/float` | `float16` ... `float64` constants, validators, increment/decrement |
 | `@jarenjs/core/bigint` | bigint helpers (`BigInt_min`, `BigInt_MinMax`, ...) |
@@ -41,14 +41,16 @@ Deep imports work too (`@jarenjs/core/text/email`, `@jarenjs/core/math/vec2f64`,
 `@jarenjs/core/string` counts string length the way JSON Schema expects — by grapheme cluster, not UTF-16 code units — without paying for `Intl.Segmenter` unless the string actually needs it:
 
 ```javascript
-import { getStringLength, isAsciiString, createRegExp } from '@jarenjs/core/string';
+import { getStringLength, isAsciiString, createRegExp, createRegExpTester } from '@jarenjs/core/string';
 
 getStringLength('hello', true);       // 5  (ASCII fast path: str.length)
 getStringLength('héllo', true);       // 5  (surrogate-aware code point count)
 getStringLength('👨‍👩‍👧‍👦', true); // 1  (grapheme segmentation, only when clusters can form)
 getStringLength('👨‍👩‍👧‍👦');       // 11 (default: plain UTF-16 length)
 
-createRegExp('^\\p{L}+$');            // cached, unicode-flagged RegExp
+createRegExp('^\\p{L}+$');            // unicode-flagged RegExp
+const matches = createRegExpTester('/^x/gi');
+matches('X'); matches('X');          // true both times; global/sticky state is isolated
 ```
 
 ## Text validation
@@ -88,7 +90,7 @@ orient2d(0, 0, 1, 0, 0, 1);                    // > 0 — counter-clockwise, exa
 haversineDistance(4.9041, 52.3676, 2.3522, 48.8566); // 429_862 m (Amsterdam–Paris)
 ringWinding([[0,0],[1,0],[1,1],[0,1],[0,0]]);  // 1 — an RFC 7946 exterior ring
 bboxOf({ type: 'Polygon', coordinates: [[[4,52],[5,52],[5,53],[4,52]]] }); // [4, 52, 5, 53]
-geohashEncode(4.9041, 52.3676, 5);             // 'u173z' — a string, so a prefix test is proximity
+geohashEncode(4.9041, 52.3676, 5);             // 'u173z' — a string identifying a cell; use distances for proximity
 
 wktToGeoJson('POINT (4.9041 52.3676)');        // { type: 'Point', coordinates: [4.9041, 52.3676] }
 geoJsonToWkt({ type: 'Point', coordinates: [4.9041, 52.3676] }); // 'POINT (4.9041 52.3676)'

package/dist/types/cache.d.ts

@@ -1,18 +1,13 @@
 /**
- * @file The suite's one bounded-cache primitive. Before this file the
- * FIFO-512 delete-oldest map was written five times (the query engine's
- * string cache, the JSONPath query cache, forms' three pointer caches)
- * with a sixth divergent flush-all variant in forms' regex cache and a
- * true LRU in the view projection memo. One implementation, one policy:
+ * @file The suite's bounded-cache primitive for compiled queries,
+ * pointers, regular expressions and view projections. One eviction policy
+ * keeps each consumer's retained working set bounded:
  *
  *  - **LRU with recency refresh**: a `get` hit re-inserts the entry, so
  *    the evicted entry is the least recently USED, not the oldest
- *    inserted. (FIFO versus LRU was never result-observable at any call
- *    site — both bound memory; LRU keeps hot entries hotter.)
+ *    inserted.
  *  - **Evict at `size >= limit` before inserting a new key**, so the
- *    cache never holds more than `limit` entries. (The old sites
- *    disagreed between `>=`-before and `>`-after; the capacity is the
- *    same, the invariant here is simply "never above `limit`".)
+ *    cache never holds more than `limit` entries for a positive integer limit.
  *  - `undefined` is the miss sentinel: a cache MUST NOT store
  *    `undefined` as a value (store `null` for "computed, negative" —
  *    the regex cache does exactly that).
@@ -44,6 +39,11 @@ export type BoundedCache<K, V> = {
      * or compute-and-insert in one step.
      */
     getOrCreate: (key: K, create: (key: K) => V) => V;
+    /**
+     * - Drop one entry; true when the
+     * key existed, including an entry whose value was undefined.
+     */
+    delete: (key: K) => boolean;
     /**
      * - Drop every entry.
      */
@@ -62,6 +62,8 @@ export type BoundedCache<K, V> = {
  *   the least recently used entry when the cache is full.
  * @property {(key: K, create: (key: K) => V) => V} getOrCreate - Lookup
  *   or compute-and-insert in one step.
+ * @property {(key: K) => boolean} delete - Drop one entry; true when the
+ *   key existed, including an entry whose value was undefined.
  * @property {() => void} clear - Drop every entry.
  * @property {() => number} size - Current entry count.
  */

package/dist/types/number.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Whether a string is exactly one JSON number (RFC 8259 section 6), with
+ * no surrounding whitespace. This checks spelling only: `1e999` is valid
+ * even though converting it to a JavaScript number overflows. Callers
+ * choose their own conversion, finiteness and safe-integer policies.
+ * @param {unknown} value - The value to check, without coercion
+ * @returns {boolean} True for a string matching the complete number grammar
+ */
+export declare function isJsonNumberString(value: unknown): boolean;
 /**
  * Checks if the given data is of boolean type or boolean-like (the strings 'true' or 'false').
  * @param {any} data - The data to check.

package/dist/types/runtime.d.ts

@@ -1,16 +1,13 @@
 /**
- * @file The runtime record: the host facts every subsystem that needs
- * one used to take separately — the clock, secure identifiers,
- * randomness and the zone provider — as one frozen record a host builds
+ * @file The runtime record: the clock, secure identifiers, randomness
+ * and the zone provider as one frozen record a host builds
  * once and hands to the store, the jobs engine, the migration runner and
  * the http binding. Nothing here IS a clock, a random source or a zone
  * database: the defaults are the platform's own (`Date.now`,
- * `crypto.randomUUID`, `Math.random`, and no zone provider, which keeps
- * a named zone the refusal it always was), so adopting the record changes
- * nothing a consumer can observe. What it buys is that a deterministic
- * run — a fixed clock, a seeded generator, a counting identifier — is
- * configured in one place, and that four subsystems can no longer
- * disagree about what time it is.
+ * `crypto.randomUUID`, `Math.random`, and no zone provider). Named zones
+ * require an injected provider. A deterministic run — a fixed clock,
+ * a seeded generator, a counting identifier — is configured in one place
+ * so the subsystems agree about time and identity.
  *
  * Precedence is fixed: a subsystem's own explicit option wins over the
  * record's member, which wins over the built-in default. The options are

package/dist/types/schema.d.ts

@@ -1,13 +1,10 @@
 /**
  * @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.
+ * value family each keyword constrains. Forms' constraint extraction,
+ * emit's dropped-constraint table and the validator's dispatch and
+ * `$ref`-sibling detection compose their lists from these shared groups
+ * and append their own extras. Consumers own their processing loops;
+ * the shared vocabulary keeps keyword membership consistent.
  *
  * ORDER IS PART OF THE CONTRACT: the validator's `$data` dispatch
  * applies keywords in list order and its error order is observable

package/dist/types/string.d.ts

@@ -33,6 +33,13 @@ export declare function isStringRegExp(data: string | RegExp | null | undefined)
  * @returns {RegExp | undefined}
  */
 export declare function createRegExp(pattern: string | RegExp | null | undefined): RegExp | undefined;
+/**
+ * Compile a pattern into a repeatable predicate. Global and sticky patterns
+ * start at index zero on every call and never change a caller's RegExp state.
+ * @param {string | RegExp | null | undefined} pattern - The regular expression
+ * @returns {((value: string) => boolean) | undefined} The tester, or undefined when no pattern was supplied
+ */
+export declare function createRegExpTester(pattern: string | RegExp | null | undefined): ((value: string) => boolean) | undefined;
 export declare function getSegmenter(): Intl.Segmenter;
 /**
  * @param {string} str

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/core",
   "private": false,
-  "version": "0.72.0",
+  "version": "0.72.3",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",

package/src/cache.js

@@ -1,19 +1,14 @@
 //@ts-check
 /**
- * @file The suite's one bounded-cache primitive. Before this file the
- * FIFO-512 delete-oldest map was written five times (the query engine's
- * string cache, the JSONPath query cache, forms' three pointer caches)
- * with a sixth divergent flush-all variant in forms' regex cache and a
- * true LRU in the view projection memo. One implementation, one policy:
+ * @file The suite's bounded-cache primitive for compiled queries,
+ * pointers, regular expressions and view projections. One eviction policy
+ * keeps each consumer's retained working set bounded:
  *
  *  - **LRU with recency refresh**: a `get` hit re-inserts the entry, so
  *    the evicted entry is the least recently USED, not the oldest
- *    inserted. (FIFO versus LRU was never result-observable at any call
- *    site — both bound memory; LRU keeps hot entries hotter.)
+ *    inserted.
  *  - **Evict at `size >= limit` before inserting a new key**, so the
- *    cache never holds more than `limit` entries. (The old sites
- *    disagreed between `>=`-before and `>`-after; the capacity is the
- *    same, the invariant here is simply "never above `limit`".)
+ *    cache never holds more than `limit` entries for a positive integer limit.
  *  - `undefined` is the miss sentinel: a cache MUST NOT store
  *    `undefined` as a value (store `null` for "computed, negative" —
  *    the regex cache does exactly that).
@@ -41,6 +36,8 @@ import { semanticKey } from './object.js';
  *   the least recently used entry when the cache is full.
  * @property {(key: K, create: (key: K) => V) => V} getOrCreate - Lookup
  *   or compute-and-insert in one step.
+ * @property {(key: K) => boolean} delete - Drop one entry; true when the
+ *   key existed, including an entry whose value was undefined.
  * @property {() => void} clear - Drop every entry.
  * @property {() => number} size - Current entry count.
  */
@@ -84,7 +81,8 @@ export function createBoundedCache(limit) {
     return value;
   }
 
-  return { get, set, getOrCreate, clear: () => map.clear(), size: () => map.size };
+  return { get, set, getOrCreate, delete: (key) => map.delete(key),
+    clear: () => map.clear(), size: () => map.size };
 }
 
 /**

package/src/number.js

@@ -1,5 +1,19 @@
 //@ts-check
 
+const JSON_NUMBER_RE = /^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$/;
+
+/**
+ * Whether a string is exactly one JSON number (RFC 8259 section 6), with
+ * no surrounding whitespace. This checks spelling only: `1e999` is valid
+ * even though converting it to a JavaScript number overflows. Callers
+ * choose their own conversion, finiteness and safe-integer policies.
+ * @param {unknown} value - The value to check, without coercion
+ * @returns {boolean} True for a string matching the complete number grammar
+ */
+export function isJsonNumberString(value) {
+  return typeof value === 'string' && JSON_NUMBER_RE.test(value);
+}
+
 /**
  * Checks if the given data is of boolean type or boolean-like (the strings 'true' or 'false').
  * @param {any} data - The data to check.

package/src/runtime.js

@@ -1,17 +1,14 @@
 //@ts-check
 /**
- * @file The runtime record: the host facts every subsystem that needs
- * one used to take separately — the clock, secure identifiers,
- * randomness and the zone provider — as one frozen record a host builds
+ * @file The runtime record: the clock, secure identifiers, randomness
+ * and the zone provider as one frozen record a host builds
  * once and hands to the store, the jobs engine, the migration runner and
  * the http binding. Nothing here IS a clock, a random source or a zone
  * database: the defaults are the platform's own (`Date.now`,
- * `crypto.randomUUID`, `Math.random`, and no zone provider, which keeps
- * a named zone the refusal it always was), so adopting the record changes
- * nothing a consumer can observe. What it buys is that a deterministic
- * run — a fixed clock, a seeded generator, a counting identifier — is
- * configured in one place, and that four subsystems can no longer
- * disagree about what time it is.
+ * `crypto.randomUUID`, `Math.random`, and no zone provider). Named zones
+ * require an injected provider. A deterministic run — a fixed clock,
+ * a seeded generator, a counting identifier — is configured in one place
+ * so the subsystems agree about time and identity.
  *
  * Precedence is fixed: a subsystem's own explicit option wins over the
  * record's member, which wins over the built-in default. The options are

package/src/schema.js

@@ -1,14 +1,11 @@
 //@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.
+ * value family each keyword constrains. Forms' constraint extraction,
+ * emit's dropped-constraint table and the validator's dispatch and
+ * `$ref`-sibling detection compose their lists from these shared groups
+ * and append their own extras. Consumers own their processing loops;
+ * the shared vocabulary keeps keyword membership consistent.
  *
  * ORDER IS PART OF THE CONTRACT: the validator's `$data` dispatch
  * applies keywords in list order and its error order is observable

package/src/string.js

@@ -88,6 +88,24 @@ export function createRegExp(pattern) {
   throw new Error(`Unknown Regular Expression Pattern Type: ${pattern}`);
 }
 
+/**
+ * Compile a pattern into a repeatable predicate. Global and sticky patterns
+ * start at index zero on every call and never change a caller's RegExp state.
+ * @param {string | RegExp | null | undefined} pattern - The regular expression
+ * @returns {((value: string) => boolean) | undefined} The tester, or undefined when no pattern was supplied
+ */
+export function createRegExpTester(pattern) {
+  const parsed = createRegExp(pattern);
+  if (parsed === undefined) return undefined;
+  if (!parsed.global && !parsed.sticky)
+    return (value) => parsed.test(value);
+  const owned = new RegExp(parsed.source, parsed.flags);
+  return (value) => {
+    owned.lastIndex = 0;
+    return owned.test(value);
+  };
+}
+
 /**
  * @type {Intl.Segmenter | null}
  */