@thi.ng/api 8.1.0 → 8.2.0

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [8.2.0](https://github.com/thi-ng/umbrella/compare/@thi.ng/api@8.1.0...@thi.ng/api@8.2.0) (2021-11-10)
+
+
+### Bug Fixes
+
+* **api:** add missing module exports ([fc8805e](https://github.com/thi-ng/umbrella/commit/fc8805eb26a828d4ee9683c714a73a7ad35ef16c))
+
+
+### Features
+
+* **api:** update IGrid types, add mixins ([f0f3236](https://github.com/thi-ng/umbrella/commit/f0f3236448e7277e089654c725d2b9335bd4706a))
+
+
+
+
+
 # [8.1.0](https://github.com/thi-ng/umbrella/compare/@thi.ng/api@8.0.6...@thi.ng/api@8.1.0) (2021-11-03)
 
 

package/README.md

@@ -60,7 +60,7 @@ node --experimental-repl-await
 > const api = await import("@thi.ng/api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 1.75 KB
+Package sizes (gzipped, pre-treeshake): ESM: 2.27 KB
 
 ## Dependencies
 

package/grid.d.ts

@@ -1,89 +1,351 @@
-import type { TypedArray, UIntArray } from "./typedarray.js";
-export interface IGrid2D<T extends any[] | TypedArray = UIntArray, P = number> {
-    readonly width: number;
-    readonly height: number;
-    readonly stride: number;
-    readonly rowStride: number;
-    readonly data: T;
-    /**
-     * Returns value at given position. If pos is outside the defined region,
+import type { NumericArray, TypedArray } from "./typedarray.js";
+export interface INDBase<BUF extends any[] | TypedArray = any[]> {
+    size: NumericArray;
+    stride: NumericArray;
+    offset: number;
+    data: BUF;
+    readonly dim: number;
+    order(): number[];
+}
+/**
+ * Semi-typechecked interface for cases accepting 1D-4D grids, i.e.
+ * {@link IGrid1D} - {@link IGrid4D}.
+ */
+export interface IGridND<BUF extends any[] | TypedArray = any[], T = any> extends INDBase<BUF> {
+    /**
+     * Returns true if given position is valid (i.e. within grid bounds).
+     *
+     * @param pos -
+     */
+    includes(...pos: [number] | [number, number] | [number, number, number] | [number, number, number, number]): boolean;
+    /**
+     * Returns index for given position. Returns negative value if outside the
+     * grid's defined region.
+     *
+     * @param pos -
+     */
+    indexAt(...pos: [number] | [number, number] | [number, number, number] | [number, number, number, number]): number;
+    /**
+     * Non-boundschecked version of {@link IGridND.indexAt}. Assumes given
+     * position is valid.
+     *
+     * @param pos -
+     */
+    indexAtUnsafe(...pos: [number] | [number, number] | [number, number, number] | [number, number, number, number]): number;
+    /**
+     * Returns value at given position. If outside the grid's defined region,
      * returns a suitable zero value.
      *
-     * @param x -
-     * @param y -
+     * @param pos -
      */
-    getAt(x: number, y: number): P;
+    getAt(...pos: [number] | [number, number] | [number, number, number] | [number, number, number, number]): T;
     /**
-     * Non-boundschecked version of {@link IGrid2D.getAt}. Assumes given
+     * Non-boundschecked version of {@link IGridND.getAt}. Assumes given
      * position is valid.
      *
-     * @param x -
-     * @param y -
+     * @param pos -
      */
-    getAtUnsafe(x: number, y: number): P;
+    getAtUnsafe(...pos: [number] | [number, number] | [number, number, number] | [number, number, number, number]): T;
     /**
      * Writes value at given position. Has no effect if outside of the defined
-     * region.
+     * region. Returns true, if succeeded.
      *
-     * @param x -
-     * @param y -
-     * @param col -
+     * @param args -
      */
-    setAt(x: number, y: number, col: P): this;
+    setAt(...args: [number, T] | [number, number, T] | [number, number, number, T] | [number, number, number, number, T]): boolean;
     /**
-     * Non-boundschecked version of {@link IGrid2D.setAt}. Assumes given
-     * position is valid.
+     * Non-boundschecked version of {@link IGridND.setAt}. Assumes given
+     * position is valid. Returns true, if succeeded.
      *
-     * @param x -
-     * @param y -
+     * @param args -
      */
-    setAtUnsafe(x: number, y: number, col: P): this;
+    setAtUnsafe(...args: [number, T] | [number, number, T] | [number, number, number, T] | [number, number, number, number, T]): boolean;
 }
-export interface IGrid3D<T extends any[] | TypedArray = UIntArray, P = number> {
-    readonly width: number;
-    readonly height: number;
-    readonly depth: number;
-    readonly stride: number;
-    readonly rowStride: number;
-    readonly sliceStride: number;
-    readonly data: T;
-    /**
-     * Returns value at given position. If pos is outside the defined region,
+/**
+ * Gridlike container for 1D accessible data.
+ *
+ * @remarks
+ * See {@link IGrid1DMixin} for mixin implementation.
+ */
+export interface IGrid1D<BUF extends any[] | TypedArray = any[], T = any> extends INDBase<BUF> {
+    readonly dim: 1;
+    /**
+     * Returns true if given position is valid (i.e. within grid bounds).
+     *
+     * @param d0 -
+     */
+    includes(d0: number): boolean;
+    /**
+     * Returns index for given position. Returns negative value if outside the
+     * grid's defined region.
+     *
+     * @param d0 -
+     */
+    indexAt(d0: number): number;
+    /**
+     * Non-boundschecked version of {@link IGrid1D.indexAt}. Assumes given
+     * position is valid.
+     *
+     * @param d0 -
+     */
+    indexAtUnsafe(d0: number): number;
+    /**
+     * Returns value at given position. If outside the grid's defined region,
      * returns a suitable zero value.
      *
-     * @param x -
-     * @param y -
-     * @param z -
+     * @param d0 -
      */
-    getAt(x: number, y: number, z: number): P;
+    getAt(d0: number): T;
     /**
-     * Non-boundschecked version of {@link IGrid3D.getAt}. Assumes given
+     * Non-boundschecked version of {@link IGrid1D.getAt}. Assumes given
      * position is valid.
      *
-     * @param x -
-     * @param y -
-     * @param z -
+     * @param d0 -
      */
-    getAtUnsafe(x: number, y: number, z: number): P;
+    getAtUnsafe(d0: number): T;
     /**
      * Writes value at given position. Has no effect if outside of the defined
-     * region.
+     * region. Returns true, if succeeded.
      *
-     * @param x -
-     * @param y -
-     * @param z -
-     * @param col -
+     * @param d0 -
+     * @param value -
      */
-    setAt(x: number, y: number, z: number, col: P): this;
+    setAt(d0: number, value: T): boolean;
+    /**
+     * Non-boundschecked version of {@link IGrid1D.setAt}. Assumes given
+     * position is valid. Returns true, if succeeded.
+     *
+     * @param d0 -
+     * @param value -
+     */
+    setAtUnsafe(d0: number, value: T): boolean;
+}
+/**
+ * Gridlike container for 2D accessible data.
+ *
+ * @remarks
+ * See {@link IGrid2DMixin} for mixin implementation.
+ */
+export interface IGrid2D<BUF extends any[] | TypedArray = any[], T = any> extends INDBase<BUF> {
+    readonly dim: 2;
+    /**
+     * Returns true if given position is valid (i.e. within grid bounds).
+     *
+     * @param d0 -
+     * @param d1 -
+     */
+    includes(d0: number, d1: number): boolean;
+    /**
+     * Returns index for given position (stated in same order as
+     * {@link IGrid2D.size} and {@link IGrid2D.stride}). Returns negative value
+     * if outside the grid's defined region.
+     *
+     * @param d0 -
+     * @param d1 -
+     */
+    indexAt(d0: number, d1: number): number;
+    /**
+     * Non-boundschecked version of {@link IGrid2D.indexAt}. Assumes given
+     * position is valid.
+     *
+     * @param d0 -
+     * @param d1 -
+     */
+    indexAtUnsafe(d0: number, d1: number): number;
+    /**
+     * Returns value at given position (given in same order as
+     * {@link IGrid2D.size} and {@link IGrid2D.stride}). If outside the grid's
+     * defined region, returns a suitable zero value.
+     *
+     * @param d0 -
+     * @param d1 -
+     */
+    getAt(d0: number, d1: number): T;
+    /**
+     * Non-boundschecked version of {@link IGrid2D.getAt}. Assumes given
+     * position is valid.
+     *
+     * @param d0 -
+     * @param d1 -
+     */
+    getAtUnsafe(d0: number, d1: number): T;
+    /**
+     * Writes value at given position (given in same order as
+     * {@link IGrid2D.size} and {@link IGrid2D.stride}). Has no effect if
+     * outside of the defined region. Returns true, if succeeded.
+     *
+     * @param d0 -
+     * @param d1 -
+     * @param value -
+     */
+    setAt(d0: number, d1: number, value: T): boolean;
+    /**
+     * Non-boundschecked version of {@link IGrid2D.setAt}. Assumes given
+     * position is valid. Returns true, if succeeded.
+     *
+     * @param d0 -
+     * @param d1 -
+     * @param value -
+     */
+    setAtUnsafe(d0: number, d1: number, value: T): boolean;
+}
+/**
+ * Gridlike container for 3D accessible data.
+ *
+ * @remarks
+ * See {@link IGrid3DMixin} for mixin implementation.
+ */
+export interface IGrid3D<BUF extends any[] | TypedArray = any[], T = any> extends INDBase<BUF> {
+    readonly dim: 3;
+    /**
+     * Returns true if given position is valid (i.e. within grid bounds).
+     *
+     * @param d0 -
+     * @param d1 -
+     * @param d2 -
+     */
+    includes(d0: number, d1: number, d2: number): boolean;
+    /**
+     * Returns index for given position (stated in same order as
+     * {@link IGrid3D.size} and {@link IGrid3D.stride}). Returns negative value
+     * if outside the grid's defined region.
+     *
+     * @param d0 -
+     * @param d1 -
+     * @param d2 -
+     */
+    indexAt(d0: number, d1: number, d2: number): number;
+    /**
+     * Non-boundschecked version of {@link IGrid3D.indexAt}. Assumes given
+     * position is valid.
+     *
+     * @param d0 -
+     * @param d1 -
+     * @param d2 -
+     */
+    indexAtUnsafe(d0: number, d1: number, d2: number): number;
+    /**
+     * Returns value at given position (given in same order as
+     * {@link IGrid3D.size} and {@link IGrid3D.stride}). If outside the grid's
+     * defined region, returns a suitable zero value.
+     *
+     * @param d0 -
+     * @param d1 -
+     * @param d2 -
+     */
+    getAt(d0: number, d1: number, d2: number): T;
+    /**
+     * Non-boundschecked version of {@link IGrid3D.getAt}. Assumes given
+     * position is valid.
+     *
+     * @param d0 -
+     * @param d1 -
+     * @param d2 -
+     */
+    getAtUnsafe(d0: number, d1: number, d2: number): T;
+    /**
+     * Writes value at given position (given in same order as
+     * {@link IGrid3D.size} and {@link IGrid3D.stride}). Has no effect if
+     * outside of the defined region. Returns true, if succeeded.
+     *
+     * @param d0 -
+     * @param d1 -
+     * @param d2 -
+     * @param value -
+     */
+    setAt(d0: number, d1: number, d2: number, value: T): boolean;
     /**
      * Non-boundschecked version of {@link IGrid3D.setAt}. Assumes given
+     * position is valid. Returns true, if succeeded.
+     *
+     * @param d0 -
+     * @param d1 -
+     * @param d2 -
+     * @param value -
+     */
+    setAtUnsafe(d0: number, d1: number, d2: number, value: T): boolean;
+}
+/**
+ * Gridlike container for 4D accessible data.
+ *
+ * @remarks
+ * See {@link IGrid4DMixin} for mixin implementation.
+ */
+export interface IGrid4D<BUF extends any[] | TypedArray = any[], T = any> extends INDBase<BUF> {
+    readonly dim: 4;
+    /**
+     * Returns true if given position is valid (i.e. within grid bounds).
+     *
+     * @param d0 -
+     * @param d1 -
+     * @param d2 -
+     * @param d3 -
+     */
+    includes(d0: number, d1: number, d2: number, d3: number): boolean;
+    /**
+     * Returns index for given position (stated in same order as
+     * {@link IGrid4D.size} and {@link IGrid4D.stride}). Returns negative value
+     * if outside the grid's defined region.
+     *
+     * @param d0 -
+     * @param d1 -
+     * @param d2 -
+     * @param d3 -
+     */
+    indexAt(d0: number, d1: number, d2: number, d3: number): number;
+    /**
+     * Non-boundschecked version of {@link IGrid4D.indexAt}. Assumes given
      * position is valid.
      *
-     * @param x -
-     * @param y -
-     * @param z -
-     * @param col -
+     * @param d0 -
+     * @param d1 -
+     * @param d2 -
+     * @param d3 -
+     */
+    indexAtUnsafe(d0: number, d1: number, d2: number, d3: number): number;
+    /**
+     * Returns value at given position (given in same order as
+     * {@link IGrid4D.size} and {@link IGrid4D.stride}). If outside the grid's
+     * defined region, returns a suitable zero value.
+     *
+     * @param d0 -
+     * @param d1 -
+     * @param d2 -
+     * @param d3 -
+     */
+    getAt(d0: number, d1: number, d2: number, d3: number): T;
+    /**
+     * Non-boundschecked version of {@link IGrid4D.getAt}. Assumes given
+     * position is valid.
+     *
+     * @param d0 -
+     * @param d1 -
+     * @param d2 -
+     * @param d3 -
+     */
+    getAtUnsafe(d0: number, d1: number, d2: number, d3: number): T;
+    /**
+     * Writes value at given position (given in same order as
+     * {@link IGrid4D.size} and {@link IGrid4D.stride}). Has no effect if
+     * outside of the defined region. Returns true, if succeeded.
+     *
+     * @param d0 -
+     * @param d1 -
+     * @param d2 -
+     * @param d3 -
+     * @param value -
+     */
+    setAt(d0: number, d1: number, d2: number, d3: number, value: T): boolean;
+    /**
+     * Non-boundschecked version of {@link IGrid4D.setAt}. Assumes given
+     * position is valid. Returns true, if succeeded.
+     *
+     * @param d0 -
+     * @param d1 -
+     * @param d2 -
+     * @param d3 -
+     * @param value -
      */
-    setAtUnsafe(x: number, y: number, z: number, col: P): this;
+    setAtUnsafe(d0: number, d1: number, d2: number, d3: number, value: T): boolean;
 }
 //# sourceMappingURL=grid.d.ts.map

package/index.d.ts

@@ -44,6 +44,7 @@ export * from "./decorators/deprecated.js";
 export * from "./decorators/nomixin.js";
 export * from "./decorators/sealed.js";
 export * from "./mixins/ienable.js";
+export * from "./mixins/igrid.js";
 export * from "./mixins/inotify.js";
 export * from "./mixins/iterable.js";
 export * from "./mixins/iwatch.js";

package/index.js

@@ -44,6 +44,7 @@ export * from "./decorators/deprecated.js";
 export * from "./decorators/nomixin.js";
 export * from "./decorators/sealed.js";
 export * from "./mixins/ienable.js";
+export * from "./mixins/igrid.js";
 export * from "./mixins/inotify.js";
 export * from "./mixins/iterable.js";
 export * from "./mixins/iwatch.js";

package/mixins/igrid.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Default implementation for {@link IGrid1D} methods.
+ */
+export declare const IGrid1DMixin: (clazz: any) => any;
+/**
+ * Default implementation for {@link IGrid2D} methods.
+ */
+export declare const IGrid2DMixin: (clazz: any) => any;
+/**
+ * Default implementation for {@link IGrid3D} methods.
+ */
+export declare const IGrid3DMixin: (clazz: any) => any;
+/**
+ * Default implementation for {@link IGrid4D} methods.
+ */
+export declare const IGrid4DMixin: (clazz: any) => any;
+//# sourceMappingURL=igrid.d.ts.map

package/mixins/igrid.js

@@ -0,0 +1,163 @@
+import { mixin } from "../mixin.js";
+/**
+ * Default implementation for {@link IGrid1D} methods.
+ */
+export const IGrid1DMixin = mixin({
+    order() {
+        return [0];
+    },
+    includes(x) {
+        return x >= 0 && x < this.size[0];
+    },
+    indexAt(x) {
+        return this.includes(x) ? this.indexAtUnsafe(x) : -1;
+    },
+    indexAtUnsafe(x) {
+        return this.offset + (x | 0) * this.stride[0];
+    },
+    getAt(x) {
+        return this.includes(x) ? this.data[this.indexAtUnsafe(x)] : 0;
+    },
+    getAtUnsafe(x) {
+        return this.data[this.indexAtUnsafe(x)];
+    },
+    setAt(x, val) {
+        return this.includes(x)
+            ? ((this.data[this.indexAtUnsafe(x)] = val), true)
+            : false;
+    },
+    setAtUnsafe(x, val) {
+        this.data[this.indexAtUnsafe(x)] = val;
+        return true;
+    },
+});
+/**
+ * Default implementation for {@link IGrid2D} methods.
+ */
+export const IGrid2DMixin = mixin({
+    order() {
+        return Math.abs(this.stride[1]) > Math.abs(this.stride[0])
+            ? [1, 0]
+            : [0, 1];
+    },
+    includes(x, y) {
+        const size = this.size;
+        return x >= 0 && x < size[0] && y >= 0 && y < size[1];
+    },
+    indexAt(x, y) {
+        return this.includes(x, y) ? this.indexAtUnsafe(x, y) : -1;
+    },
+    indexAtUnsafe(x, y) {
+        return (this.offset + (x | 0) * this.stride[0] + (y | 0) * this.stride[1]);
+    },
+    getAt(x, y) {
+        return this.includes(x, y) ? this.data[this.indexAtUnsafe(x, y)] : 0;
+    },
+    getAtUnsafe(x, y) {
+        return this.data[this.indexAtUnsafe(x, y)];
+    },
+    setAt(x, y, val) {
+        return this.includes(x, y)
+            ? ((this.data[this.indexAtUnsafe(x, y)] = val), true)
+            : false;
+    },
+    setAtUnsafe(x, y, val) {
+        this.data[this.indexAtUnsafe(x, y)] = val;
+        return true;
+    },
+});
+/**
+ * Default implementation for {@link IGrid3D} methods.
+ */
+export const IGrid3DMixin = mixin({
+    order() {
+        return strideOrder(this.stride);
+    },
+    includes(x, y, z) {
+        const size = this.size;
+        return (x >= 0 &&
+            x < size[0] &&
+            y >= 0 &&
+            y < size[1] &&
+            z >= 0 &&
+            z < size[2]);
+    },
+    indexAt(x, y, z) {
+        return this.includes(x, y, z) ? this.indexAtUnsafe(x, y, z) : -1;
+    },
+    indexAtUnsafe(x, y, z) {
+        const stride = this.stride;
+        return (this.offset +
+            (x | 0) * stride[0] +
+            (y | 0) * stride[1] +
+            (z | 0) * stride[2]);
+    },
+    getAt(x, y, z) {
+        return this.includes(x, y, z)
+            ? this.data[this.indexAtUnsafe(x, y, z)]
+            : 0;
+    },
+    getAtUnsafe(x, y, z) {
+        return this.data[this.indexAtUnsafe(x, y, z)];
+    },
+    setAt(x, y, z, val) {
+        return this.includes(x, y, z)
+            ? ((this.data[this.indexAtUnsafe(x, y, z)] = val), true)
+            : false;
+    },
+    setAtUnsafe(x, y, z, val) {
+        this.data[this.indexAtUnsafe(x, y, z)] = val;
+        return true;
+    },
+});
+/**
+ * Default implementation for {@link IGrid4D} methods.
+ */
+export const IGrid4DMixin = mixin({
+    order() {
+        return strideOrder(this.stride);
+    },
+    includes(x, y, z, w) {
+        const size = this.size;
+        return (x >= 0 &&
+            x < size[0] &&
+            y >= 0 &&
+            y < size[1] &&
+            z >= 0 &&
+            z < size[2] &&
+            w >= 0 &&
+            w < size[3]);
+    },
+    indexAt(x, y, z, w) {
+        return this.includes(x, y, z, w) ? this.indexAtUnsafe(x, y, z, w) : -1;
+    },
+    indexAtUnsafe(x, y, z, w) {
+        const stride = this.stride;
+        return (this.offset +
+            (x | 0) * stride[0] +
+            (y | 0) * stride[1] +
+            (z | 0) * stride[2] +
+            (w | 0) * stride[3]);
+    },
+    getAt(x, y, z, w) {
+        return this.includes(x, y, z, w)
+            ? this.data[this.indexAtUnsafe(x, y, z, w)]
+            : 0;
+    },
+    getAtUnsafe(x, y, z, w) {
+        return this.data[this.indexAtUnsafe(x, y, z, w)];
+    },
+    setAt(x, y, z, w, val) {
+        return this.includes(x, y, z, w)
+            ? ((this.data[this.indexAtUnsafe(x, y, z, w)] = val), true)
+            : false;
+    },
+    setAtUnsafe(x, y, z, w, val) {
+        this.data[this.indexAtUnsafe(x, y, z, w)] = val;
+        return true;
+    },
+});
+const strideOrder = (strides) => [...strides]
+    .map((x, i) => [x, i])
+    .sort((a, b) => Math.abs(b[0]) - Math.abs(a[0]))
+    .map((x) => x[1]);

package/mixins/inotify.js

@@ -51,7 +51,7 @@ export const INotifyMixin = mixin({
     },
     __listener(listeners, f, scope) {
         let i = listeners.length;
-        while (--i >= 0) {
+        while (i-- > 0) {
             const l = listeners[i];
             if (l[0] === f && l[1] === scope) {
                 break;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@thi.ng/api",
-    "version": "8.1.0",
+    "version": "8.2.0",
     "description": "Common, generic types, interfaces & mixins",
     "type": "module",
     "module": "./index.js",
@@ -159,6 +159,9 @@
         "./mixins/ienable": {
             "import": "./mixins/ienable.js"
         },
+        "./mixins/igrid": {
+            "import": "./mixins/igrid.js"
+        },
         "./mixins/inotify": {
             "import": "./mixins/inotify.js"
         },
@@ -214,5 +217,5 @@
             "import": "./watch.js"
         }
     },
-    "gitHead": "852cd2450617c86d15d18477dc634f17f04202eb"
+    "gitHead": "5fe52419af63984ebe53032201b2a6174b9cb159"
 }