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.

[mackinleysmith]

This is something weird I had to do to get Vercel to build my fork without erroring out.

The error message I was getting was:

✘ [ERROR] Syntax error "n"
    ../../node_modules/.pnpm/@convex-dev+geospatial@https+++codeload.github.com+mackinleysmith+geospatial+tar.gz+071ac5f5d_veafjjmfdyevjqqmh7gvbjmbv4/node_modules/@convex-dev/geospatial/dist/esm/package.json:1:2:
      1 │ {\n  "type": "module"\n}
        ╵   ^
✖ esbuild failed: Error: Build failed with 1 error:
../../node_modules/.pnpm/@convex-dev+geospatial@https+++codeload.github.com+mackinleysmith+geospatial+tar.gz+071ac5f5d_veafjjmfdyevjqqmh7gvbjmbv4/node_modules/@convex-dev/geospatial/dist/esm/package.json:1:2: ERROR: Syntax error "n"
Error: Command "cd ../../packages/backend && pnpm dlx convex deploy --cmd 'cd ../.. && turbo run build' --cmd-url-env-var-name NEXT_PUBLIC_CONVEX_URL --check-build-environment disable" exited with 1

I'm definitely open to reverting this before merging if it presents some unforeseen consequence -- I am by no means attached to it.

@ianmacartney what do you think?

[mackinleysmith]

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.

[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: ***@***.***>