@gridworkjs/query 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 gridworkjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+<p align="center">
+  <img src="logo.svg" width="256" height="256" alt="@gridworkjs/query">
+</p>
+
+<h1 align="center">@gridworkjs/query</h1>
+
+<p align="center">Higher-level spatial queries against any gridwork index</p>
+
+## Install
+
+```
+npm install @gridworkjs/query
+```
+
+## Why
+
+Spatial indexes give you `search()` (rectangular intersection) and `nearest()` (k closest items). But real applications need more: circular radius searches, raycasting, containment checks, distance-annotated results, filtered nearest-neighbor. This package provides those queries as standalone functions that work with any gridwork index.
+
+## Usage
+
+Every query function takes a spatial index as its first argument. The index carries its own accessor, so you never pass it twice.
+
+```js
+import { radius, knn, ray, within } from '@gridworkjs/query'
+import { createQuadtree } from '@gridworkjs/quadtree'
+import { point, rect, bounds } from '@gridworkjs/core'
+
+const tree = createQuadtree(entity => bounds(entity.position))
+tree.insert({ id: 'player', position: point(100, 200), hp: 80 })
+tree.insert({ id: 'enemy-1', position: point(120, 210), hp: 50 })
+tree.insert({ id: 'enemy-2', position: point(400, 100), hp: 90 })
+tree.insert({ id: 'chest', position: point(105, 195), hp: null })
+```
+
+### Radius - "What's near me?"
+
+Find all entities within 50 units of the player. A tower defense game checking which enemies are in range:
+
+```js
+const inRange = radius(tree, { x: 100, y: 200 }, 50)
+// => [{ item: { id: 'chest', ... }, distance: 7.07 },
+//     { item: { id: 'enemy-1', ... }, distance: 22.36 }]
+
+for (const { item, distance } of inRange) {
+  if (item.hp != null) dealDamage(item, falloff(distance))
+}
+```
+
+### KNN - "What's closest?"
+
+Find the 3 nearest items to a point, but only enemies, and only within 200 units. An AI deciding which target to engage:
+
+```js
+const targets = knn(tree, { x: 100, y: 200 }, 3, {
+  maxDistance: 200,
+  filter: item => item.id.startsWith('enemy')
+})
+// => [{ item: { id: 'enemy-1', ... }, distance: 22.36 }]
+
+const primary = targets[0]?.item
+```
+
+### Ray - "What does this line hit?"
+
+Cast a ray from the player eastward. A bullet, a line of sight check, or a laser:
+
+```js
+const hits = ray(tree, { x: 100, y: 200 }, { x: 1, y: 0 })
+// => [{ item: { id: 'chest', ... }, distance: 5 },
+//     { item: { id: 'enemy-2', ... }, distance: 300 }]
+
+const firstHit = hits[0]?.item
+```
+
+### Within - "What's fully inside this area?"
+
+Find all entities completely contained in a selection rectangle. A strategy game box-selecting units:
+
+```js
+const selected = within(tree, rect(90, 190, 130, 220))
+// => [{ id: 'player', ... }, { id: 'chest', ... }, { id: 'enemy-1', ... }]
+```
+
+## API
+
+### `radius(index, point, r, options?)`
+
+Find all items within distance `r` of a point. Returns `{ item, distance }[]` sorted by distance ascending.
+
+- `index` - any spatial index implementing the gridwork protocol
+- `point` - `{ x, y }` center point
+- `r` - search radius (non-negative)
+- `options.filter` - optional predicate to filter results
+
+### `knn(index, point, k, options?)`
+
+Find the `k` nearest items to a point with distance annotations. Returns `{ item, distance }[]` sorted by distance ascending.
+
+- `index` - any spatial index implementing the gridwork protocol
+- `point` - `{ x, y }` query point
+- `k` - number of nearest neighbors (positive integer)
+- `options.maxDistance` - exclude items farther than this distance
+- `options.filter` - predicate to filter candidates
+
+### `ray(index, origin, direction, options?)`
+
+Cast a ray and find all items it intersects. Returns `{ item, distance }[]` sorted by distance along the ray.
+
+- `index` - any spatial index implementing the gridwork protocol
+- `origin` - `{ x, y }` ray starting point
+- `direction` - `{ x, y }` direction vector (automatically normalized)
+- `options.maxDistance` - maximum ray length
+
+### `within(index, region)`
+
+Find all items fully contained within a region. Unlike `search()` which returns items that intersect, `within()` requires complete containment. Returns plain items (no distance annotation).
+
+- `index` - any spatial index implementing the gridwork protocol
+- `region` - bounds object, or any gridwork geometry (point, rect, circle)
+
+## Works with Any Gridwork Index
+
+These functions accept any object implementing the gridwork spatial index protocol. Use whichever index fits your data:
+
+- `@gridworkjs/quadtree` - dynamic, sparse data
+- `@gridworkjs/rtree` - rectangles, bulk loading
+- `@gridworkjs/hashgrid` - uniform distributions
+- `@gridworkjs/kd` - static point sets
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@gridworkjs/query",
+  "version": "1.0.0",
+  "description": "Higher-level spatial queries against any gridwork index",
+  "type": "module",
+  "main": "src/index.js",
+  "types": "./types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./src/index.js"
+    }
+  },
+  "scripts": {
+    "test": "node --test",
+    "prepublishOnly": "npx tsc --declaration --allowJs --emitDeclarationOnly --skipLibCheck --target es2020 --module nodenext --moduleResolution nodenext --strict false --esModuleInterop true --outDir ./types src/index.js"
+  },
+  "keywords": [
+    "spatial",
+    "query",
+    "knn",
+    "radius",
+    "raycast",
+    "containment",
+    "spatial-index",
+    "gridwork"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gridworkjs/query.git"
+  },
+  "files": [
+    "src/",
+    "types/"
+  ],
+  "dependencies": {
+    "@gridworkjs/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "@gridworkjs/quadtree": "file:../quadtree",
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.js

@@ -0,0 +1,4 @@
+export { radius } from './radius.js'
+export { knn } from './knn.js'
+export { ray } from './ray.js'
+export { within } from './within.js'

package/src/knn.js

@@ -0,0 +1,66 @@
+import { bounds, distanceToPoint } from '@gridworkjs/core/bounds'
+import { validateIndex, validateFiniteNumber } from './validate.js'
+
+/**
+ * Enhanced k-nearest-neighbor query with maxDistance and filter support.
+ * Returns { item, distance }[] sorted by distance ascending.
+ *
+ * @param {object} index - A spatial index implementing the gridwork protocol
+ * @param {{ x: number, y: number }} point - Query point
+ * @param {number} k - Number of nearest neighbors to find
+ * @param {{ maxDistance?: number, filter?: function }} [options]
+ * @returns {{ item: any, distance: number }[]}
+ */
+export function knn(index, point, k, options) {
+  validateIndex(index)
+  validateFiniteNumber(point.x, 'point.x')
+  validateFiniteNumber(point.y, 'point.y')
+
+  if (typeof k !== 'number' || !Number.isInteger(k)) {
+    throw new Error('k must be an integer')
+  }
+  if (k <= 0) return []
+
+  const accessor = index.accessor
+  const maxDistance = options && options.maxDistance
+  const filter = options && options.filter
+
+  if (maxDistance !== undefined && maxDistance !== null) {
+    validateFiniteNumber(maxDistance, 'maxDistance')
+    if (maxDistance < 0) throw new Error('maxDistance must be non-negative')
+  }
+
+  const candidates = index.nearest(point, filter ? k * 4 : k)
+  const results = []
+
+  for (let i = 0; i < candidates.length && results.length < k; i++) {
+    const item = candidates[i]
+    const b = bounds(accessor(item))
+    const dist = distanceToPoint(b, point.x, point.y)
+
+    if (maxDistance != null && dist > maxDistance) break
+
+    if (!filter || filter(item)) {
+      results.push({ item, distance: dist })
+    }
+  }
+
+  if (filter && results.length < k && candidates.length > 0) {
+    const allItems = index.nearest(point, index.size)
+    results.length = 0
+
+    for (let i = 0; i < allItems.length && results.length < k; i++) {
+      const item = allItems[i]
+      const b = bounds(accessor(item))
+      const dist = distanceToPoint(b, point.x, point.y)
+
+      if (maxDistance != null && dist > maxDistance) break
+
+      if (filter(item)) {
+        results.push({ item, distance: dist })
+      }
+    }
+  }
+
+  return results
+}

package/src/radius.js

@@ -0,0 +1,48 @@
+import { bounds, distanceToPoint } from '@gridworkjs/core/bounds'
+import { validateIndex, validateFiniteNumber } from './validate.js'
+
+/**
+ * Find all items within a given radius of a point.
+ * Returns { item, distance }[] sorted by distance ascending.
+ *
+ * @param {object} index - A spatial index implementing the gridwork protocol
+ * @param {{ x: number, y: number }} point - Center point
+ * @param {number} r - Search radius
+ * @param {{ filter?: function }} [options]
+ * @returns {{ item: any, distance: number }[]}
+ */
+export function radius(index, point, r, options) {
+  validateIndex(index)
+  validateFiniteNumber(point.x, 'point.x')
+  validateFiniteNumber(point.y, 'point.y')
+  validateFiniteNumber(r, 'radius')
+
+  if (r < 0) throw new Error('radius must be non-negative')
+  if (r === 0) return []
+
+  const accessor = index.accessor
+  const searchBounds = {
+    minX: point.x - r,
+    minY: point.y - r,
+    maxX: point.x + r,
+    maxY: point.y + r
+  }
+
+  const candidates = index.search(searchBounds)
+  const filter = options && options.filter
+  const results = []
+
+  for (let i = 0; i < candidates.length; i++) {
+    const item = candidates[i]
+    const b = bounds(accessor(item))
+    const dist = distanceToPoint(b, point.x, point.y)
+    if (dist <= r) {
+      if (!filter || filter(item)) {
+        results.push({ item, distance: dist })
+      }
+    }
+  }
+
+  results.sort((a, b) => a.distance - b.distance)
+  return results
+}

package/src/ray.js

@@ -0,0 +1,102 @@
+import { bounds } from '@gridworkjs/core/bounds'
+import { validateIndex, validateFiniteNumber } from './validate.js'
+
+/**
+ * Cast a ray through a spatial index and find all items it intersects.
+ * Returns { item, distance }[] sorted by distance along the ray.
+ *
+ * @param {object} index - A spatial index implementing the gridwork protocol
+ * @param {{ x: number, y: number }} origin - Ray origin point
+ * @param {{ x: number, y: number }} direction - Ray direction vector (will be normalized)
+ * @param {{ maxDistance?: number }} [options]
+ * @returns {{ item: any, distance: number }[]}
+ */
+export function ray(index, origin, direction, options) {
+  validateIndex(index)
+  validateFiniteNumber(origin.x, 'origin.x')
+  validateFiniteNumber(origin.y, 'origin.y')
+  validateFiniteNumber(direction.x, 'direction.x')
+  validateFiniteNumber(direction.y, 'direction.y')
+
+  const len = Math.sqrt(direction.x * direction.x + direction.y * direction.y)
+  if (len === 0) throw new Error('direction vector must be non-zero')
+
+  const dx = direction.x / len
+  const dy = direction.y / len
+
+  const maxDist = (options && options.maxDistance) || Infinity
+  if (options && options.maxDistance !== undefined) {
+    validateFiniteNumber(options.maxDistance, 'maxDistance')
+    if (options.maxDistance < 0) throw new Error('maxDistance must be non-negative')
+  }
+
+  const indexBounds = index.bounds
+  if (!indexBounds) return []
+
+  const accessor = index.accessor
+  const searchBounds = raySearchBounds(origin, dx, dy, maxDist, indexBounds)
+  const candidates = index.search(searchBounds)
+  const results = []
+
+  for (let i = 0; i < candidates.length; i++) {
+    const item = candidates[i]
+    const b = bounds(accessor(item))
+    const t = rayIntersectsAABB(origin, dx, dy, b)
+
+    if (t !== null && t <= maxDist) {
+      results.push({ item, distance: t })
+    }
+  }
+
+  results.sort((a, b) => a.distance - b.distance)
+  return results
+}
+
+function raySearchBounds(origin, dx, dy, maxDist, indexBounds) {
+  let endDist = maxDist
+  if (!Number.isFinite(endDist)) {
+    const w = indexBounds.maxX - indexBounds.minX
+    const h = indexBounds.maxY - indexBounds.minY
+    endDist = Math.sqrt(w * w + h * h) * 2
+  }
+
+  const endX = origin.x + dx * endDist
+  const endY = origin.y + dy * endDist
+
+  return {
+    minX: Math.min(origin.x, endX),
+    minY: Math.min(origin.y, endY),
+    maxX: Math.max(origin.x, endX),
+    maxY: Math.max(origin.y, endY)
+  }
+}
+
+function rayIntersectsAABB(origin, dx, dy, box) {
+  let tmin = -Infinity
+  let tmax = Infinity
+
+  if (dx !== 0) {
+    let t1 = (box.minX - origin.x) / dx
+    let t2 = (box.maxX - origin.x) / dx
+    if (t1 > t2) { const tmp = t1; t1 = t2; t2 = tmp }
+    tmin = Math.max(tmin, t1)
+    tmax = Math.min(tmax, t2)
+  } else {
+    if (origin.x < box.minX || origin.x > box.maxX) return null
+  }
+
+  if (dy !== 0) {
+    let t1 = (box.minY - origin.y) / dy
+    let t2 = (box.maxY - origin.y) / dy
+    if (t1 > t2) { const tmp = t1; t1 = t2; t2 = tmp }
+    tmin = Math.max(tmin, t1)
+    tmax = Math.min(tmax, t2)
+  } else {
+    if (origin.y < box.minY || origin.y > box.maxY) return null
+  }
+
+  if (tmin > tmax) return null
+  if (tmax < 0) return null
+
+  return tmin >= 0 ? tmin : 0
+}

package/src/validate.js

@@ -0,0 +1,13 @@
+import { isSpatialIndex } from '@gridworkjs/core/protocol'
+
+export function validateIndex(index) {
+  if (!isSpatialIndex(index)) {
+    throw new Error('first argument must be a spatial index')
+  }
+}
+
+export function validateFiniteNumber(value, name) {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    throw new Error(`${name} must be a finite number`)
+  }
+}

