diff --git a/docs/modules/types/api-reference/array-types.md b/docs/modules/types/api-reference/array-types.md index e8b8798..7f07c2d 100644 --- a/docs/modules/types/api-reference/array-types.md +++ b/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 diff --git a/docs/upgrade-guide.md b/docs/upgrade-guide.md index bf752a0..754ba7b 100644 --- a/docs/upgrade-guide.md +++ b/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. diff --git a/docs/whats-new.md b/docs/whats-new.md index e73fe9a..7ae134a 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -45,6 +45,12 @@ +## 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 diff --git a/modules/core/src/classes/matrix3.ts b/modules/core/src/classes/matrix3.ts index 7218cbf..2c62228 100644 --- a/modules/core/src/classes/matrix3.ts +++ b/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 diff --git a/modules/core/src/classes/matrix4.ts b/modules/core/src/classes/matrix4.ts index 8bb0680..48e0219 100644 --- a/modules/core/src/classes/matrix4.ts +++ b/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 diff --git a/modules/core/src/classes/vector2.ts b/modules/core/src/classes/vector2.ts index cdbf698..e30387c 100644 --- a/modules/core/src/classes/vector2.ts +++ b/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. diff --git a/modules/core/src/classes/vector3.ts b/modules/core/src/classes/vector3.ts index f1355e7..7fde2c5 100644 --- a/modules/core/src/classes/vector3.ts +++ b/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. diff --git a/modules/core/src/classes/vector4.ts b/modules/core/src/classes/vector4.ts index 14caf22..344e11e 100644 --- a/modules/core/src/classes/vector4.ts +++ b/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. diff --git a/modules/types/src/array-types.ts b/modules/types/src/array-types.ts index 63ad497..a44bdd7 100644 --- a/modules/types/src/array-types.ts +++ b/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; diff --git a/modules/types/src/index.ts b/modules/types/src/index.ts index 551dcca..a9f3e66 100644 --- a/modules/types/src/index.ts +++ b/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';