fast-astar 1.0.6 → 2.0.0

package/README.md

@@ -1,55 +1,291 @@
 # fast-astar
 
-fast-astar is an implementation of a* algorithm using javascript. Small and fast.
+A high-performance A* pathfinding algorithm library with WebAssembly support. Small, fast, and memory-efficient.
 
-# Use
-Install fast-astar using npm or introduce Grid.js and Astar.js on the page
+## Features
+
+- 🚀 **Multiple Implementations**: Ultra A*, Master A*, and WebAssembly A* with automatic selection
+- ⚡ **High Performance**: Optimized for speed with WebAssembly support
+- 💾 **Memory Efficient**: Sparse data structures for ultra-large maps (up to 100,000×100,000)
+- 🎬 **Animation Support**: Full search process visualization with step-by-step callbacks
+- 🌐 **Universal**: Works in Node.js, browsers, and Web Workers
+- 📦 **Zero Dependencies**: Pure JavaScript/WebAssembly implementation
+
+## Installation
 
-**Install:**
 ```bash
-npm install fast-astar --save
+npm install fast-astar
 ```
 
-**Install:**
+## Quick Start
+
+### Basic Usage
+
 ```javascript
-import {Grid,Astar} from "fast-astar";
+import { Grid, Astar } from 'fast-astar';
 
 // Create a grid
-let grid = new Grid({
-        col:11,                  // col
-        row:7,                   // row
-        render:function(){       // Optional, this method is triggered when the grid point changes
-            // console.log(this);
-        }
-    });
-
-// Add obstacles to the grid
-[[5,2],[5,3],[5,4]].forEach(item => {
-    grid.set(item,'value',1);    // Values greater than 0 are obstacles
+const grid = new Grid({
+    col: 20,  // width
+    row: 15,  // height
+    render: function() {
+        // Optional: called when grid points change (for animation)
+    }
+});
+
+// Add obstacles
+grid.setWalkAt(5, 5, false);  // Set obstacle at (5, 5)
+grid.setWalkAt(6, 5, false);
+grid.setWalkAt(7, 5, false);
+
+// Create A* instance
+const astar = new Astar(grid);
+
+// Find path
+const path = await astar.search(
+    [0, 0],    // start point [x, y]
+    [19, 14],  // end point [x, y]
+    {
+        rightAngle: false,      // Allow diagonal movement (default: false)
+        optimalResult: true     // Ensure optimal path (default: true)
+    }
+);
+
+console.log(path);  // [[0,0], [1,1], [2,2], ...]
+```
+
+### Advanced Usage
+
+```javascript
+import { Grid, Astar } from 'fast-astar';
+
+// Create grid with memory-efficient mode for large maps
+const grid = new Grid({
+    col: 10000,
+    row: 10000,
+    useMemoryEfficientMode: true  // Enable for maps > 1000×1000
+});
+
+// Set obstacles in batch
+const obstacles = [[5, 2], [5, 3], [5, 4], [10, 10]];
+grid.setObstacles(obstacles);
+
+// Create A* with specific algorithm preference
+const astar = new Astar(grid, {
+    prefer: 'wasm',  // 'ultra' | 'master' | 'wasm' | 'auto' (default)
+    strategy: 'auto' // 'auto' | 'performance' | 'memory' | 'compatibility'
+});
+
+// Search with options
+const path = await astar.search(
+    [0, 0],
+    [9999, 9999],
+    {
+        rightAngle: false,
+        optimalResult: true
+    }
+);
+
+// Get current implementation info
+const info = astar.getCurrentImplementation();
+console.log(info.name);  // e.g., "WebAssembly A*"
+```
+
+## API Reference
+
+### Grid
+
+#### Constructor
+
+```javascript
+new Grid(options)
+```
+
+**Options:**
+- `col` (number): Grid width (columns)
+- `row` (number): Grid height (rows)
+- `render` (function, optional): Callback function triggered when grid points change
+- `useMemoryEfficientMode` (boolean, optional): Enable memory-efficient mode for large maps (>1000×1000)
+
+#### Methods
+
+- `setWalkAt(x, y, walkable)`: Set whether a cell is walkable
+- `isWalkableAt(x, y)`: Check if a cell is walkable
+- `setObstacles(obstacles)`: Set multiple obstacles at once (array of [x, y] pairs)
+- `clearObstacles()`: Remove all obstacles
+- `get([x, y])`: Get node at position
+- `set([x, y], key, value)`: Set node property (for animation)
+
+### Astar
+
+#### Constructor
+
+```javascript
+new Astar(grid, options)
+```
+
+**Options:**
+- `prefer` (string): Preferred algorithm - `'ultra'` | `'master'` | `'wasm'` | `'auto'` (default)
+- `strategy` (string): Selection strategy - `'auto'` | `'performance'` | `'memory'` | `'compatibility'`
+- `avoid` (string): Algorithm to avoid
+- `debug` (boolean): Enable debug logging
+
+#### Methods
+
+- `search(start, end, options)`: Find path from start to end
+  - Returns: `Promise<Array<[x, y]> | null>`
+  - Options:
+    - `rightAngle` (boolean): Only allow 4-directional movement (default: false)
+    - `optimalResult` (boolean): Ensure optimal path (default: true)
+- `getCurrentImplementation()`: Get current algorithm implementation info
+- `getPerformanceStats()`: Get performance statistics
+- `getMemoryUsage()`: Get memory usage information
+
+## Algorithm Selection
+
+The library automatically selects the optimal algorithm based on map size:
+
+| Map Size | Algorithm | Performance |
+|----------|-----------|-------------|
+| ≤50×50 | Master A* | Best for small maps |
+| 50×50 - 1000×1000 | WebAssembly A* | **17-25x faster** than JS |
+| 1000×1000 - 10000×10000 | WebAssembly A* | **25x faster** than JS |
+| ≥10000×10000 | WebAssembly A* (Sparse) | **18x faster** than JS |
+
+### Manual Selection
+
+```javascript
+// Force specific algorithm
+const astar = new Astar(grid, { prefer: 'wasm' });
+
+// Performance priority
+const astar = new Astar(grid, { strategy: 'performance' });
+
+// Memory priority
+const astar = new Astar(grid, { strategy: 'memory' });
+```
+
+## Animation Support
+
+For visualization, provide a `render` callback in the Grid constructor:
+
+```javascript
+const grid = new Grid({
+    col: 20,
+    row: 15,
+    render: function() {
+        // This is called during pathfinding
+        // Use grid.set([x, y], 'type', 'open'|'close'|'highlight'|'update')
+        // to track the search process
+    }
 });
 
-// Pass the grid as a parameter to the Astar object
-let astar = new Astar(grid),
-    path = astar.search(
-        [2,3],                   // start
-        [8,3],                   // end
-        {                        // option
-            rightAngle:false,    // default:false,Allow diagonal
-            optimalResult:true   // default:true,In a few cases, the speed is slightly slower
-        }
-    );
+const astar = new Astar(grid);
+const path = await astar.search([0, 0], [19, 14]);
+
+// During search, the render callback will be triggered with:
+// - 'open': Node added to open set
+// - 'close': Node added to closed set
+// - 'highlight': Current node being examined
+// - 'update': Node cost updated
+```
+
+## Performance
+
+Benchmark results (average of 3 runs):
+
+| Map Size | WebAssembly A* | Ultra A* | Master A* |
+|----------|----------------|----------|-----------|
+| 100×100 | **0.12ms** | 1.9ms | 0.58ms |
+| 500×500 | **2.3ms** | 37.9ms | 17.7ms |
+| 1000×1000 | **9.6ms** | 167.7ms | 53.1ms |
+| 5000×5000 | **1.0ms** | 25.7ms | 11.5ms |
+| 10000×10000 | **2.3ms** | 58.6ms | 26.3ms |
+| 50000×50000 | **20.6ms** | 369.4ms | - |
+| 100000×100000 | **46.9ms** | 836.0ms | - |
+
+## Memory Optimization
+
+For large maps (>1000×1000), enable memory-efficient mode:
+
+```javascript
+const grid = new Grid({
+    col: 10000,
+    row: 10000,
+    useMemoryEfficientMode: true  // Uses bitmap compression
+});
+
+// Memory usage comparison:
+// - Standard mode: ~1.4GB for 10000×10000
+// - Memory-efficient mode: ~12MB for 10000×10000
+```
+
+For ultra-large maps (>10 billion nodes), WebAssembly automatically uses sparse HashMap implementation:
 
