@zeitfall/quadtree 1.0.0 → 1.0.1

package/.github/workflows/publish.yml

@@ -23,10 +23,14 @@ jobs:
           node-version-file: package.json
           registry-url: 'https://registry.npmjs.org/'
 
-      - name: Build Library
-        run: |
-          npm ci
-          npm run build
+      - name: Install Dependencies
+        run: npm ci
+
+      - name: Test
+        run: npm run test
+
+      - name: Build
+        run: npm run build
 
       - name: Publish
         run: npm publish --provenance --access public

package/README.md

@@ -0,0 +1,89 @@
+## Overview
+
+A TypeScript implementation of a region-based QuadTree for spatial partitioning of 2D point data, supporting generic payloads, capacity-based subdivision, and depth-limiting.
+
+## Mathematical & Algorithmic Properties
+
+| Operation / Metric | Average Case | Worst Case |
+| --- | --- | --- |
+| Insertion | O(log n) | O(n) |
+| Spatial Query | O(log n + k) | O(n) |
+| Space Complexity | O(n) | O(n) |
+
+*Note: `n` represents the total number of inserted points; `k` represents the number of points intersecting the query region.*
+
+## API Reference
+
+### `QuadTree<I unknown>`
+
+The primary structural class representing a node within the spatial tree.
+
+* **Constructor**
+`constructor(boundary: QuadTreeBoundary, threshold: number, depth = 0, maxDepth = 8)`
+Initializes a node with a defined spatial boundary, capacity threshold, current depth layer, and structural depth limit.
+* **`insert(x: number, y: number, value: I): boolean`**
+Inserts a point payload into the tree. Returns `true` if insertion succeeds, or `false` if the coordinates fall outside the node boundary.
+* *Mechanism*: Governed by internal fields `#threshold`, `#depth`, and `#maxDepth`. If the node capacity exceeds `#threshold` and `#depth` is less than `#maxDepth`, `#subdivide()` is executed, transforming the leaf into an internal node and redistributing existing payloads to four child quadrants (`#nodeNW`, `#nodeNE`, `#nodeSW`, `#nodeSE`).
+
+
+* **`query(region: QuadTreeRegion, result: QuadTreeInsertable<I>[]): void`**
+Populates the `result` array with all payloads contained within the specified `QuadTreeRegion`. Evaluates intersection via `region.intersects` before performing point-in-boundary checks.
+* **`clear(): void`**
+Clears all internal point references and recursively clears child node instances.
+
+### `QuadTreeBoundary`
+
+Implements `QuadTreeRegion`. Defines the spatial bounding box for a node.
+
+* **Constructor**
+`constructor(x: number, y: number, width: number, height: number)`
+Sets the origin coordinates (`x`, `y`) and spatial dimensions (`width`, `height`).
+* **Properties**
+`x: number`, `y: number`, `width: number`, `height: number`, `left: number`, `right: number`, `top: number`, `bottom: number`
+* **`contains(x: number, y: number): boolean`**
+Evaluates whether a point falls within the spatial boundaries.
+* **`intersects(other: QuadTreeBoundary): boolean`**
+Evaluates Axis-Aligned Bounding Box (AABB) intersection between two boundaries.
+
+### `QuadTreeRegion`
+
+An interface defining spatial bounds evaluation.
+
+* **`contains(x: number, y: number): boolean`**
+* **`intersects(boundary: QuadTreeBoundary): boolean`**
+
+### `QuadTreeInsertable<I unknown>`
+
+An interface representing the structured storage layout of data elements.
+
+* **Properties**
+`x: number`, `y: number`, `value: I`
+
+---
+
+## Operational Context (Behavioral Notes)
+
+* **Boundary Conditions:** Coordinate boundaries evaluate containment using inclusive lower bounds and exclusive upper bounds: `[x, x + width)` and `[y, y + height)`.
+* **Subdivision Behavior:** Structural subdivision is lazy. Node splitting occurs only when point allocations exceed the target node `#threshold`, provided the maximum structural depth limitation (`#maxDepth`) has not been reached.
+* **Clearing Mechanics:** The `.clear()` routine executes a post-order traversal to empty local point arrays, unset structural split states, and nullify all internal child node pointers, freeing references for immediate garbage collection.
+
+---
+
+## Usage Example
+
+```typescript
+import { QuadTree, QuadTreeBoundary, QuadTreeInsertable } from './quadtree';
+
+const boundary = new QuadTreeBoundary(0, 0, 200, 200);
+const quadTree = new QuadTree<string>(boundary, 2, 0, 4);
+
+quadTree.insert(10, 15, "Payload_A");
+quadTree.insert(45, 80, "Payload_B");
+quadTree.insert(12, 18, "Payload_C"); 
+
+const queryRegion = new QuadTreeBoundary(0, 0, 50, 50);
+const matchedPoints: QuadTreeInsertable<string>[] = [];
+
+quadTree.query(queryRegion, matchedPoints);
+
+```

