@zeitfall/quadtree 1.0.0

package/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Build and Publish
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    
+    permissions:
+      contents: read
+      id-token: write 
+
+    steps:
+      - name: Fetch Repository
+        uses: actions/checkout@v6
+        with:
+          ref: main
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: package.json
+          registry-url: 'https://registry.npmjs.org/'
+
+      - name: Build Library
+        run: |
+          npm ci
+          npm run build
+
+      - name: Publish
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vlad Matsko
+
+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/index.ts

@@ -0,0 +1,231 @@
+class QuadTree<I = unknown> {
+    #boundary: QuadTreeBoundary;
+    #threshold: number;
+    #depth: number;
+    #maxDepth: number;
+
+    #insertables: QuadTreeInsertable<I>[];
+    #divided: boolean;
+
+    #nodeNW: QuadTree<I> | null;
+    #nodeNE: QuadTree<I> | null;
+    #nodeSW: QuadTree<I> | null;
+    #nodeSE: QuadTree<I> | null;
+
+    constructor(boundary: QuadTreeBoundary, threshold: number, depth = 0, maxDepth = 8) {
+        this.#boundary = boundary;
+        this.#threshold = threshold;
+        this.#depth = depth;
+        this.#maxDepth = maxDepth;
+
+        this.#insertables = [];
+        this.#divided = false;
+
+        this.#nodeNW = null;
+        this.#nodeNE = null;
+        this.#nodeSW = null;
+        this.#nodeSE = null;
+    }
+
+    insert(x: number, y: number, value: I): boolean {
+        const positionInsideBoundary = this.#boundary.contains(x, y);
+
+        if (!positionInsideBoundary) {
+            return false;
+        }
+
+        if (this.#divided) {
+            return this.#tryInsertIntoChildren(x, y, value);
+        }
+
+        if (this.#insertables.length < this.#threshold || this.#depth >= this.#maxDepth) {
+            this.#insertables.push({ x, y, value });
+
+            return true;
+        }
+
+        this.#subdivide();
+
+        for (const insertable of this.#insertables) {
+            this.#tryInsertIntoChildren(insertable.x, insertable.y, insertable.value);
+        }
+
+        this.#insertables.length = 0;
+
+        return this.#tryInsertIntoChildren(x, y, value);
+    }
+
+    query(region: QuadTreeRegion, result: QuadTreeInsertable<I>[]) {
+        const regionIntersectsBoundary = region.intersects(this.#boundary);
+
+        if (!regionIntersectsBoundary) {
+            return;
+        }
+
+        if (this.#divided) {
+            this.#nodeNW!.query(region, result);
+            this.#nodeNE!.query(region, result);
+            this.#nodeSW!.query(region, result);
+            this.#nodeSE!.query(region, result);
+
+            return;
+        }
+
+        for (const insertable of this.#insertables) {
+            if (region.contains(insertable.x, insertable.y)) {
+                result.push(insertable);
+            }
+        }
+    }
+
+    clear() {
+        this.#insertables.length = 0;
+        this.#divided = false;
+
+        this.#nodeNW?.clear();
+        this.#nodeNE?.clear();
+        this.#nodeSW?.clear();
+        this.#nodeSE?.clear();
+
+        this.#nodeNW = null;
+        this.#nodeNE = null;
+        this.#nodeSW = null;
+        this.#nodeSE = null;
+    }
+
+    #tryInsertIntoChildren(x: number, y: number, value: I) {
+        return this.#nodeNW!.insert(x, y, value)
+            || this.#nodeNE!.insert(x, y, value)
+            || this.#nodeSW!.insert(x, y, value)
+            || this.#nodeSE!.insert(x, y, value);
+    }
+
+    #subdivide() {
+        const boundaryHalfWidth = this.#boundary.width / 2;
+        const boundaryHalfHeight = this.#boundary.height / 2;
+        const nodeNextDepth = this.#depth + 1;
+
+        const northWestBoundary = new QuadTreeBoundary(
+            this.#boundary.x,
+            this.#boundary.y,
+            boundaryHalfWidth,
+            boundaryHalfHeight
+        );
+        this.#nodeNW = new QuadTree(northWestBoundary, this.#threshold, nodeNextDepth, this.#maxDepth);
+
+        const northEastBoundary = new QuadTreeBoundary(
+            this.#boundary.x + boundaryHalfWidth,
+            this.#boundary.y,
+            boundaryHalfWidth,
+            boundaryHalfHeight
+        );
+        this.#nodeNE = new QuadTree(northEastBoundary, this.#threshold, nodeNextDepth, this.#maxDepth);
+
+        const southWestBoundary = new QuadTreeBoundary(
+            this.#boundary.x,
+            this.#boundary.y + boundaryHalfHeight,
+            boundaryHalfWidth,
+            boundaryHalfHeight
+        );
+
+        this.#nodeSW = new QuadTree(southWestBoundary, this.#threshold, nodeNextDepth, this.#maxDepth);
+
+        const southEastBoundary = new QuadTreeBoundary(
+            this.#boundary.x + boundaryHalfWidth,
+            this.#boundary.y + boundaryHalfHeight,
+            boundaryHalfWidth,
+            boundaryHalfHeight
+        );
+        this.#nodeSE = new QuadTree(southEastBoundary, this.#threshold, nodeNextDepth, this.#maxDepth);
+
+        this.#divided = true;
+    }
+}
+
+class QuadTreeBoundary implements QuadTreeRegion {
+    #x: number;
+    #y: number;
+    #width: number;
+    #height: number;
+
+    #left: number;
+    #right: number;
+    #top: number;
+    #bottom: number;
+
+    constructor(x: number, y: number, width: number, height: number) {
+        this.#x = x;
+        this.#y = y;
+        this.#width = width;
+        this.#height = height;
+
+        this.#left = x;
+        this.#right = x + width;
+        this.#top = y;
+        this.#bottom = y + height;
+    }
+
+    get x() {
+        return this.#x;
+    }
+
+    get y() {
+        return this.#y;
+    }
+
+    get width() {
+        return this.#width;
+    }
+
+    get height() {
+        return this.#height;
+    }
+
+    get left() {
+        return this.#left;
+    }
+
+    get right() {
+        return this.#right;
+    }
+
+    get top() {
+        return this.#top;
+    }
+
+    get bottom() {
+        return this.#bottom;
+    }
+
+    contains(x: number, y: number) {
+        return x >= this.#left
+            && x < this.#right
+            && y >= this.#top
+            && y < this.#bottom;
+    }
+
+    intersects(other: QuadTreeBoundary) {
+        return this.#left < other.#right
+            && this.#right > other.#left
+            && this.#top < other.#bottom
+            && this.#bottom > other.#top;
+    }
+}
+
+interface QuadTreeRegion {
+    contains(x: number, y: number): boolean;
+    intersects(boundary: QuadTreeBoundary): boolean;
+}
+
+interface QuadTreeInsertable<I = unknown> {
+    x: number;
+    y: number;
+    value: I;
+}
+
+export {
+    QuadTree,
+    QuadTreeBoundary,
+    type QuadTreeRegion,
+    type QuadTreeInsertable
+};

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@zeitfall/quadtree",
+  "type": "module",
+  "version": "1.0.0",
+  "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"
+		}
+	},
+  "scripts": {
+    "dev": "tsc --watch | node --watch ./dist/index.js",
+    "build": "tsc"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "author": {
+    "name": "Vladyslav",
+    "email": "zzeitfall@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zeitfall/quadtree.git"
+  },
+  "devDependencies": {
+    "typescript": "^6.0.3"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,43 @@
+{
+  // Visit https://aka.ms/tsconfig to read more about this file
+  "compilerOptions": {
+    // File Layout
+    // "rootDir": "./src",
+    "outDir": "./dist",
+
+    // Environment Settings
+    // See also https://aka.ms/tsconfig/module
+    "module": "nodenext",
+    "target": "esnext",
+    "types": [],
+    // For nodejs:
+    // "lib": ["esnext"],
+    // "types": ["node"],
+    // and npm install -D @types/node
+
+    // Other Outputs
+    "sourceMap": true,
+    "declaration": true,
+    "declarationMap": true,
+
+    // Stricter Typechecking Options
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+
+    // Style Options
+    "noImplicitReturns": true,
+    "noImplicitOverride": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    // "noFallthroughCasesInSwitch": true,
+    // "noPropertyAccessFromIndexSignature": true,
+
+    // Recommended Options
+    "strict": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "noUncheckedSideEffectImports": true,
+    "moduleDetection": "force",
+    "skipLibCheck": true,
+  }
+}