@xtia/grid 0.0.6 → 0.0.8

package/README.md

@@ -1,6 +1,6 @@
 # `Grid`
 
-**Alpha**: Some API details may change
+**Alpha**: Pre-0.1.0 API details may change
 
 ## Summary
 
@@ -11,8 +11,8 @@ A mutable 2D grid with efficient region views, spatial operations, and seamless
 - **Mutable 2D storage** with type safety
 - **Zero-copy region views** - edit or provide subgrids and transformation layers without copying
 - **Spatial operations** - fill, paste, flood fill, pathfinding
-- **Pipe2D integration** - materialise pipes, get pipe views
-- **Consistent API** - for grids and regions
+- **First-class Pipe2D interoperability** – use grids as sources for pipes, or pipes as sources for grids
+- **Consistent API** - for grids, regions, and your existing 2D structures
 - **Mask support** - apply operations to arbitrary shapes
 
 ## Example
@@ -48,7 +48,7 @@ const grid = Grid.from(source);
 
 ### Wrapping existing structures
 
-Use Grid's interface over any read/write 2D structure:
+Use Grid's interface and features over any read/write 2D structure:
 
 ```ts
 const gameMap = [
@@ -134,7 +134,7 @@ const mountainCells = world.cells.toFlatArrayXY()
 
 ## Cell interface
 
-`grid.cells` provides a Pipe2D, for convenient transformation, of live-view interfaces relating to positions in the grid.
+`grid.cells` provides a Pipe2D, for convenient transformation, of Cell objects, each representing a live view into a grid location.
 
 ```ts
 const topLeft = world.cells.get(0, 0);
