Registry / ai-ml / astar-typescript

astar-typescript

library1.2.7jsnpmunverified

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.

ai-ml

npm install astar-typescript

github ↗package ↗

INSTALL

IMPORT

SIG · ASTAR-TYPESCRIPT

astar-typescript

ai-mljavascriptv1.2.7

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

AStarFinder

✓ import { AStarFinder } from 'astar-typescript';

✗ import AStarFinder from 'astar-typescript';

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.

AStarFinder

✓ const { AStarFinder } = require('astar-typescript');

✗ const AStarFinder = require('astar-typescript');

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`.

AStarFinderOptions

✓ import type { AStarFinderOptions } from 'astar-typescript';

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.

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.

import { AStarFinder } from 'astar-typescript'; // Define a grid matrix: 0 for walkable, 1 for obstacles. const myMatrix = [ [0, 0, 0, 0, 0, 0, 0, 0], [0, 0, 0, 0, 0, 0, 0, 1], [0, 0, 1, 1, 0, 1, 1, 0], [0, 0, 1, 0, 0, 0, 1, 0], [0, 0, 0, 0, 0, 0, 1, 0], [1, 1, 1, 0, 1, 0, 1, 0], [0, 0, 0, 0, 1, 0, 1, 0], [0, 0, 1, 0, 0, 0, 0, 0] ]; // Create an AStarFinder instance with grid data and optional settings. const aStarInstance = new AStarFinder({ grid: { matrix: myMatrix }, diagonalAllowed: true, // Allow diagonal movements (default is true) heuristic: 'Manhattan' // Choose a heuristic function ('Manhattan', 'Euclidean', 'Chebyshev', 'Octile') }); // Define start and goal positions. const startPos = { x: 0, y: 0 }; const goalPos = { x: 4, y: 5 }; // Find the path. const myPathway = aStarInstance.findPath(startPos, goalPos); if (myPathway.length > 0) { console.log('Path found:', myPathway); } else { console.log('No path found. The goal might be unreachable or completely blocked.'); } // Example of using the 'closeWhenNoPath' option (introduced in v1.2.7) const blockedScenarioMatrix = [ [0, 0, 0], [0, 1, 0], [0, 0, 0] ]; const blockedPathFinder = new AStarFinder({ grid: { matrix: blockedScenarioMatrix }, closeWhenNoPath: true // If no direct path, return the closest point reached }); const closestPath = blockedPathFinder.findPath({x:0, y:0}, {x:0, y:2}); console.log('Path for blocked scenario (closest point if no direct path):', closestPath);

Debug

Known issues

gotchaWhen `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.

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).

affects: >=1.0.0

gotchaThe 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.

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.

affects: >=1.0.0

gotchaPerformance 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.

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.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'findPath')

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`.

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 } });`

Error: Value for matrix must be a number type 0 or 1

The `grid.matrix` provided to the `AStarFinder` constructor contains elements that are not `0` or `1`, violating the expected grid format.

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.

Error: Start position is not inside the grid bounds

Either the `startPos` or `goalPos` coordinates (or both) supplied to `findPath` fall outside the defined `width` and `height` of the grid initialized with `AStarFinder`.

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`).

Upgrade

Version history

1.2.7latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

29 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/digitsensitive/astar-typescript ↗

packagehttps://www.npmjs.com/package/astar-typescript ↗