diff --git a/docs/whats-new.md b/docs/whats-new.md index 2c36665b..e73fe9a9 100644 --- a/docs/whats-new.md +++ b/docs/whats-new.md @@ -45,11 +45,22 @@ +## 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. diff --git a/modules/core/src/classes/matrix3.ts b/modules/core/src/classes/matrix3.ts index 2be038c4..8d8b9476 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} 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 meaning that it is highly compatible with other libraries + */ export class Matrix3 extends Matrix { static get IDENTITY(): Readonly { return getIdentityMatrix(); diff --git a/modules/core/src/classes/matrix4.ts b/modules/core/src/classes/matrix4.ts index 82392ad4..234e3286 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} 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 meaning that it is highly compatible with other libraries + */ export class Matrix4 extends Matrix { static get IDENTITY(): Readonly { return getIdentityMatrix(); diff --git a/modules/core/src/classes/vector2.ts b/modules/core/src/classes/vector2.ts index 2d58b1bd..cdbf698e 100644 --- a/modules/core/src/classes/vector2.ts +++ b/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 + * Two-element vector class with common linear algebra operations. + * Subclass of Array meaning that it is highly compatible with other libraries */ export class Vector2 extends Vector { // Creates a new, empty vec2 diff --git a/modules/core/src/classes/vector3.ts b/modules/core/src/classes/vector3.ts index 21262fbe..f1355e75 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} 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 + * Three-element vector class with common linear algebra operations. + * Subclass of Array meaning that it is highly compatible with other libraries */ export class Vector3 extends Vector { static get ZERO(): Vector3 { diff --git a/modules/core/src/classes/vector4.ts b/modules/core/src/classes/vector4.ts index 1c4abd77..14caf22e 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} 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 + * Four-element vector class with common linear algebra operations. + * Subclass of Array meaning that it is highly compatible with other libraries */ export class Vector4 extends Vector { static get ZERO(): Vector4 { diff --git a/modules/core/src/gl-matrix/wip/types.d.ts b/modules/core/src/gl-matrix/wip/types.d.ts deleted file mode 100644 index c2fc33a9..00000000 --- a/modules/core/src/gl-matrix/wip/types.d.ts +++ /dev/null @@ -1,93 +0,0 @@ -// @ts-nocheck -/* eslint-disable */ - -interface IndexedCollection extends Iterable { - readonly length: number; - [index: number]: number; -} - -// prettier-ignore -declare type mat2 = - | [number, number, - number, number] - | IndexedCollection; - -// prettier-ignore -declare type mat2d = - | [number, number, - number, number, - number, number] - | IndexedCollection; - -// prettier-ignore -declare type mat3 = - | [number, number, number, - number, number, number, - number, number, number] - | IndexedCollection; - -// prettier-ignore -declare type mat4 = - | [number, number, number, number, - number, number, number, number, - number, number, number, number, - number, number, number, number] - | IndexedCollection; - -declare type quat = [number, number, number, number] | IndexedCollection; - -// prettier-ignore -declare type quat2 = - | [number, number, number, number, - number, number, number, number] - | IndexedCollection; - -declare type vec2 = [number, number] | IndexedCollection; -declare type vec3 = [number, number, number] | IndexedCollection; -declare type vec4 = [number, number, number, number] | IndexedCollection; - -// prettier-ignore -declare type ReadonlyMat2 = - | readonly [ - number, number, - number, number - ] - | IndexedCollection; - -// prettier-ignore -declare type ReadonlyMat2d = - | readonly [ - number, number, - number, number, - number, number - ] - | IndexedCollection; - -// prettier-ignore -declare type ReadonlyMat3 = - | readonly [ - number, number, number, - number, number, number, - number, number, number - ] - | IndexedCollection; - -// prettier-ignore -declare type ReadonlyMat4 = - | readonly [ - number, number, number, number, - number, number, number, number, - number, number, number, number, - number, number, number, number - ] - | IndexedCollection; - -declare type ReadonlyQuat = readonly [number, number, number, number] | IndexedCollection; - -declare type ReadonlyQuat2 = - | readonly [number, number, number, number, number, number, number, number] - | IndexedCollection; - -declare type ReadonlyVec2 = readonly [number, number] | IndexedCollection; -declare type ReadonlyVec3 = readonly [number, number, number] | IndexedCollection; -declare type ReadonlyVec4 = readonly [number, number, number, number] | IndexedCollection; diff --git a/modules/core/src/index.ts b/modules/core/src/index.ts index 5866f02b..8b5be8eb 100644 --- a/modules/core/src/index.ts +++ b/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'; diff --git a/modules/types/src/array-types.ts b/modules/types/src/array-types.ts index 7917b7c2..82976c2c 100644 --- a/modules/types/src/array-types.ts +++ b/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 +]; diff --git a/modules/types/src/index.ts b/modules/types/src/index.ts index a924e9a8..fef17e65 100644 --- a/modules/types/src/index.ts +++ b/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';