@jarenjs/core 0.9.2 → 0.34.0

package/ARCHITECTURE.md

@@ -95,38 +95,70 @@ flowchart TB
             TextIndex["text/index.js"]
             Basic["basic.js<br/>Alpha, numeric, hex"]
             Email["email.js<br/>Email validation"]
-            Host["host.js<br/>URL, IP, hostname"]
+            Host["host.js<br/>URL, IP, hostname, URI/IRI"]
             Identifiers["identifiers.js<br/>UUID, GUID"]
             Base64["base64.js<br/>Base64 validation"]
-            Punycode["punycode.js<br/>IDN encoding"]
+            Punycode["punycode.js<br/>Punycode codec + IDNA"]
             I18n["i18n.js<br/>Unicode category checks"]
+            IRegexp["iregexp.js<br/>I-Regexp (RFC 9485)"]
+            TextMisc["misc.js<br/>Assorted text testers"]
         end
 
         subgraph DateModule["Date Processing"]
-            Dates["dates.js<br/>RFC 3339 / ISO 8601"]
+            DatesIndex["dates/index.js"]
+            DatesRfc["rfc3339.js<br/>RFC 3339 / ISO 8601"]
+            DatesCivil["civil.js<br/>Gregorian day-number math"]
+            DatesFormat["format.js<br/>LDML pattern compiler"]
+            DatesDuration["duration.js<br/>ISO 8601 durations"]
+        end
+
+        subgraph GeoModule["Spatial"]
+            GeoIndex["geo/index.js"]
+            GeoPred["predicates.js<br/>Robust orientation"]
+            GeoDist["distance.js<br/>Great-circle measurement"]
+            GeoRing["ring.js<br/>Closure, winding, area, containment"]
+            GeoBbox["bbox.js<br/>Bounding boxes"]
+            GeoHash["geohash.js<br/>Base-32 cells"]
+            GeoJson["geojson.js<br/>Typed-geometry traversal"]
+            GeoValid["valid.js + wkt.js<br/>Validity testers"]
+            GeoTree["index-tree.js<br/>Packed-Hilbert box index"]
+            GeoMerc["mercator.js + simplify.js<br/>Projection out, simplification"]
         end
 
         subgraph MathModules["Mathematics"]
             MathIndex["math/index.js"]
             Int32Math["int32.js<br/>Fixed-point math"]
-            Float64Math["float64.js<br/>Float64 utilities"]
+            Float64Math["float64.js<br/>Float64 utilities, remap, clamp01"]
             Vec2I32["vec2i32.js<br/>2D integer vectors"]
             Vec2F64["vec2f64.js<br/>2D float vectors"]
             Vec3F64["vec3f64.js<br/>3D float vectors"]
+            Mat4Math["mat4.js<br/>4x4 matrices"]
+            ProjectMath["project.js<br/>3D to 2D projection"]
+            SolveMath["solve.js<br/>Numeric root finders"]
+            WordMath["word.js<br/>BigInt fixed-width words"]
+            FormatMath["format.js<br/>Number format/parse"]
+        end
+
+        subgraph DomainModules["Domain Kernels"]
+            ConvertIndex["convert/index.js<br/>Unit and currency conversion"]
+            FinanceIndex["finance/index.js<br/>TVM, bonds, cash flow, returns"]
         end
 
         subgraph FunctionModule["Function Utilities"]
             FunctionUtil["function.js<br/>trueThat, falseThat"]
         end
 
-        subgraph StringModule["String Utilities"]
-            StringUtil["string.js<br/>RegExp, grapheme counting"]
+        subgraph StringModules["String &amp; Scanning"]
+            StringUtil["string.js<br/>RegExp, grapheme counting, fnv1a"]
+            ScanUtil["scan.js<br/>Char-code classes for parsers"]
+            MessageUtil["message.js<br/>Message template/catalog compiler"]
+            ColorUtil["color.js<br/>Mixing, relative luminance"]
         end
     end
 
     CoreModule --> ScalarModules
     CoreModule --> CollectionModules
-    CoreModule --> StringModule
+    CoreModule --> StringModules
     CoreModule --> FunctionModule
 
     TextIndex --> Basic