package/src/within.js

@@ -0,0 +1,29 @@
+import { bounds, contains } from '@gridworkjs/core/bounds'
+import { validateIndex } from './validate.js'
+
+/**
+ * Find all items fully contained within a region.
+ * Unlike search() which returns items that intersect, within() requires full containment.
+ *
+ * @param {object} index - A spatial index implementing the gridwork protocol
+ * @param {object} region - Bounding region (bounds object or geometry)
+ * @returns {any[]}
+ */
+export function within(index, region) {
+  validateIndex(index)
+
+  const accessor = index.accessor
+  const regionBounds = bounds(region)
+  const candidates = index.search(regionBounds)
+  const results = []
+
+  for (let i = 0; i < candidates.length; i++) {
+    const item = candidates[i]
+    const b = bounds(accessor(item))
+    if (contains(regionBounds, b)) {
+      results.push(item)
+    }
+  }
+
+  return results
+}

package/types/index.d.ts

@@ -0,0 +1,4 @@
+export { radius } from "./radius.js";
+export { knn } from "./knn.js";
+export { ray } from "./ray.js";
+export { within } from "./within.js";

package/types/knn.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Enhanced k-nearest-neighbor query with maxDistance and filter support.
+ * Returns { item, distance }[] sorted by distance ascending.
+ *
+ * @param {object} index - A spatial index implementing the gridwork protocol
+ * @param {{ x: number, y: number }} point - Query point
+ * @param {number} k - Number of nearest neighbors to find
+ * @param {{ maxDistance?: number, filter?: function }} [options]
+ * @returns {{ item: any, distance: number }[]}
+ */
+export function knn(index: object, point: {
+    x: number;
+    y: number;
+}, k: number, options?: {
+    maxDistance?: number;
+    filter?: Function;
+}): {
+    item: any;
+    distance: number;
+}[];