package/index.test.ts

@@ -0,0 +1,155 @@
+import { it, describe, beforeEach } from 'node:test';
+import assert from 'node:assert';
+
+import {
+    QuadTree,
+    QuadTreeBoundary,
+    type QuadTreeInsertable
+    // @ts-ignore
+} from './index.ts';
+
+class TestRegion {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+
+    constructor(x: number, y: number, width: number, height: number) {
+        this.x = x;
+        this.y = y;
+        this.width = width;
+        this.height = height;
+    }
+
+    contains(x: number, y: number): boolean {
+        return x >= this.x && x < this.x + this.width && y >= this.y && y < this.y + this.height;
+    }
+
+    intersects(boundary: QuadTreeBoundary): boolean {
+        return this.x < boundary.right &&
+            this.x + this.width > boundary.left &&
+            this.y < boundary.bottom &&
+            this.y + this.height > boundary.top;
+    }
+}
+
+describe('QuadTree', () => {
+    let quadTreeBoundary: QuadTreeBoundary;
+    let quadTree: QuadTree<string>;
+
+    beforeEach(() => {
+        quadTreeBoundary = new QuadTreeBoundary(0, 0, 100, 100);
+        quadTree = new QuadTree<string>(quadTreeBoundary, 2);
+    });
+
+    it('should successfully insert points within boundaries', () => {
+        const inserted1 = quadTree.insert(10, 10, 'Point A');
+        const inserted2 = quadTree.insert(50, 50, 'Point B');
+
+        assert.strictEqual(inserted1, true);
+        assert.strictEqual(inserted2, true);
+    });
+
+    it('should fail to insert points outside boundaries', () => {
+        const insertedOutside = quadTree.insert(150, 50, 'Outside');
+        const insertedNegative = quadTree.insert(-10, 20, 'Negative');
+
+        assert.strictEqual(insertedOutside, false);
+        assert.strictEqual(insertedNegative, false);
+    });
+
+    it('should subdivide when threshold is exceeded', () => {
+        quadTree.insert(10, 10, 'NW Point');
+        quadTree.insert(60, 10, 'NE Point');
+
+        const insertedThird = quadTree.insert(10, 60, 'SW Point');
+        assert.strictEqual(insertedThird, true);
+
+        const nwResult: QuadTreeInsertable<string>[] = [];
+        const nwRegion = new TestRegion(0, 0, 50, 50);
+
+        quadTree.query(nwRegion, nwResult);
+
+        assert.strictEqual(nwResult.length, 1);
+        assert.strictEqual(nwResult[0]?.value, 'NW Point');
+
+        const swResult: QuadTreeInsertable<string>[] = [];
+        const swRegion = new TestRegion(0, 50, 50, 50);
+
+        quadTree.query(swRegion, swResult);
+
+        assert.strictEqual(swResult.length, 1);
+        assert.strictEqual(swResult[0]?.value, 'SW Point');
+    });
+
+    it('should respect maxDepth and not subdivide further', () => {
+        const flatTree = new QuadTree<string>(quadTreeBoundary, 1, 0, 0);
+
+        const inserted1 = flatTree.insert(10, 10, 'A');
+        const inserted2 = flatTree.insert(20, 20, 'B');
+        const inserted3 = flatTree.insert(30, 30, 'C');
+
+        assert.strictEqual(inserted1, true);
+        assert.strictEqual(inserted2, true);
+        assert.strictEqual(inserted3, true);
+
+        const result: QuadTreeInsertable<string>[] = [];
+
+        flatTree.query(new TestRegion(0, 0, 100, 100), result);
+
+        assert.strictEqual(result.length, 3);
+    });
+
+    it('should return only points within the queried region', () => {
+        quadTree.insert(10, 10, 'Target 1');
+        quadTree.insert(20, 20, 'Target 2');
+        quadTree.insert(80, 80, 'Far point');
+
+        const result: QuadTreeInsertable<string>[] = [];
+        const queryRegion = new TestRegion(0, 0, 30, 30);
+
+        quadTree.query(queryRegion, result);
+
+        assert.strictEqual(result.length, 2);
+
+        const values = result.map(r => r.value);
+
+        assert.ok(values.includes('Target 1'));
+        assert.ok(values.includes('Target 2'));
+        assert.ok(!values.includes('Far point'));
+    });
+
+    it('should clear all nodes and elements', () => {
+        quadTree.insert(10, 10, 'A');
+        quadTree.insert(60, 60, 'B');
+        quadTree.insert(20, 80, 'C');
+
+        quadTree.clear();
+
+        const result: QuadTreeInsertable<string>[] = [];
+
+        quadTree.query(new TestRegion(0, 0, 100, 100), result);
+
+        assert.strictEqual(result.length, 0);
+    });
+});
+
+describe('QuadTreeBoundary', () => {
+    it('contains method checks bounds correctly', () => {
+        const b = new QuadTreeBoundary(10, 10, 20, 20);
+
+        assert.strictEqual(b.contains(15, 15), true);
+        assert.strictEqual(b.contains(10, 10), true);
+        assert.strictEqual(b.contains(30, 15), false);
+        assert.strictEqual(b.contains(15, 30), false);
+    });
+
+    it('intersects method detects overlapping boundaries', () => {
+        const b1 = new QuadTreeBoundary(0, 0, 50, 50);
+        const b2 = new QuadTreeBoundary(25, 25, 50, 50);
+        const b3 = new QuadTreeBoundary(60, 60, 10, 10);
+
+        assert.strictEqual(b1.intersects(b2), true);
+        assert.strictEqual(b1.intersects(b3), false);
+    });
+});

