feat(types): Sized numeric arrays (#16)

docs/modules/types/api-reference/array-types.md

@@ -4,23 +4,41 @@ math.gl provides a number of numeric array types.
 
 TypeScript types to simplify working with a mix of typed arrays and standard JavaScript arrays containing numbers.
 
+
+
 ## Types
 
 ### `TypedArray`
 
-Any JavaScript typed array.
+Type matching any non-big JavaScript typed array.
+
+### `TypedArrayConstructor`
+
+Type matching constructor for any non-big JavaScript typed array.
+
+### `BigTypedArray`
+
+Type matching any big JavaScript typed array.
+
+### `BigTypedArrayConstructor`
+
+Type matching constructor for any big JavaScript typed array.
 
 ### `NumberArray`
 
 A classic JavaScript array containing numbers. Included for completeness, it is recommended to just use the type `number[]` in this case.
 
+### `NumberArray2-NumberArray16`
+
+JavaScript number arrays of specific lengths.
+
 ### `NumericArray`
 
-Any JavaScript typed array, or any classic JavaScript array containing numbers
+Type matching any classic JavaScript array containing numbers or any non-big typed array.
 
-### `NumberArray2-NumberArray16`
+### `NumericArray2-NumericArray16`
 
-JavaScript number arrays of specific lengths.
+Types matching number arrays of specific lengths or typed arrays.
 
 ## Utilities
 

docs/upgrade-guide.md

@@ -1,5 +1,10 @@
 # Upgrade Guide
 
+## Upgrading to v4.1
+
+- The `NumberArray` type now only covers classic JavaScript arrays `number[]`, not typed arrays. Use `NumericArray` to cover both classic and typed arrays.
+- `isTypedArray()`, `isNumericArray()` - These utilities now return booleans rather than a typecasted input, but instead perform type narrowing, meaning that code after a check does not need a cast.
+
 ## Upgrading to v4.0
 
 - math.gl v4.0 is now packaged as ESM modules, but with additional CommonJS exports. In most cases you should not have problems importing 4.0.

docs/whats-new.md

@@ -45,6 +45,12 @@
   </tbody>
 </table>
 
+## v5.0
+
+Release Date: TBD, maybe Q4, 2024.
+
+Goal: Stronger type guarantees for math classes via the new sized array types.
+
 ## v4.1
 
 Release Date: Q3, 2024.
@@ -57,9 +63,10 @@ Release Date: Q3, 2024.
 
 **`@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.
+- `Bounds`, `Bounds2D` and `Bounds3D` - New types for expressing [bounds](./modules/types/api-reference/bounds) (extents): .
+- `NumberArray2` - `NumberArray16` - New types to specify numeric arrays of a specific length: . 
+- `NumericArray2` - `NumericArray16` - New types to specify numeric arrays of a specific length: . 
+- `isTypedArray()`, `isNumericArray()` - These utilities now perform typescript type narrowing.
 
 ## v4.0
 

modules/core/src/classes/matrix3.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 // Copyright (c) 2017 Uber Technologies, Inc.
 
-import {NumericArray, NumberArray9} from '@math.gl/types';
+import {NumericArray, NumericArray9} from '@math.gl/types';
 import {Matrix} from './base/matrix';
 import {checkVector} from '../lib/validators';
 
@@ -38,7 +38,7 @@ 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;
+export type Matrix3Like = Matrix3 | NumericArray9;
 
 /**
  * A 3x3 matrix with common linear algebra operations

modules/core/src/classes/matrix4.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 // Copyright (c) 2017 Uber Technologies, Inc.
 
-import {NumericArray, NumberArray16} from '@math.gl/types';
+import {NumericArray, NumericArray16} from '@math.gl/types';
 import {Matrix} from './base/matrix';
 import {checkVector} from '../lib/validators';
 
@@ -59,7 +59,7 @@ 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]);
 
 /** Helper type that captures array length for a 4x4 matrix */
-export type Matrix4Like = Matrix4 | NumberArray16;
+export type Matrix4Like = Matrix4 | NumericArray16;
 
 /**
  * A 4x4 matrix with common linear algebra operations

modules/core/src/classes/vector2.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 // Copyright (c) 2017 Uber Technologies, Inc.
 
-import {NumericArray, NumberArray2} from '@math.gl/types';
+import {NumericArray, NumericArray2} from '@math.gl/types';
 
 import {Vector} from './base/vector';
 import {config, isArray} from '../lib/common';
@@ -17,7 +17,7 @@ import {
 import {vec2_transformMat4AsVector} from '../lib/gl-matrix-extras';
 
 /** Helper type that captures array length for a 2 element vector */
-export type Vector2Like = Vector2 | NumberArray2;
+export type Vector2Like = Vector2 | NumericArray2;
 
 /**
  * Two-element vector class with common linear algebra operations.

modules/core/src/classes/vector3.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 // Copyright (c) 2017 Uber Technologies, Inc.
 
-import {NumericArray, NumberArray3} from '@math.gl/types';
+import {NumericArray, NumericArray3} from '@math.gl/types';
 import {Vector} from './base/vector';
 import {config, isArray} from '../lib/common';
 import {checkNumber} from '../lib/validators';
@@ -26,7 +26,7 @@ const ORIGIN = [0, 0, 0];
 let ZERO: Vector3;
 
 /** Helper type that captures array length for a 3 element vector */
-export type Vector3Like = Vector3 | NumberArray3;
+export type Vector3Like = Vector3 | NumericArray3;
 
 /**
  * Three-element vector class with common linear algebra operations.

modules/core/src/classes/vector4.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 // Copyright (c) 2017 Uber Technologies, Inc.
 
-import {NumericArray, NumberArray4} from '@math.gl/types';
+import {NumericArray, NumericArray4} from '@math.gl/types';
 /* eslint-disable camelcase */
 import {
   transformMat4 as vec4_transformMat4,
@@ -20,7 +20,7 @@ import type {Matrix4} from './matrix4';
 let ZERO: Vector4;
 
 /** Helper type that captures array length for a 4 element vector */
-export type Vector4Like = Vector4 | NumberArray4;
+export type Vector4Like = Vector4 | NumericArray4;
 
 /**
  * Four-element vector class with common linear algebra operations.

modules/types/src/array-types.ts

@@ -3,7 +3,7 @@
 // Copyright (c) vis.gl contributors
 
 /**
- * TypeScript type covering all typed arrays
+ * Type covering all non-big typed arrays
  */
 export type TypedArray =
   | Int8Array
@@ -16,10 +16,9 @@ export type TypedArray =
   | Float32Array
   | Float64Array;
 
-// TODO
-// | BigInt64Array
-// | BigUint64Array;
-
+/**
+ * Type covering constructors for all non-big typed arrays
+ */
 export type TypedArrayConstructor =
   | Int8ArrayConstructor
   | Uint8ArrayConstructor
@@ -32,12 +31,17 @@ export type TypedArrayConstructor =
   | Float64ArrayConstructor;
 
 /**
- * TypeScript type covering all typed arrays and classic arrays consisting of numbers
+ * Type covering all big typed arrays
  */
-export type NumericArray = TypedArray | number[];
+export type BigTypedArray = BigInt64Array | BigUint64Array;
+
+/**
+ * Type covering constructors for all big typed arrays
+ */
+export type BigTypedArrayConstructor = BigInt64ArrayConstructor | BigUint64ArrayConstructor;
 
 /**
- * TypeScript type for classic arrays consisting of numbers
+ * Type for classic arrays consisting of numbers
  * @note Included for completeness / orthogonality, prefer `number[]` in actual use
  */
 export type NumberArray = number[];
@@ -98,3 +102,35 @@ export type NumberArray16 = [
   number,
   number
 ];
+
+/**
+ * Type covering classic arrays consisting of numbers as well as typed arrays
+ */
+export type NumericArray = TypedArray | number[];
+
+/** Array with exactly 1 number, or a typed array */
+export type NumericArray1 = NumberArray1 | TypedArray;
+
+/** Array with exactly 2 numbers, or a typed array */
+export type NumericArray2 = NumberArray2 | TypedArray;
+
+/** Array with exactly 3 numbers, or a typed array */
+export type NumericArray3 = NumberArray3 | TypedArray;
+
+/** Array with exactly 4 numbers, or a typed array */
+export type NumericArray4 = NumberArray4 | TypedArray;
+
+/** Array with exactly 6 numbers, or a typed array */
+export type NumericArray6 = NumberArray6 | TypedArray;
+
+/** Array with exactly 8 numbers, or a typed array */
+export type NumericArray8 = NumberArray8 | TypedArray;
+
+/** Array with exactly 9 numbers, or a typed array */
+export type NumericArray9 = NumberArray9 | TypedArray;
+
+/** Array with exactly 12 numbers, or a typed array */
+export type NumericArray12 = NumberArray12 | TypedArray;
+
+/** Array with exactly 16 numbers, or a typed array */
+export type NumericArray16 = NumberArray16 | TypedArray;

modules/types/src/index.ts

@@ -3,9 +3,12 @@
 // Copyright (c) vis.gl contributors
 
 export type {
+  // typed arrays
   TypedArray,
   TypedArrayConstructor,
-  NumericArray,
+  BigTypedArray,
+  BigTypedArrayConstructor,
+  // numeric arrays (sized number arrays)
   NumberArray,
   NumberArray1,
   NumberArray2,
@@ -15,7 +18,18 @@ export type {
   NumberArray8,
   NumberArray9,
   NumberArray12,
-  NumberArray16
+  NumberArray16,
+  // numeric arrays (sized number arrays or typed arrays)
+  NumericArray,
+  NumericArray1,
+  NumericArray2,
+  NumericArray3,
+  NumericArray4,
+  NumericArray6,
+  NumericArray8,
+  NumericArray9,
+  NumericArray12,
+  NumericArray16
 } from './array-types';
 
 export {isTypedArray, isNumberArray, isNumericArray} from './is-array';