Typescript Support

[unlikelyzero]

This is an open forum to discuss all things Open MCT and Typescript!

[skrobchik]

Are there any plans to transition to Typescript? If so, how can one help?

[Fedezable]

Hello, anyone interested in a full conversion of OpenMCT in Typescript?
If the idea is welcome, I could start working on it on a fork in the next few weeks.

[tristan-f-r]

TypeScript sounds nice; once this repository moves to Vite, it sounds nice to add internally. It can also help catch some bugs and make it easier for end users to use this library (if it gets out that far) - and it can help quite a bit with enhancing the CodeQL warnings.

[ozyx]

We currently use tsc to generate TypeScript typings from JSDoc comments within our API-- this previously wasn't working super well due to the presence of all the AMD modules. Now that we're all ES6, tsc can infer types from ES6 classes as well as imports (🎉🎉🎉) so we can start taking advantage of that ASAP!

[ikirk]

Types seem not to be well-enough defined for typescript when consuming OpenMCT as a node module, but it's possible I'm just not familiar enough with typescript to really know the solutions. The issues I am currently running into are:

• node_modules/openmct/dist/openmct.d.ts as the API.md doc says to include in tsconfig.json doesn't seem to exist after npm install, but node_modules/openmct/dist/types/index.d.ts does. Have the types moved to that file?
• When adding a telemetry type (following the tutorial as a general framework)), the type TypeDefinition doesn't seem to have a name attribute, but after some tracing around does seem to have a label attribute. Typescript then reads initialize to be a required field, but this isn't reflected in the API docs, nor seems to really be required for TypeDefinition.
• Because of a reference to the type CompositionProvider in the function definition for addProvider and because the class CompositionProvider actually exists, typescript refers to the existing implementation of that class and requires that objects passed to openmct.compositions.addProvider extend that class, rather than the behavior described in the API docs where they should only need to implement appliesTo and load.

I propose we resolve this with a set of interfaces for the things that consumers of OpenMCT may want to or need to implement such as ICompositionProvider, IObjectProvider, and TypeDefinition, and then having the relevant internal implementations implement those interfaces. More than making it easier to develop in Typescript, this would give a nice starting point for new OpenMCT users to look at what they need to implement in order to develop and inject their own plugins. A potential implementation for ICompositionProvider (for example) based on the API docs and the methods in the current CompositionProvider that throw exceptions with messages about child classes needing to implement their own methods might look like:

interface ICompositionProvider
{
    /**
     * Indicates whether this provider applies to the given object
     * @param domainObject the object to check
     * @returns true if composition provider applies to this object,
     *          false otherwise.
     */
    appliesTo: (domainObject: DomainObject) => boolean;

    /**
     * Load any domain objects contained in the composition of this domain
     * object.
     * @param {DomainObject} domainObject the domain object
     *        for which to load the composition
     * @returns {Promise<Identifer[]>} a promise for the
     *          Identifiers in this composition
     */
    load: (domainObject: DomainObject) => Promise<Identifier[]>;

    /**
     * Attach listeners for changes to the composition of a given domain object.
     * Supports `add` and `remove` events.
     *
     * @param {DomainObject} domainObject to listen to
     * @param {string} event the event to bind to, either `add` or `remove`.
     * @param {Function} callback callback to invoke when event is triggered.
     * @param {any} [context] to use when invoking callback.
     */
    on?: (domainObject: DomainObject, event: string, callback: Function, context?: any) => void;

    /**
     * Remove a listener that was previously added for a given domain object.
     * event name, callback, and context must be the same as when the listener
     * was originally attached.
     *
     * @param {DomainObject} domainObject to remove listener for
     * @param {string} event event to stop listening to: `add` or `remove`.
     * @param {Function} callback callback to remove.
     * @param {any} context of callback to remove.
     */
    off?: (domainObject: DomainObject, event: string, callback: Function, context?: any) => void;

    /**
     * Remove a domain object from another domain object's composition.
     *
     * This method is optional; if not present, adding to a domain object's
     * composition using this provider will be disallowed.
     *
     * @param {DomainObject} domainObject the domain object
     *        which should have its composition modified
     * @param {Identifier} childId the domain object to remove
     */
    remove?: (domainObject: DomainObject, childId: Identifier) => void;

    /**
     * Add a domain object to another domain object's composition.
     *
     * This method is optional; if not present, adding to a domain object's
     * composition using this provider will be disallowed.
     *
     * @param {DomainObject} parent the domain object
     *        which should have its composition modified
     * @param {Identifier} childId the domain object to add
     */
    add?: (parent: DomainObject, childId: Identifier) => void;

    /**
     * @param {DomainObject} parent
     * @param {Identifier} childId
     * @returns {boolean}
     */
    includes?: (parent: DomainObject, childId: Identifier) => boolean;

    /**
     * 
     * @param domainObject 
     * @param oldIndex 
     * @param newIndex 
     * @returns 
     */
    reorder?: (domainObject: DomainObject, oldIndex: number, newIndex: number) => void;
}

The above is of course written in typescript, but there could potentially be an equivalent way to accomplish the same with javascript to keep it in line with the rest of the project.

[akhenry]

@akhenry

[akhenry]

@ikirk Our typescript support is definitely something we're trying to improve, so this feedback is really valuable, thank you.

node_modules/openmct/dist/openmct.d.ts as the API.md doc says to include in tsconfig.json doesn't seem to exist after npm install, but node_modules/openmct/dist/types/index.d.ts does. Have the types moved to that file?

Good catch! API.md is wrong, we will correct that. Thank you!

When adding a telemetry type (following the tutorial as a general framework)), the type TypeDefinition doesn't seem to have a name attribute, but after some tracing around does seem to have a label attribute.

The code will support either label or name for legacy reasons. The preferred usage is name and we will update the TypeDefinition to reflect that. Thanks!

Because of a reference to the type CompositionProvider in the function definition for addProvider and because the class CompositionProvider actually exists, typescript refers to the existing implementation of that class and requires that objects passed to openmct.compositions.addProvider extend that class, rather than the behavior described in the API docs where they should only need to implement appliesTo and load.

Another great catch, thank you! API and type definitions will be aligned here.