package/package.json

@@ -1,20 +1,20 @@
 {
   "name": "@zeitfall/quadtree",
   "type": "module",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Implementation of point-region quadtree algorithm",
   "license": "MIT",
   "types": "./dist/index.d.ts",
-	"module": "./dist/index.js",
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		}
-	},
+  "module": "./dist/index.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "scripts": {
-    "dev": "tsc --watch | node --watch ./dist/index.js",
-    "build": "tsc"
+    "test": "node --experimental-strip-types --test",
+    "build": "tsc -p tsconfig.build.json"
   },
   "engines": {
     "node": ">=22.19.0"
@@ -27,7 +27,17 @@
     "type": "git",
     "url": "git+https://github.com/zeitfall/quadtree.git"
   },
+  "keywords": [
+    "typescript",
+    "quadtree",
+    "quad-tree",
+    "spatial-partitioning",
+    "spatial-indexing",
+    "spatial-index",
+    "collision-detection"
+  ],
   "devDependencies": {
+    "@types/node": "^25.9.1",
     "typescript": "^6.0.3"
   }
-}
+}

package/tsconfig.build.json

@@ -0,0 +1,4 @@
+{
+    "extends": "./tsconfig.json",
+    "exclude": ["./*.test.ts"]
+}

package/tsconfig.json

@@ -9,10 +9,9 @@
     // See also https://aka.ms/tsconfig/module
     "module": "nodenext",
     "target": "esnext",
-    "types": [],
     // For nodejs:
     // "lib": ["esnext"],
-    // "types": ["node"],
+    "types": ["node"],
     // and npm install -D @types/node
 
     // Other Outputs