@jarenjs/core 0.34.2 → 0.43.1

package/ARCHITECTURE.md

@@ -120,7 +120,8 @@ flowchart TB
             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"]
+            GeoValid["valid.js<br/>Structural judgment"]
+            GeoWkt["wkt.js<br/>Well-Known Text round trip"]
             GeoTree["index-tree.js<br/>Packed-Hilbert box index"]
             GeoMerc["mercator.js + simplify.js<br/>Projection out, simplification"]
         end
@@ -194,6 +195,7 @@ flowchart TB
     GeoIndex --> GeoHash
     GeoIndex --> GeoJson
     GeoIndex --> GeoValid
+    GeoIndex --> GeoWkt
     GeoIndex --> GeoTree
     GeoIndex --> GeoMerc
 
@@ -549,7 +551,7 @@ passed straight in without the `type` discriminator being involved.
 | `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 |
+| `wkt.js` | the Well-Known Text round trip — `wktToGeoJson`, `geoJsonToWkt` and `isValidWkt`, one grammar walk with and without a builder |
 | `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 |
@@ -557,6 +559,45 @@ passed straight in without the `type` discriminator being involved.
 The three validity testers back the `geoFormats` group in
 [`@jarenjs/formats`](../formats) (`geohash`, `wkt`, `geojson`).
 
