feat: Add sized array types (#11)

docs/whats-new.md

@@ -45,11 +45,22 @@
   </tbody>
 </table>
 
+## v4.1
+
+Release Date: Q3, 2024.
+
+- [SPDX](https://spdx.org/licenses/) license headers.
+
+**`@math.gl/core`**
+
+- New `Vector2Like` - `Matrix4Like` types to specify numeric inputs of a specific length.
 
 **`@math.gl/types`**
 
 - New types for expressing [bounds](./modules/types/api-reference/bounds) (extents): `Bounds`, `Bounds2D` and `Bounds3D`.
-- 
+- New types to specify numeric arrays of a specific length: `NumberArray2` - `NumberArray16`. 
+- `isTypedArray()` and `isNumericArray()` utilities now perform typescript type narrowing.
+
 ## v4.0
 
 Release Date: Oct 14, 2023.

modules/core/src/classes/matrix3.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 // Copyright (c) 2017 Uber Technologies, Inc.
 
-import {NumericArray} from '@math.gl/types';
+import {NumericArray, NumberArray9} from '@math.gl/types';
 import {Matrix} from './base/matrix';
 import {checkVector} from '../lib/validators';
 
@@ -36,6 +36,13 @@ enum INDICES {
 
 const IDENTITY_MATRIX = Object.freeze([1, 0, 0, 0, 1, 0, 0, 0, 1]);
 
+/** Helper type that captures array length for a 3x3 matrix */
+export type Matrix3Like = Matrix3 | NumberArray9;
+
+/**
+ * A 3x3 matrix with common linear algebra operations
+ * Subclass of Array<number> meaning that it is highly compatible with other libraries
+ */
 export class Matrix3 extends Matrix {
   static get IDENTITY(): Readonly<Matrix3> {
     return getIdentityMatrix();

modules/core/src/classes/matrix4.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 // Copyright (c) 2017 Uber Technologies, Inc.
 
-import {NumericArray} from '@math.gl/types';
+import {NumericArray, NumberArray16} from '@math.gl/types';
 import {Matrix} from './base/matrix';
 import {checkVector} from '../lib/validators';
 
@@ -57,7 +57,13 @@ const DEFAULT_FAR = 500;
 
 const IDENTITY_MATRIX = Object.freeze([1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1]);
 
-/** 4x4 matrix */
+/** Helper type that captures array length for a 4x4 matrix */
+export type Matrix4Like = Matrix4 | NumberArray16;
+
+/**
+ * A 4x4 matrix with common linear algebra operations
+ * Subclass of Array<number> meaning that it is highly compatible with other libraries
+ */
 export class Matrix4 extends Matrix {
   static get IDENTITY(): Readonly<Matrix4> {
     return getIdentityMatrix();

modules/core/src/classes/vector2.ts

@@ -3,6 +3,8 @@
 // Copyright (c) vis.gl contributors
 // Copyright (c) 2017 Uber Technologies, Inc.
 
+import {NumericArray, NumberArray2} from '@math.gl/types';
+
 import {Vector} from './base/vector';
 import {config, isArray} from '../lib/common';
 import {checkNumber} from '../lib/validators';
@@ -13,11 +15,13 @@ import {
   transformMat2 as vec2_transformMat2
 } from '../gl-matrix/vec2';
 import {vec2_transformMat4AsVector} from '../lib/gl-matrix-extras';
-import {NumericArray} from '@math.gl/types';
+
+/** Helper type that captures array length for a 2 element vector */
+export type Vector2Like = Vector2 | NumberArray2;
 
 /**
- * Two-element vector class.
- * Subclass of Array<number>
+ * Two-element vector class with common linear algebra operations.
+ * Subclass of Array<number> meaning that it is highly compatible with other libraries
  */
 export class Vector2 extends Vector {
   // Creates a new, empty vec2

modules/core/src/classes/vector3.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 // Copyright (c) 2017 Uber Technologies, Inc.
 
-import {NumericArray} from '@math.gl/types';
+import {NumericArray, NumberArray3} from '@math.gl/types';
 import {Vector} from './base/vector';
 import {config, isArray} from '../lib/common';
 import {checkNumber} from '../lib/validators';
@@ -25,9 +25,12 @@ const ORIGIN = [0, 0, 0];
 
 let ZERO: Vector3;
 
+/** Helper type that captures array length for a 3 element vector */
+export type Vector3Like = Vector3 | NumberArray3;
+
 /**
- * Three-element vector class.
- * Subclass of Array<number>
+ * Three-element vector class with common linear algebra operations.
+ * Subclass of Array<number> meaning that it is highly compatible with other libraries
  */
 export class Vector3 extends Vector {
   static get ZERO(): Vector3 {

modules/core/src/classes/vector4.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 // Copyright (c) 2017 Uber Technologies, Inc.
 
-import {NumericArray} from '@math.gl/types';
+import {NumericArray, NumberArray4} from '@math.gl/types';
 /* eslint-disable camelcase */
 import {
   transformMat4 as vec4_transformMat4,
@@ -19,9 +19,12 @@ import type {Matrix4} from './matrix4';
 
 let ZERO: Vector4;
 
+/** Helper type that captures array length for a 4 element vector */
+export type Vector4Like = Vector4 | NumberArray4;
+
 /**
- * Four-element vector class.
- * Subclass of Array<number>
+ * Four-element vector class with common linear algebra operations.
+ * Subclass of Array<number> meaning that it is highly compatible with other libraries
  */
 export class Vector4 extends Vector {
   static get ZERO(): Vector4 {

modules/core/src/index.ts

@@ -15,6 +15,12 @@ export {Matrix3} from './classes/matrix3';
 export {Matrix4} from './classes/matrix4';
 export {Quaternion} from './classes/quaternion';
 
+export type {Vector2Like} from './classes/vector2';
+export type {Vector3Like} from './classes/vector3';
+export type {Vector4Like} from './classes/vector4';
+export type {Matrix3Like} from './classes/matrix3';
+export type {Matrix4Like} from './classes/matrix4';
+
 // experimental
 export {SphericalCoordinates} from './classes/spherical-coordinates';
 export {Pose} from './classes/pose';

modules/types/src/array-types.ts

@@ -40,4 +40,61 @@ export type NumericArray = TypedArray | number[];
  * TypeScript type covering all typed arrays and classic arrays consisting of numbers
  * @note alias for NumericArray
  */
-export type NumberArray = NumericArray;
+export type NumberArray = TypedArray | number[];
+
+/** Array with exactly 1 number */
+export type NumberArray1 = [number];
+
+/** Array with exactly 2 numbers */
+export type NumberArray2 = [number, number];
+
+/** Array with exactly 3 numbers */
+export type NumberArray3 = [number, number, number];
+
+/** Array with exactly 4 numbers */
+export type NumberArray4 = [number, number, number, number];
+
+/** Array with exactly 6 numbers */
+export type NumberArray6 = [number, number, number, number, number, number];
+
+/** Array with exactly 8 numbers */
+export type NumberArray8 = [number, number, number, number, number, number, number, number];
+
+/** Array with exactly 9 numbers */
+export type NumberArray9 = [number, number, number, number, number, number, number, number, number];
+
+/** Array with exactly 12 numbers */
+export type NumberArray12 = [
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number
+];
+
+/** Array with exactly 16 numbers */
+export type NumberArray16 = [
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number,
+  number
+];

modules/types/src/index.ts

@@ -2,7 +2,21 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) vis.gl contributors
 
-export type {TypedArray, TypedArrayConstructor, NumericArray, NumberArray} from './array-types';
+export type {
+  TypedArray,
+  TypedArrayConstructor,
+  NumericArray,
+  NumberArray,
+  NumberArray1,
+  NumberArray2,
+  NumberArray3,
+  NumberArray4,
+  NumberArray6,
+  NumberArray8,
+  NumberArray9,
+  NumberArray12,
+  NumberArray16
+} from './array-types';
 export {isTypedArray, isNumericArray} from './is-array';
 
 export type {Bounds, Bounds2D, Bounds3D} from './bounds-types';