-console.log('Result',path);      // [[2,3],[3,2],[4,1],[5,1],[6,1],[7,2],[8,3]]
+```javascript
+// 100000×100000 map automatically uses sparse implementation
+const grid = new Grid({ col: 100000, row: 100000 });
+const astar = new Astar(grid, { prefer: 'wasm' });
+// Automatically uses WebAssembly A* (Sparse) - only stores visited nodes
 ```
 
+## Building from Source
+
+### Prerequisites
+
+- Rust (for WebAssembly compilation)
+- wasm-pack
+- Node.js 16+
+
+### Build Commands
+
+```bash
+# Development build (faster compilation, includes debug info)
+npm run build:dev
+
+# Release build (optimized, smaller size)
+npm run build:rel
+```
+
+### Testing
+
+```bash
+# Run performance tests
+npm test
+
+# Full test suite (requires more memory)
+npm run test:full
+
+# WebAssembly-specific tests
+npm run test:wasm
+```
+
+## Browser Support
+
+- Chrome/Edge: ✅ Full support
+- Firefox: ✅ Full support
+- Safari: ✅ Full support (iOS 11.3+)
+- Node.js: ✅ Full support (v16+)
+
+## License
+
+MIT
+
+## Related
+
+- [A* Search Algorithm (Wikipedia)](https://en.wikipedia.org/wiki/A*_search_algorithm)
+- [A* Pathfinding for Beginners](https://www.gamedev.net/articles/programming/artificial-intelligence/a-pathfinding-for-beginners-r2003/)
 
-# Demo
-- [https://sbfkcel.github.io/fast-astar](https://sbfkcel.github.io/fast-astar)
+## Contributing
 
-# Related
-- [wiki](http://wikipedia.moesalih.com/A*_search_algorithm)
-- [achieve](https://www.gamedev.net/articles/programming/artificial-intelligence/a-pathfinding-for-beginners-r2003/)
+Contributions are welcome! Please feel free to submit a Pull Request.
 
+## Changelog
 
-# License
-MIT
+### v0.1.0
+- Initial release with WebAssembly support
+- Multiple algorithm implementations (Ultra, Master, WASM)
+- Automatic algorithm selection
+- Memory-efficient mode for large maps
+- Sparse implementation for ultra-large maps (100K×100K+)
+- Animation support with step-by-step callbacks

package/index.js

@@ -0,0 +1,282 @@
+// 🚀 A* 算法最终整合版本 - 智能自适应入口
+// 自动选择最优算法实现，支持所有环境
+
+import Grid from './Grid.js';
+import Astar from './Astar.js';
+import { isNode, isBrowser, getEnvironmentInfo, checkCompatibility, getPerformanceNow } from './utils.js';
+
+// 便捷创建函数
+function createAstar(gridOptions = {}, astarOptions = {}) {
+    const grid = new Grid(gridOptions);
+    return new Astar(grid, astarOptions);
+}
+
+// 快速路径查找
+function quickPath(gridSize, obstacles = [], start = [0, 0], end = null) {
+    // 输入验证
+    if (typeof gridSize !== 'number' && !Array.isArray(gridSize)) {
+        throw new Error('gridSize 必须是数字或数组 [width, height]');
+    }
+    
+    if (gridSize <= 0 || (Array.isArray(gridSize) && (gridSize[0] <= 0 || gridSize[1] <= 0))) {
+        throw new Error('网格大小必须大于0');
+    }
+    
+    if (!Array.isArray(start) || start.length < 2) {
+        throw new Error('起点必须是包含至少2个元素的数组 [x, y]');
+    }
+    
+    const size = Array.isArray(gridSize) ? gridSize : [gridSize, gridSize];
+    const grid = new Grid({ col: size[0], row: size[1] });
+    
+    // 设置障碍物
+    if (obstacles.length > 0) {
+        if (!Array.isArray(obstacles)) {
+            throw new Error('障碍物必须是数组');
+        }
+        grid.setObstacles(obstacles);
+    }
+    
+    // 默认终点为右下角
+    const endPoint = end || [size[0] - 1, size[1] - 1];
+    
+    if (!Array.isArray(endPoint) || endPoint.length < 2) {
+        throw new Error('终点必须是包含至少2个元素的数组 [x, y]');
+    }
+    
+    const astar = new Astar(grid);
+    return astar.search(start, endPoint);
+}
+
+// 批量路径查找
+async function findMultiplePaths(gridOptions, pathRequests) {
+    // 输入验证
+    if (!gridOptions || (typeof gridOptions !== 'object' && typeof gridOptions !== 'number')) {
+        throw new Error('gridOptions 必须是对象或数字');
+    }
+    
+    if (!Array.isArray(pathRequests)) {
+        throw new Error('pathRequests 必须是数组');
+    }
+    
+    if (pathRequests.length === 0) {
+        return [];
+    }
+    
+    const grid = new Grid(gridOptions);
+    const astar = new Astar(grid);
+    
+    const results = [];
+    for (const request of pathRequests) {
+        try {
+            // 验证请求格式
+            if (!request || !Array.isArray(request.start) || !Array.isArray(request.end)) {
+                throw new Error('每个请求必须包含 start 和 end 数组');
+            }
+            
+            const path = await astar.search(request.start, request.end, request.options || {});
+            results.push({
+                success: true,
+                path,
+                request
+            });
+        } catch (error) {
+            results.push({
+                success: false,
+                error: error.message,
+                request
+            });
+        }
+    }
+    
+    return results;
+}
+
+// 性能基准测试
+function benchmark(gridSize = 100, iterations = 100) {
+    // 输入验证
+    if (typeof gridSize !== 'number' || gridSize <= 0) {
+        throw new Error('gridSize 必须是大于0的数字');
+    }
+    
+    if (typeof iterations !== 'number' || iterations <= 0) {
+        throw new Error('iterations 必须是大于0的数字');
+    }
+    
+    if (iterations > 10000) {
+        console.warn('⚠️  迭代次数过大，可能会影响性能');
+    }
+    
+    const grid = new Grid({ col: gridSize, row: gridSize });
+    const astar = new Astar(grid);
+    
+    // 预热
+    for (let i = 0; i < 10; i++) {
+        astar.search([0, 0], [gridSize - 1, gridSize - 1]);
+    }
+    
+    // 测试
+    const startTime = getPerformanceNow();
+    
+    for (let i = 0; i < iterations; i++) {
+        astar.search([0, 0], [gridSize - 1, gridSize - 1]);
+    }
+    
+    const endTime = getPerformanceNow();
+    const totalTime = endTime - startTime;
+    
+    return {
+        totalTime,
+        avgTime: totalTime / iterations,
+        throughput: iterations / (totalTime / 1000),
+        gridSize,
+        iterations
+    };
+}
+
+    // 预设配置
+    const presets = {
+        // 游戏开发预设
+        game: {
+            strategy: 'performance',
+            appType: 'game',
+            performance: 'high',
+            memory: 'moderate',
+            prefer: 'wasm'
+        },
+        
+        // Web应用预设
+        web: {
+            strategy: 'auto',
+            appType: 'web',
+            performance: 'medium',
+            memory: 'moderate'
+        },
+        
+        // 移动应用预设
+        mobile: {
+            strategy: 'memory',
+            appType: 'mobile',
+            performance: 'medium',
+            memory: 'strict',
+            avoid: 'wasm'
+        },
+        
+        // 服务端预设
+        server: {
+            strategy: 'performance',
+            appType: 'server',
+            performance: 'extreme',
+            memory: 'relaxed',
+            prefer: 'wasm'
+        },
+        
+        // 嵌入式预设
+        embedded: {
+            strategy: 'memory',
+            appType: 'embedded',
+            performance: 'low',
+            memory: 'strict',
+            avoid: 'wasm'
+        }
+    };
+
+// 预设工厂函数
+function createPresetAstar(grid, presetName, customOptions = {}) {
+    const preset = presets[presetName];
+    if (!preset) {
+        throw new Error(`未知预设: ${presetName}. 可用预设: ${Object.keys(presets).join(', ')}`);
+    }
+    
+    return new Astar(grid, { ...preset, ...customOptions });
+}
+
+// 智能创建函数 - 根据网格大小自动选择最佳配置
+function createSmartAstar(gridOptions, customOptions = {}) {
+    const grid = new Grid(gridOptions);
+    const gridSize = grid.col * grid.row;
+    
+    let autoOptions = {};
+    
+    // 根据网格大小自动选择策略
+    if (gridSize > 250000) {
+        autoOptions = { strategy: 'performance', prefer: 'wasm' };
+    } else if (gridSize > 50000) {
+        autoOptions = { strategy: 'performance', prefer: 'master' };
+    } else if (gridSize > 10000) {
+        autoOptions = { strategy: 'auto' };
+    } else {
+        autoOptions = { strategy: 'compatibility' };
+    }
+    
+    return new Astar(grid, { ...autoOptions, ...customOptions });
+}
+
+// 主要导出API
+const AstarLib = {
+    // 核心类
+    Grid: Grid,
+    Astar: Astar,
+    
+    // 工厂函数
+    create: createAstar,
+    createAstar,
+    createSmartAstar,
+    createPresetAstar,
+    
+    // 便捷函数
+    quickPath,
+    findMultiplePaths,
+    
+    // 工具函数
+    benchmark,
+    getEnvironmentInfo,
+    checkCompatibility,
+    
+    // 预设配置
+    presets,
+    
+    // 快速创建函数
+    createGameAstar: (grid, options = {}) => createPresetAstar(grid, 'game', options),
+    createWebAstar: (grid, options = {}) => createPresetAstar(grid, 'web', options),
+    createMobileAstar: (grid, options = {}) => createPresetAstar(grid, 'mobile', options),
+    createServerAstar: (grid, options = {}) => createPresetAstar(grid, 'server', options),
+    createEmbeddedAstar: (grid, options = {}) => createPresetAstar(grid, 'embedded', options),
+    
+    // 版本信息
+    version: '2.0.0',
+    name: 'Smart A* Algorithm Library',
+    
+    // 环境标识
+    isNode,
+    isBrowser
+};
+
+// 自动兼容性检查
+const compatibility = checkCompatibility();
+if (!compatibility.compatible) {
+    console.error('❌ 兼容性检查失败:', compatibility.issues);
+    
+    // 在浏览器环境中，如果只是缺少一些API，不要抛出错误
+    if (isBrowser && compatibility.issues.length > 0) {
+        console.warn('⚠️  浏览器环境兼容性问题，但将继续运行:', compatibility.issues);
+    } else {
+        throw new Error('环境不兼容: ' + compatibility.issues.join(', '));
+    }
+}
+
+if (compatibility.warnings.length > 0 && typeof console !== 'undefined') {
+    console.warn('⚠️  兼容性警告:', compatibility.warnings);
+}
+
+// 初始化日志
+if (typeof console !== 'undefined' && console.log) {
+    console.log('🚀 Smart A* Algorithm Library v2.0.0 已加载');
+    console.log('📱 环境:', compatibility.environment.platform);
+    console.log('💾 内存:', compatibility.environment.memory);
+    console.log('🖥️  CPU核心:', compatibility.environment.cores);
+}
+
+// ES Module 导出
+export default AstarLib;
+export { Grid, Astar, createAstar, createSmartAstar, quickPath, benchmark, presets };

package/package.json

@@ -1,28 +1,30 @@
 {
   "name": "fast-astar",
-  "version": "1.0.6",
+  "type": "module",
+  "version": "2.0.0",
   "description": "fast-astar is an implementation of a* algorithm using javascript. Small and fast.",
-  "main": "dist/index.js",
-  "scripts": {
-    "test": "node test.js"
-  },
+  "files": [
+    "astar.wasm",
+    "wasm.js",
+    "wasm.d.ts",
+    "index.js",
+    "Grid.js",
+    "Astar.js"
+  ],
+  "main": "index.js",
+  "types": "wasm.d.ts",
+  "sideEffects": [
+    "./snippets/*"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/sbfkcel/fast-astar.git"
   },
-  "keywords": [
-    "astar",
-    "a-star",
-  	"a*",
-    "algorithm",
-    "graph",
-    "traversal",
-    "path search"
-  ],
-  "author": "sbfkcel@163.com",
-  "license": "MIT",
-  "bugs": {
-    "url": "https://github.com/sbfkcel/fast-astar/issues"
-  },
-  "homepage": "https://github.com/sbfkcel/fast-astar#readme"
-}
+  "scripts": {
+    "test": "node tests/test.js",
+    "test:full": "node --max-old-space-size=8192 tests/test.js",
+    "test:wasm": "node tests/test_wasm.js",
+    "build:dev": "./scripts/build-dev.sh",
+    "build:rel": "./scripts/build-rel.sh"
+  }
+}