Add support for filtering to queryNearest

[mackinleysmith]

This PR adds filtering support to the queryNearest method, allowing users to filter results using the same filter builder API available in query. This addresses the feature request in #17 and the discussion in the Discord thread.

Changes

• Extended queryNearest signature: The method now accepts an options object that can include both maxDistance and filter parameters, while maintaining backwards compatibility with the existing numeric maxDistance parameter.
• Filter builder support: Users can now apply the same filter conditions available in query:
  • eq() - equality filters
  • in() - value in a set filters
  • gte() / lt() - sort key range filters
• Backend implementation: Updated nearestPoints query to accept filtering conditions and sorting intervals, passing them through to ClosestPointQuery.
• Documentation: Updated README with examples showing the new filtering capabilities.

Example Usage

const result = await geospatial.queryNearest(
  ctx,
  { latitude: 40.7813, longitude: -73.9737 },
  maxResults,
  {
    maxDistance: 10000,
    filter: (q) => q.eq("category", "coffee"),
  },
);

Benefits

• Filtering helps constrain the search space and can speed up lookups
• Consistent API with the existing query method
• Backwards compatible - existing code using numeric maxDistance continues to work
• Enables use cases like finding nearest points matching specific criteria (e.g., "nearest coffee shops" or "nearest available books")

Testing

• Added tests for must and should filter conditions in pointQuery.test.ts
• Verified sort key interval filtering works correctly
• Existing tests continue to pass

---

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[ianmacartney]

I’m planning to drop the cjs path and that statement entirely soon. Sorry it bit you!

…

On Thu, Nov 6, 2025 at 8:54 AM MacKinley Smith ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In package.json <#23 (comment)>: > @@ -23,8 +23,8 @@ "scripts": { "build": "npm run build:esm && npm run build:cjs", "build:go": "cd src/s2-bindings && python build.py", - "build:esm": "tsc --project ./esm.json && echo '{\\n \"type\": \"module\"\\n}' > dist/esm/package.json", - "build:cjs": "tsc --project ./commonjs.json && echo '{\\n \"type\": \"commonjs\"\\n}' > dist/commonjs/package.json", + "build:esm": "tsc --project ./esm.json && echo -e '{\n \"type\": \"module\"\n}' > dist/esm/package.json", Oof... turns out that echo -e is not supported on macOS, so I'm updating this to use a node script for full cross platform support. Another option is to use printf, but that might lose compatibility with Windows. I sure am shaving yaks today. — Reply to this email directly, view it on GitHub <#23 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACZQW64KT5JNGJV4M4EOOL33N4NZAVCNFSM6AAAAACLHWDVKSVHI2DSMVQWIX3LMV43YUDVNRWFEZLROVSXG5CSMV3GSZLXHMZTIMRZGM3DANRTGU> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[mackinleysmith]

Thank you for the approval, @sethconve! I have resolved the merge conflict on this branch and also opened another PR for my follow-on work to optimize the server-side aspect of this, #25. Please let me know if there's anything I can do to be helpful with getting this across the finish line. Cheers!