@pulseindex/sdk 4.0.0 → 4.0.1

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 4.0.1
+
+### The covering threshold, corrected against a real app
+
+`withinRadius` is a pre-filter the caller narrows exactly afterwards, so excess
+area is cheaper than predicates. 4.0.0's threshold was too strict: it rejected
+the coarse cell at 5 km, turning a 10-cell covering into 167. Measured through
+the sibling PHP SDK against a real application with 100,000 properties, a 5 km
+radius went from 3,082 µs to 926 µs on wall time — the cost is the request, not
+the search.
+
+The coarse cell is now taken up to 3.0× the circle, which still rejects it at
+2 km where it wastes 4.73× to 6.91×. Both SDKs are regenerated against one
+shared vector fixture, so they still agree cell for cell.
+
 ## 4.0.0
 
 **A major, not a minor.** The previous draft of these notes said 3.2.0. Checking

package/dist/index.d.mts

@@ -402,11 +402,17 @@ declare class GeoHash {
      * How much area outside the circle a covering may carry before a finer
      * precision is worth its cell count.
      *
-     * 2.0 is where the measured choices come out right at every radius: it
-     * rejects the coarse cell at 2 km (6.91x) and 5 km (2.76x) and accepts it at
-     * 15 km (1.44x), which is also where the cell count turns from 47 into 1,120.
+     * `withinRadius` is a pre-filter the caller narrows exactly afterwards, so
+     * excess area is cheaper than predicates.
+     *
+     * 2.0 was the first attempt and it was too strict. It rejected the coarse
+     * cell at 5 km, so a covering that had cost 10 cells cost 167, and the demo
+     * benchmark went from beating PostgreSQL to losing to it by 2.76x on wall
+     * time — the cost is the request, not the search. 3.0 keeps the cheap
+     * covering at 5 km (2.76x) and still rejects the coarse cell at 2 km, where
+     * it wastes 4.73x to 6.91x depending on latitude.
      */
-    static readonly ACCEPTABLE_COVER_RATIO = 2;
+    static readonly ACCEPTABLE_COVER_RATIO = 3;
     private static readonly NEIGHBORS;
     private static readonly BORDERS;
     static encode(lat: number, lon: number, precision?: number): string;

package/dist/index.d.ts

@@ -402,11 +402,17 @@ declare class GeoHash {
      * How much area outside the circle a covering may carry before a finer
      * precision is worth its cell count.
      *
-     * 2.0 is where the measured choices come out right at every radius: it
-     * rejects the coarse cell at 2 km (6.91x) and 5 km (2.76x) and accepts it at
-     * 15 km (1.44x), which is also where the cell count turns from 47 into 1,120.
+     * `withinRadius` is a pre-filter the caller narrows exactly afterwards, so
+     * excess area is cheaper than predicates.
+     *
+     * 2.0 was the first attempt and it was too strict. It rejected the coarse
+     * cell at 5 km, so a covering that had cost 10 cells cost 167, and the demo
+     * benchmark went from beating PostgreSQL to losing to it by 2.76x on wall
+     * time — the cost is the request, not the search. 3.0 keeps the cheap
+     * covering at 5 km (2.76x) and still rejects the coarse cell at 2 km, where
+     * it wastes 4.73x to 6.91x depending on latitude.
      */
-    static readonly ACCEPTABLE_COVER_RATIO = 2;
+    static readonly ACCEPTABLE_COVER_RATIO = 3;
     private static readonly NEIGHBORS;
     private static readonly BORDERS;
     static encode(lat: number, lon: number, precision?: number): string;

package/dist/index.js

@@ -65,11 +65,17 @@ var GeoHash = class {
    * How much area outside the circle a covering may carry before a finer
    * precision is worth its cell count.
    *
-   * 2.0 is where the measured choices come out right at every radius: it
-   * rejects the coarse cell at 2 km (6.91x) and 5 km (2.76x) and accepts it at
-   * 15 km (1.44x), which is also where the cell count turns from 47 into 1,120.
+   * `withinRadius` is a pre-filter the caller narrows exactly afterwards, so
+   * excess area is cheaper than predicates.
+   *
+   * 2.0 was the first attempt and it was too strict. It rejected the coarse
+   * cell at 5 km, so a covering that had cost 10 cells cost 167, and the demo
+   * benchmark went from beating PostgreSQL to losing to it by 2.76x on wall
+   * time — the cost is the request, not the search. 3.0 keeps the cheap
+   * covering at 5 km (2.76x) and still rejects the coarse cell at 2 km, where
+   * it wastes 4.73x to 6.91x depending on latitude.
    */
-  static ACCEPTABLE_COVER_RATIO = 2;
+  static ACCEPTABLE_COVER_RATIO = 3;
   static NEIGHBORS = {
     n: ["p0r21436x8zb9dcf5h7kjnmqesgutwvy", "bc01fg45238967deuvhjyznpkmstqrwx"],
     s: ["14365h7k9dcfesgujnmqp0r2twvyx8zb", "238967debc01fg45kmstqrwxuvhjyznp"],

package/dist/index.mjs

@@ -42,11 +42,17 @@ var GeoHash = class {
    * How much area outside the circle a covering may carry before a finer
    * precision is worth its cell count.
    *
-   * 2.0 is where the measured choices come out right at every radius: it
-   * rejects the coarse cell at 2 km (6.91x) and 5 km (2.76x) and accepts it at
-   * 15 km (1.44x), which is also where the cell count turns from 47 into 1,120.
+   * `withinRadius` is a pre-filter the caller narrows exactly afterwards, so
+   * excess area is cheaper than predicates.
+   *
+   * 2.0 was the first attempt and it was too strict. It rejected the coarse
+   * cell at 5 km, so a covering that had cost 10 cells cost 167, and the demo
+   * benchmark went from beating PostgreSQL to losing to it by 2.76x on wall
+   * time — the cost is the request, not the search. 3.0 keeps the cheap
+   * covering at 5 km (2.76x) and still rejects the coarse cell at 2 km, where
+   * it wastes 4.73x to 6.91x depending on latitude.
    */
-  static ACCEPTABLE_COVER_RATIO = 2;
+  static ACCEPTABLE_COVER_RATIO = 3;
   static NEIGHBORS = {
     n: ["p0r21436x8zb9dcf5h7kjnmqesgutwvy", "bc01fg45238967deuvhjyznpkmstqrwx"],
     s: ["14365h7k9dcfesgujnmqp0r2twvyx8zb", "238967debc01fg45kmstqrwxuvhjyznp"],

package/package.json

@@ -1,7 +1,11 @@
 {
   "name": "@pulseindex/sdk",
-  "version": "4.0.0",
-  "description": "Official Node.js & TypeScript SDK for PulseIndex — hosted search and filtering for large entity sets",
+  "version": "4.0.1",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mohammed-alfarra/pulseindex-js.git"
+  },
+  "description": "Official Node.js & TypeScript SDK for PulseIndex \u2014 hosted search and filtering for large entity sets",
   "license": "MIT",
   "author": "PulseIndex",
   "keywords": [