Breaking change syncing TypeScript declarations with their implementations

BREAKING_CHANGES.md

@@ -1,3 +1,9 @@
+## From 37.x to 38
+
+- **TypeScript declarations**: expanded coverage and corrected types may expose build errors. Remove conflicting local declaration shims and fix code rejected by the new types.
+- **TypeScript libraries**: typed-array factories now declare BigInt support. Add `ES2020.BigInt` if your `lib` list does not include `ES2020` or later. Your `target` can stay unchanged.
+- **Accessor types**: `setXFrom` methods and setters that return no value now declare `void`. Getter types include `null` or `undefined` where applicable.
+
 ## From 36.x to 37
 
 - **vtkCamera**: `setModelTransformMatrix` now expects matrices in gl-matrix column-major order, consistent with `vtkTransform`, `vtkMatrixBuilder`, and `userMatrix` on `vtkProp3D`. Remove any transpose previously applied to column-major rotation or translation matrices to compensate for the old behavior. Transpose row-major matrices before passing them. ([#3586](https://github.com/Kitware/vtk-js/pull/3586))

Sources/Common/Core/AnimationMixer/index.d.ts

@@ -1,5 +1,5 @@
 import { Nullable } from '../../../types';
-import { vtkObject } from '../../../interfaces';
+import { vtkObject, vtkSubscription } from '../../../interfaces';
 import vtkAnimationClip from '../../DataModel/AnimationClip';
 import vtkAnimationScene from '../AnimationScene';
 import vtkArmature from '../../DataModel/Armature';
@@ -12,18 +12,33 @@ export interface SkinningData {
   jointCount: number;
 }
 
-export interface AnimationBindingContext {
-  animation: object;
+export type AnimationBindingContext = {
   deltaTime: number;
   mixer: vtkAnimationMixer;
   time: number;
-}
+} & (
+  | { animation: object; animations?: never }
+  | { animation?: never; animations: object[] }
+);
 
 export interface AnimationSource {
   name: string;
-  evaluate(time: number): unknown;
+  duration?: number;
+  weight?: number;
+  evaluate(time: number, loop?: boolean): unknown;
 }
 
+export type AnimationBindingOptions = {
+  enabled?: boolean;
+  time?: number;
+  loop?: boolean;
+  timeScale?: number;
+};
+
+export type AnimationEndEvent =
+  | { name: string; clip: vtkAnimationClip }
+  | { name: string; binding: object };
+
 export interface AnimationSceneData {
   actors?: Map<string, object>;
   actorNodeIds?: Map<object, string>;
@@ -125,6 +140,16 @@ export interface vtkAnimationMixer extends vtkObject {
    */
   stop(): void;
 
+  /** Alias of stop(). */
+  stopAll(): void;
+
+  /** Subscribe to a clip or animation binding reaching its end. */
+  onAnimationEnd(
+    callback: (event: AnimationEndEvent) => void,
+    priority?: number
+  ): vtkSubscription;
+  invokeAnimationEnd(event: AnimationEndEvent): void;
+
   /**
    * Get the name of the currently playing clip.
    */
@@ -133,7 +158,7 @@ export interface vtkAnimationMixer extends vtkObject {
   /**
    * Check if the mixer is currently playing.
    */
-  isPlaying(): boolean;
+  isPlaying(): Nullable<boolean>;
 
   /**
    * Set the skeleton to animate.
@@ -197,7 +222,7 @@ export interface vtkAnimationMixer extends vtkObject {
     name: string,
     apply: (updates: unknown, context: AnimationBindingContext) => void,
     animations?: object[],
-    options?: { enabled?: boolean; time?: number }
+    options?: AnimationBindingOptions
   ): boolean;
 
   /**
@@ -239,13 +264,19 @@ export interface vtkAnimationMixer extends vtkObject {
   getAnimationNames(): string[];
 
   /** Play every imported animation channel with the given name. */
-  playAnimation(name: string): boolean;
+  playAnimation(name: string, options?: AnimationBindingOptions): boolean;
 
   /** Play a node animation by name, or the first one when omitted. */
-  playNodeAnimation(name?: string): void;
+  playNodeAnimation(
+    name?: Nullable<string>,
+    options?: AnimationBindingOptions
+  ): void;
 
   /** Play a pointer animation by name, or the first one when omitted. */
-  playPointerAnimation(name?: string): void;
+  playPointerAnimation(
+    name?: Nullable<string>,
+    options?: AnimationBindingOptions
+  ): void;
 
   /** Return true when the mixer contains any animation. */
   hasAnimations(): boolean;

Sources/Common/Core/CellArray/index.d.ts

@@ -23,7 +23,7 @@ export interface vtkCellArray extends vtkDataArray {
    * Get the sizes of the cells in this array.
    * @param {Boolean} [recompute] Recompute the cell sizes.
    */
-  getCellSizes(recompute?: boolean): any;
+  getCellSizes(recompute?: boolean): number[];
 
   /**
    * Set the data of this array.
@@ -35,7 +35,7 @@ export interface vtkCellArray extends vtkDataArray {
    * Returns the point indices at the given location as a subarray.
    * @param loc
    */
-  getCell(loc: any): void;
+  getCell(loc: number): TypedArray;
 
   /**
    * Insert a cell to this array in the next available slot.
@@ -82,13 +82,18 @@ export function newInstance(
  * @param cellArray
  * @returns {number[]} An array of cell sizes.
  */
-export function extractCellSizes(cellArray: any): number[];
+declare function extractCellSizes(cellArray: any): number[];
 
 /**
  * @static
  * @param cellArray
  */
-export function getNumberOfCells(cellArray: any): any;
+declare function getNumberOfCells(cellArray: any): any;
+
+export declare const STATIC: Readonly<{
+  extractCellSizes: typeof extractCellSizes;
+  getNumberOfCells: typeof getNumberOfCells;
+}>;
 
 /**
  * vtkCellArray stores dataset topologies as an explicit connectivity table

Sources/Common/Core/ClassHierarchy/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * An array of class names that ignores duplicates: pushing a name already in
+ * the hierarchy leaves the array unchanged and still reports its length.
+ */
+export interface ClassHierarchy extends Array<string> {
+  push(...names: string[]): number;
+}
+
+/**
+ * The subclass carries no static members of its own; it inherits Array's.
+ */
+declare const ClassHierarchy: {
+  new (...items: string[]): ClassHierarchy;
+};
+export default ClassHierarchy;

Sources/Common/Core/DataArray/Constants.d.ts

@@ -0,0 +1,42 @@
+export declare const DataTypeByteSize: {
+  Int8Array: number;
+  Uint8Array: number;
+  Uint8ClampedArray: number;
+  Int16Array: number;
+  Uint16Array: number;
+  Int32Array: number;
+  Uint32Array: number;
+  Float32Array: number;
+  Float64Array: number;
+};
+
+/**
+ * Constants capturing the various VTK data types.
+ */
+export declare const VtkDataTypes: {
+  readonly VOID: '';
+  readonly CHAR: 'Int8Array';
+  readonly SIGNED_CHAR: 'Int8Array';
+  readonly UNSIGNED_CHAR: 'Uint8Array';
+  /**
+   * Should be used for VTK.js internal purpose only
+   */
+  readonly UNSIGNED_CHAR_CLAMPED: 'Uint8ClampedArray';
+  readonly SHORT: 'Int16Array';
+  readonly UNSIGNED_SHORT: 'Uint16Array';
+  readonly INT: 'Int32Array';
+  readonly UNSIGNED_INT: 'Uint32Array';
+  readonly FLOAT: 'Float32Array';
+  readonly DOUBLE: 'Float64Array';
+};
+
+export type VtkDataTypes = (typeof VtkDataTypes)[keyof typeof VtkDataTypes];
+
+export declare const DefaultDataType: VtkDataTypes;
+
+declare const _default: {
+  DefaultDataType: typeof DefaultDataType;
+  DataTypeByteSize: typeof DataTypeByteSize;
+  VtkDataTypes: typeof VtkDataTypes;
+};
+export default _default;

Sources/Common/Core/DataArray/index.d.ts

@@ -1,3 +1,4 @@
+import { DataTypeByteSize, VtkDataTypes } from './Constants';
 import { vtkObject, vtkRange, GetStateOptions } from '../../../interfaces';
 import {
   Float,
@@ -83,10 +84,16 @@ export interface vtkDataArray extends vtkObject {
    */
   setValue(valueIdx: NonNegativeInteger, value: number): void;
 
+  /** Get a value by its flat component index. */
+  getValue(valueIdx: number): number;
+
+  /** Set a value by its flat component index. */
+  setValue(valueIdx: number, value: number): void;
+
   /**
    *
    */
-  getData(): number[] | TypedArray;
+  getData(): TypedArray;
 
   /**
    * Call this method when the underlying data has changed
@@ -324,7 +331,7 @@ export interface vtkDataArray extends vtkObject {
    * without converting and copying to a plain Array.
    * @returns {object}
    */
-  getState(options?: GetStateOptions): object;
+  getState(options?: GetStateOptions): object | null;
 
   /**
    * Deep copy of another vtkDataArray into this one.
@@ -391,7 +398,7 @@ export interface vtkDataArray extends vtkObject {
    * @see insertNextTuple
    * @see insertNextTuples
    */
-  initialize(): void;
+  initialize(): vtkDataArray;
 
   // --- via macro --
 
@@ -427,7 +434,7 @@ export interface vtkDataArray extends vtkObject {
  * @param {Number} [component] (default: 0) indice to use inside tuple size
  * @param {Number} [numberOfComponents] (default: 1) size of the tuple
  */
-export function computeRange(
+declare function computeRange(
   values: ArrayLike<number>,
   component?: number,
   numberOfComponents?: number
@@ -440,7 +447,7 @@ export function computeRange(
  * @param {Number} offset offset index to select the desired component in the tuple
  * @param {Number} numberOfComponents size of tuple in a multi-channel array
  */
-export function fastComputeRange(
+declare function fastComputeRange(
   values: ArrayLike<number>,
   offset: number,
   numberOfComponents: number
@@ -451,7 +458,7 @@ export function fastComputeRange(
  * Create helper object that can be used to gather min, max, count, sum of
  * a set of values.
  */
-export function createRangeHelper(): vtkRangeHelper;
+declare function createRangeHelper(): vtkRangeHelper;
 
 /**
  * Return the name of a typed array
@@ -463,14 +470,22 @@ export function createRangeHelper(): vtkRangeHelper;
  *
  * @param typedArray to extract its type from
  */
-export function getDataType(typedArray: TypedArray): string;
+declare function getDataType(typedArray: TypedArray): string;
 
 /**
  * Return the max norm of a given vtkDataArray
  *
  * @param dataArray to process
  */
-export function getMaxNorm(dataArray: vtkDataArray): number;
+declare function getMaxNorm(dataArray: vtkDataArray): number;
+
+export declare const STATIC: Readonly<{
+  computeRange: typeof computeRange;
+  createRangeHelper: typeof createRangeHelper;
+  fastComputeRange: typeof fastComputeRange;
+  getDataType: typeof getDataType;
+  getMaxNorm: typeof getMaxNorm;
+}>;
 
 /**
  * Method use to decorate a given object (publicAPI+model) with vtkDataArray characteristics.
@@ -497,37 +512,6 @@ export function extend(
  */
 export function newInstance(initialValues?: object): vtkDataArray;
 
-/**
- * Constants capturing the number of bytes per element based on its data type.
- */
-export enum DataTypeByteSize {
-  Int8Array,
-  Uint8Array,
-  Uint8ClampedArray,
-  Int16Array,
-  Uint16Array,
-  Int32Array,
-  Uint32Array,
-  Float32Array,
-  Float64Array,
-}
-
-/**
- * Constants capturing the various VTK data types.
- */
-export enum VtkDataTypes {
-  VOID,
-  CHAR,
-  SIGNED_CHAR,
-  UNSIGNED_CHAR,
-  SHORT,
-  UNSIGNED_SHORT,
-  INT,
-  UNSIGNED_INT,
-  FLOAT,
-  DOUBLE,
-}
-
 /**
  * vtkDataArray is an abstract superclass for data array objects containing
  * numeric data.

Sources/Common/Core/Endian/index.d.ts

@@ -5,11 +5,18 @@ import { Nullable } from '../../../types';
  */
 export function getEndianness(): Nullable<string>;
 
-export const ENDIANNESS: string;
+export const ENDIANNESS: Nullable<string>;
 
 /**
  *
  * @param {ArrayBuffer} buffer
  * @param {Number} wordSize
  */
 export function swapBytes(buffer: ArrayBuffer, wordSize: number): void;
+
+declare const _default: {
+  ENDIANNESS: Nullable<string>;
+  getEndianness: typeof getEndianness;
+  swapBytes: typeof swapBytes;
+};
+export default _default;

Sources/Common/Core/HalfFloat/index.d.ts

@@ -7,16 +7,16 @@
  * @param {number} input
  * @return encoded half float number (16 bits)
  */
-export function toHalf(input: number): number;
+declare function toHalf(input: number): number;
 
 /**
  * Convert a half float representation to a number
  * @param {number} input
  * @return decoded half float number
  */
-export function fromHalf(input: number): number;
+declare function fromHalf(input: number): number;
 
-export declare const HalfFloat: {
+declare const HalfFloat: {
   toHalf: typeof toHalf;
   fromHalf: typeof fromHalf;
 };