Registry / database / js-quadtree

js-quadtree

JSON →
library3.3.6jsnpmunverified

js-quadtree is a JavaScript library providing a robust and configurable quadtree implementation, suitable for both Node.js environments and direct browser usage. Currently at stable version 3.3.6, the library appears to follow an infrequent release cadence, with recent updates primarily consisting of minor version bumps without significant feature changes or breaking modifications. Its key differentiators include the ability to specify maximum capacity per node, automatic removal of empty sub-nodes, configurable maximum depth to prevent excessive subdivision, and a customizable point equality comparison function crucial for accurate removal operations when dealing with custom data. It supports inserting plain objects with `x` and `y` properties in addition to its own `Point` objects, which can hold arbitrary custom data, making it flexible for various spatial indexing needs.

npm install js-quadtree
INSTALL
IMPORT
SIG · JS-QUADTREE
J
js-quadtree
databasejavascriptv3.3.6
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

QuadTree
import { QuadTree } from 'js-quadtree';
import QuadTree from 'js-quadtree';
js-quadtree uses named exports for all its core classes in ESM. There is no default export.
Box
const { Box } = require('js-quadtree');
const Box = require('js-quadtree');
When using CommonJS, destructure the required module to access specific classes like Box, Point, or Circle.
Point
const point = new QT.Point(x, y, data);
const point = new Point(x, y, data);
When using the library via CDN in a browser, all classes (QuadTree, Box, Point, Circle) are globally accessible under the 'QT' namespace.

Demonstrates quadtree creation, configuration, insertion of various point types (including custom data and plain objects), querying with a circular region, and point removal, showcasing common API interactions.

import { QuadTree, Box, Point, Circle } from 'js-quadtree'; // 1. Define the bounding area for the quadtree const boundingArea = new Box(0, 0, 1000, 1000); // x, y, width, height // 2. Configure the quadtree (optional parameters) const config = { capacity: 8, // Max points per node before subdividing (default: 4) removeEmptyNodes: true, // Automatically clean up empty sub-nodes (default: false) maximumDepth: 10, // Prevent infinite subdivision, -1 for no limit (default: -1) // Custom comparison function for point removal if data is complex arePointsEqual: (p1, p2) => p1.data && p2.data && p1.data.id === p2.data.id }; // 3. Instantiate the quadtree with initial points (optional) const initialPoints = [ new Point(100, 200, { id: 'a', type: 'player' }), new Point(500, 700, { id: 'b', type: 'enemy' }), { x: 150, y: 250, data: { id: 'c', type: 'item' } } // Custom object insert, requires x/y ]; const quadtree = new QuadTree(boundingArea, config, initialPoints); console.log(`Initial quadtree has ${quadtree.length} points.`); // 4. Insert more points individually or as an array quadtree.insert(new Point(300, 400, { id: 'd', type: 'obstacle' })); quadtree.insert([ new Point(80, 120, { id: 'e', type: 'item' }), { x: 900, y: 100, data: { id: 'f', type: 'effect' } } ]); // 5. Query for objects within a specific area (e.g., a circle) const searchArea = new Circle(150, 150, 100); // centerX, centerY, radius const results = quadtree.query(searchArea); console.log(`Found ${results.length} items in the search area.`); results.forEach(point => console.log(` - Point at (${point.x}, ${point.y}) with data:`, point.data)); // 6. Remove a point const pointToRemove = new Point(100, 200, { id: 'a' }); quadtree.remove(pointToRemove); // Requires arePointsEqual config if data matters for equality console.log('Attempted to remove point (100, 200). New total points:', quadtree.length);
Debug
Known issues
gotchaWhen consuming `js-quadtree` via a CDN in a browser, all core classes (QuadTree, Box, Point, Circle) are exposed under the global `QT` namespace. Attempting to use them without this prefix (e.g., `new QuadTree(...)` instead of `new QT.QuadTree(...)`) will result in a `ReferenceError`.
fix
Always prefix class constructors with `QT.` (e.g., `new QT.QuadTree()`, `new QT.Point()`) when using the CDN build in a browser environment.
affects: >=1.0.0
gotchaThe default `arePointsEqual` comparison function used for `remove()` operations only checks `x` and `y` coordinates. If points contain custom data that should also be considered for equality (e.g., a unique ID in the `data` object), you must provide a custom `arePointsEqual` function in the QuadTree configuration. Otherwise, `remove()` might fail to find or incorrectly remove points.
fix
Pass a `config` object to the `QuadTree` constructor with a custom `arePointsEqual` property that implements your desired comparison logic (e.g., `(p1, p2) => p1.x === p2.x && p1.y === p2.y && p1.data.id === p2.data.id`).
affects: >=1.0.0
gotchaEnabling `removeEmptyNodes: true` and setting a very low `capacity` with a large `maximumDepth` can lead to increased computational overhead, especially during frequent insertions and removals, due to the constant re-evaluation and restructuring of the quadtree's internal nodes.
fix
Tune `capacity` and `maximumDepth` parameters based on your specific application's data distribution and performance requirements. For static or mostly additive data sets, consider disabling `removeEmptyNodes` if the overhead is noticeable. Profile your application to find optimal values.
affects: >=1.0.0
Errors
Common errors & fixes
ReferenceError: QuadTree is not defined
Attempting to use `QuadTree`, `Box`, `Point`, or `Circle` directly in a browser environment after loading via CDN, without the `QT` prefix.
fix
In browser CDN usage, access classes via the global `QT` object: `new QT.QuadTree(...)`, `new QT.Box(...)`, etc. Ensure proper ESM/CJS imports in Node.js: `import { QuadTree } from 'js-quadtree';` or `const { QuadTree } = require('js-quadtree');`.
TypeError: Cannot read properties of undefined (reading 'x') (or 'y')
An object passed to `quadtree.insert()` or `quadtree.remove()` does not have numeric `x` and `y` properties, which are fundamental for the quadtree's spatial indexing.
fix
Ensure all objects inserted into or removed from the quadtree conform to the expected interface by having both `x` and `y` numeric properties, either as `Point` instances or custom objects.
The point you are trying to remove is not in the quadtree.
The `remove()` method was called with a `Point` object that, according to the `arePointsEqual` configuration (or its default), does not exactly match any existing point in the quadtree.
fix
Verify that the `Point` object passed to `remove()` is identical to one previously inserted. If using custom data, implement a custom `arePointsEqual` function in the `QuadTree` configuration that accurately compares unique identifiers or relevant properties within your `data` objects.
Upgrade
Version history
3.3.6latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
7 hits · last 30 days
node
6
Amazon
1
Resources
js-quadtree — npm install js-quadtree · libregistry