A* Pathfinding Algorithm

Common errors

• ReferenceError: astar is not defined

  cause The `astar` object was not correctly loaded or imported into the current scope. This typically happens if the script tag is missing in the browser or the CommonJS/ESM import is incorrect in Node.js/bundled environments.
  fix In browsers, ensure `<script src='astar.js'></script>` is present and loaded before your code. In Node.js, use `const { astar } = require('javascript-astar');` (for CJS) or `import { astar } from 'javascript-astar';` (for ESM).

• TypeError: Graph is not a constructor

  cause The `Graph` class was not properly imported or made available. In module environments, this often means it wasn't destructured correctly during the `require` or `import` statement.
  fix In module environments, ensure `Graph` is destructured from the package: `const { Graph } = require('javascript-astar');` or `import { Graph } from 'javascript-astar';`. In browsers, verify the `astar.js` script is loaded to expose the global `Graph`.

• Invalid weight value (e.g., 'Weight cannot be negative', 'Weight cannot be between 0 and 1 exclusive')

  cause A node in the `Graph` was initialized or modified with a weight value that violates the library's constraints (negative, or a decimal between 0 and 1 exclusively).
  fix Review the weights defined in your `Graph` grid. Valid weights are `0` (for walls), `1`, or any number `> 1` (including decimals). Adjust any invalid weight values accordingly.

Warnings

• breaking The internal algorithm was fundamentally changed from version 0.0.1 to use a Binary Heap, significantly improving performance over the original list-based approach. While this is a positive change, it represents a breaking change in internal implementation details.
  Fix: Upgrade to a newer version (0.4.1 or later) to benefit from the performance improvements. Review existing code for any direct reliance on the internal algorithm structures of versions prior to 0.0.1.
• gotcha Node weights in the graph have specific constraints: a weight of 0 marks a node as an impassable 'wall'. Weights cannot be negative, nor can they be fractional values exclusively between 0 and 1 (e.g., 0.5 is invalid). Decimal values greater than 1 are permitted.
  Fix: Ensure all graph node weights adhere to the specified rules: `0` for walls, `1` for standard passable nodes, or any number `> 1` (including decimals) for custom movement costs. Avoid negative weights or weights between 0 and 1 (exclusive).
• gotcha When included directly in browser environments via a `<script>` tag, the library exposes `astar` and `Graph` as global variables. This can lead to global namespace pollution, potentially conflicting with other scripts or libraries.
  Fix: To avoid global conflicts, consider using a module bundler (like Webpack or Rollup) to integrate `javascript-astar` as a module. Alternatively, encapsulate its usage within an Immediately Invoked Function Expression (IIFE) in browser scripts to limit variable scope.

Install

• npm install javascript-astar npm
• yarn add javascript-astar yarn
• pnpm add javascript-astar pnpm

Imports

• astar
  wrong:

  import astar from 'javascript-astar'; // Incorrect for named export
  const astar = require('javascript-astar'); // This assigns the full module object, not just the 'astar' property

  correct:

  import { astar } from 'javascript-astar'; // ESM
  const { astar } = require('javascript-astar'); // CJS

  The `astar` object contains the main `search` function and `heuristics` object. In browser environments, `astar` is available as a global variable.
• Graph
  wrong:

  new astar.Graph(); // Incorrect, `Graph` is a separate top-level export/global, not a property of `astar`

  correct:

  import { Graph } from 'javascript-astar'; // ESM
  const { Graph } = require('javascript-astar'); // CJS

  The `Graph` class is used to construct the grid for pathfinding. In browser environments, `Graph` is available as a global variable.
• astar.heuristics.diagonal
  wrong:

  import { diagonal } from 'javascript-astar'; // Heuristics are nested under the `astar` object

  correct:

  import { astar } from 'javascript-astar';
  const diagonalHeuristic = astar.heuristics.diagonal;

  Access specific heuristics as properties of the `astar.heuristics` object.

Quickstart

Demonstrates initializing a graph, performing basic A* search, and utilizing options for diagonal movement and custom node weights.

const { astar, Graph } = require('javascript-astar'); // For Node.js or bundlers; for browsers, `astar` and `Graph` are globals.

// Basic usage: Find path on a grid without diagonal movement or custom weights.
var graph = new Graph([
	[1,1,1,1],
	[0,1,1,0],
	[0,0,1,1]
]);
var start = graph.grid[0][0];
var end = graph.grid[1][2];
var result = astar.search(graph, start, end);
console.log('Path (no diagonals, no weight):', result.map(node => `(${node.x},${node.y})`).join(' -> '));

// With diagonals: Enable diagonal moves and use the diagonal heuristic.
var graphDiagonal = new Graph([
	[1,1,1,1],
	[0,1,1,0],
	[0,0,1,1]
], { diagonal: true });
var startDiagonal = graphDiagonal.grid[0][0];
var endDiagonal = graphDiagonal.grid[1][2];
var resultWithDiagonals = astar.search(graphDiagonal, startDiagonal, endDiagonal, { heuristic: astar.heuristics.diagonal });
console.log('Path (with diagonals):', resultWithDiagonals.map(node => `(${node.x},${node.y})`).join(' -> '));

// With weights: Define custom movement costs for nodes (0 for walls).
var graphWithWeight = new Graph([
	[1,1,2,30],
	[0,4,1.3,0],
	[0,0,5,1]
]);
var startWithWeight = graphWithWeight.grid[0][0];
var endWithWeight = graphWithWeight.grid[1][2];
var resultWithWeight = astar.search(graphWithWeight, startWithWeight, endWithWeight);
console.log('Path (with weights):', resultWithWeight.map(node => `(${node.x},${node.y})`).join(' -> '));