@gridworkjs/hashgrid 1.0.0

package/README.md

@@ -0,0 +1,102 @@
+<p align="center">
+  <img src="logo.svg" width="256" height="256" alt="@gridworkjs/hashgrid">
+</p>
+
+<h1 align="center">@gridworkjs/hashgrid</h1>
+
+<p align="center">Spatial hash grid for uniform distributions and fast neighbor lookups</p>
+
+## Install
+
+```
+npm install @gridworkjs/hashgrid
+```
+
+## Usage
+
+```js
+import { createHashGrid } from '@gridworkjs/hashgrid'
+import { point, rect, bounds } from '@gridworkjs/core'
+
+// create a hash grid - cellSize should match your data's density
+const grid = createHashGrid(item => bounds(item.position), { cellSize: 50 })
+
+// insert items
+grid.insert({ id: 1, position: point(10, 20) })
+grid.insert({ id: 2, position: point(50, 60) })
+grid.insert({ id: 3, position: rect(70, 70, 90, 90) })
+
+// search for items intersecting a region
+grid.search({ minX: 0, minY: 0, maxX: 55, maxY: 65 })
+// => [{ id: 1, ... }, { id: 2, ... }]
+
+// also accepts geometry objects as queries
+grid.search(rect(0, 0, 55, 65))
+
+// find nearest neighbors
+grid.nearest({ x: 12, y: 22 }, 2)
+// => [{ id: 1, ... }, { id: 2, ... }]
+
+// remove by identity
+grid.remove(item)
+
+grid.size   // number of items
+grid.bounds // bounding box of all items
+grid.clear()
+```
+
+## When to Use a Hash Grid
+
+Hash grids are ideal when your data is **uniformly distributed** and items are roughly the same size. They offer O(1) cell lookups, making them excellent for collision detection, particle systems, and game engines.
+
+If your data is clustered or varies widely in size, consider `@gridworkjs/quadtree` or `@gridworkjs/rtree` instead.
+
+## Choosing a Cell Size
+
+The `cellSize` parameter controls the width and height of each grid cell. For best performance:
+
+- Set `cellSize` to roughly the size of your items or the typical query range
+- Too small: items span many cells, increasing memory and insert cost
+- Too large: cells contain many items, reducing search selectivity
+
+## API
+
+### `createHashGrid(accessor, options)`
+
+Creates a new hash grid. The `accessor` function maps each item to its bounding box (`{ minX, minY, maxX, maxY }`). Use `bounds()` from `@gridworkjs/core` to convert geometries.
+
+The `cellSize` option is required.
+
+Returns a spatial index implementing the gridwork protocol.
+
+### `grid.insert(item)`
+
+Adds an item to the grid. The item is placed into every cell its bounding box overlaps.
+
+### `grid.remove(item)`
+
+Removes an item by identity (`===`). Returns `true` if found and removed.
+
+### `grid.search(query)`
+
+Returns all items whose bounds intersect the query. Accepts bounds objects or geometry objects (point, rect, circle).
+
+### `grid.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.
+
+### `grid.clear()`
+
+Removes all items from the grid.
+
+### `grid.size`
+
+Number of items in the grid.
+
+### `grid.bounds`
+
+Bounding box of all items, or `null` if empty.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@gridworkjs/hashgrid",
+  "version": "1.0.0",
+  "description": "Spatial hash grid for uniform distributions and fast neighbor lookups",
+  "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": [
+    "hashgrid",
+    "spatial-hash",
+    "spatial",
+    "spatial-index",
+    "gridwork",
+    "uniform",
+    "collision",
+    "search",
+    "nearest-neighbor"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gridworkjs/hashgrid.git"
+  },
+  "files": [
+    "src/",
+    "types/"
+  ],
+  "dependencies": {
+    "@gridworkjs/core": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  }
+}

package/src/hashgrid.js

