{"id":12839,"library":"astar-typescript","title":"A* Pathfinding for TypeScript","description":"AStar-Typescript is a JavaScript library, written in TypeScript, that implements the A* (A-star) pathfinding algorithm. It is primarily designed for use in HTML5 games and other browser-based projects, providing a robust solution for calculating efficient paths on grid-based maps. The current stable version is 1.2.7, with development focused on feature enhancements and code improvements, such as the recent addition of a 'Get as close as possible' option for blocked paths. This library differentiates itself through its TypeScript-first approach, offering type safety and modern syntax. It supports various heuristic functions including Manhattan, Euclidean, Chebyshev, and Octile, and allows configuration for diagonal movements. Its API is designed for ease of use, accepting both predefined grid matrices and randomly generated grid structures, making it flexible for diverse game development scenarios. Releases appear to be ad-hoc based on feature additions and enhancements.","status":"active","version":"1.2.7","language":"javascript","source_language":"en","source_url":"https://github.com/digitsensitive/astar-typescript","tags":["javascript","A-star","A*","Algorithm","Graph","Pathfinding","Search","Shakey","Traversal","typescript"],"install":[{"cmd":"npm install astar-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add astar-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add astar-typescript","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This is the standard and recommended way to import the `AStarFinder` class in modern TypeScript and ES module environments. Attempting a default import will typically result in `undefined` or the entire module object, not the `AStarFinder` class itself.","wrong":"import AStarFinder from 'astar-typescript';","symbol":"AStarFinder","correct":"import { AStarFinder } from 'astar-typescript';"},{"note":"For CommonJS environments, destructuring the `require` call is the correct method to access the named `AStarFinder` class. A direct `require` (as shown in some older README examples) would assign the entire module object to `AStarFinder`, requiring subsequent access like `AStarFinder.AStarFinder`.","wrong":"const AStarFinder = require('astar-typescript');","symbol":"AStarFinder","correct":"const { AStarFinder } = require('astar-typescript');"},{"note":"When using TypeScript, it is good practice to import type definitions separately using `import type` if you only need the type information for improved bundle size and clarity.","symbol":"AStarFinderOptions","correct":"import type { AStarFinderOptions } from 'astar-typescript';"}],"quickstart":{"code":"import { AStarFinder } from 'astar-typescript';\n\n// Define a grid matrix: 0 for walkable, 1 for obstacles.\nconst myMatrix = [\n  [0, 0, 0, 0, 0, 0, 0, 0],\n  [0, 0, 0, 0, 0, 0, 0, 1],\n  [0, 0, 1, 1, 0, 1, 1, 0],\n  [0, 0, 1, 0, 0, 0, 1, 0],\n  [0, 0, 0, 0, 0, 0, 1, 0],\n  [1, 1, 1, 0, 1, 0, 1, 0],\n  [0, 0, 0, 0, 1, 0, 1, 0],\n  [0, 0, 1, 0, 0, 0, 0, 0]\n];\n\n// Create an AStarFinder instance with grid data and optional settings.\nconst aStarInstance = new AStarFinder({\n  grid: { matrix: myMatrix },\n  diagonalAllowed: true, // Allow diagonal movements (default is true)\n  heuristic: 'Manhattan' // Choose a heuristic function ('Manhattan', 'Euclidean', 'Chebyshev', 'Octile')\n});\n\n// Define start and goal positions.\nconst startPos = { x: 0, y: 0 };\nconst goalPos = { x: 4, y: 5 };\n\n// Find the path.\nconst myPathway = aStarInstance.findPath(startPos, goalPos);\n\nif (myPathway.length > 0) {\n  console.log('Path found:', myPathway);\n} else {\n  console.log('No path found. The goal might be unreachable or completely blocked.');\n}\n\n// Example of using the 'closeWhenNoPath' option (introduced in v1.2.7)\nconst blockedScenarioMatrix = [\n  [0, 0, 0],\n  [0, 1, 0],\n  [0, 0, 0]\n];\nconst blockedPathFinder = new AStarFinder({\n  grid: { matrix: blockedScenarioMatrix },\n  closeWhenNoPath: true // If no direct path, return the closest point reached\n});\nconst closestPath = blockedPathFinder.findPath({x:0, y:0}, {x:0, y:2});\nconsole.log('Path for blocked scenario (closest point if no direct path):', closestPath);","lang":"typescript","description":"This quickstart demonstrates how to instantiate `AStarFinder` using a predefined grid matrix, configure search parameters like diagonal movements and heuristic functions, and then find a path between specified start and goal coordinates. It also includes an example of the `closeWhenNoPath` option, which provides a path to the nearest reachable point if the direct goal is inaccessible."},"warnings":[{"fix":"Always check if the returned path array is empty and handle this scenario gracefully. For situations where a partial path to the nearest reachable point is desired even if the goal is blocked, set the `closeWhenNoPath` option to `true` during `AStarFinder` instantiation (available since v1.2.7).","message":"When `findPath` returns an empty array, it indicates that no valid path was found from the start to the goal position. This commonly occurs if the goal is completely surrounded by obstacles or lies within an inaccessible area.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure that your `grid.matrix` adheres strictly to the `0` (walkable) and `1` (unwalkable) convention. Validate and sanitize any external grid data to match this format before passing it to the `AStarFinder` constructor.","message":"The grid matrix supplied to `AStarFinder` expects specific numeric values: `0` for walkable cells and `1` for unwalkable (obstacle) cells. Using any other numeric or non-numeric values will lead to unexpected pathfinding results or runtime errors.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For performance-critical scenarios, consider strategies like using a smaller, localized subgrid for pathfinding around agents, limiting the maximum search distance, or pre-calculating common paths. Experiment with different `heuristic` functions and disable `diagonalAllowed` if diagonal movement is not essential, as these can impact computational load.","message":"Performance of the A* algorithm can degrade substantially with very large grids (e.g., hundreds or thousands of units wide/tall) or when performing frequent pathfinding queries in real-time applications without proper optimization.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that `new AStarFinder(...)` was successfully called and the instance was correctly assigned to the variable before attempting to call any of its methods. For example: `const aStarInstance = new AStarFinder({ grid: { matrix: myMatrix } });`","cause":"This error occurs when `findPath` is called on an `AStarFinder` variable that has not been properly initialized, or is `undefined` because its constructor failed or was not invoked with `new`.","error":"TypeError: Cannot read properties of undefined (reading 'findPath')"},{"fix":"Inspect your `myMatrix` array to ensure all cell values are strictly `0` (walkable) or `1` (unwalkable). Convert any other values from your data source to this binary format before passing the matrix.","cause":"The `grid.matrix` provided to the `AStarFinder` constructor contains elements that are not `0` or `1`, violating the expected grid format.","error":"Error: Value for matrix must be a number type 0 or 1"},{"fix":"Confirm that the `x` and `y` properties of both `startPos` and `goalPos` are non-negative and are less than the respective `width` and `height` of your grid (i.e., `0 <= x < width` and `0 <= y < height`).","cause":"Either the `startPos` or `goalPos` coordinates (or both) supplied to `findPath` fall outside the defined `width` and `height` of the grid initialized with `AStarFinder`.","error":"Error: Start position is not inside the grid bounds"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null}