package/types/radius.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Find all items within a given radius of a point.
+ * Returns { item, distance }[] sorted by distance ascending.
+ *
+ * @param {object} index - A spatial index implementing the gridwork protocol
+ * @param {{ x: number, y: number }} point - Center point
+ * @param {number} r - Search radius
+ * @param {{ filter?: function }} [options]
+ * @returns {{ item: any, distance: number }[]}
+ */
+export function radius(index: object, point: {
+    x: number;
+    y: number;
+}, r: number, options?: {
+    filter?: Function;
+}): {
+    item: any;
+    distance: number;
+}[];

package/types/ray.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Cast a ray through a spatial index and find all items it intersects.
+ * Returns { item, distance }[] sorted by distance along the ray.
+ *
+ * @param {object} index - A spatial index implementing the gridwork protocol
+ * @param {{ x: number, y: number }} origin - Ray origin point
+ * @param {{ x: number, y: number }} direction - Ray direction vector (will be normalized)
+ * @param {{ maxDistance?: number }} [options]
+ * @returns {{ item: any, distance: number }[]}
+ */
+export function ray(index: object, origin: {
+    x: number;
+    y: number;
+}, direction: {
+    x: number;
+    y: number;
+}, options?: {
+    maxDistance?: number;
+}): {
+    item: any;
+    distance: number;
+}[];

package/types/validate.d.ts

@@ -0,0 +1,2 @@
+export function validateIndex(index: any): void;
+export function validateFiniteNumber(value: any, name: any): void;

package/types/within.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Find all items fully contained within a region.
+ * Unlike search() which returns items that intersect, within() requires full containment.
+ *
+ * @param {object} index - A spatial index implementing the gridwork protocol
+ * @param {object} region - Bounding region (bounds object or geometry)
+ * @returns {any[]}
+ */
+export function within(index: object, region: object): any[];