@jarenjs/core 0.72.2 → 0.73.0

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"]

package/README.md

@@ -12,7 +12,7 @@ None of it depends on JSON Schema: every module can be used standalone in any Ja
 | `@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`, ...), 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 (`createBoundedCache`), the reference-keyed `createWeakCache`, and `createSemanticCache` — keyed by what a value IS, for caches whose entries decide a result |
+| `@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`, ...) |

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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/core",
   "private": false,
-  "version": "0.72.2",
+  "version": "0.73.0",
   "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