@zakkster/lite-path

🧭 What is lite-path?

@zakkster/lite-path is a production-grade A* pathfinder that never allocates during searches.

It gives you:

• 🧭 A* with 4-way and 8-way movement
• ⏱️ O(1) state reset via epoch tracking (no .fill() per search)
• 📊 Flat Int32Array binary heap (cache-friendly)
• ⛰️ Weighted terrain (cost per cell)
• 📝 Zero-allocation path reconstruction into pre-allocated buffer
• 🪶 < 1.5 KB minified

The epoch trick is the key: instead of clearing arrays between searches, we just bump a counter.

Part of the @zakkster/lite-* ecosystem — micro-libraries built for deterministic, cache-friendly game development.

🚀 Install

npm i @zakkster/lite-path

🕹️ Quick Start

import { Pathfinder } from '@zakkster/lite-path';

const pf = new Pathfinder(100, 100, true); // 100x100 grid, diagonals on

// Set up terrain (0 = wall, 1 = normal, >1 = expensive)
pf.grid[50 + 25 * 100] = 0; // wall at (50, 25)
pf.grid[60 + 30 * 100] = 5; // swamp at (60, 30)

// Find path
const out = new Float32Array(2000);
const waypoints = pf.findPath(10, 10, 90, 90, out);

for (let i = 0; i < waypoints; i++) {
    const x = out[i * 2], y = out[i * 2 + 1];
    drawWaypoint(x, y);
}

🧠 Why This Exists

Existing A* libraries allocate node objects and reset arrays per search. lite-path uses epoch tracking — incrementing a single integer makes all previous state stale in O(1). The flat binary heap stores indices in an Int32Array, not node objects.

📊 Comparison

| Library | Size | Reset Cost | Heap | Allocations | Install | |---------|------|-----------|------|-------------|---------| | pathfinding | ~12 KB | O(N) fill | Array-based | High | npm i pathfinding | | javascript-astar | ~5 KB | O(N) fill | Array-based | Medium | npm i javascript-astar | | lite-path | < 1.5 KB | O(1) epoch | Int32Array flat heap | Zero | npm i @zakkster/lite-path |

⚙️ API

new Pathfinder(cols, rows, allowDiagonals?)

grid: Uint8Array — Direct access. 0 = wall, 1 = walkable, >1 = weighted.

findPath(startX, startY, endX, endY, outPath) — Returns waypoint count (0 = no path). Path excludes start node.

🧪 Benchmark

100x100 grid, 1000 pathfinding calls:
  pathfinding:       45ms (node allocation + array reset)
  javascript-astar:  28ms (array reset per call)
  lite-path:         12ms (epoch bump = O(1) reset, zero alloc)

📦 TypeScript

Full TypeScript declarations included in Pathfinder.d.ts.

📚 LLM-Friendly Documentation

See llms.txt for AI-optimized metadata and usage examples.

License

MIT