@jarenjs/linq 0.34.2 → 0.43.3

package/README.md

@@ -42,6 +42,16 @@ played by the provider seam below.
   concurrency bound and the `parallel`/`concat`/`switch`/`exhaust`
   vocabulary; barrier operators buffer and run through the one engine
   so streaming answers equal in-memory answers by construction.
+- **Geography is spellable.** The whole §8.14 family is on the
+  expression surface: `p.location.within(region)`,
+  `p.location.distance(here)`, `p.route.geoLength()`,
+  `p.location.geohash(6)`, and the conversion pair `geoParse`/`geoText`
+  that reads a WKT column and writes one back. A plain GeoJSON object
+  embeds as a literal; `.params({ region })` binds it at call time
+  instead, which is the shape a spatial index can be probed with. The
+  spatial measurements are `geoArea`/`geoLength` because `length` on
+  this surface is already `$string-length` — the mapping table says so
+  in its own row.
 - **The provider contract.** Any object with
   `execute(queryDocument, { externals })` is a provider.
   `@jarenjs/db` implements it — a chain over a SQLite-backed

package/docs/LINQ-FORMAT.md

@@ -115,7 +115,22 @@ is part of THIS design.
 | `Cast<S>` | `$assert` per item | native | `(schema)` → `Seq<S>`; needs `compileTypeTest` (`JL0003`) |
 | `Zip` | — no positional co-iteration in the grammar | unsupported (`JL0006`) | — |
 | expression methods | `eq ne lt le gt ge` → `$eq…$ge`; `and or not`; `add sub mul div idiv mod neg`; `startsWith endsWith contains matches upper lower length concat substring replace` → §8.7; `count sum avg min max` → §8.8 (aggregates as expressions, e.g. over a group); `year month day epoch` → §8.13; `exists isEmpty`; `at all get` | native | on `Expr<…>`, per the typed-surface order |
-| spatial family (§8.14) | — surface deferred to the relational order; hand-write the document (`fromDocument`) today | unsupported (`JL0006`-adjacent: no methods exist yet) | — |
+| spatial family (§8.14) | `bbox geoArea geoLength centroid` → `$bbox $area $length $centroid`; `distance within bboxIntersects` → `$distance $within $bbox-intersects`; `geohash(precision?)` → `$geohash` (optional arity, like `substring`); `geoParse geoText geohashBounds geohashNeighbours` → the conversion family; `geoSimplify(tolerance)` → `$geo-simplify`. A plain JSON polygon embeds as a literal (`p.at.within(poly)`); `.params({ region })` makes it an external instead | native | on `Expr<…>`, per the typed-surface order |
+
+Two spatial names are deliberately not the obvious ones, and the reason
+is the same one that made §8.14's `$length` and §8.7's `$string-length`
+two operators: **`length` on this surface is already `$string-length`**,
+and §8.14's `$length` is a geodesic line measurement. One method name
+cannot carry both, and renaming the shipped string method for symmetry
+would break a published surface for a cosmetic gain — so the spatial one
+is **`geoLength`**, and **`geoArea`** joins it, because a bare `area()`
+on an arbitrary expression reads as arithmetic to a C# eye. The prefix
+names the family the way `geoParse`/`geoText` already do.
+
+Every method name shadows a data member of the same name — that is what
+the null prototype on the method table is for, and what `get(name)`
+escapes. A position stored as `at` is the case that bites: `p.at` is the
+index method, so it reads `p.get('at').within(region)`.
 
 ## 5. Deferred execution and re-enumeration
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/linq",
   "private": false,
-  "version": "0.34.2",
+  "version": "0.43.3",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -47,7 +47,7 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.34.2",
-    "@jarenjs/json": "^0.34.2"
+    "@jarenjs/core": "^0.43.3",
+    "@jarenjs/json": "^0.43.3"
   }
 }

package/src/expression.js

@@ -216,6 +216,27 @@ const METHODS = {
   // arrives with the relational order)
   year: unary('$year'), month: unary('$month'), day: unary('$day'),
   epoch: unary('$epoch'),
+  // §8.14 spatial. `geoArea`/`geoLength` rather than `area`/`length`:
+  // `length` is already `$string-length` on this surface and renaming a
+  // shipped method for symmetry is a breaking change for a cosmetic
+  // gain, while a bare `area()` on an arbitrary expression reads as
+  // arithmetic. The prefix names the family the way `geoParse`/`geoText`
+  // do, and it is the same reason `$length` and `$string-length` are two
+  // operators in the first place.
+  bbox: unary('$bbox'), geoArea: unary('$area'),
+  geoLength: unary('$length'), centroid: unary('$centroid'),
+  distance: binary('$distance'), within: binary('$within'),
+  bboxIntersects: binary('$bbox-intersects'),
+  geoParse: unary('$geo-parse'), geoText: unary('$geo-text'),
+  geohashBounds: unary('$geohash-bounds'),
+  geohashNeighbours: unary('$geohash-neighbours'),
+  geoSimplify: binary('$geo-simplify'),
+  geohash(record, precision) {
+    const args = precision === undefined
+      ? record.doc
+      : [record.doc, toExpression(precision)];
+    return makeExpr({ $geohash: args }, record.epoch, false);
+  },
   // path navigation
   at(record, index) {
     if (record.pathable && Number.isInteger(index)) {