@xtia/grid 0.1.1 → 0.3.0

package/README.md

@@ -43,7 +43,7 @@ const source = imagePipe
 	.crop(10, 10, 64, 64)
 	.scale(.5)
 	.rotateLeft();
-const grid = Grid.from(source);
+const grid = Grid.init(source);
 ```
 
 ### Wrapping existing structures
@@ -97,7 +97,7 @@ world.writeMask(mask).fill("mountain");
 const lakeRegion = world.region(25, 25, 30, 30);
 
 // do we want a distinct, self-contained copy of the region?
-const lakeGrid = Grid.from(lakeRegion);
+const lakeGrid = Grid.init(lakeRegion);
 ```
 
 ## Transformation Layers
@@ -225,9 +225,9 @@ Unlike visibility maps, which are lazily evaluated according to the supplied `is
 
 ## 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.
+`Grid` itself is an interface that sits on top of a synchronous 2D read/write mechanism. `GridBase` is a subclass of `Grid` with built-in storage.
 
-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)`.
+Although the factory methods `Grid.solid<T>()` and `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)`.
 
 We can perform batched updates, suppressing the 'change' event until a process concludes, with `grid.batchUpdate(callback)`.
 
@@ -238,7 +238,7 @@ Pipe2D makes it easy to save and restore grid data:
 ```ts
 const snapshot = world.pipe.stash();
 
-const restored = Grid.from(snapshot);
+const restored = Grid.init(snapshot);
 // or paste it to an existing grid
 world.paste(snapshot);
 ```

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;
@@ -69,13 +94,15 @@ export declare class Grid<T> {
     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 from<T>(source: Source2D<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

@@ -219,65 +219,52 @@ export class Grid {
                 throw new RangeError(`Cell coordinates must be bounded integers; got (${x}, ${y})`);
             }
             return new Cell(x, y, this);
-        }).strict().withCache();
+        }).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})`);
+        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})`);
         }
     }
     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();
+        this.assertValidCoordinates(x, y, true);
+        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));
                 }
             }
         });
@@ -289,7 +276,7 @@ export class Grid {
         return new Grid(this.width, this.height, this.parentGet, (x, y, v) => {
             const writable = getMask(x, y);
             if (writable) {
-                this.set(x, y, v);
+                this.parentSet(x, y, v);
             }
         }, cb => this.batch(cb));
     }
@@ -310,12 +297,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;
         }
-        if (x < 0 || y < 0 || x + width > this.width || y + height > this.height) {
-            throw new Error("Requested region exceeds the parent's bounds");
+        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;
+            }
+        }
+        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 +338,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);
@@ -342,22 +354,29 @@ export class Grid {
         }
         return this;
     }
-    static init(width, height, initCell) {
+    static init(widthOrSource, height, initCell) {
+        if (typeof widthOrSource == "object")
+            return new GridBase(widthOrSource);
         return new GridBase({
-            width,
-            height,
+            width: widthOrSource,
+            height: height,
             get: initCell
         });
     }
-    static from(source) {
-        return new GridBase(source);
-    }
     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);
     }
+    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 {
     triggerEvent(name, data) {

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.1",
+  "version": "0.3.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",