@xtia/grid 0.2.0 → 0.4.0

package/README.md

@@ -22,7 +22,7 @@ npm i @xtia/grid
 ```
 
 ```ts
-import { Grid } from "@xtia/grid"; // ~4.8kb gzipped (2.2kb + Pipe2D dep)
+import { Grid } from "@xtia/grid"; // ~5.1kb gzipped (2.5kb + Pipe2D dep)
 
 // initialise a 30x20 Grid<number> of 0's
 const numGrid = Grid.solid(30, 20, 0);
@@ -115,11 +115,11 @@ spriteMap.set(1, 0, "forest.png"); // modify the view
 console.log(world.get(1, 0)); // read the parent: "forest"
 ```
 
-For one-way read-mapping, use `grid.pipe` - a [Pipe2D](https://github.com/tiadrop/pipe2d) view into the grid's data.
+For one-way read-mapping, use `grid.values` - a [Pipe2D](https://github.com/tiadrop/pipe2d) view into the grid's data.
 
 ```ts
 // create a one-way, player-centred sprite map
-const viewport = world.pipe
+const viewport = world.values
 	.oob("mountain")
 	.map(t => t + ".png")
 	.crop(playerX - 5, playerY - 5, 10, 10);
@@ -138,7 +138,7 @@ const colourMap = new Map(Object.entries({
 	forest: C.x080,
 	mountain: C.xa70
 }));
-const minimap = world.pipe
+const minimap = world.values
 	.map(colourMap)
 	.floorCoordinates()
 	.crop(viewX, viewY, vw, vh)
