@gridworkjs/quadtree 1.0.0

package/README.md

@@ -0,0 +1,98 @@
+<p align="center">
+  <img src="logo.svg" width="256" height="256" alt="@gridworkjs/quadtree">
+</p>
+
+<h1 align="center">@gridworkjs/quadtree</h1>
+
+<p align="center">quadtree spatial index for sparse, uneven point and region data</p>
+
+## install
+
+```
+npm install @gridworkjs/quadtree
+```
+
+## usage
+
+```js
+import { createQuadtree } from '@gridworkjs/quadtree'
+import { point, rect, bounds } from '@gridworkjs/core'
+
+// create a quadtree with a bounds accessor
+const tree = createQuadtree(item => bounds(item.position))
+
+// insert items - any shape, the accessor extracts bounds
+tree.insert({ id: 1, position: point(10, 20) })
+tree.insert({ id: 2, position: point(50, 60) })
+tree.insert({ id: 3, position: rect(70, 70, 90, 90) })
+
+// search for items intersecting a region
+tree.search({ minX: 0, minY: 0, maxX: 55, maxY: 65 })
+// => [{ id: 1, ... }, { id: 2, ... }]
+
+// also accepts geometry objects as queries
+tree.search(rect(0, 0, 55, 65))
+
+// find nearest neighbors
+tree.nearest({ x: 12, y: 22 }, 2)
+// => [{ id: 1, ... }, { id: 2, ... }]
+
+// remove by identity
+tree.remove(item)
+
+tree.size   // number of items
+tree.bounds // current root bounds
+tree.clear()
+```
+
+## options
+
+```js
+createQuadtree(accessor, {
+  bounds: { minX: 0, minY: 0, maxX: 1000, maxY: 1000 }, // world bounds (optional, auto-grows)
+  maxItems: 16,  // items per node before splitting
+  maxDepth: 8    // maximum tree depth
+})
+```
+
+If `bounds` is omitted, the tree auto-creates bounds from the first insert and grows as needed.
+
+## API
+
+### `createQuadtree(accessor, options?)`
+
+Creates a new quadtree. The `accessor` function maps each item to its bounding box (`{ minX, minY, maxX, maxY }`). Use `bounds()` from `@gridworkjs/core` to convert geometries.
+
+Returns a spatial index implementing the gridwork protocol.
+
+### `index.insert(item)`
+
+Adds an item to the tree.
+
+### `index.remove(item)`
+
+Removes an item by identity (`===`). Returns `true` if found and removed.
+
+### `index.search(query)`
+
+Returns all items whose bounds intersect the query. Accepts bounds objects or geometry objects (point, rect, circle).
+
+### `index.nearest(point, k?)`
+
+Returns the `k` nearest items to the given point, sorted by distance. Defaults to `k=1`. Accepts `{ x, y }` or a point geometry.
+
+### `index.clear()`
+
+Removes all items. Preserves fixed bounds if provided at construction.
+
+### `index.size`
+
+Number of items in the tree.
+
+### `index.bounds`
+
+Current root bounds, or `null` if empty and no fixed bounds were set.
+
+## license
+
+MIT

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@gridworkjs/quadtree",
+  "version": "1.0.0",
+  "description": "quadtree spatial index for sparse, uneven point and region data",
+  "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": [
+    "quadtree",
+    "spatial",
+    "spatial-index",
+    "gridwork",
+    "point",
+    "region",
+    "search",
+    "nearest-neighbor"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gridworkjs/quadtree.git"
+  },
+  "files": [
+    "src/",
+    "types/"
+  ],
+  "dependencies": {
+    "@gridworkjs/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/index.js

@@ -0,0 +1 @@
+export { createQuadtree } from './quadtree.js'

package/src/quadtree.js

@@ -0,0 +1,312 @@
+import {
+  SPATIAL_INDEX, bounds as toBounds,
+  intersects, contains, distanceToPoint
+} from '@gridworkjs/core'
+
+/**
+ * @typedef {{ minX: number, minY: number, maxX: number, maxY: number }} Bounds
+ * @typedef {{ x: number, y: number }} Point
+ * @typedef {(item: T) => Bounds} Accessor
+ * @template T
+ */
+
+/**
+ * @typedef {object} QuadtreeOptions
+ * @property {Bounds} [bounds] - fixed world bounds (auto-grows if omitted)
+ * @property {number} [maxItems=16] - items per node before splitting
+ * @property {number} [maxDepth=8] - maximum tree depth
+ */
+
+/**
+ * @typedef {object} SpatialIndex
+ * @property {true} [SPATIAL_INDEX]
+ * @property {number} size
+ * @property {Bounds | null} bounds
+ * @property {(item: any) => void} insert
+ * @property {(item: any) => boolean} remove
+ * @property {(query: Bounds | object) => any[]} search
+ * @property {(point: Point, k?: number) => any[]} nearest
+ * @property {() => void} clear
+ */
+
+function createNode(bounds) {
+  return { bounds, items: [], children: null }
+}
+
+function childBounds(bounds) {
+  const midX = (bounds.minX + bounds.maxX) / 2
+  const midY = (bounds.minY + bounds.maxY) / 2
+  return [
+    { minX: bounds.minX, minY: bounds.minY, maxX: midX, maxY: midY },
+    { minX: midX, minY: bounds.minY, maxX: bounds.maxX, maxY: midY },
+    { minX: bounds.minX, minY: midY, maxX: midX, maxY: bounds.maxY },
+    { minX: midX, minY: midY, maxX: bounds.maxX, maxY: bounds.maxY }
+  ]
+}
+
+function split(node, maxItems, maxDepth, depth) {
+  const quads = childBounds(node.bounds)
+  node.children = quads.map(b => createNode(b))
+
+  const kept = []
+  for (const entry of node.items) {
+    if (!pushDown(node.children, entry, maxItems, maxDepth, depth + 1)) {
+      kept.push(entry)
+    }
+  }
+  node.items = kept
+}
+
+function pushDown(children, entry, maxItems, maxDepth, depth) {
+  for (const child of children) {
+    if (contains(child.bounds, entry.bounds)) {
+      insertEntry(child, entry, maxItems, maxDepth, depth)
+      return true
+    }
+  }
+  return false
+}
+
+function insertEntry(node, entry, maxItems, maxDepth, depth) {
+  if (node.children) {
+    if (!pushDown(node.children, entry, maxItems, maxDepth, depth + 1)) {
+      node.items.push(entry)
+    }
+    return
+  }
+
+  node.items.push(entry)
+
+  if (node.items.length > maxItems && depth < maxDepth) {
+    split(node, maxItems, maxDepth, depth)
+  }
+}
+
+function searchNode(node, query, results) {
+  if (!intersects(node.bounds, query)) return
+
+  for (const entry of node.items) {
+    if (intersects(entry.bounds, query)) {
+      results.push(entry.item)
+    }
+  }
+
+  if (node.children) {
+    for (const child of node.children) {
+      searchNode(child, query, results)
+    }
+  }
+}
+
+function removeEntry(node, item, itemBounds) {
+  const idx = node.items.findIndex(e => e.item === item)
+  if (idx !== -1) {
+    node.items.splice(idx, 1)
+    return true
+  }
+
+  if (node.children) {
+    for (const child of node.children) {
+      if (intersects(child.bounds, itemBounds)) {
+        if (removeEntry(child, item, itemBounds)) {
+          tryCollapse(node)
+          return true
+        }
+      }
+    }
+  }
+
+  return false
+}
+
+function tryCollapse(node) {
+  if (!node.children) return
+  let total = node.items.length
+  for (const child of node.children) {
+    if (child.children) return
+    total += child.items.length
+  }
+  if (total === 0) {
+    node.children = null
+  }
+}
+
+function growToContain(root, target) {
+  while (!contains(root.bounds, target)) {
+    const { minX, minY, maxX, maxY } = root.bounds
+    const w = Math.max(maxX - minX, 1)
+    const h = Math.max(maxY - minY, 1)
+
+    const tcx = (target.minX + target.maxX) / 2
+    const rcx = (minX + maxX) / 2
+    const tcy = (target.minY + target.maxY) / 2
+    const rcy = (minY + maxY) / 2
+
+    let newBounds, quadrant
+
+    if (tcx < rcx && tcy < rcy) {
+      newBounds = { minX: minX - w, minY: minY - h, maxX, maxY }
+      quadrant = 3
+    } else if (tcx >= rcx && tcy < rcy) {
+      newBounds = { minX, minY: minY - h, maxX: maxX + w, maxY }
+      quadrant = 2
+    } else if (tcx < rcx && tcy >= rcy) {
+      newBounds = { minX: minX - w, minY, maxX, maxY: maxY + h }
+      quadrant = 1
+    } else {
+      newBounds = { minX, minY, maxX: maxX + w, maxY: maxY + h }
+      quadrant = 0
+    }
+
+    const newRoot = createNode(newBounds)
+    const quads = childBounds(newBounds)
+    newRoot.children = quads.map((b, i) => i === quadrant ? root : createNode(b))
+    root = newRoot
+  }
+  return root
+}
+
+function normalizeBounds(input) {
+  if (input != null && typeof input === 'object' &&
+      'minX' in input && 'minY' in input && 'maxX' in input && 'maxY' in input) {
+    return input
+  }
+  return toBounds(input)
+}
+
+function heapPush(heap, entry) {
+  heap.push(entry)
+  let i = heap.length - 1
+  while (i > 0) {
+    const p = (i - 1) >> 1
+    if (heap[p].dist <= heap[i].dist) break
+    ;[heap[p], heap[i]] = [heap[i], heap[p]]
+    i = p
+  }
+}
+
+function heapPop(heap) {
+  const top = heap[0]
+  const last = heap.pop()
+  if (heap.length > 0) {
+    heap[0] = last
+    let i = 0
+    for (;;) {
+      let s = i
+      const l = 2 * i + 1
+      const r = 2 * i + 2
+      if (l < heap.length && heap[l].dist < heap[s].dist) s = l
+      if (r < heap.length && heap[r].dist < heap[s].dist) s = r
+      if (s === i) break
+      ;[heap[i], heap[s]] = [heap[s], heap[i]]
+      i = s
+    }
+  }
+  return top
+}
+
+function nearestSearch(root, px, py, k) {
+  if (!root || k <= 0) return []
+
+  const results = []
+  const heap = []
+
+  heapPush(heap, { kind: 'node', node: root, dist: distanceToPoint(root.bounds, px, py) })
+
+  while (heap.length > 0 && results.length < k) {
+    const cur = heapPop(heap)
+
+    if (cur.kind === 'item') {
+      results.push(cur.item)
+      continue
+    }
+
+    const node = cur.node
+
+    for (const entry of node.items) {
+      heapPush(heap, { kind: 'item', item: entry.item, dist: distanceToPoint(entry.bounds, px, py) })
+    }
+
+    if (node.children) {
+      for (const child of node.children) {
+        heapPush(heap, { kind: 'node', node: child, dist: distanceToPoint(child.bounds, px, py) })
+      }
+    }
+  }
+
+  return results
+}
+
+/**
+ * Creates a quadtree spatial index.
+ *
+ * @param {(item: any) => Bounds} accessor - maps items to their bounding boxes
+ * @param {QuadtreeOptions} [options]
+ * @returns {SpatialIndex}
+ */
+export function createQuadtree(accessor, options = {}) {
+  const maxItems = options.maxItems ?? 16
+  const maxDepth = options.maxDepth ?? 8
+  const fixedBounds = options.bounds ? normalizeBounds(options.bounds) : null
+
+  let root = fixedBounds ? createNode(fixedBounds) : null
+  let size = 0
+
+  const index = {
+    [SPATIAL_INDEX]: true,
+
+    get size() { return size },
+
+    get bounds() { return root ? root.bounds : null },
+
+    insert(item) {
+      const itemBounds = accessor(item)
+      const entry = { item, bounds: itemBounds }
+
+      if (!root) {
+        const { minX, minY, maxX, maxY } = itemBounds
+        const w = Math.max(maxX - minX, 1)
+        const h = Math.max(maxY - minY, 1)
+        root = createNode({
+          minX: minX - w, minY: minY - h,
+          maxX: maxX + w, maxY: maxY + h
+        })
+      }
+
+      if (!contains(root.bounds, itemBounds)) {
+        root = growToContain(root, itemBounds)
+      }
+
+      insertEntry(root, entry, maxItems, maxDepth, 0)
+      size++
+    },
+
+    remove(item) {
+      if (!root) return false
+      const itemBounds = accessor(item)
+      const removed = removeEntry(root, item, itemBounds)
+      if (removed) size--
+      return removed
+    },
+
+    search(query) {
+      if (!root) return []
+      const queryBounds = normalizeBounds(query)
+      const results = []
+      searchNode(root, queryBounds, results)
+      return results
+    },
+
+    nearest(point, k = 1) {
+      if (!root) return []
+      return nearestSearch(root, point.x, point.y, k)
+    },
+
+    clear() {
+      root = fixedBounds ? createNode(fixedBounds) : null
+      size = 0
+    }
+  }
+
+  return index
+}

package/types/index.d.ts

@@ -0,0 +1 @@
+export { createQuadtree } from "./quadtree.js";

package/types/quadtree.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Creates a quadtree spatial index.
+ *
+ * @param {(item: any) => Bounds} accessor - maps items to their bounding boxes
+ * @param {QuadtreeOptions} [options]
+ * @returns {SpatialIndex}
+ */
+export function createQuadtree(accessor: (item: any) => Bounds, options?: QuadtreeOptions): SpatialIndex;
+export type Bounds<T> = {
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+};
+export type Point<T> = {
+    x: number;
+    y: number;
+};
+export type Accessor<T> = (item: T) => Bounds;
+export type QuadtreeOptions = {
+    /**
+     * - fixed world bounds (auto-grows if omitted)
+     */
+    bounds?: Bounds;
+    /**
+     * - items per node before splitting
+     */
+    maxItems?: number;
+    /**
+     * - maximum tree depth
+     */
+    maxDepth?: number;
+};
+export type SpatialIndex = {
+    SPATIAL_INDEX?: true;
+    size: number;
+    bounds: Bounds | null;
+    insert: (item: any) => void;
+    remove: (item: any) => boolean;
+    search: (query: Bounds | object) => any[];
+    nearest: (point: Point, k?: number) => any[];
+    clear: () => void;
+};