+**WKT is one grammar walk with two entry points.** `isValidWkt` is a format
+tester — it runs per value in the validator and per keystroke in the form
+layer — so it must not allocate a geometry to answer a boolean; and two
+hand-maintained grammars for one syntax would drift apart. Both are avoided by
+giving every scan function a sink: absent, it validates; present, it appends
+the value it just recognized, and `wktToGeoJson` reads the result. A committed
+corpus of 181 strings, its malformed half included, asserts
+`isValidWkt(s) === (wktToGeoJson(s) !== null)` for every entry — a divergence
+is a failing test, not a note. `geoJsonToWkt` writes the string back, and the
+parse-write-parse direction is asserted over the corpus; the write-parse-write
+direction is *not* claimed, because WKT whitespace, the `M` measure and number
+spelling are normalized on the way through.
+
+Against [`wellknown`](https://www.npmjs.com/package/wellknown), the established
+WKT↔GeoJSON converter (`npm run benchmark:geo`, Node v24.19.0):
+
+| scenario | Jaren | wellknown | ratio |
+|---|---|---|---|
+| parse a `POINT` | 439 ns | 1.34 µs | **3.1×** |
+| parse a 2000-vertex `POLYGON` | 820 µs | 2.20 ms | **2.7×** |
+| write that polygon | 160 µs | 213 µs | **1.3×** |
+| validate a `POINT` | 241 ns | 1.29 µs | **5.4×** |
+| validate that polygon | 493 µs | 1.94 ms | **3.9×** |
+
+The last two rows are the ones the sink exists for: `wellknown` has no
+predicate, so validating means parsing and throwing the geometry away. And the
+comparison is *not* like-for-like on work done — **wellknown validates less**
+and is still slower. Over the corpus it accepts 38 strings this grammar
+refuses (no ring closure, no four-point ring or two-point line minimum, no
+coordinate count checked against the modifier, no tag list, and text after the
+geometry ignored); it refuses 22 this one accepts (`M`/`ZM` geometries, `EMPTY`
+for POINT/MULTIPOINT/GEOMETRYCOLLECTION); and on 10 more the two produce
+*different geometries*, because wellknown answers an EMPTY geometry for a
+POLYGON/MULTILINESTRING/MULTIPOLYGON carrying a modifier and writes a
+MULTIPOINT's measure into the altitude slot. Every one of those classes has a
+pinned size in the benchmark's equivalence table, so a difference cannot be
+quietly absorbed, and the entries behind each are listed under it. The
+stringify output is byte-identical on the polygon.
+
 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

package/README.md

@@ -10,7 +10,7 @@ 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` predicate, `__proto__`-safe `setObjectMember`, `deepFreeze`, map/set merging |
+| `@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/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 |
@@ -75,7 +75,7 @@ Grouped by file: `email` (RFC 5321 + internationalized addresses), `host` (hostn
 ```javascript
 import {
   orient2d, haversineDistance, ringWinding, bboxOf,
-  geohashEncode, isValidWkt, createBboxIndex,
+  geohashEncode, wktToGeoJson, geoJsonToWkt, createBboxIndex,
 } from '@jarenjs/core/geo';
 
 orient2d(0, 0, 1, 0, 0, 1);                    // > 0 — counter-clockwise, exactly
@@ -83,17 +83,20 @@ haversineDistance(4.9041, 52.3676, 2.3522, 48.8566); // 429_862 m (Amsterdam–P
 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
+
+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)'
 
 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:
+Four 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).
+- **WKT is one grammar walk with two entry points.** `isValidWkt` and `wktToGeoJson` run the *same* scan, parameterized by a sink that is absent for the predicate and present for the parser — so the `wkt` format tester (which runs per value in the validator and per keystroke in the form layer) allocates nothing, and the two cannot drift apart. A committed corpus asserts `isValidWkt(s) === (wktToGeoJson(s) !== null)` for all 181 entries, malformed half included. `geoJsonToWkt` writes the string back, and `wktToGeoJson(geoJsonToWkt(g))` returns `g`; the text direction is *not* claimed, because whitespace, the `M` measure and number spelling are normalized. Against [`wellknown`](https://www.npmjs.com/package/wellknown) the parse is 3.1× faster on a `POINT` and the yes-or-no answer 5.4× — and wellknown *validates less* while being slower, which is the honest framing; the table and every language difference are in [ARCHITECTURE](./ARCHITECTURE.md).
 
 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).
 

package/dist/types/function.d.ts

@@ -1,3 +1,28 @@
+/**
+ * True when a value is a thenable — the shape `await` and the sync-capable
+ * async helpers below key on. A `then` that is not a function is data.
+ * @param {any} value
+ * @returns {boolean}
+ */
+export declare function isThenable(value: any): boolean;
+/**
+ * Sync-capable-async composition: apply `next` to a result that may be
+ * a value or a promise, WITHOUT allocating a promise when it is already
+ * a value. This is how a seam whose implementations may answer either
+ * way (a database driver, an idempotency ledger) keeps its synchronous
+ * fast path exact while the asynchronous one composes naturally.
+ * @param {any} value - A value or a promise of one
+ * @param {(value: any) => any} next
+ * @returns {any} `next`'s result, promise-wrapped only if the input was
+ */
+export declare function chain(value: any, next: (value: any) => any): any;
+/**
+ * Lift a value-or-promise into a promise — the ONE allocation a public
+ * asynchronous surface pays per call over a sync-capable seam.
+ * @param {any} value
+ * @returns {Promise<any>}
+ */
+export declare function toPromise(value: any): Promise<any>;
 /**
  * trueThat
  * acts as a dummy validator that always returns true

package/dist/types/geo/bbox.d.ts

@@ -2,6 +2,14 @@
  * The bounding box of a list of positions, as `[west, south, east, north]`.
  * Returns null for an empty list — there is no box that bounds nothing,
  * and an all-Infinity placeholder would silently intersect everything.
+ *
+ * Null too when any position is non-finite. Narrowing would drop it —
+ * every comparison against `NaN` is false — and answer with a finite,
+ * plausible box that does not contain the input it was asked to bound.
+ * A pre-filter built on such a box loses matching rows silently, which
+ * is the one failure a two-stage spatial plan cannot survive, so a
+ * position that cannot be bounded refuses the box rather than leaving
+ * it too small.
  * @param {Array<number[]>} positions
  * @returns {number[] | null}
  */
@@ -30,3 +38,23 @@ export declare function bboxContains(box: number[], x: number, y: number): boole
  * @returns {number[]}
  */
 export declare function bboxUnion(a: number[], b: number[]): number[];
+/**
+ * A box as the `Polygon` that covers it — the rectangle written
+ * counter-clockwise from its south-west corner, which is RFC 7946's
+ * exterior winding, and closed.
+ *
+ * A box is four numbers and a polygon is a value the rest of the
+ * language can measure, contain and intersect, so this is the crossing
+ * between the two: a geohash cell, an index probe box or a `bbox`
+ * member becomes something `$within` and `$area` can take.
+ *
+ * @param {number[] | null} box - [west, south, east, north]
+ * @returns {{ type: string, coordinates: number[][][] } | null} null for no box
+ * @example
+ * bboxPolygon([4, 52, 5, 53]);
+ * // { type: 'Polygon', coordinates: [[[4,52],[5,52],[5,53],[4,53],[4,52]]] }
+ */
+export declare function bboxPolygon(box: number[] | null): {
+    type: string;
+    coordinates: number[][][];
+} | null;

package/dist/types/geo/distance.d.ts

@@ -57,6 +57,38 @@ export declare function initialBearing(lon1: number, lat1: number, lon2: number,
  * @returns {[number, number]} the destination as a GeoJSON position
  */
 export declare function destinationPoint(lon: number, lat: number, bearing: number, distance: number, radius?: number): [number, number];
+/**
+ * The bounding box of a geodesic circle: every position within
+ * `distance` metres of `(lon, lat)` on the same sphere lies inside it.
+ * This is what turns "nearer than r" into a box a range index can seek.
+ *
+ * The latitude bounds are the circle's due-north and due-south points,
+ * but the longitude bounds are **not** its due-east and due-west ones:
+ * the circle reaches its extreme meridians where it runs tangent to
+ * them, further out than a 90° bearing travels — 0.4 % further at 80°N
+ * over 100 km. A box built from four bearings is therefore too small,
+ * and too small is the one error a conservative pre-filter cannot
+ * survive. The extreme half-width is `asin(sin δ / cos φ)` for angular
+ * radius δ at latitude φ.
+ *
+ * `null` when the circle reaches a pole (`|lat| + δ >= 90°`), where the
+ * longitude bound does not exist because the circle spans every
+ * meridian, and for any non-finite or negative input.
+ *
+ * West and east are NOT wrapped into `[-180, 180]`: a circle spanning
+ * the antimeridian answers a west below -180 or an east above 180, so
+ * a caller can tell that case apart — RFC 7946 asks producers to cut
+ * there, and a wrapped box would silently claim the short way round.
+ *
+ * @param {number} lon - centre longitude, degrees
+ * @param {number} lat - centre latitude, degrees
+ * @param {number} distance - radius in metres (or in `radius`'s unit)
+ * @param {number} [radius] - sphere radius
+ * @returns {[number, number, number, number] | null} `[west, south, east, north]`
+ * @example
+ * circleBounds(5, 52, 1000); // [4.98539…, 51.99101…, 5.01461…, 52.00899…]
+ */
+export declare function circleBounds(lon: number, lat: number, distance: number, radius?: number): [number, number, number, number] | null;
 /**
  * Total great-circle length of a line of positions, in metres. An empty
  * or single-position line has length 0.

package/dist/types/geo/geojson.d.ts

@@ -27,7 +27,10 @@ export declare function geometryOf(value: any): object | null;
 export declare function eachPosition(value: any, visit: (position: number[]) => void): void;
 /**
  * The bounding box of any GeoJSON value, as `[west, south, east, north]`.
- * Null when the value contains no positions.
+ * Null when the value contains no positions, and null when any position
+ * it walks is non-finite — the rule `bboxOfPositions` states, for the
+ * same reason: a box that does not bound its input is worse than no
+ * box.
  *
  * A `bbox` member already present on the value is ignored: it is an
  * optimization the producer may have got wrong, and recomputing is the

package/dist/types/geo/simplify.d.ts

@@ -29,3 +29,31 @@ export declare function simplifyLine(line: Array<number[]>, tolerance: number):
  * @returns {Array<number[]>}
  */
 export declare function simplifyRing(ring: Array<number[]>, tolerance: number): Array<number[]>;
+/**
+ * A whole GeoJSON value with its vertices dropped — the same value,
+ * reduced. Lines go through {@link simplifyLine} and rings through
+ * {@link simplifyRing}, so **a ring stays closed and a line keeps both
+ * endpoints**; points and multipoints have no run to collapse and come
+ * back untouched.
+ *
+ * Accepts what the traversal layer accepts: a geometry, a Feature, a
+ * FeatureCollection or a GeometryCollection. Foreign members, ids and
+ * properties ride along — the value that comes back is the value that
+ * went in, with fewer positions, so it can be stored or sent as-is.
+ * Anything this does not recognize is returned unchanged rather than
+ * dropped.
+ *
+ * The tolerance is in the coordinate's own units, which for GeoJSON is
+ * **degrees** — a planar vertex-dropping threshold, never a distance. A
+ * degree of longitude is not a fixed length, so calling it metres would
+ * be the planar-for-geodesic confusion the rest of this module exists to
+ * prevent.
+ *
+ * @param {any} value
+ * @param {number} tolerance - in degrees
+ * @returns {any} a new value; the input is not modified
+ * @example
+ * simplifyGeometry({ type: 'LineString', coordinates: [[0,0],[1,0.001],[2,0]] }, 0.01);
+ * // { type: 'LineString', coordinates: [[0,0],[2,0]] }
+ */
+export declare function simplifyGeometry(value: any, tolerance: number): any;

package/dist/types/geo/wkt.d.ts

@@ -4,6 +4,9 @@
  * coordinate count consistent with the `Z`/`M`/`ZM` modifier and with
  * itself, closed polygon rings, and nothing before or after.
  *
+ * This is the non-allocating half of the walk {@link wktToGeoJson}
+ * builds with, so the two accept exactly the same language.
+ *
  * @param {string} text
  * @returns {boolean}
  * @example
@@ -12,5 +15,67 @@
  * isValidWkt('POLYGON ((0 0, 4 0, 4 4, 1 1))');          // false (open ring)
  * isValidWkt('POINT Z (1 2)');                           // false (Z wants 3)
  * isValidWkt('LINESTRING (0 0, 1 1 1)');                 // false (mixed dimension)
+ * isValidWkt('CIRCLE EMPTY');                            // false (not one of the seven)
  */
 export declare function isValidWkt(text: string): boolean;
+/**
+ * The GeoJSON geometry a WKT string names, or `null` when the text is
+ * not well-formed WKT — the same judgment {@link isValidWkt} makes,
+ * from the same walk. `null` rather than a throw is the kernel's
+ * posture for "no answer" (`bboxOf`, `centroidOf`, `geohashBounds` all
+ * answer it), so no call site has to wrap this in a try.
+ *
+ * Three rules decide what a lenient parser would silently lose:
+ *
+ * - `EMPTY` becomes an empty coordinate array (`POINT EMPTY` →
+ *   `{ type: 'Point', coordinates: [] }`), never `null`: unparseable
+ *   and validly empty are different answers.
+ * - The `M` measure is dropped and `Z` is kept. RFC 7946 §3.1.1 defines
+ *   a position's third element as altitude, and a measure is not one —
+ *   writing it there would be a lie. `POINT ZM (1 2 3 4)` → `[1, 2, 3]`,
+ *   `POINT M (1 2 3)` → `[1, 2]`.
+ * - Coordinate ranges are not judged. `POINT (999 999)` parses;
+ *   `isValidGeoJson` is the value gate.
+ *
+ * @param {string} text
+ * @returns {object | null}
+ * @example
+ * wktToGeoJson('POINT (4.9041 52.3676)');
+ * // { type: 'Point', coordinates: [4.9041, 52.3676] }
+ * wktToGeoJson('POLYGON ((0 0, 4 0, 4 4, 0 0))');
+ * // { type: 'Polygon', coordinates: [[[0,0],[4,0],[4,4],[0,0]]] }
+ * wktToGeoJson('POINT EMPTY');       // { type: 'Point', coordinates: [] }
+ * wktToGeoJson('POLYGON ((0 0))');   // null
+ */
+export declare function wktToGeoJson(text: string): object | null;
+/**
+ * A GeoJSON value as a WKT string, or `null` for a value with no
+ * geometry to write. Accepts what the traversal layer accepts: a bare
+ * position, a geometry, a Feature or a FeatureCollection.
+ *
+ * `options.dim` is 2 (the default) or 3. At 3, a geometry whose every
+ * position carries a third element is written with a `Z` modifier;
+ * anything else is written 2D with the third elements dropped, because
+ * one WKT geometry carries one modifier for all of its coordinates. The
+ * decision is made per tagged geometry, so a GeometryCollection may mix
+ * 2D and 3D members — each writes its own modifier. Invalid WKT is
+ * never emitted.
+ *
+ * A non-finite coordinate yields `null`: a value that cannot be written
+ * is not written approximately.
+ *
+ * @param {any} value
+ * @param {{ dim?: number }} [options]
+ * @returns {string | null}
+ * @example
+ * geoJsonToWkt({ type: 'Point', coordinates: [4.9041, 52.3676] });
+ * // 'POINT (4.9041 52.3676)'
+ * geoJsonToWkt([4.9041, 52.3676]);          // 'POINT (4.9041 52.3676)'
+ * geoJsonToWkt({ type: 'Point', coordinates: [] });    // 'POINT EMPTY'
+ * geoJsonToWkt({ type: 'Point', coordinates: [1, 2, 3] }, { dim: 3 });
+ * // 'POINT Z (1 2 3)'
+ * geoJsonToWkt({ type: 'Point', coordinates: [NaN, 2] });         // null
+ */
+export declare function geoJsonToWkt(value: any, options?: {
+    dim?: number;
+}): string | null;

package/dist/types/object.d.ts

@@ -136,6 +136,24 @@ export declare function semanticKey(value: any): string;
  * @returns {boolean}
  */
 export declare function isJsonObject(value: any): boolean;
+/**
+ * True when a value is representable as JSON as it stands: `null`, a
+ * boolean, a finite number, a string, or an array/plain object (own
+ * enumerable members, prototype `Object.prototype` or `null`) whose
+ * members all are. Everything else — `undefined`, `bigint`, `symbol`,
+ * functions, `NaN`/`±Infinity`, class instances (`Error`, `Date`, `Map`,
+ * `Response`, DOM nodes ...) and any cycle — is not.
+ *
+ * This is the boundary predicate for "JSON only crosses": a host that
+ * hands a value into application state asks it once, before the value
+ * can carry an object the state validator would have to reject. It is
+ * TOTAL — a hostile accessor that throws makes the value not-JSON rather
+ * than propagating.
+ *
+ * @param {any} value
+ * @returns {boolean}
+ */
+export declare function isJsonValue(value: any): boolean;
 /**
  * Assign a member so that a key named `__proto__` becomes an own data
  * property instead of reassigning the object's prototype. Every builder

package/dist/types/scan.d.ts

@@ -21,6 +21,7 @@ export declare const CC_0 = 48;
 export declare const CC_1 = 49;
 export declare const CC_9 = 57;
 export declare const CC_COLON = 58;
+export declare const CC_SEMICOLON = 59;
 export declare const CC_LT = 60;
 export declare const CC_EQ = 61;
 export declare const CC_GT = 62;

package/dist/types/string.d.ts

@@ -94,6 +94,28 @@ export declare function fromCodePoints(codePoints: number[]): string;
  * @returns {number} -1 when a < b, 0 when equal, 1 when a > b
  */
 export declare function compareCodePoints(a: string, b: string): number;
+/**
+ * The exclusive upper bound of the strings beginning with `prefix`: the
+ * smallest string that sorts above every one of them. For a
+ * well-formed `value`, `value` begins with `prefix` **iff**
+ * `prefix <= value < codePointPrefixSuccessor(prefix)` under
+ * {@link compareCodePoints} — which is what lets a caller spell a
+ * prefix test as a half-open range, the form an ordered index can seek
+ * rather than test row by row.
+ *
+ * Null when there is no such string, and the caller then has no range
+ * to offer: the empty prefix (every string begins with it) and a
+ * prefix of nothing but U+10FFFF (nothing sorts above it).
+ *
+ * The bound never lands in the surrogate range, because it has to be a
+ * string the caller can hand on — to a comparator, a database
+ * parameter, a serializer. No well-formed string sorts inside that
+ * range, so stepping over it leaves the equivalence above intact.
+ *
+ * @param {string} prefix - The prefix to bound
+ * @returns {string | null} The exclusive upper bound, or null when none exists
+ */
+export declare function codePointPrefixSuccessor(prefix: string): string | null;
 /** FNV-1a 32-bit offset basis — the seed a fresh hash starts from. */
 export declare const FNV1A_OFFSET_BASIS = 2166136261;
 /**

package/dist/types/text/sse.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @file An incremental Server-Sent-Events codec (WHATWG HTML §9.2).
+ * `createSseEventDecoder` yields complete events `{ event, id, data,
+ * retry }` from network chunks fed in any split — mid-line, mid-event,
+ * CR, LF or CRLF line endings; `createSseDecoder` is the data-only view
+ * of the same machine (the shape every OpenAI-compatible streaming
+ * endpoint needs: just the `data:` payloads, in order); and
+ * `encodeSseEvent` renders one event back to wire text.
+ *
+ * Dispatch follows the specification: field lines are `name: value`
+ * with one optional leading space in the value, `:` lines are comments,
+ * an event is dispatched on the blank line exactly when its data buffer
+ * is non-empty (multi-line data joins with `\n`), the last-event-id is
+ * a stream attribute that persists across events (an `id` field whose
+ * value carries U+0000 is ignored), and `retry` must be ASCII digits.
+ * `end()` flushes a final event from a stream that never sent its
+ * closing blank line.
+ */
+export type SseEvent = {
+    event: string | null;
+    id: string | null;
+    data: string;
+    retry: number | null;
+};
+/**
+ * One decoded event. `event` is the `event:` field of the block, `null`
+ * when the block had none (the specification's default type "message");
+ * `id` is the stream's last-event-id at dispatch, `null` while the
+ * stream has not set one; `data` is the joined data payload; `retry` is
+ * the reconnection time a `retry:` field set since the previous
+ * dispatch, `null` otherwise.
+ * @typedef {Object} SseEvent
+ * @property {string | null} event
+ * @property {string | null} id
+ * @property {string} data
+ * @property {number | null} retry
+ */
+/**
+ * An incremental decoder yielding complete events.
+ * @returns {{ feed: (chunk: string) => SseEvent[], end: () => SseEvent[] }}
+ *   `feed` returns the events completed by this chunk; `end` flushes a
+ *   final event from a stream that never sent its closing blank line.
+ */
+export declare function createSseEventDecoder(): {
+    feed: (chunk: string) => SseEvent[];
+    end: () => SseEvent[];
+};
+/**
+ * The data-only view of the event decoder: `feed` yields the complete
+ * `data:` payloads in order and every other field is ignored — the
+ * shape a chat-completion stream consumer needs.
+ * @returns {{ feed: (chunk: string) => string[], end: () => string[] }}
+ */
+export declare function createSseDecoder(): {
+    feed: (chunk: string) => string[];
+    end: () => string[];
+};
+/**
+ * Render one event as wire text: the optional `event:`, `id:` and
+ * `retry:` lines, the data split on `\n` into one `data:` line each,
+ * and the dispatching blank line. Throws `TypeError` for text the frame
+ * cannot carry: a line terminator inside `event` or `id`, U+0000 inside
+ * `id`, a bare carriage return inside `data` (a decoder would read it
+ * as a line break and corrupt the framing), or a `retry` that is not a
+ * non-negative integer.
+ * @param {{ event?: string | null, id?: string | null, data: string, retry?: number | null }} fields
+ * @returns {string}
+ */
+export declare function encodeSseEvent(fields: {
+    event?: string | null;
+    id?: string | null;
+    data: string;
+    retry?: number | null;
+}): string;

package/docs/GEO.md

@@ -35,6 +35,20 @@ rejecting candidates before the real test. Also `initialBearing`,
 `destinationPoint`, `lineLength(positions)`. The ellipsoid is
 deliberately not modelled.
 
+`circleBounds(lon, lat, metres)` answers the `[west, south, east,
+north]` box a "nearer than r" test can be seeked with — the shape a
+range index needs before the exact distance runs. Its longitude bounds
+are **not** the circle's due-east and due-west points: the circle
+reaches its extreme meridians where it runs tangent to them, which is
+`asin(sin δ / cos φ)` from the centre and 0.4 % further than a 90°
+bearing travels at 80°N over 100 km. A box built from four bearings is
+too small, and a pre-filter that is too small drops matching rows
+silently. It answers `null` when the circle reaches a pole (there is no
+longitude bound to give), and it does not wrap west/east into
+`[-180, 180]` — a circle spanning the antimeridian answers a west below
+-180, which is how a caller detects the case RFC 7946 asks producers to
+cut.
+
 ## Rings — `ring.js`
 
 `isRingClosed`, `ringSignedArea` (shoelace over `orient2d` terms —
@@ -56,6 +70,15 @@ never-matching, keeping positions aligned with the caller's array.
 Build and probe are level with Flatbush (`npm run benchmark:geo`; the
 table lives in [ARCHITECTURE](../ARCHITECTURE.md)).
 
+**A box is refused rather than made too small.** `bboxOfPositions` and
+`bboxOf` answer `null` for an empty input *and* whenever any position
+they are asked to bound has a non-finite coordinate — they never skip
+the position and bound the rest. A narrowing loop would drop it
+silently (every comparison against `NaN` is false) and return a finite,
+plausible box that does not contain its input, and a candidate filter
+built on such a box loses matching entries with nothing to show for it.
+`null` is the answer every caller already handles.
+
 ## GeoJSON traversal — `geojson.js`
 
 The one layer that reads the `type` discriminator; every function takes
@@ -66,7 +89,7 @@ mass), `containsPosition`, `geoDistance` (between representative
 positions), `ringsClosed`. Nothing here validates — malformed input
 yields null or 0 — because judgment lives one module over.
 
-## Validity — `valid.js`, `wkt.js`, `geohash.js`
+## Validity — `valid.js`, `geohash.js`
 
 The one-call judgments backing the `geoFormats` group in
 `@jarenjs/formats`:
@@ -76,11 +99,61 @@ The one-call judgments backing the `geoFormats` group in
   invariant a JSON Schema provably cannot express. The shallow twin of
   the meta-schema artifacts in `@jarenjs/json`, which locate failures
   and (via `$query`) also check winding.
-- `isValidWkt(text)` — strict ISO 19125 grammar: seven tags, `Z`/`M`/
-  `ZM` modifiers (unmodified accepts 2 or 3 coordinates, as PostGIS
-  does), consistent counts, closed rings, `EMPTY`, no surrounding text.
 - `isValidGeohash(hash)` — non-empty, lowercase base-32 alphabet.
 
+## Well-Known Text — `wkt.js`
+
+The round trip with the text encoding every spatial database emits.
+`wktToGeoJson(text)` returns a geometry or `null`; `geoJsonToWkt(value,
+options?)` returns a string or `null`; `isValidWkt(text)` answers
+yes-or-no. **All three are one grammar walk**: each scan function takes
+a sink that is absent for the predicate and present for the parser, so
+the format tester allocates nothing and the two entry points cannot
+drift. A committed corpus asserts `isValidWkt(s) === (wktToGeoJson(s)
+!== null)` for every entry, malformed half included — a divergence is a
+failing test.
+
+The grammar is strict ISO 19125: the seven tags and no others,
+`Z`/`M`/`ZM` modifiers (unmodified accepts 2 or 3 coordinates, as
+PostGIS does), coordinate counts consistent with the modifier and with
+the geometry's first point, rings of four or more positions that close,
+`EMPTY`, and no text before or after.
+
+Four rules decide what a lenient converter loses:
+
+- **`EMPTY` is an empty coordinate array**, not `null`: `POINT EMPTY` →
+  `{ type: 'Point', coordinates: [] }`. Unparseable and validly empty
+  are different answers.
+- **`Z` is kept and `M` is dropped.** RFC 7946 §3.1.1 defines a
+  position's third element as altitude; a WKT measure is not one, so
+  writing it there would be a lie. `POINT ZM (1 2 3 4)` → `[1, 2, 3]`,
+  `POINT M (1 2 3)` → `[1, 2]`. The measure is discarded, and it is
+  discarded on purpose.
+- **The parser does not judge ranges.** `POINT (999 999)` parses;
+  `isValidGeoJson` is the value gate, and duplicating it here would make
+  the two entry points disagree.
+- **A value that cannot be written is not written approximately.**
+  `geoJsonToWkt` answers `null` for a non-finite coordinate, and writes
+  numbers with the shortest round-tripping spelling (`String(n)`, what
+  `JSON.stringify` uses) — never a fixed precision, which would silently
+  move the point.
+
+`geoJsonToWkt` accepts what the traversal layer accepts: a Feature
+writes its geometry, a FeatureCollection a `GEOMETRYCOLLECTION` of its
+features' geometries, a bare position a `POINT`. `options.dim` is 2 (the
+default) or 3; at 3 a geometry whose every position carries a third
+element gets a `Z` modifier, and anything else is written 2D with the
+third elements dropped, because one WKT geometry carries one modifier
+for all of its coordinates. The decision is made per tagged geometry, so
+a `GEOMETRYCOLLECTION` may mix 2D and 3D members — invalid WKT is never
+emitted.
+
+**One direction round-trips and the other does not.**
+`wktToGeoJson(geoJsonToWkt(g))` returns `g`, and that is asserted over
+the whole corpus. `geoJsonToWkt(wktToGeoJson(s)) === s` is false in
+general and is not claimed: whitespace, the `M` measure and number
+spelling are all normalized.
+
 ## Geohash — `geohash.js`
 
 `geohashEncode(lon, lat, precision)`, `geohashDecode`, `geohashBounds`,

package/package.json

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

package/src/function.js

@@ -5,6 +5,40 @@ import {
 
 // export * from './function-tools-xtra';
 
+/**
+ * True when a value is a thenable — the shape `await` and the sync-capable
+ * async helpers below key on. A `then` that is not a function is data.
+ * @param {any} value
+ * @returns {boolean}
+ */
+export function isThenable(value) {
+  return value !== null && typeof value === 'object' && typeof value.then === 'function';
+}
+
+/**
+ * Sync-capable-async composition: apply `next` to a result that may be
+ * a value or a promise, WITHOUT allocating a promise when it is already
+ * a value. This is how a seam whose implementations may answer either
+ * way (a database driver, an idempotency ledger) keeps its synchronous
+ * fast path exact while the asynchronous one composes naturally.
+ * @param {any} value - A value or a promise of one
+ * @param {(value: any) => any} next
+ * @returns {any} `next`'s result, promise-wrapped only if the input was
+ */
+export function chain(value, next) {
+  return isThenable(value) ? value.then(next) : next(value);
+}
+
+/**
+ * Lift a value-or-promise into a promise — the ONE allocation a public
+ * asynchronous surface pays per call over a sync-capable seam.
+ * @param {any} value
+ * @returns {Promise<any>}
+ */
+export function toPromise(value) {
+  return isThenable(value) ? value : Promise.resolve(value);
+}
+
 /**
  * trueThat
  * acts as a dummy validator that always returns true