Designating the data type for Object3D.userData in Three.js using TypeScript

Question

Designating the data type for Object3D.userData in Three.js using TypeScript

Within the realm of Three.js, there exists a field on the Object3D class known as userData. This particular property is defined in the type declaration file

node_modules/three/src/core/Object3D.d.ts

:

/**
 * Base class for scene graph objects
 */
export class Object3D extends EventDispatcher {

[...]

    /**
     * An object that can be used to store custom data about the Object3d. It should not hold references to functions as these will not be cloned.
     * @default {}
     */
    userData: { [key: string]: any };

[...]

}

In an effort to impose stronger typing on the userData attribute, I crafted a module type declaration named src/typings/three.d.ts:

declare module 'three' {
  export class Object3D {
    userData: MyType1 | MyType2;
  }
}

type MyType1 = {
  type: 'type1';
  radius: number;
};
type MyType2 = {
  type: 'type2';
  name: string;
};

Despite successfully overwriting the userData property, all other type declarations within the three module were replaced rather than merged. This outcome proved to be more destructive than beneficial, evident in the absence of additional properties.

Is there an effective method to merge type declarations whereby solely the userData is substituted without impacting the entire module?

https://i.sstatic.net/VQZtG.png

typescript three.js extend user-data .d.ts

Answer 1

Answer №1

When working with typescript terminology, you are attempting "declaration merging" in combination with "module augmentation". The issue with your current example has a few fixable problems and one limitation imposed by the language.

Let's address these problems and provide some solutions before suggesting an alternative method for achieving the desired outcome.

If you intend to augment a class definition through module augmentation, your augmentation should be represented as an un-exported interface rather than an exported class definition. This means replacing export class Object3D with interface Object3D. Although it may not be intuitive, the documentation explains that certain merges are not allowed in TypeScript.
It is crucial to match the signature of the class you are augmenting precisely, including generic parameters and extends statements. Make sure to adhere to the exact structure of the class during augmentation.
The structure of @types/three involves various export statements spread across different files, which can complicate module augmentation. When targeting a specific file for module augmentation, ensure your declare module statement aligns directly with that file without being affected by intermediary exports.

To summarize, here's an almost functional approach:

import { BaseEvent, EventDispatcher } from "three";

declare module "three/src/core/Object3D" {
  interface Object3D<E extends BaseEvent> extends EventDispatcher<E> {
    somethingElse: string;
    userData: MyType1 | MyType2; // Unexpected behavior due to TypeScript limitations
  }
}

It's important to note that declaration merging cannot alter the type of an existing property on the original class definition. Instead, it can only add new properties to the class.

An Effective Alternative Approach

To overcome this limitation, consider creating a new class declaration that extends the original class and overrides the necessary type:

declare module "three" {
  import { BaseEvent } from "three/src/core/EventDispatcher";
  import { Object3D as Object3DOriginal } from "three/src/core/Object3D";
  export * from "three/src/Three";
  export class Object3D<E extends BaseEvent = Event> extends Object3DOriginal<
    E
  > {
    userData: MyType1 | MyType2;
  }
}

For a working example, refer to this codesandbox link.

Answer 2

When working with typescript terminology, you are attempting "declaration merging" in combination with "module augmentation". The issue with your current example has a few fixable problems and one limitation imposed by the language.

Let's address these problems and provide some solutions before suggesting an alternative method for achieving the desired outcome.

If you intend to augment a class definition through module augmentation, your augmentation should be represented as an un-exported interface rather than an exported class definition. This means replacing export class Object3D with interface Object3D. Although it may not be intuitive, the documentation explains that certain merges are not allowed in TypeScript.
It is crucial to match the signature of the class you are augmenting precisely, including generic parameters and extends statements. Make sure to adhere to the exact structure of the class during augmentation.
The structure of @types/three involves various export statements spread across different files, which can complicate module augmentation. When targeting a specific file for module augmentation, ensure your declare module statement aligns directly with that file without being affected by intermediary exports.

To summarize, here's an almost functional approach:

import { BaseEvent, EventDispatcher } from "three";

declare module "three/src/core/Object3D" {
  interface Object3D<E extends BaseEvent> extends EventDispatcher<E> {
    somethingElse: string;
    userData: MyType1 | MyType2; // Unexpected behavior due to TypeScript limitations
  }
}

It's important to note that declaration merging cannot alter the type of an existing property on the original class definition. Instead, it can only add new properties to the class.

An Effective Alternative Approach

To overcome this limitation, consider creating a new class declaration that extends the original class and overrides the necessary type:

declare module "three" {
  import { BaseEvent } from "three/src/core/EventDispatcher";
  import { Object3D as Object3DOriginal } from "three/src/core/Object3D";
  export * from "three/src/Three";
  export class Object3D<E extends BaseEvent = Event> extends Object3DOriginal<
    E
  > {
    userData: MyType1 | MyType2;
  }
}

For a working example, refer to this codesandbox link.

Designating the data type for Object3D.userData in Three.js using TypeScript

Answer №1

Similar questions

Error: The function req.logIn is not recognized - Passport JS

Unauthorized Token Authentication in .NET and Angular Application

Encountering Next.js Hydration Issue when Using Shadcn Dialog Component

This function template is designed to work with a wide range of inputs, thanks to its generic nature. It allows a callback function to be executed with a set of parameters of any type

Having trouble displaying a group of threeJs renderers

Unable to access Papa Parse results beyond the 'complete' function

Step-by-step guide on uploading a file for API testing

Guide on making a three-dimensional trapezoid using three.js

Position Geometry on Plane by picking 3 intersecting points

Angular 7: Show selected value upon clicking Radio button

Guide to generating multiple instances of Isocohedrons (polygons) with react-three/fiber and react-three/drei for rendering an unlimited number of shapes

Guide to retrieving specific attributes from an object within an array of objects using Angular Typescript

How does the plain constant continue to be effective in the Composition API of Vue 3?

Triggering an event from a higher-level component to a lower-level component

Mean value calculated for each hour within a given array

The browser appears to be interpreting the JavaScript file as HTML, resulting in the error message "Uncaught SyntaxError: Unexpected token '<'"

Merge the values of checkboxes into a single variable

Using type aliases in Typescript to improve string interpolation

The cube from Three.js refuses to render after being bundled with Webpack in a Wordpress environment

The Observable pipeline is typically void until it undergoes a series of refreshing actions