@@ -236,7 +236,7 @@ We can perform batched updates, suppressing the 'change' event until a process c
 Pipe2D makes it easy to save and restore grid data:
 
 ```ts
-const snapshot = world.pipe.stash();
+const snapshot = world.values.stash();
 
 const restored = Grid.init(snapshot);
 // or paste it to an existing grid

package/lib/grid.d.ts

@@ -32,6 +32,31 @@ type CostFunc<T> = (cell: Cell<T>, context: {
     traversalType: TraversalType;
     from: Cell<T>;
 }) => number;
+type RectSpec = ({
+    left: number;
+    width: number;
+    right?: undefined;
+} | {
+    left: number;
+    width?: undefined;
+    right: number;
+} | {
+    left?: undefined;
+    width: number;
+    right: number;
+}) & ({
+    top: number;
+    height: number;
+    bottom?: undefined;
+} | {
+    top: number;
+    height?: undefined;
+    bottom: number;
+} | {
+    top?: undefined;
+    height: number;
+    bottom: number;
+});
 export declare class Cell<T> {
     readonly x: number;
     readonly y: number;
@@ -57,8 +82,9 @@ export declare class Grid<T> {
     private parentGet;
     private parentSet;
     private batch;
-    readonly cells: Pipe2D<Cell<T>>;
     protected constructor(width: number, height: number, parentGet: GetXYFunc<T>, parentSet: (x: number, y: number, value: T) => void, batch: (cb: () => void) => void);
+    readonly cells: Pipe2D<Cell<T>>;
+    values: Pipe2D<T>;
     pipe: Pipe2D<T>;
     batchUpdate(fn: () => void): void;
     get(x: number, y: number): T;
@@ -66,16 +92,19 @@ export declare class Grid<T> {
     trySet(x: number, y: number, value: T): boolean;
     fill(value: T): void;
     paste(source: Source2D<T>, x?: number, y?: number): void;
+    paste(get: GetXYFunc<T>): void;
     writeMask(mask: Source2D<boolean> | GetXYFunc<boolean>): Grid<T>;
     [Symbol.iterator](): IterableIterator<T>;
     forEach(callback: (value: T, x: number, y: number) => void): void;
-    map<U>(read: (initial: T, x: number, y: number) => U, write: (local: U, x: number, y: number) => T): Grid<U>;
+    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>;
+    region(rect: RectSpec): Grid<T>;
     scroll(xDelta: number, yDelta: number, fill: T): this;
     static init<T>(width: number, height: number, initCell: (x: number, y: number) => T): GridBase<T>;
     static init<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>;
+    private assertValidCoordinates;
 }
 export declare class GridBase<T> extends Grid<T> {
     private data;

package/lib/grid.js

@@ -6,7 +6,12 @@ export var TraversalType;
     TraversalType[TraversalType["diagonal"] = 1] = "diagonal";
     TraversalType[TraversalType["shortcut"] = 2] = "shortcut";
 })(TraversalType || (TraversalType = {}));
+const cardinalOffsets = [[-1, 0], [1, 0], [0, -1], [0, 1]];
+const allOffsets = [[-1, -1], [-1, 0], [-1, 1], [0, -1], [0, 1], [1, -1], [1, 0], [1, 1]];
 export class Cell {
+    x;
+    y;
+    gridView;
     constructor(x, y, gridView) {
         this.x = x;
         this.y = y;
@@ -36,12 +41,11 @@ export class Cell {
     }
     getNeighbours(includeDiagonals = false) {
         const offsets = includeDiagonals
-            ? [[-1, -1], [-1, 0], [-1, 1], [0, -1], [0, 1], [1, -1], [1, 0], [1, 1]]
-            : [[-1, 0], [1, 0], [0, -1], [0, 1]];
+            ? allOffsets
+            : cardinalOffsets;
         return offsets
-            .map(([ox, oy]) => [ox + this.x, oy + this.y])
-            .filter(([tx, ty]) => tx >= 0 && tx < this.gridView.width && ty >= 0 && ty < this.gridView.height)
-            .map(([tx, ty]) => this.gridView.cells.get(tx, ty));
+            .map(o => this.look(o[0], o[1]))
+            .filter(v => v);
     }
     look(xDelta, yDelta) {
         const [x, y] = [this.x + xDelta, this.y + yDelta];
@@ -50,8 +54,11 @@ export class Cell {
         return this.gridView.cells.get(xDelta + this.x, yDelta + this.y);
     }
     findPath(target, getCost, options = {}) {
-        const pathMap = this.calculateCosts(getCost, Object.assign(Object.assign({}, options), { stopAt: target }), true);
-        return pathMap === null || pathMap === void 0 ? void 0 : pathMap.get(...this.getSiblingXY(target));
+        const pathMap = this.calculateCosts(getCost, {
+            ...options,
+            stopAt: target,
+        }, true);
+        return pathMap?.get(...this.getSiblingXY(target));
     }
     getPathMap(getCost, options = {}) {
         return this.calculateCosts(getCost, options, true);
@@ -60,16 +67,14 @@ export class Cell {
         return this.calculateCosts(getCost, options);
     }
     calculateCosts(getCost, options, asPathMap = false) {
-        var _a, _b;
-        var _c;
         const visited = new Set();
         const costs = new Map();
-        const maxCost = (_c = options.maxCost) !== null && _c !== void 0 ? _c : Infinity;
+        const maxCost = options.maxCost ?? Infinity;
         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; }
+            ? (cell) => getCost.get(cell.value) ?? Infinity
             : getCost;
         costs.set(this, 0);
         const queue = new OrderedQueue([this, 0]);
@@ -79,7 +84,7 @@ export class Cell {
             if (visited.has(current))
                 continue;
             visited.add(current);
-            (_a = options.onVisit) === null || _a === void 0 ? void 0 : _a.call(options, { cell: current, cost: costs.get(current) });
+            options.onVisit?.({ cell: current, cost: costs.get(current) });
             if (stopAtCell && current === stopAtCell) {
                 break;
             }
@@ -92,7 +97,7 @@ export class 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);
+                : options.shortcutMap?.get(current.x, current.y);
             if (shortcutCells) {
                 const shortcuts = shortcutCells.map(loc => this.getSiblingCell(loc)).map(cell => ({
                     traversalType: TraversalType.shortcut,
@@ -101,7 +106,6 @@ export class Cell {
                 neighbours.push(...shortcuts);
             }
             neighbours.forEach(n => {
-                var _a;
                 if (visited.has(n.cell))
                     return;
                 const moveCost = getCostFn(n.cell, {
@@ -111,10 +115,10 @@ export class Cell {
                 if (moveCost === Infinity)
                     return;
                 const newCost = currentCost + moveCost;
-                const oldCost = (_a = costs.get(n.cell)) !== null && _a !== void 0 ? _a : Infinity;
+                const oldCost = costs.get(n.cell) ?? Infinity;
                 if (newCost < oldCost && newCost <= maxCost) {
                     costs.set(n.cell, newCost);
-                    pathInfo === null || pathInfo === void 0 ? void 0 : pathInfo.set(n.cell, current);
+                    pathInfo?.set(n.cell, current);
                     queue.add(n.cell, newCost);
                 }
             });
@@ -181,9 +185,8 @@ export class Cell {
         }
     }
     createVisibilityMap(isClear, options = {}) {
-        var _a;
         const maxDistance = options.maxDistance;
-        const boundariesVisible = (_a = options.boundariesVisible) !== null && _a !== void 0 ? _a : true;
+        const boundariesVisible = options.boundariesVisible ?? true;
         return new Pipe2D(this.gridView.width, this.gridView.height, (x, y) => {
             if (!isClear(this)) {
                 return x === this.x && y === this.y ? boundariesVisible : false;
@@ -208,76 +211,73 @@ function getDistance(c1, c2) {
     return Math.sqrt(Math.pow(c2.x - c1.x, 2) + Math.pow(c2.y - c1.y, 2));
 }
 export class Grid {
+    width;
+    height;
+    parentGet;
+    parentSet;
+    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) => {
-            if (x < 0 || x >= this.width || y < 0 || y >= this.height || !Number.isInteger(x) || !Number.isInteger(y)) {
+        if (!Number.isInteger(width) || !Number.isInteger(height) || width < 0 || height < 0) {
+            throw new Error(`Grid width & height must be non-negative integers; got (${width} x ${height})`);
+        }
+        this.cells = new Pipe2D(width, height, (x, y) => {
+            if (x < 0 || x >= width || y < 0 || y >= height || !Number.isInteger(x) || !Number.isInteger(y)) {
                 throw new RangeError(`Cell coordinates must be bounded integers; got (${x}, ${y})`);
             }
             return new Cell(x, y, this);
-        }).strict().withCache();
-        this.pipe = new Pipe2D(this);
-        if (!Number.isInteger(width) || !Number.isInteger(height)) {
-            throw new Error(`Grid width & height must be integer; got (${width} x ${height})`);
-        }
-        if (width < 0 || height < 0) {
-            throw new Error(`Grid width/height may not be less than 0; got (${width} x ${height})`);
-        }
+        }).withCache();
     }
+    cells;
+    values = new Pipe2D(this);
+    pipe = this.values;
     batchUpdate(fn) {
         this.batch(fn);
     }
     get(x, y) {
-        if (!Number.isInteger(x) || !Number.isInteger(y)) {
-            throw new Error(`Coordinates must be integer; got (${x}, ${y})`);
-        }
-        if (x < 0 || x >= this.width || y < 0 || y >= this.height) {
-            throw new RangeError("Coordinates out of bounds");
-        }
+        this.assertValidCoordinates(x, y);
         return this.parentGet(x, y);
     }
     set(x, y, value) {
-        if (!Number.isInteger(x) || !Number.isInteger(y)) {
-            throw new Error(`Coordinates must be integer; got (${x}, ${y})`);
-        }
-        if (x < 0 || x >= this.width || y < 0 || y >= this.height) {
-            throw new RangeError("Coordinates out of bounds");
-        }
+        this.assertValidCoordinates(x, y);
         this.parentSet(x, y, value);
     }
     trySet(x, y, value) {
         if (x < 0
             || x >= this.width
             || y < 0
-            || y >= this.height
-            || !Number.isInteger(x)
-            || !Number.isInteger(y))
+            || y >= this.height)
             return false;
-        this.set(x, y, value);
+        this.parentSet(x, y, value);
         return true;
     }
     fill(value) {
         this.batchUpdate(() => {
             for (let y = 0; y < this.height; y++) {
                 for (let x = 0; x < this.width; x++) {
-                    this.set(x, y, value);
+                    this.parentSet(x, y, value);
                 }
             }
         });
     }
-    paste(source, x = 0, y = 0) {
-        const cachedSource = new Pipe2D(source).stash();
+    paste(_source, x = 0, y = 0) {
+        this.assertValidCoordinates(x, y, true);
+        const source = typeof _source == "function"
+            ? new Pipe2D(this.width, this.height, _source)
+            : _source;
+        const sourcePipe = source instanceof Pipe2D ? source : new Pipe2D(source);
+        const cachedSource = sourcePipe.stash();
         this.batchUpdate(() => {
             for (let oy = 0; oy < source.height; oy++) {
                 for (let ox = 0; ox < source.width; ox++) {
                     const tx = ox + x, ty = oy + y;
                     if (tx < 0 || tx >= this.width || ty < 0 || ty >= this.height)
                         continue;
-                    this.set(tx, ty, cachedSource.get(ox, oy));
+                    this.parentSet(tx, ty, cachedSource.get(ox, oy));
                 }
             }
         });
@@ -287,10 +287,15 @@ export class Grid {
             ? mask
             : (x, y) => mask.get(x, y);
         return new Grid(this.width, this.height, this.parentGet, (x, y, v) => {
-            const writable = getMask(x, y);
-            if (writable) {
-                this.set(x, y, v);
+            try {
+                const writable = getMask(x, y);
+                if (!writable)
+                    return;
+            }
+            catch (e) {
+                throw new Error(`Failed to read write-mask at (${x}, ${y})`, { cause: e });
             }
+            this.parentSet(x, y, v);
         }, cb => this.batch(cb));
     }
     *[Symbol.iterator]() {
@@ -310,12 +315,39 @@ export class Grid {
     map(read, write) {
         return new Grid(this.width, this.height, (x, y) => read(this.parentGet(x, y), x, y), (x, y, value) => this.parentSet(x, y, write(value, x, y)), fn => this.batch(fn));
     }
-    region(x, y, width, height) {
-        if (!Number.isInteger(x) || !Number.isInteger(y)) {
-            throw new Error(`Region boundaries must be integer; got (${x}, ${y}), (${width} x ${height})`);
+    region(xOrRect, y = 0, width = 0, height = 0) {
+        let x;
+        if (typeof xOrRect == "number") {
+            x = xOrRect;
+        }
+        else {
+            if (xOrRect.left === undefined) {
+                width = xOrRect.width;
+                x = (this.width - 1 - xOrRect.right) - width + 1;
+            }
+            else {
+                x = xOrRect.left;
+                width = xOrRect.width === undefined
+                    ? (this.width - 1 - xOrRect.right) - x + 1
+                    : xOrRect.width;
+            }
+            if (xOrRect.top === undefined) {
+                height = xOrRect.height;
+                y = (this.height - 1 - xOrRect.bottom) - height + 1;
+            }
+            else {
+                y = xOrRect.top;
+                height = xOrRect.height === undefined
+                    ? (this.height - 1 - xOrRect.bottom) - y + 1
+                    : xOrRect.height;
+            }
         }
-        if (x < 0 || y < 0 || x + width > this.width || y + height > this.height) {
-            throw new Error("Requested region exceeds the parent's bounds");
+        this.assertValidCoordinates(x, y);
+        if (!Number.isInteger(width) || !Number.isInteger(height)) {
+            throw new Error("Region dimensions must be integer");
+        }
+        if (x + width > this.width || y + height > this.height) {
+            throw new RangeError("Requested region exceeds the parent's bounds");
         }
         return new Grid(width, height, (tx, ty) => {
             return this.parentGet(tx + x, ty + y);
@@ -324,9 +356,7 @@ export class Grid {
         }, fn => this.batch(fn));
     }
     scroll(xDelta, yDelta, fill) {
-        if (!Number.isInteger(xDelta) || !Number.isInteger(yDelta)) {
-            throw new Error(`Scroll offsets must be integer; got (${xDelta}, ${yDelta})`);
-        }
+        this.assertValidCoordinates(xDelta, yDelta, true);
         this.paste(this, xDelta, yDelta);
         if (xDelta > 0) {
             this.region(0, 0, xDelta, this.height).fill(fill);
@@ -357,12 +387,22 @@ export class Grid {
     static wrap(width, height, get, set, batch = cb => cb()) {
         return new Grid(width, height, get, set, batch);
     }
+    assertValidCoordinates(x, y, ignoreBounds = false) {
+        if (!Number.isInteger(x) || !Number.isInteger(y)) {
+            throw new Error(`Coordinates must be integer; got (${x}, ${y})`);
+        }
+        if (!ignoreBounds && (x < 0 || x >= this.width || y < 0 || y >= this.height)) {
+            throw new RangeError(`Coordinates out of bounds (${x}, ${y}) / (${this.width}, ${this.height})`);
+        }
+    }
 }
 export class GridBase extends Grid {
+    data;
+    eventHandlers = {};
     triggerEvent(name, data) {
-        var _a;
-        (_a = this.eventHandlers[name]) === null || _a === void 0 ? void 0 : _a.forEach(obj => obj.fn(data));
+        this.eventHandlers[name]?.forEach(obj => obj.fn(data));
     }
+    batchState = null;
     batchUpdate(fn) {
         if (this.batchState) {
             this.batchState.level++;
@@ -384,8 +424,6 @@ export class GridBase extends Grid {
     }
     constructor(source) {
         super(source.width, source.height, (x, y) => this.data[y * this.width + x], (x, y, value) => this._set(x, y, value), fn => this.batchUpdate(fn));
-        this.eventHandlers = {};
-        this.batchState = null;
         const sourcePipe = source instanceof Pipe2D
             ? source
             : new Pipe2D(source);

package/lib/utils.js

@@ -1,6 +1,6 @@
 export class OrderedQueue {
+    queue = [];
     constructor(...items) {
-        this.queue = [];
         items.forEach(v => this.add(...v));
     }
     add(value, priority) {

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "2D store and utilities, with zero-copy regions and transform layers, pathfinding, Pipe2D interop",
   "name": "@xtia/grid",
   "exports": {
@@ -21,6 +21,7 @@
   "files": [
     "lib/"
   ],
+  "license": "MIT",
   "devDependencies": {
     "@vitest/coverage-v8": "^4.1.10",
     "typescript": "^7.0.2",