@@ -0,0 +1,324 @@
+import {
+  SPATIAL_INDEX, bounds as toBounds,
+  intersects, 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} HashGridOptions
+ * @property {number} cellSize - Width and height of each grid cell
+ */
+
+function validateAccessorBounds(b) {
+  if (b === null || typeof b !== 'object') {
+    throw new Error('accessor must return a bounds object')
+  }
+  if (!Number.isFinite(b.minX) || !Number.isFinite(b.minY) ||
+      !Number.isFinite(b.maxX) || !Number.isFinite(b.maxY)) {
+    throw new Error('accessor returned non-finite bounds')
+  }
+  if (b.minX > b.maxX || b.minY > b.maxY) {
+    throw new Error('accessor returned inverted bounds (minX > maxX or minY > maxY)')
+  }
+}
+
+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 cellKey(cx, cy) {
+  return cx + ',' + cy
+}
+
+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
+}
+
+/**
+ * Creates a spatial hash grid index.
+ *
+ * @param {(item: any) => Bounds | object} accessor - Maps items to their bounding boxes or geometries
+ * @param {HashGridOptions} options
+ * @returns {import('@gridworkjs/core').SpatialIndex}
+ */
+export function createHashGrid(accessor, options = {}) {
+  const cellSize = options.cellSize
+
+  if (cellSize == null) {
+    throw new Error('cellSize is required')
+  }
+  if (!Number.isFinite(cellSize) || cellSize <= 0) {
+    throw new Error('cellSize must be a positive finite number')
+  }
+  if (typeof accessor !== 'function') {
+    throw new Error('accessor must be a function')
+  }
+
+  const invCellSize = 1 / cellSize
+  const cells = new Map()
+  let size = 0
+  let totalBounds = null
+
+  function toCell(v) {
+    return Math.floor(v * invCellSize)
+  }
+
+  function cellRange(b) {
+    return {
+      minCX: Math.floor(b.minX * invCellSize),
+      minCY: Math.floor(b.minY * invCellSize),
+      maxCX: Math.floor(b.maxX * invCellSize),
+      maxCY: Math.floor(b.maxY * invCellSize)
+    }
+  }
+
+  function addToCell(cx, cy, entry) {
+    const key = cellKey(cx, cy)
+    let bucket = cells.get(key)
+    if (!bucket) {
+      bucket = []
+      cells.set(key, bucket)
+    }
+    bucket.push(entry)
+  }
+
+  function removeFromCell(cx, cy, entry) {
+    const key = cellKey(cx, cy)
+    const bucket = cells.get(key)
+    if (!bucket) return
+    const idx = bucket.indexOf(entry)
+    if (idx !== -1) {
+      bucket.splice(idx, 1)
+      if (bucket.length === 0) cells.delete(key)
+    }
+  }
+
+  function recalcBounds() {
+    if (size === 0) {
+      totalBounds = null
+      return
+    }
+    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity
+    const seen = new Set()
+    for (const bucket of cells.values()) {
+      for (const entry of bucket) {
+        if (seen.has(entry)) continue
+        seen.add(entry)
+        const b = entry.bounds
+        if (b.minX < minX) minX = b.minX
+        if (b.minY < minY) minY = b.minY
+        if (b.maxX > maxX) maxX = b.maxX
+        if (b.maxY > maxY) maxY = b.maxY
+      }
+    }
+    totalBounds = { minX, minY, maxX, maxY }
+  }
+
+  const index = {
+    [SPATIAL_INDEX]: true,
+
+    get size() { return size },
+
+    get bounds() { return totalBounds },
+
+    insert(item) {
+      const raw = accessor(item)
+      const itemBounds = normalizeBounds(raw)
+      validateAccessorBounds(itemBounds)
+
+      const entry = { item, bounds: itemBounds }
+      const { minCX, minCY, maxCX, maxCY } = cellRange(itemBounds)
+
+      for (let cx = minCX; cx <= maxCX; cx++) {
+        for (let cy = minCY; cy <= maxCY; cy++) {
+          addToCell(cx, cy, entry)
+        }
+      }
+
+      if (totalBounds === null) {
+        totalBounds = { ...itemBounds }
+      } else {
+        if (itemBounds.minX < totalBounds.minX) totalBounds.minX = itemBounds.minX
+        if (itemBounds.minY < totalBounds.minY) totalBounds.minY = itemBounds.minY
+        if (itemBounds.maxX > totalBounds.maxX) totalBounds.maxX = itemBounds.maxX
+        if (itemBounds.maxY > totalBounds.maxY) totalBounds.maxY = itemBounds.maxY
+      }
+
+      size++
+    },
+
+    remove(item) {
+      const raw = accessor(item)
+      const itemBounds = normalizeBounds(raw)
+      const { minCX, minCY, maxCX, maxCY } = cellRange(itemBounds)
+
+      let entry = null
+      const firstKey = cellKey(minCX, minCY)
+      const bucket = cells.get(firstKey)
+      if (bucket) {
+        entry = bucket.find(e => e.item === item) ?? null
+      }
+
+      if (!entry) {
+        for (let cx = minCX; cx <= maxCX && !entry; cx++) {
+          for (let cy = minCY; cy <= maxCY && !entry; cy++) {
+            if (cx === minCX && cy === minCY) continue
+            const b = cells.get(cellKey(cx, cy))
+            if (b) entry = b.find(e => e.item === item) ?? null
+          }
+        }
+      }
+
+      if (!entry) return false
+
+      for (let cx = minCX; cx <= maxCX; cx++) {
+        for (let cy = minCY; cy <= maxCY; cy++) {
+          removeFromCell(cx, cy, entry)
+        }
+      }
+
+      size--
+      recalcBounds()
+      return true
+    },
+
+    search(query) {
+      if (size === 0) return []
+      const queryBounds = normalizeBounds(query)
+      const { minCX, minCY, maxCX, maxCY } = cellRange(queryBounds)
+
+      const results = []
+      const seen = new Set()
+
+      for (let cx = minCX; cx <= maxCX; cx++) {
+        for (let cy = minCY; cy <= maxCY; cy++) {
+          const bucket = cells.get(cellKey(cx, cy))
+          if (!bucket) continue
+          for (const entry of bucket) {
+            if (seen.has(entry)) continue
+            seen.add(entry)
+            if (intersects(entry.bounds, queryBounds)) {
+              results.push(entry.item)
+            }
+          }
+        }
+      }
+
+      return results
+    },
+
+    nearest(queryPoint, k = 1) {
+      if (size === 0 || k <= 0) return []
+
+      const px = queryPoint.x
+      const py = queryPoint.y
+
+      const results = []
+      const seen = new Set()
+      let ring = 0
+      const centerCX = toCell(px)
+      const centerCY = toCell(py)
+
+      const heap = []
+
+      // expand in rings until we have k candidates and the ring is far enough
+      while (true) {
+        const minCX = centerCX - ring
+        const maxCX = centerCX + ring
+        const minCY = centerCY - ring
+        const maxCY = centerCY + ring
+
+        for (let cx = minCX; cx <= maxCX; cx++) {
+          for (let cy = minCY; cy <= maxCY; cy++) {
+            if (ring > 0 && cx > minCX && cx < maxCX && cy > minCY && cy < maxCY) continue
+            const bucket = cells.get(cellKey(cx, cy))
+            if (!bucket) continue
+            for (const entry of bucket) {
+              if (seen.has(entry)) continue
+              seen.add(entry)
+              heapPush(heap, { dist: distanceToPoint(entry.bounds, px, py), item: entry.item })
+            }
+          }
+        }
+
+        // the minimum possible distance to any item in the next ring
+        const nextRingDist = ring * cellSize
+        const haveCandidates = heap.length >= k
+
+        if (haveCandidates) {
+          let kthDist = peekKth(heap, k)
+          if (kthDist <= nextRingDist) break
+        }
+
+        // if we've checked all cells, stop
+        if (seen.size >= size) break
+        ring++
+      }
+
+      while (heap.length > 0 && results.length < k) {
+        results.push(heapPop(heap).item)
+      }
+
+      return results
+    },
+
+    clear() {
+      cells.clear()
+      size = 0
+      totalBounds = null
+    }
+  }
+
+  return index
+}
+
+function peekKth(heap, k) {
+  // extract k items, record the kth distance, then put them back
+  if (heap.length < k) return Infinity
+  const extracted = []
+  for (let i = 0; i < k; i++) {
+    extracted.push(heapPop(heap))
+  }
+  const kthDist = extracted[extracted.length - 1].dist
+  for (const e of extracted) {
+    heapPush(heap, e)
+  }
+  return kthDist
+}

package/src/index.js

@@ -0,0 +1 @@
+export { createHashGrid } from './hashgrid.js'

package/types/hashgrid.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Creates a spatial hash grid index.
+ *
+ * @param {(item: any) => Bounds | object} accessor - Maps items to their bounding boxes or geometries
+ * @param {HashGridOptions} options
+ * @returns {import('@gridworkjs/core').SpatialIndex}
+ */
+export function createHashGrid(accessor: (item: any) => Bounds | object, options?: HashGridOptions): any;
+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 HashGridOptions = {
+    /**
+     * - Width and height of each grid cell
+     */
+    cellSize: number;
+};

package/types/index.d.ts

@@ -0,0 +1 @@
+export { createHashGrid } from "./hashgrid.js";