@xtia/grid 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,156 @@
+# `Grid`
+
+## Summary
+
+A mutable 2D grid with efficient region views, spatial operations, and seamless interoperability with [Pipe2D](https://github.com/tiadrop/pipe2d). Store, edit, and transform 2D data with an ergonomic API designed for practical use.
+
+## Features
+
+- **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
+- **Mask support** - apply operations to arbitrary shapes
+
+## Example
+
+```
+npm i @xtia/grid
+```
+
+```ts
+import { Grid } from "@xtia/grid";
+
+// initialise a 30x20 Grid<number> of 0's
+const numGrid = Grid.solid(30, 20, 0);
+
+// change a value
+numGrid.set(3, 3, 50);
+
+// initialise a chessboard
+const chessGrid = Grid.init(8, 8, (x, y) => 
+  (x + y) % 2 === 0 ? 'black' : 'white'
+);
+
+// read a value
+const colour = chessGrid.get(4, 5);
+
+// initialise a grid from a Pipe2D
+const source = imagePipe
+	.crop(10, 10, 64, 64)
+	.scale(.5)
+	.rotateLeft();
+const grid = Grid.from(source);
+```
+
+## Regions
+
+Use `grid.region(x, y, w, h)` to define a subgrid. The subgrid is a **view** into the parent; changes to the subgrid affect the parent and vice-versa.
+
+```ts
+// game map with terrain
+const world = Grid.solid(100, 100, 0); // 0 = grass
+
+// add a lake
+world.region(30, 30, 20, 20).fill(1); // 1 = water
+
+// add mountains around the lake with a circular mask
+const centre = world.cells.get(40, 40);
+const mask = (x: number, y: number) => {
+  const dist = Math.hypot(x - centre.x, y - centre.y);
+  return dist > 12 && dist < 18; // mountain ring
+};
+world.fill(2, mask); // 2 = mountain
+
+// get a view of just the interesting area
+const lakeRegion = world.region(25, 25, 30, 30);
+
+// do we want a distinct, self-contained copy of the region?
+const lakeGrid = Grid.from(lakeRegion);
+```
+
+## Transformation Layers
+
+`grid.map(read, write)` creates a **view** that reads and writes the parent through the provided transformation functions.
+
+```ts
+const sprites = ["grass.png", "water.png", "mountain.png", "forest.png"];
+const spriteMap = world.map(
+	n => sprites[n],
+	s => sprites.indexOf(s)
+);
+
+world.set(0, 0, 2); // modify the parent
+console.log(spriteMap.get(0, 0)); // read the transformed view: "mountain.png"
+spriteMap.set(1, 0, "forest.png"); // modify the view
+console.log(world.get(1, 0)); // read the parent: 3
+```
+
+For one-way read-mapping, use `grid.pipe` - a [Pipe2D](https://github.com/tiadrop/pipe2d) view into the grid's data.
+
+## Cell interface
+
+`grid.cells` provides a Pipe2D, for convenient transformation, of live-view interfaces relating to positions in the grid.
+
+```ts
+const topLeft = world.cells.get(0, 0);
+console.log(topLeft.value); // 2
+
+topLeft.value = 3; // modifies the underlying data
+console.log(spriteMap.get(0, 0)); // now "forest.png";
+
+// navigate by offset
+const adjacentCell = topLeft.look(1, 0);
+console.log(adjacentCell.x, adjacentCell.y); // 1, 0
+```
+
+Cells provide methods for locational utilities such as pathfinding and visibility mapping.
+
+Cells are unique to, owned by, and coordinated relative to the view that provided them. Their pathfinding and visibility mapping features are unaware of space outside of their view's bounds.
+
+### Path finding
+```
+const costs = [1, Infinity, Infinity, 2]; // grass=1, water/mountain=impassable, forest=2
+
+const start = world.cells.get(5, 5);
+const destination = world.cells.get(90, 90);
+const path = start.findPath(
+	destination,
+	(cell) => costs[cell.value]
+); // Cell<number>[]
+```
+
+### Visibility mapping
+
+```ts
+const visibility = start.createVisibilityMap(
+	cell => cell.value == 0 // anything except grass blocks vision
+);
+
+// any 2d source, including visibility maps, can be used as a mask
+// paste(source: Source2D<T>, mask?: Source2D<boolean>)
+screenGrid.paste(spriteMap, visibility.map(v => v != Visibility.hidden));
+
+// using pipe2d's convenience
+const mountainCells = world.cells.toFlatArrayXY().filter(c => c.value === 2);
+```
+
+### Reusing path data
+
+Use `cell.getPathMap(costFunc)` to create a Pipe2D of optimal paths from the parent cell. The grid space is explored once to produce an internal traversal map, and paths to individual cells are constructed form that data (and cached) when that pipe is queried.
+
+```ts
+const pathMap = start.getPathMap(c => costs[c]);
+
+const pathToCentre = pathMap.get(50, 50);
+const pathToCorner = pathMap.get(99, 99);
+```
+
+## 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)`.
+
+You can perform batched updates, holding off the 'change' event until the batch process concludes, with `grid.batchUpdate(callback)`.

package/lib/grid.d.ts

@@ -1,5 +1,5 @@
 import { Pipe2D } from "@xtia/pipe2d";
-import { Angle, GetXYFunc, Source2D } from "./utils.js";
+import { GetXYFunc, Source2D } from "./utils.js";
 type ChangeEvent<T> = {
     changedCells: Set<Cell<T>>;
 };
@@ -54,41 +54,28 @@ export declare class Cell<T> {
 export declare class Grid<T> {
     readonly width: number;
     readonly height: number;
-    private batch;
     private parentGet;
     private parentSet;
+    private batch;
     readonly cells: Pipe2D<Cell<T>>;
-    protected constructor(width: number, height: number, get: GetXYFunc<T>, set: (x: number, y: number, value: T) => void, batch: (cb: () => void) => void);
-    private writeMasks;
+    protected constructor(width: number, height: number, parentGet: GetXYFunc<T>, parentSet: (x: number, y: number, value: T) => void, batch: (cb: () => void) => void);
     pipe: Pipe2D<T>;
-    private isWritable;
     batchUpdate(fn: () => void): void;
     get(x: number, y: number): T;
     set(x: number, y: number, value: T): void;
     trySet(x: number, y: number, value: T): boolean;
-    fill(value: T): void;
-    paste(x: number, y: number, source: Source2D<T>): void;
-    applyWriteMask(mask: Source2D<boolean>): () => void;
+    fill(value: T, mask?: Source2D<boolean> | GetXYFunc<boolean>): void;
+    paste(x: number, y: number, source: Source2D<T>, mask?: Source2D<boolean> | GetXYFunc<boolean>): void;
     [Symbol.iterator](): IterableIterator<{
         x: number;
         y: number;
         value: T;
     }>;
     forEach(callback: (value: T, x: number, y: number) => void): void;
-    getVisibilityMap(originX: number, originY: number, maxDistance: number, isWall: (value: T, x: number, y: number) => boolean, options?: {
-        startAngle?: Angle;
-        endAngle?: Angle;
-        includeWalls?: boolean;
-        angleStep?: Angle;
-    }): Pipe2D<boolean>;
-    getFloodMap(startX: number, startY: number, predicate: (value: T, x: number, y: number, initialValue: T) => boolean, options?: {
-        includeDiagonals?: boolean;
-        maxDistance?: number;
-    }): Pipe2D<boolean>;
     combine<U, R>(aux: Source2D<U>, cb: (source: T, aux: U) => R): GridBase<R>;
     map<U>(read: (initial: T, x: number, y: number) => U, write: (local: U, x: number, y: number) => T): Grid<U>;
     region(x: number, y: number, width: number, height: number): Grid<T>;
-    static init<T>(width: number, height: number, initCell: () => T): GridBase<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>;
 }
@@ -99,7 +86,6 @@ export declare class GridBase<T> extends Grid<T> {
     private batchState;
     batchUpdate(fn: () => void): void;
     constructor(source: Source2D<T>);
-    constructor(width: number, height: number, cellInit: GetXYFunc<T>);
     on<K extends keyof EventMap<T>>(eventName: K, handler: (data: EventMap<T>[K]) => void): () => void;
     private xyToIndex;
     private _set;

package/lib/grid.js

@@ -1,5 +1,5 @@
 import { Pipe2D } from "@xtia/pipe2d";
-import { angleToRadians, OrderedQueue } from "./utils.js";
+import { OrderedQueue } from "./utils.js";
 export var TraversalType;
 (function (TraversalType) {
     TraversalType[TraversalType["cardinal"] = 0] = "cardinal";
@@ -177,6 +177,8 @@ export class Cell {
     }
     createVisibilityMap(isWall, maxDistance = Infinity) {
         return new Pipe2D(this.gridView.width, this.gridView.height, (x, y) => {
+            if (isWall(this))
+                return Visibility.hidden;
             const distance = getDistance(this, { x, y });
             if (distance > maxDistance) {
                 return Visibility.hidden;
@@ -200,20 +202,16 @@ function getDistance(c1, c2) {
     return Math.sqrt(Math.pow(c2.x - c1.x, 2) + Math.pow(c2.y - c1.y, 2));
 }
 export class Grid {
-    constructor(width, height, get, set, batch) {
+    constructor(width, height, parentGet, parentSet, batch) {
         this.width = width;
         this.height = height;
+        this.parentGet = parentGet;
+        this.parentSet = parentSet;
         this.batch = batch;
         this.cells = new Pipe2D(this.width, this.height, (x, y) => {
             return new Cell(x, y, this);
         }).strict().withCache();
-        this.writeMasks = [];
         this.pipe = new Pipe2D(this);
-        this.parentGet = get;
-        this.parentSet = set;
-    }
-    isWritable(x, y) {
-        return !this.writeMasks.some(mask => !mask.mask.get(x, y));
     }
     batchUpdate(fn) {
         this.batch(fn);
@@ -228,8 +226,7 @@ export class Grid {
         if (x < 0 || x >= this.width || y < 0 || y >= this.height) {
             throw new RangeError("Coordinates out of bounds");
         }
-        if (this.isWritable(x, y))
-            this.parentSet(x, y, value);
+        this.parentSet(x, y, value);
     }
     trySet(x, y, value) {
         if (x < 0 || x >= this.width || y < 0 || y >= this.height)
@@ -237,39 +234,41 @@ export class Grid {
         this.set(x, y, value);
         return true;
     }
-    fill(value) {
+    fill(value, mask) {
+        const maskSource = typeof mask == "function" ? {
+            width: this.width,
+            height: this.height,
+            get: mask
+        } : mask;
         this.batchUpdate(() => {
             for (let y = 0; y < this.height; y++) {
                 for (let x = 0; x < this.width; x++) {
-                    const tx = x;
-                    const ty = y;
-                    this.trySet(tx, ty, value);
+                    if (maskSource && !maskSource.get(x, y))
+                        continue;
+                    this.trySet(x, y, value);
                 }
             }
         });
     }
-    paste(x, y, source) {
+    paste(x, y, source, mask) {
+        const maskSource = typeof mask == "function" ? {
+            width: this.width,
+            height: this.height,
+            get: mask
+        } : mask;
         const cachedSource = new GridBase(source);
         this.batchUpdate(() => {
             for (let oy = 0; oy < source.height; oy++) {
                 for (let ox = 0; ox < source.width; ox++) {
                     const tx = ox + x;
                     const ty = oy + y;
+                    if (maskSource && !maskSource.get(tx, ty))
+                        continue;
                     this.trySet(tx, ty, cachedSource.get(ox, oy));
                 }
             }
         });
     }
-    applyWriteMask(mask) {
-        const unique = { mask };
-        this.writeMasks.push(unique);
-        return () => {
-            const idx = this.writeMasks.indexOf(unique);
-            if (idx == -1)
-                throw new Error("Mask was not present");
-            this.writeMasks.splice(idx, 1);
-        };
-    }
     *[Symbol.iterator]() {
         for (let y = 0; y < this.height; y++) {
             for (let x = 0; x < this.width; x++) {
@@ -284,91 +283,15 @@ export class Grid {
             }
         }
     }
-    getVisibilityMap(originX, originY, maxDistance, isWall, options) {
-        const { startAngle = { asTurns: 0 }, endAngle = { asTurns: 1 }, includeWalls = false, angleStep = { asDegrees: 1 } } = options || {};
-        const visibilityGrid = new GridBase(this.width, this.height, () => false);
-        const startRad = angleToRadians(startAngle);
-        const endRad = angleToRadians(endAngle);
-        const stepRad = angleToRadians(angleStep);
-        const totalAngle = endRad > startRad
-            ? endRad - startRad
-            : endRad + (2 * Math.PI) - startRad;
-        const effectiveStepRad = Math.max(0.001, Math.min(stepRad, totalAngle));
-        const steps = Math.ceil(totalAngle / effectiveStepRad);
-        for (let i = 0; i <= steps; i++) {
-            const angle = startRad + i * effectiveStepRad;
-            if (angle > endRad && i > 0)
-                break;
-            const endX = Math.round(originX + maxDistance * Math.cos(angle));
-            const endY = Math.round(originY + maxDistance * Math.sin(angle));
-            let x0 = originX;
-            let y0 = originY;
-            let x1 = endX;
-            let y1 = endY;
-            const dx = Math.abs(x1 - x0);
-            const dy = Math.abs(y1 - y0);
-            const sx = x0 < x1 ? 1 : -1;
-            const sy = y0 < y1 ? 1 : -1;
-            let err = dx - dy;
-            while (true) {
-                if (x0 < 0 || x0 >= this.width || y0 < 0 || y0 >= this.height) {
-                    break;
-                }
-                const isWallCell = isWall(this.get(x0, y0), x0, y0);
-                if (isWallCell) {
-                    if (includeWalls) {
-                        visibilityGrid.set(x0, y0, true);
-                    }
-                    break;
-                }
-                else {
-                    visibilityGrid.set(x0, y0, true);
-                }
-                if (x0 === x1 && y0 === y1)
-                    break;
-                const e2 = 2 * err;
-                if (e2 > -dy) {
-                    err -= dy;
-                    x0 += sx;
-                }
-                if (e2 < dx) {
-                    err += dx;
-                    y0 += sy;
-                }
-            }
-        }
-        return visibilityGrid.pipe;
-    }
-    getFloodMap(startX, startY, predicate, options) {
-        const { includeDiagonals = false, maxDistance = Infinity } = options || {};
-        const result = new GridBase(this.width, this.height, () => false);
-        const startValue = this.get(startX, startY);
-        if (!predicate(startValue, startX, startY, startValue)) {
-            return result.pipe;
-        }
-        const queue = [[startX, startY, 0]];
-        result.set(startX, startY, true);
-        while (queue.length > 0) {
-            const [x, y, distance] = queue.shift();
-            if (distance >= maxDistance)
-                continue;
-            this.cells.get(x, y).getNeighbours(includeDiagonals)
-                .forEach(neighbour => {
-                if (result.get(neighbour.x, neighbour.y))
-                    return;
-                if (predicate(neighbour.value, neighbour.x, neighbour.y, startValue)) {
-                    result.set(neighbour.x, neighbour.y, true);
-                    queue.push([neighbour.x, neighbour.y, distance + 1]);
-                }
-            });
-        }
-        return result.pipe;
-    }
     combine(aux, cb) {
         const width = Math.min(this.width, aux.width);
         const height = Math.min(this.height, aux.height);
-        return new GridBase(width, height, (x, y) => {
-            return cb(this.get(x, y), aux.get(x, y));
+        return new GridBase({
+            width,
+            height,
+            get: (x, y) => {
+                return cb(this.get(x, y), aux.get(x, y));
+            }
         });
     }
     map(read, write) {
@@ -384,7 +307,11 @@ export class Grid {
         }, fn => this.batch(fn));
     }
     static init(width, height, initCell) {
-        return new GridBase(width, height, initCell);
+        return new GridBase({
+            width,
+            height,
+            get: initCell
+        });
     }
     static from(source) {
         return new GridBase(source);
@@ -416,22 +343,14 @@ export class GridBase extends Grid {
             this.triggerChange(changed);
         }
     }
-    constructor(widthOrSource, height, cellInit) {
-        const source = typeof widthOrSource == "object"
-            ? widthOrSource
-            : {
-                width: widthOrSource,
-                height: height,
-                get: cellInit
-            };
+    constructor(source) {
         super(source.width, source.height, (x, y) => this.data[this.xyToIndex(x, y)], (x, y, value) => this._set(x, y, value), fn => this.batchUpdate(fn));
         this.eventHandlers = {};
         this.batchState = null;
-        this.data = Array.from({ length: source.width * source.height }, (_, i) => {
-            const x = i % source.width;
-            const y = Math.floor(i / source.width);
-            return source.get(x, y);
-        });
+        const sourcePipe = source instanceof Pipe2D
+            ? source
+            : new Pipe2D(source);
+        this.data = sourcePipe.toFlatArrayXY();
     }
     on(eventName, handler) {
         const unique = { fn: handler };

package/package.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.0.1",
-  "description": "2D store and utilities",
+  "version": "0.0.3",
+  "description": "2D store and utilities, with zero-copy regions and transform layers, pathfinding, Pipe2D interop",
   "name": "@xtia/grid",
   "exports": {
     ".": {
@@ -11,16 +11,14 @@
   },
   "scripts": {
     "build": "npx tsc",
-    "test": "npx jest"
+    "test": "npx vitest run"
   },
   "files": [
     "lib/"
   ],
   "devDependencies": {
-    "@swc/jest": "^0.2.39",
-    "@types/jest": "^30.0.0",
-    "jest": "^30.4.2",
-    "typescript": "^7.0.2"
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
   },
   "dependencies": {
     "@xtia/pipe2d": "^2.1.0"