@@ -210,9 +210,9 @@ Unlike visibility maps, which are lazily evaluated according to the supplied `is
 
 `Grid` itself is an interface for reading and writing 2D data. `GridBase` - a subclass of `Grid` - maintains the actual storage of such data.
 
-Although the Grid factory methods (`Grid.solid()`, `Grid.from()`, `Grid.init()`) return a `GridBase<T>`, the mental model is that we're simply working with `Grid`s, therefore those factory methods live on `Grid`. The only API distinction is that `GridBase` provides a 'change' event, via `grid.on("change", handler)`.
+Although the Grid factory methods (`Grid.solid<T>()`, `Grid.from<T>()`, `Grid.init<T>()`) belong to `Grid`, they return a `GridBase<T>`. `Grid.wrap<T>()` is an exception, returning `Grid<T>`, as it uses a storage layer provided by the user. The only API distinction is that `GridBase` provides a 'change' event, via `grid.on("change", handler)`.
 
-You can perform batched updates, holding off the 'change' event until the batch process concludes, with `grid.batchUpdate(callback)`.
+We can perform batched updates, suppressing the 'change' event until a process concludes, with `grid.batchUpdate(callback)`.
 
 ## Save and load
 

package/lib/grid.d.ts

@@ -13,15 +13,16 @@ type PathFindOptions<T> = {
         cell: Cell<T>;
         cost: number;
     }) => void;
-    shortcutMap?: Source2D<Cell<T>[] | undefined>;
+    shortcutMap?: Source2D<Cell<T>[] | undefined> | GetXYFunc<Cell<T>[]>;
 };
 type CostMapOptions<T> = PathFindOptions<T> & {
-    stopAt?: [number, number] | Cell<T>;
+    stopAt?: LocationSpec<T>;
 };
 type VisibilityOptions = {
     maxDistance?: number;
     boundariesVisible?: boolean;
 };
+type LocationSpec<T> = Cell<T> | [number, number];
 export declare enum TraversalType {
     cardinal = 0,
     diagonal = 1,
@@ -38,16 +39,16 @@ export declare class Cell<T> {
     constructor(x: number, y: number, gridView: Grid<T>);
     get value(): T;
     set value(v: T);
+    private getSiblingCell;
+    private getSiblingXY;
     getNeighbours(includeDiagonals?: boolean): Cell<T>[];
     look(xDelta: number, yDelta: number): Cell<T> | undefined;
-    findPath(target: Cell<T> | [number, number], getCost: CostFunc<T>, options?: PathFindOptions<T>): Cell<T>[] | null;
-    getPathMap(getCost: CostFunc<T>, options?: PathFindOptions<T>): Pipe2D<Cell<T>[] | null>;
-    getCostMap(getCost: CostFunc<T>, options?: CostMapOptions<T>): Pipe2D<number>;
+    findPath(target: LocationSpec<T>, getCost: CostFunc<T> | Map<T, number>, options?: PathFindOptions<T>): Cell<T>[] | null;
+    getPathMap(getCost: CostFunc<T> | Map<T, number>, options?: PathFindOptions<T>): Pipe2D<Cell<T>[] | null>;
+    getCostMap(getCost: CostFunc<T> | Map<T, number>, options?: CostMapOptions<T>): Pipe2D<number>;
     private calculateCosts;
-    getLineTo(target: {
-        x: number;
-        y: number;
-    } | [number, number]): IterableIterator<Cell<T>>;
+    getLineTo(target: LocationSpec<T>): IterableIterator<Cell<T>>;
+    getLineTo(x: number, y: number): IterableIterator<Cell<T>>;
     createVisibilityMap(isClear: (cell: Cell<T>) => boolean, options?: VisibilityOptions): Pipe2D<boolean>;
 }
 export declare class Grid<T> {

package/lib/grid.js

@@ -18,6 +18,22 @@ export class Cell {
     set value(v) {
         this.gridView.set(this.x, this.y, v);
     }
+    getSiblingCell(location) {
+        if (Array.isArray(location))
+            return this.gridView.cells.get(...location);
+        if (location.gridView !== this.gridView) {
+            throw new Error("Target cell belongs to a different Grid");
+        }
+        return location;
+    }
+    getSiblingXY(location) {
+        if (Array.isArray(location))
+            return location;
+        if (location.gridView !== this.gridView) {
+            throw new Error("Target cell belongs to a different Grid");
+        }
+        return [location.x, location.y];
+    }
     getNeighbours(includeDiagonals = false) {
         const offsets = includeDiagonals
             ? [[-1, -1], [-1, 0], [-1, 1], [0, -1], [0, 1], [1, -1], [1, 0], [1, 1]]
@@ -34,15 +50,12 @@ export class Cell {
         return this.gridView.cells.get(xDelta + this.x, yDelta + this.y);
     }
     findPath(target, getCost, options = {}) {
-        const targetXY = Array.isArray(target)
-            ? target
-            : [target.x, target.y];
         const pathMap = this.calculateCosts(getCost, {
-            stopAt: targetXY,
+            stopAt: target,
             allowDiagonal: options.allowDiagonal,
             maxCost: options.maxCost,
         }, true);
-        return pathMap === null || pathMap === void 0 ? void 0 : pathMap.get(...targetXY);
+        return pathMap === null || pathMap === void 0 ? void 0 : pathMap.get(...this.getSiblingXY(target));
     }
     getPathMap(getCost, options = {}) {
         return this.calculateCosts(getCost, options, true);
@@ -59,41 +72,43 @@ export class Cell {
         const pathInfo = asPathMap
             ? new Map()
             : null;
+        const getCostFn = getCost instanceof Map
+            ? (cell) => { var _a; return (_a = getCost.get(cell.value)) !== null && _a !== void 0 ? _a : Infinity; }
+            : getCost;
         costs.set(this, 0);
         const queue = new OrderedQueue(cell => { var _a; return (_a = costs.get(cell)) !== null && _a !== void 0 ? _a : Infinity; }, this);
-        const targetCell = Array.isArray(options.stopAt)
-            ? this.gridView.cells.get(options.stopAt[0], options.stopAt[1])
-            : options.stopAt;
-        if (targetCell && targetCell.gridView !== this.gridView) {
-            throw new Error("Target cell belongs to a different Grid");
-        }
+        const stopAtCell = options.stopAt && this.getSiblingCell(options.stopAt);
         while (queue.length > 0) {
             const current = queue.take();
-            (_a = options.onVisit) === null || _a === void 0 ? void 0 : _a.call(options, { cell: current, cost: costs.get(current) });
             if (visited.has(current))
                 continue;
             visited.add(current);
-            if (targetCell && current === targetCell) {
+            (_a = options.onVisit) === null || _a === void 0 ? void 0 : _a.call(options, { cell: current, cost: costs.get(current) });
+            if (stopAtCell && current === stopAtCell) {
                 break;
             }
             const currentCost = costs.get(current);
             const neighbours = current.getNeighbours(options.allowDiagonal).map(cell => ({
-                traversalType: cell.x == current.x && cell.y == current.y ? TraversalType.cardinal : TraversalType.diagonal,
+                traversalType: cell.x == current.x && cell.y == current.y
+                    ? TraversalType.cardinal
+                    : TraversalType.diagonal,
                 cell
             }));
-            if (options.shortcutMap) {
-                const shortcuts = (_b = options.shortcutMap.get(current.x, current.y)) === null || _b === void 0 ? void 0 : _b.map(cell => ({
+            const shortcutCells = typeof options.shortcutMap == "function"
+                ? options.shortcutMap(current.x, current.y)
+                : (_b = options.shortcutMap) === null || _b === void 0 ? void 0 : _b.get(current.x, current.y);
+            if (shortcutCells) {
+                const shortcuts = shortcutCells.map(cell => ({
                     traversalType: TraversalType.shortcut,
                     cell
                 }));
-                if (shortcuts)
-                    neighbours.push(...shortcuts);
+                neighbours.push(...shortcuts);
             }
             neighbours.forEach(n => {
                 var _a;
                 if (visited.has(n.cell))
                     return;
-                const moveCost = getCost(n.cell, {
+                const moveCost = getCostFn(n.cell, {
                     traversalType: n.traversalType,
                     from: current,
                 });
@@ -135,10 +150,10 @@ export class Cell {
         return this.gridView.cells.map(costs, () => Infinity)
             .strict();
     }
-    *getLineTo(target) {
-        const [targetX, targetY] = Array.isArray(target)
-            ? target
-            : [target.x, target.y];
+    *getLineTo(targetOrX, _targetY) {
+        const [targetX, targetY] = typeof targetOrX == "number"
+            ? [targetOrX, _targetY]
+            : this.getSiblingXY(targetOrX);
         if (this.x === targetX && this.y === targetY) {
             yield this;
             return;
@@ -182,7 +197,7 @@ export class Cell {
                     return false;
                 }
             }
-            for (const cell of this.getLineTo({ x, y })) {
+            for (const cell of this.getLineTo([x, y])) {
                 if (isClear(cell))
                     continue;
                 return cell.x === x && cell.y === y

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "2D store and utilities, with zero-copy regions and transform layers, pathfinding, Pipe2D interop",
   "name": "@xtia/grid",
   "exports": {