@xtia/grid 0.1.0 → 0.2.0

package/README.md

@@ -22,7 +22,7 @@ npm i @xtia/grid
 ```
 
 ```ts
-import { Grid } from "@xtia/grid"; // ~4.8kb gzipped
+import { Grid } from "@xtia/grid"; // ~4.8kb gzipped (2.2kb + Pipe2D dep)
 
 // initialise a 30x20 Grid<number> of 0's
 const numGrid = Grid.solid(30, 20, 0);
@@ -32,7 +32,7 @@ numGrid.set(3, 3, 50);
 
 // initialise a chessboard
 const chessGrid = Grid.init(8, 8, (x, y) => 
-  (x + y) % 2 === 0 ? 'black' : 'white'
+	(x + y) % 2 === 0 ? 'black' : 'white'
 );
 
 // read a value
@@ -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
@@ -106,12 +106,11 @@ const lakeGrid = Grid.from(lakeRegion);
 
 ```ts
 const spriteMap = world.map(
-	type => type + ".png",
-	sprite => sprite.replace(/\..*/, '')
+	type => type + ".png", // add .png on parent-read
+	sprite => sprite.replace(/\..*/, '') // remove it on parent-write
 );
 
-world.set(0, 0, "mountain"); // modify the parent
-console.log(spriteMap.get(0, 0)); // read the transformed view: "mountain.png"
+console.log(spriteMap.get(0, 0)); // read the transformed view: "grass.png"
 spriteMap.set(1, 0, "forest.png"); // modify the view
 console.log(world.get(1, 0)); // read the parent: "forest"
 ```
@@ -144,7 +143,6 @@ const minimap = world.pipe
 	.floorCoordinates()
 	.crop(viewX, viewY, vw, vh)
 	.stretch(canvas.width, canvas.height);
-
 ```
 
 ## Cell interface
@@ -227,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)`.
 
@@ -240,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);
 ```
@@ -248,7 +246,7 @@ world.paste(snapshot);
 For persistent storage or transmission, Pipe2D can export as array:
 
 ```ts
-const saved = snapshot.toFlatArrayXY(); // ["mountain", "forest", "grass", ...]
+const saved = snapshot.toFlatArrayXY(); // ["grass", "forest", "grass", ...]
 
 const restoredSnapshot = Pipe2D.fromFlatArrayXY(saved);
 ```

package/lib/grid.d.ts

@@ -67,18 +67,13 @@ export declare class Grid<T> {
     fill(value: T): void;
     paste(source: Source2D<T>, x?: number, y?: number): void;
     writeMask(mask: Source2D<boolean> | GetXYFunc<boolean>): Grid<T>;
-    [Symbol.iterator](): IterableIterator<{
-        x: number;
-        y: number;
-        value: T;
-    }>;
+    [Symbol.iterator](): IterableIterator<T>;
     forEach(callback: (value: T, x: number, y: number) => void): void;
-    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>;
     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>;
 }
@@ -90,7 +85,6 @@ export declare class GridBase<T> extends Grid<T> {
     batchUpdate(fn: () => void): void;
     constructor(source: Source2D<T>);
     on<K extends keyof EventMap<T>>(eventName: K, handler: (data: EventMap<T>[K]) => void): () => void;
-    private xyToIndex;
     private _set;
     private triggerChange;
 }

package/lib/grid.js

@@ -215,6 +215,9 @@ export class Grid {
         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)) {
+                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);
@@ -293,7 +296,7 @@ export class Grid {
     *[Symbol.iterator]() {
         for (let y = 0; y < this.height; y++) {
             for (let x = 0; x < this.width; x++) {
-                yield { x, y, value: this.get(x, y) };
+                yield this.get(x, y);
             }
         }
     }
@@ -304,22 +307,11 @@ export class Grid {
             }
         }
     }
-    combine(aux, cb) {
-        const width = Math.min(this.width, aux.width);
-        const height = Math.min(this.height, aux.height);
-        return new GridBase({
-            width,
-            height,
-            get: (x, y) => {
-                return cb(this.get(x, y), aux.get(x, y));
-            }
-        });
-    }
     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) || !Number.isInteger(width) || !Number.isInteger(height)) {
+        if (!Number.isInteger(x) || !Number.isInteger(y)) {
             throw new Error(`Region boundaries must be integer; got (${x}, ${y}), (${width} x ${height})`);
         }
         if (x < 0 || y < 0 || x + width > this.width || y + height > this.height) {
@@ -350,16 +342,15 @@ 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));
     }
@@ -387,11 +378,12 @@ export class GridBase extends Grid {
         if (this.batchState.level == 0) {
             const changed = this.batchState.changedCells;
             this.batchState = null;
-            this.triggerChange(changed);
+            if (changed.size > 0)
+                this.triggerChange(changed);
         }
     }
     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));
+        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
@@ -411,20 +403,11 @@ export class GridBase extends Grid {
             this.eventHandlers[eventName].splice(idx, 1);
         };
     }
-    xyToIndex(x, y) {
-        if (x < 0 || x >= this.width || y < 0 || y >= this.height) {
-            throw new Error(`Coordinates out of bounds: (${x}, ${y})`);
-        }
-        if (!Number.isInteger(x) || !Number.isInteger(y)) {
-            throw new Error(`Coordinates must be integer; got (${x}, ${y})`);
-        }
-        return y * this.width + x;
-    }
     _set(x, y, value) {
-        const idx = this.xyToIndex(x, y);
+        const idx = y * this.width + x;
         if (this.data[idx] === value)
             return;
-        this.data[this.xyToIndex(x, y)] = value;
+        this.data[idx] = value;
         if (this.batchState) {
             this.batchState.changedCells.add(this.cells.get(x, y));
             return;

package/package.json

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