@jarenjs/core 0.34.0 → 0.43.1

package/src/geo/bbox.js

@@ -17,6 +17,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}
  */
@@ -31,6 +39,8 @@ export function bboxOfPositions(positions) {
   for (let i = 0; i < n; i++) {
     const x = positions[i][0];
     const y = positions[i][1];
+    if (!Number.isFinite(x) || !Number.isFinite(y))
+      return null;
     if (x < west) west = x;
     if (x > east) east = x;
     if (y < south) south = y;
@@ -77,4 +87,35 @@ export function bboxUnion(a, b) {
   ];
 }
 
+/**
+ * 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 function bboxPolygon(box) {
+  if (box === null || !Array.isArray(box) || box.length < 4)
+    return null;
+  const west = box[0];
+  const south = box[1];
+  const east = box[2];
+  const north = box[3];
+  return {
+    type: 'Polygon',
+    coordinates: [[
+      [west, south], [east, south], [east, north], [west, north], [west, south],
+    ]],
+  };
+}
+
 //#endregion

package/src/geo/distance.js

@@ -135,6 +135,54 @@ export function destinationPoint(lon, lat, bearing, distance, radius = EARTH_RAD
   return [((l2 * RAD + 540) % 360) - 180, p2 * RAD];
 }
 
+/**
+ * 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 function circleBounds(lon, lat, distance, radius = EARTH_RADIUS) {
+  if (!Number.isFinite(lon) || !Number.isFinite(lat)
+    || !Number.isFinite(distance) || distance < 0) return null;
+  const d = distance / radius;
+  const dDeg = d * RAD;
+  // at or past a pole the circle covers every meridian, so no box bounds it
+  if (Math.abs(lat) + dDeg >= 90) return null;
+  // the tangent half-width is never narrower than the angular radius
+  // itself (cos φ <= 1), and at the equator the asin(sin …) round trip
+  // loses the last bit of exactly that value — taking the wider of the
+  // two restores an inequality the real numbers always satisfy rather
+  // than padding by a constant nobody could justify
+  const tangent = Math.asin(Math.sin(d) / Math.cos(lat * DEG)) * RAD;
+  const half = tangent > dDeg ? tangent : dDeg;
+  return [lon - half, lat - dDeg, lon + half, lat + dDeg];
+}
+
 /**
  * Total great-circle length of a line of positions, in metres. An empty
  * or single-position line has length 0.

package/src/geo/geojson.js

@@ -105,7 +105,10 @@ export function eachPosition(value, visit) {
 
 /**
  * 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
@@ -123,16 +126,21 @@ export function bboxOf(value) {
   let east = -Infinity;
   let north = -Infinity;
   let seen = false;
+  let bounded = true;
   eachPosition(value, (p) => {
     const x = p[0];
     const y = p[1];
     seen = true;
+    if (!Number.isFinite(x) || !Number.isFinite(y)) {
+      bounded = false;
+      return;
+    }
     if (x < west) west = x;
     if (x > east) east = x;
     if (y < south) south = y;
     if (y > north) north = y;
   });
-  return seen ? [west, south, east, north] : null;
+  return seen && bounded ? [west, south, east, north] : null;
 }
 
 /**

package/src/geo/index.js

@@ -21,7 +21,7 @@
 //   geohash.js     the string encoding that needs no new vocabulary
 //   geojson.js     the one layer that knows the `type` discriminator
 //   valid.js       the one-call structural judgment (rings must close)
-//   wkt.js         a validity tester for the databases' text encoding
+//   wkt.js         the round trip with the databases' text encoding
 //   index-tree.js  a static packed-Hilbert box index for spatial joins
 //   mercator.js    the projection out, for anything that draws a map
 //   simplify.js    dropping the vertices that land on the same pixel

package/src/geo/simplify.js

@@ -127,4 +127,73 @@ export function simplifyRing(ring, tolerance) {
   return simplified.length >= 4 ? simplified : ring.slice();
 }
 
+/** Every line/ring of a coordinate nest `depth` levels above the leaf. */
+function simplifyNest(value, depth, tolerance, simplify) {
+  if (!Array.isArray(value))
+    return value;
+  if (depth === 0)
+    return simplify(value, tolerance);
+  const out = new Array(value.length);
+  for (let i = 0; i < value.length; i++)
+    out[i] = simplifyNest(value[i], depth - 1, tolerance, simplify);
+  return out;
+}
+
+/**
+ * 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 function simplifyGeometry(value, tolerance) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value))
+    return value;
+  if (value.type === 'FeatureCollection') {
+    if (!Array.isArray(value.features))
+      return value;
+    return { ...value, features: value.features.map((f) => simplifyGeometry(f, tolerance)) };
+  }
+  if (value.type === 'Feature') {
+    return { ...value, geometry: simplifyGeometry(value.geometry, tolerance) };
+  }
+  if (value.type === 'GeometryCollection') {
+    if (!Array.isArray(value.geometries))
+      return value;
+    return { ...value, geometries: value.geometries.map((g) => simplifyGeometry(g, tolerance)) };
+  }
+  switch (value.type) {
+    case 'LineString':
+      return { ...value, coordinates: simplifyNest(value.coordinates, 0, tolerance, simplifyLine) };
+    case 'MultiLineString':
+      return { ...value, coordinates: simplifyNest(value.coordinates, 1, tolerance, simplifyLine) };
+    case 'Polygon':
+      return { ...value, coordinates: simplifyNest(value.coordinates, 1, tolerance, simplifyRing) };
+    case 'MultiPolygon':
+      return { ...value, coordinates: simplifyNest(value.coordinates, 2, tolerance, simplifyRing) };
+    default: // Point, MultiPoint, and anything unrecognized: nothing to drop
+      return value;
+  }
+}
+
 //#endregion