@@ -136,18 +168,41 @@ flowchart TB
     TextIndex --> Base64
     TextIndex --> Punycode
     TextIndex --> I18n
+    TextIndex --> IRegexp
+    TextIndex --> TextMisc
 
     MathIndex --> Int32Math
     MathIndex --> Float64Math
     MathIndex --> Vec2I32
     MathIndex --> Vec2F64
     MathIndex --> Vec3F64
+    MathIndex --> Mat4Math
+    MathIndex --> ProjectMath
+    MathIndex --> SolveMath
+    MathIndex --> WordMath
+    MathIndex --> FormatMath
+
+    DatesIndex --> DatesRfc
+    DatesIndex --> DatesCivil
+    DatesIndex --> DatesFormat
+    DatesIndex --> DatesDuration
+
+    GeoIndex --> GeoPred
+    GeoIndex --> GeoDist
+    GeoIndex --> GeoRing
+    GeoIndex --> GeoBbox
+    GeoIndex --> GeoHash
+    GeoIndex --> GeoJson
+    GeoIndex --> GeoValid
+    GeoIndex --> GeoTree
+    GeoIndex --> GeoMerc
 
     style CorePackage fill:#e1f5fe
     style CoreModule fill:#bbdefb
     style TextModules fill:#c8e6c9
     style MathModules fill:#ffccbc
     style DateModule fill:#fff9c4
+    style GeoModule fill:#b2dfdb
 ```
 
 ---
@@ -206,7 +261,7 @@ flowchart TB
 | `@jarenjs/refs` | None | Schema reference data |
 | `jarenjs` (root) | All packages | Public API aggregation |
 
-> **Note:** For broader Jaren architecture, see the root [`ARCHITECTURE.md`](../../ARCHITECTURE.md). For development guides, see [`HOWTO.md`](../../HOWTO.md).
+> **Note:** For broader Jaren architecture, see the root [`ARCHITECTURE.md`](../../docs/ARCHITECTURE.md). For development guides, see [`HOWTO.md`](../../docs/HOWTO.md).
 
 ---
 
@@ -383,9 +438,41 @@ getStringLength("👨‍👩‍👧‍👦", false); // 11 (code units)
 getStringLength("👨‍👩‍👧‍👦", true);  // 1 (grapheme cluster)
 ```
 
-### 5. Date Module (`dates.js`)
-
-RFC 3339 and ISO 8601 compliant date/time parsing.
+### 5. Date Module (`dates/`)
+
+RFC 3339 and ISO 8601 validation, plus the suite's calendar kernel.
+
+**Dates are not a type here.** They are the two forms JSON already has — an
+RFC 3339 **string** (lexical, what documents, schemas, forms and TOML
+contain) and **epoch milliseconds** (arithmetic, what a chart plots). A
+wrapper object, even an immutable one, could not be a query-engine item, a
+JSON Patch target or part of app state; it is why `canonicalizeJson` turns a
+`Date` into `{}`. The parts record from `parseRFC3339Parts` is the working
+intermediate and is plain data, never an opaque handle.
+
+| Module | Owns |
+|---|---|
+| `rfc3339.js` | validation, lexical decomposition, epoch conversion |
+| `civil.js` | proleptic Gregorian arithmetic over integers |
+| `format.js` | LDML pattern → compiled formatter |
+| `duration.js` | ISO 8601 duration decomposition and date arithmetic |
+
+Calendar math goes through day numbers (`daysFromCivil`/`civilFromDays`),
+never through `Date`: the conversions are ~10 integer operations and allocate
+nothing, where an allocate-mutate-read `Date` round trip costs about 165× as
+much for the same answer. For the same reason every `getDateTypeOf*` getter
+has a `getEpochOf*` twin — the same validity check and the same engine parse,
+returning epoch milliseconds instead of a `Date` — so a consumer comparing
+against precomputed bounds (the `formatMinimum`/`formatMaximum` validators)
+allocates nothing per value. Formatting is the two-stage compiler again — a
+pattern is scanned once into a chain of appenders, which measured ~4.5×
+against re-scanning it per call.
+
+Locale-dependent presentation (month and weekday names, meridiem, relative
+phrasing) is deliberately **not** here, so this package stays zero-dependency
+and free of data that drifts per language: `compileDateFormat` takes a names
+provider, and a pattern using `MMMM`/`EEEE`/`a` without one is a compile
+error rather than a silent English fallback.
 
 ```mermaid
 flowchart TB
@@ -425,11 +512,130 @@ import {
   CONST_TICKS_HOUR,      // 3600000
   CONST_TICKS_DAY,       // 86400000
   CONST_RFC3339_DAYS,    // Days per month array
-  CONST_RFC3339_REGEX_ISDATE,  // Date regex
-  CONST_RFC3339_REGEX_ISTIME,  // Time regex
 } from '@jarenjs/core/dates';
 ```
 
