@xtia/grid 0.0.5 → 0.0.7

package/README.md

@@ -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
@@ -22,7 +22,7 @@ npm i @xtia/grid
 ```
 
 ```ts
-import { Grid } from "@xtia/grid"; // ~5.3kb gzipped
+import { Grid } from "@xtia/grid"; // ~4.8kb gzipped
 
 // initialise a 30x20 Grid<number> of 0's
 const numGrid = Grid.solid(30, 20, 0);
@@ -46,6 +46,34 @@ const source = imagePipe
 const grid = Grid.from(source);
 ```
 
+### Wrapping existing structures
+
+Use Grid's interface over any read/write 2D structure:
+
+```ts
+const gameMap = [
+	[0, 1, -1, 2],
+	[1, 0, 1, 0],
+	[-1, 1, 0, 2],
+	[2, 0, 2, -1]
+];
+
+// create a *live view* Grid over gameMap
+const grid = Grid.wrap(
+	gameMap[0].length, // width
+	gameMap.length, // height
+	(x, y) => gameMap[y][x], // get
+	(x, y, value) => gameMap[y][x] = value // set
+);
+
+// reading the grid = reading the source
+gameMap[0][0] = 50;
+console.log(grid.get(0, 0)); // 50
+// writing to the grid = writing to the source
+grid.set(3, 3, 100);
+console.log(gameMap[3][3]); // 100
+```
+
 ## Regions
 
 Use `grid.region(x, y, w, h)` to define a subgrid. The subgrid is **zero-copy view** into the parent; changes to the subgrid affect the parent and vice-versa.
@@ -106,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);
@@ -176,15 +204,15 @@ const pathToCentre = pathMap.get(50, 50);
 const pathToCorner = pathMap.get(99, 99);
 ```
 
-Unlike visibility maps, which are lazily evaluated according to the supplied `isWall` function *when the map is queried*, path maps necessarily reflect the underlying data *when the map is created*. This distinction is hinted through the `create*` vs `get*` naming.
+Unlike visibility maps, which are lazily evaluated according to the supplied `isClear` function *when the map is queried* (but can be easily cached with `visMap.withCache()`), path maps use a relatively expensive traversal map that's created *when the map is created*. This distinction is hinted through the `create*` vs `get*` naming.
 
 ## The storage layer
 
 `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

@@ -16,12 +16,13 @@ type PathFindOptions<T> = {
     shortcutMap?: Source2D<Cell<T>[] | undefined>;
 };
 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;
+    findPath(target: LocationSpec<T>, 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>;
     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> {
@@ -77,6 +78,7 @@ export declare class Grid<T> {
     static init<T>(width: number, height: number, initCell: (x: number, y: number) => T): GridBase<T>;
     static from<T>(source: Source2D<T>): GridBase<T>;
     static solid<T>(width: number, height: number, fillValue: T): GridBase<T>;
+    static wrap<T>(width: number, height: number, get: (x: number, y: number) => T, set: (x: number, y: number, value: T) => void, batch?: (callback: () => void) => void): Grid<T>;
 }
 export declare class GridBase<T> extends Grid<T> {
     private data;

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);
@@ -61,24 +74,21 @@ export class Cell {
             : null;
         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) {
+            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) {
@@ -135,10 +145,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 +192,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
@@ -314,6 +324,9 @@ export class Grid {
     static solid(width, height, fillValue) {
         return new GridBase(Pipe2D.solid(fillValue, width, height));
     }
+    static wrap(width, height, get, set, batch = cb => cb()) {
+        return new Grid(width, height, get, set, batch);
+    }
 }
 export class GridBase extends Grid {
     triggerEvent(name, data) {

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "2D store and utilities, with zero-copy regions and transform layers, pathfinding, Pipe2D interop",
   "name": "@xtia/grid",
   "exports": {
@@ -9,6 +9,7 @@
     },
     "./lib/*": null
   },
+  "keywords": ["grid", "game-dev", "pathfinding", "cellular-automata"],
   "scripts": {
     "build": "npx tsc",
     "test": "npx vitest run"