+**Working with the calendar:**
+
+```javascript
+import {
+  parseRFC3339Parts, addToParts, startOfParts, compileDateFormat,
+} from '@jarenjs/core/dates';
+
+const parts = parseRFC3339Parts('2026-01-31');
+addToParts(parts, 1, 'month');          // 2026-02-28 — month math clamps
+startOfParts(parts, 'week');            // the Monday of that week (ISO 8601)
+
+const fmt = compileDateFormat("yyyy-'W'ww");  // compile once…
+fmt(parts);                             // …call many: '2026-W05'
+```
+
+### 5b. Geo Module (`geo/`)
+
+The spatial kernel. As with dates, **there is no geometry type**: the
+representation is GeoJSON ([RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946)),
+whose positions are `[longitude, latitude]` arrays and whose rings are arrays
+of those. They are already JSON items, so they stay patchable, schema-checkable
+and addressable; a wrapper class would break all three. Every function here
+takes plain numbers and plain arrays, so a `Polygon`'s `coordinates` can be
+passed straight in without the `type` discriminator being involved.
+
+| Module | Owns |
+|---|---|
+| `predicates.js` | robust orientation — the sign every spatial test rests on |
+| `distance.js` | great-circle measurement on the WGS 84 sphere |
+| `ring.js` | ring closure, winding, area and containment |
+| `bbox.js` | bounding boxes, the cheap half of every spatial test |
+| `geohash.js` | the base-32 cell encoding, and its validity tester |
+| `geojson.js` | the one layer that knows the `type` discriminator |
+| `valid.js` | `isValidGeoJson` — the one-call structural judgment (rings must close), the boolean twin of the schema artifacts in `@jarenjs/json` |
+| `wkt.js` | `isValidWkt` — a strict validity tester for Well-Known Text |
+| `index-tree.js` | a static packed-Hilbert box index for spatial joins |
+| `mercator.js` | Web Mercator, the projection *out* for anything that draws |
+| `simplify.js` | Douglas-Peucker — dropping the vertices a drawing cannot show |
+
+The three validity testers back the `geoFormats` group in
+[`@jarenjs/formats`](../formats) (`geohash`, `wkt`, `geojson`).
+
+Two decisions carry the module. **Orientation is computed exactly**, through
+Shewchuk's adaptive precision arithmetic: a naive floating-point determinant
+returns the *wrong sign* on near-collinear input, which makes a containment
+test contradict itself and a clipper emit self-intersecting output. The test
+suite pins real longitude/latitude fixtures on the San Francisco–Los Angeles
+line where the naive form reports "collinear" and the truth is one side or the
+other. The cheap filter runs first, so the exact path costs nothing until it is
+needed.
+
+**Distance is spherical, and the planar shortcut is refused.** A degree of
+longitude spans ~111 km at the equator and ~68 km at 52°N, so a Euclidean norm
+on raw degrees is 64% wrong over 1 km at Dutch latitudes. `haversineDistance`
+is the answer (<0.5% anywhere); `equirectDistance` is the *screening* form
+(0.02% at 430 km, 12.4% intercontinentally — a few multiply-adds against
+haversine's transcendentals) for rejecting candidates before the real test —
+the same build-then-probe shape the query engine's hash join uses. The
+ellipsoid is deliberately not modelled.
+
+RFC 7946 removed coordinate-reference-system support and mandates WGS 84, so
+there is no SRID table and no reprojection: conformance removes the need rather
+than an omission hiding it.
+
+**Measured against the field** (`npm run benchmark:geo`, Node v22.22.2). Every
+scenario asserts result equivalence before any timing, and the harness refuses
+to print a table if the engines disagree: distance, area, length and bounding
+box come out *bit-identical* to Turf, containment agrees on a 400-point sweep,
+and the index returns exactly Flatbush's answer on 200 queries. Ratios are the
+rival's time over this kernel's, so above 1 means Jaren is faster.
+
+| scenario | Jaren | rival | ratio |
+|---|---|---|---|
+| distance, two positions | 26.2 ns | 128.5 ns (turf) | **4.9×** |
+| distance vs an ellipsoidal library | 52.3 ns | 648.4 ns (geolib) | **12.4×** |
+| line length, 500 positions | 20.5 µs | 63.6 µs (turf) | **3.1×** |
+| point in polygon, 12 vertices | 228 ns | 327 ns (turf) | **1.4×** |
+| bounding box, 2000 vertices | 15.3 µs | 18.1 µs (turf) | **1.2×** |
+| polygon area, 2000 vertices | 18.8 µs | 20.4 µs (turf) | **1.1×** |
+| centroid, 2000 vertices | 18.4 µs | 19.1 µs (turf) | 1.0× |
+| index build, 100k boxes | 12.2 ms | 12.4 ms (flatbush) | 1.0× |
+| index probe, 100k boxes | 529 ns | 529 ns (flatbush) | 1.0× |
+| point in polygon, 2000 vertices | 8.2 µs | 3.7 µs (turf) | **0.5×** |
+
+One row is a loss, and it is kept on purpose. **Point-in-polygon on a large
+ring runs at about half Turf's speed** because every edge that could matter
+goes through the exact orientation predicate, where Turf uses naive
+floating-point arithmetic. That is the trade this module exists to make — it
+is the difference between a containment test that is right on near-collinear
+input and one that is merely fast. Cheap straddle/span tests already skip the
+predicate on edges that cannot affect the answer, which took this from 0.2×
+to 0.5×; the rest is the predicate itself.
+
+Two former losses closed, and both closures carry a lesson about profiling
+before fixing:
+
+- **Index build** was 2.6× behind Flatbush, and the assumed cause — the leaf
+  sort permuting the four-wide bounds rows on every swap — turned out to be
+  wrong: fixing it moved nothing. A phase profile put ~60% of the build in
+  the *Hilbert distance* computation, a 16-step bisection loop with a float
+  division per step. The classical loop is now the bit-parallel transform
+  (identical values, verified exhaustively at the corners and over 200k
+  pseudo-random points), the sort orders a `Uint32Array` permutation with an
+  insertion-sort cutoff, and the bounds are written once, already in leaf
+  order. Build and probe are both level with Flatbush now.
+- **Centroid** walked the same `eachPosition` as `bboxOf` yet lost where
+  `bboxOf` won. The difference was the callback body: accumulating doubles
+  into *closure variables* writes a boxed heap number per `+=` — two per
+  vertex — where `bboxOf`'s comparisons rarely write at all. The accumulators
+  are a small `Float64Array` now (raw double stores, no boxing), and the row
+  is level with Turf.
+
+```javascript
+import { orient2d, haversineDistance, ringWinding, geohashEncode } from '@jarenjs/core/geo';
+
+orient2d(0, 0, 1, 0, 0, 1);                    // > 0 — counter-clockwise, exactly
+haversineDistance(4.9041, 52.3676, 2.3522, 48.8566);  // 429_862 m
+ringWinding([[0,0],[1,0],[1,1],[0,1],[0,0]]);  // 1 — RFC 7946 exterior ring
+geohashEncode(4.9041, 52.3676, 5);             // 'u173z' — a string, so $starts-with is proximity
+```
+
 ### 6. Text Module (`text/`)
 
 Comprehensive string format validation organized by domain.
@@ -457,12 +663,11 @@ flowchart TB
 
         subgraph EmailModule["email.js"]
             Email["isValidEmail()<br/>Basic RFC 5322"]
-            EmailFull["isValidEmailFull()<br/>Comprehensive"]
             IDNEmail["isValidIdnEmail()<br/>Internationalized"]
         end
 
         subgraph HostModule["host.js"]
-            URL["isValidUrl() / isValidUrlFull()"]
+            URL["isValidUrl()<br/>Web-scheme URI"]
             URI["isValidUri() / isValidUriFull()"]
             IPv4["isValidIPv4()"]
             IPv6["isValidIPv6()"]
@@ -471,16 +676,14 @@ flowchart TB
         end
 
         subgraph Base64Module["base64.js"]
-            B64["isValidBase64()<br/>Multiple implementations"]
-            B64Fast["isValidBase64Fast()<br/>Optimized"]
-            B64Full["isValidBase64Full()<br/>Strict padding"]
+            B64["isValidBase64()<br/>RFC 4648"]
         end
 
         subgraph PunycodeModule["punycode.js"]
-            ToASCII["toASCII()<br/>Unicode → Punycode"]
-            ToUnicode["toUnicode()<br/>Punycode → Unicode"]
-            Encode["encode()<br/>Raw encoding"]
-            Decode["decode()<br/>Raw decoding"]
+            Encode["punycodeEncode()<br/>One label, RFC 3492"]
+            Decode["punycodeDecode()<br/>One label, RFC 3492"]
+            ToASCII["domainToASCII()<br/>Whole name → ACE"]
+            ToUnicode["domainToUnicode()<br/>ACE → Unicode"]
         end
 
         subgraph I18nModule["i18n.js"]
@@ -490,13 +693,13 @@ flowchart TB
             Hebrew["isHebrew()"]
             Arabic["isArabicIndicDigit()"]
             CJK["isHiragana() / isKatakana() / isHan()"]
-            Contextual["checkContextualRules()<br/>IDN label rules"]
+            Contextual["checkContextualRules()<br/>IDN label rules, over code points"]
         end
 
         subgraph Misc["misc.js"]
             ISBN["ISBN-10 / ISBN-13 validation"]
             Country["isValidCountryAlpha2()<br/>ISO 3166-1"]
-            IBAN["isValidIBAN()"]
+            IBAN["isValidIBAN()<br/>ISO 13616 + MOD 97-10"]
         end
     end
 ```
@@ -531,7 +734,7 @@ flowchart TB
             Standard["Standard math<br/>sqrt, pow, sin, cos"]
             GCD["GCD calculation"]
             InverseSqrt["Fast inverse square root<br/>(Quake III algorithm)"]
-            Interpolation["Interpolation<br/>lerp, norm, map"]
+            Interpolation["Normalization<br/>norm (free export: remap)"]
         end
 
         subgraph Vec2I32["vec2i32.js"]
@@ -797,4 +1000,4 @@ export function isNumberType(data) {
 
 When contributing, remember: this package is used by `@jarenjs/validate` and `@jarenjs/formats`. Changes here have downstream effects. Maintain backward compatibility, optimize for performance, and keep the API predictable.
 
-For questions about the broader architecture, see the root [`ARCHITECTURE.md`](../../ARCHITECTURE.md). For development workflows, see [`HOWTO.md`](../../HOWTO.md).
+For questions about the broader architecture, see the root [`ARCHITECTURE.md`](../../docs/ARCHITECTURE.md). For development workflows, see [`HOWTO.md`](../../docs/HOWTO.md).

package/README.md

@@ -1,6 +1,6 @@
 # @jarenjs/core
 
-The zero-dependency foundation of [Jaren](https://github.com/jklarenbeek/jarenjs). Everything the validator, the formats package and the forms package are built on lives here — type guards, Unicode-aware string handling, a large text-validation toolbox, number range helpers, and fixed-point and vector math.
+The zero-dependency foundation of [Jaren](https://github.com/jklarenbeek/jarenjs). Everything the rest of the suite is built on lives here — type guards, Unicode-aware string handling, a large text-validation toolbox, number range helpers, fixed-point and vector math, the calendar kernel, the spatial kernel, the message-catalog compiler, unit/currency conversion and a finance library.
 
 None of it depends on JSON Schema: every module can be used standalone in any JavaScript project.
 
@@ -10,18 +10,25 @@ 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`), map/set merging |
-| `@jarenjs/core/string` | Unicode string helpers (`countCodePoints`, `compareCodePoints`, ...), cached regex compilation |
+| `@jarenjs/core/object` | deep equality (`equalsDeep`, JSON-only `equalsJson`), the `isJsonObject` predicate, `__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/chunk` | cutting a value down to size: `sizeOf` (the suite's one size rule — a string is its length, anything else its JSON), `excerpt`, `truncate`, and `chunkText` by size, line or separator with offsets that locate a piece in its source |
 | `@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/integer` | `int8` ... `uint64` ranges and validators |
 | `@jarenjs/core/float` | `float16` ... `float64` constants, validators, increment/decrement |
 | `@jarenjs/core/bigint` | bigint helpers (`BigInt_min`, `BigInt_MinMax`, ...) |
-| `@jarenjs/core/dates` | RFC 3339 / ISO 8601 date-time parsing and validation |
+| `@jarenjs/core/dates` | RFC 3339 / ISO 8601 validation, plus the calendar kernel: integer date arithmetic, compiled formatting, durations |
+| `@jarenjs/core/geo` | the spatial kernel over GeoJSON: robust orientation, great-circle measurement, rings, bounding boxes, geohash, GeoJSON/WKT validity, a packed-Hilbert box index, Web Mercator and Douglas-Peucker simplification |
 | `@jarenjs/core/text` | text validators: emails, hostnames, IPs, URIs/IRIs, UUIDs, punycode, ... |
-| `@jarenjs/core/math` | int32/float64 math and 2D/3D vector classes |
+| `@jarenjs/core/math` | int32/float64 math and 2D/3D vector classes; the linear `remap` and unit-interval `clamp01` |
+| `@jarenjs/core/finance` | zero-dependency finance/trading formulas: TVM, cash flow, amortization, interest, depreciation, bonds, technical indicators, returns/risk |
+| `@jarenjs/core/convert` | pure deterministic quantity conversion: affine dimensional units and rate-table currency |
 
-Deep imports work too (`@jarenjs/core/text/email`, `@jarenjs/core/math/vec2f64`, ...).
+Deep imports work too (`@jarenjs/core/text/email`, `@jarenjs/core/math/vec2f64`, `@jarenjs/core/finance/tvm`, ...).
 
 ## Strings and Unicode
 
@@ -51,13 +58,60 @@ isValidIPv6('::ffff:192.168.0.1');        // true
 isValidUriTemplate('/users{/id}{?q}');    // true (RFC 6570)
 ```
 
-Grouped by file: `email` (RFC 5321 + internationalized addresses), `host` (hostnames, IDN hostnames, IPv4/IPv6, MAC, URI/URL/IRI and references, URI templates), `identifiers` (UUID, GUID, C/HTML/CSS identifiers), `iregexp` (I-Regexp / RFC 9485 validation and translation to `RegExp`: `isValidIRegexp`, `compileIRegexp`), `base64`, `basic` (alpha, numeric, hex, web colors), `misc` (ISBN-10/13, ISO 3166 country codes, IBAN), `i18n` (Unicode script tests and IDNA context checks) and a complete `punycode` implementation.
+Grouped by file: `email` (RFC 5321 + internationalized addresses), `host` (hostnames, IDN hostnames, IPv4/IPv6, MAC, URI/URL/IRI and references, URI templates), `identifiers` (UUID, GUID, C/HTML/CSS identifiers), `iregexp` (I-Regexp / RFC 9485 validation and translation to `RegExp`: `isValidIRegexp`, `compileIRegexp`), `base64`, `basic` (alpha, numeric, hex, web colors), `misc` (ISBN-10/13, ISO 3166 country codes, ISO 13616 IBAN including its MOD 97-10 check digits), `i18n` (Unicode script tests and IDNA context checks) and `punycode` (the RFC 3492 codec, `punycodeEncode`/`punycodeDecode`, plus the domain-level `domainToASCII`/`domainToUnicode`).
+
+`host` answers `uri`, `uri-reference`, `iri` and `iri-reference` from one character-code scanner: RFC 3987 is RFC 3986 with the unreserved class widened by `ucschar` and `iprivate` admitted in the query, so both grammars are the same walk with one flag. That is what makes every URI an IRI by construction rather than by coincidence.
 
 ## Dates, numbers and math
 
-- `dates` — RFC 3339 date/time/date-time validation and parsing into `Date` (leap years and month lengths included), ISO 8601 durations, and the more lenient ISO date-time forms.
+- `dates` — RFC 3339 date/time/date-time validation and parsing (leap years and month lengths included), the more lenient ISO date-time forms, and the suite's calendar kernel: proleptic Gregorian arithmetic over integer day numbers (`addToParts`, `startOfParts`, `endOfParts` — month math clamps, so 31 Jan plus a month is 28 Feb), ISO 8601 duration decomposition, and `compileDateFormat`, which turns an LDML pattern into a formatter once instead of re-scanning it per call. Dates stay JSON: an RFC 3339 string or epoch milliseconds, never a wrapper object. Locale names live in `@jarenjs/locales`, so a pattern needing `MMMM` takes a names provider. The full module reference is [docs/DATES.md](./docs/DATES.md).
 - `integer`/`float`/`bigint` — range constants and validators for every fixed-width type from `int8` to `uint64` and `float16` to `float64`, including float increment/decrement in representable steps.
-- `math` — asm.js-style typed math (`Int32`, `Float64`) and vector classes (`Vec2i32`, `Vec2f64`, `Vec3f64`) with a fast integer sine approximation.
+- `math` — asm.js-style typed math (`Int32`, `Float64`) and vector classes (`Vec2i32`, `Vec2f64`, `Vec3f64`) with a fast integer sine approximation; reference in [docs/MATH.md](./docs/MATH.md).
+
+## Geospatial
+
+`@jarenjs/core/geo` is the suite's spatial kernel, and its representation is GeoJSON itself ([RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946)) rather than a geometry class: positions are `[longitude, latitude]` arrays, a `Polygon`'s `coordinates` *is* an array of rings, so every value stays a plain JSON item — patchable, schema-checkable, addressable by pointer and path. RFC 7946 fixes the coordinate system to WGS 84, so there is no SRID table and no reprojection *in*; the one projection that exists goes *out*, for drawing.
+
+```javascript
+import {
+  orient2d, haversineDistance, ringWinding, bboxOf,
+  geohashEncode, isValidWkt, createBboxIndex,
+} from '@jarenjs/core/geo';
+
+orient2d(0, 0, 1, 0, 0, 1);                    // > 0 — counter-clockwise, exactly
+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
+isValidWkt('POINT (4.9041 52.3676)');          // true — strict ISO 19125 grammar
+
+const index = createBboxIndex(regions.map(bboxOf));       // packed-Hilbert, build once
+for (const i of index.search(...bboxOf(point))) confirm(regions[i]); // candidates, then the exact test
+```
+
+Three design decisions carry the module:
+
+- **Orientation is computed exactly** (Shewchuk's adaptive predicates): a naive floating-point determinant returns the *wrong sign* on near-collinear input, which makes containment contradict itself. Every ring winding and point-in-polygon answer rests on this sign, and the deliberate cost is on the [benchmark page](https://jklarenbeek.github.io/jarenjs/#/benchmarks?suite=geo).
+- **Measurement is spherical, drawing is projected, and the two never mix.** A Euclidean norm on raw degrees is 64% wrong over 1 km at Dutch latitudes, so `haversineDistance`/`sphericalRingArea` work on the sphere (`equirectDistance` is the cheap screening form for rejecting candidates first), while `projectMercator`/`fitMercator` and `simplifyLine`/`simplifyRing` exist for renderers — never measure on a projected coordinate.
+- **Validity is a separate concern from traversal.** `eachPosition`, `bboxOf`, `centroidOf` and friends measure without judging; `isValidGeoJson` (structure plus the ring closure a JSON Schema provably cannot express), `isValidWkt` and `isValidGeohash` are the one-call judgments that back the `geoFormats` group in [`@jarenjs/formats`](../formats), next to the full GeoJSON meta-schema artifacts in [`@jarenjs/json`](../json).
+
+The spatial query operators (`$distance`, `$within`, `$geohash`, spatial joins over the box index) live in the query engine in [`@jarenjs/json`](../json); the streaming map chart that draws a FeatureCollection with bounded memory lives in [`@jarenjs/charts`](../../components/charts). The full module reference is [docs/GEO.md](./docs/GEO.md).
+
+## Messages
+
+`@jarenjs/core/message` is the template/catalog compiler behind the validator's uniform error messages and the form layer's labels — msgid plus parameters in, rendered text out, so every message is translatable by swapping a catalog ([`@jarenjs/locales`](../locales) ships eleven language packs over it):
+
+```javascript
+import { compileMessageTemplate, compileMessageCatalog } from '@jarenjs/core/message';
+
+const t = compileMessageTemplate('must be {comparison} {limit}');
+t({ comparison: '>=', limit: 18 });   // 'must be >= 18'
+```
+
+## Units, currency and finance
+
+- `convert` — pure, deterministic quantity conversion over a registry of affine dimensional units (`convert(1, 'nmi', 'km')` → `1.852`; dimensions include length, area, volume, mass, temperature, time, speed, pressure, energy, angle and more, with `unitsOf`/`dimensionOf` for discovery). Currency is rate-table based: rates come in as data, never from a network call inside this package. Reference in [docs/CONVERT.md](./docs/CONVERT.md).
+- `finance` — zero-dependency finance and trading formulas grouped by file: `tvm` (`pmt(0.05/12, 360, 250000)` → `-1342.05`, plus `fv`/`pv`/`nper`/`rate`), `cashflow` (NPV/IRR), `amortization`, `interest`, `depreciation`, `bond`, `returns` (returns and risk measures) and `indicators` (SMA/EMA/WMA, MACD, RSI, Bollinger bands — windowed values pad with `null` until the window fills, so outputs align with inputs). Reference in [docs/FINANCE.md](./docs/FINANCE.md).
 
 ## JSON addressing standards
 
@@ -65,4 +119,4 @@ The JSON addressing and query standards — JSON validation helpers, JSON Pointe
 
 ## Development
 
-Unit tests live in `test/core/` at the repository root (`npm run test:core`). This package's internals are described in its own [ARCHITECTURE](./ARCHITECTURE.md) document; see the repository [README](../../README.md) and [ARCHITECTURE](../../ARCHITECTURE.md) for the monorepo picture, and the [ROADMAP](../../ROADMAP.md) for planned work.
+Unit tests live in `test/core/` at the repository root (`npm run test:core`). This package's internals are described in its own [ARCHITECTURE](./ARCHITECTURE.md) document, with per-module references under [docs/](./docs/) (`MATH`, `CONVERT`, `FINANCE`, `DATES`, `GEO`); see the repository [README](../../README.md) and [ARCHITECTURE](../../docs/ARCHITECTURE.md) for the monorepo picture, and the [ROADMAP](../../docs/ROADMAP.md) for planned work.

package/dist/types/array.d.ts

@@ -26,3 +26,16 @@ export declare function isUniqueArray(arr: any[]): boolean;
  * @returns {boolean} True if all 'values' are included in 'arr', false otherwise.
  */
 export declare function includesAll(arr: any[], values: any[]): boolean;
+/**
+ * The value when it is one of `allowed`, otherwise `fallback`. The point
+ * is untrusted input: a value restored from storage, a share link or a
+ * stale state slice can be anything, and a UI that switches on it directly
+ * renders nothing at all for a name it does not know. Narrowing to a known
+ * set turns that blank into the fallback.
+ * @template T
+ * @param {unknown} value - The candidate, from anywhere.
+ * @param {readonly T[]} allowed - The values that may pass through.
+ * @param {T} fallback - Used when `value` is not one of `allowed`.
+ * @returns {T}
+ */
+export declare function pickAllowed<T>(value: unknown, allowed: readonly T[], fallback: T): T;