Typings for TypeScript

[ssougnez]

Hi,

I'm currently using ckeditor5 in TypeScript and I think it would be pretty usefull to ship typings definition. Is there something planed about this? I think it should be possible to auto generated them based on the JS files.

EDIT (by @Reinmar, 07.04.2023): It's out! 🚀 Read more in #504 (comment).

EDIT (by @filipsobol, 22.03.2023): The TypeScript migration is at the finish line. Alpha release of version 37 with typings is already out and being tested. We have updated our Vue integration and are in the process of updating React and Angular. You can follow the progress here: #11704.

EDIT (by @Reinmar, 23.08.2022): It's happening. We're migrating to Typescript 🎉 Having official typings is the main goal of the migration.

---

If you'd like support for TypeScript to be introduced react with 👍 to this post.

[Reinmar]

Quoting myself from #347 (comment):

We maintain a very thorough API documentation (JSDoc-based notation) so it should not be hard to generate type definitions and maintain them in https://github.com/DefinitelyTyped/DefinitelyTyped.

I agree that it'd be great if typings were available. But we won't be able to work on that now. I wonder, though, how much work it requires, in general, to produce those typings out of JSDoc comments. The problem in our case may lay in the fact that JSDoc didn't work well for ES6 so we came out with https://www.npmjs.com/package/@ckeditor/jsdoc-plugins – a set of plugins which fix stuff after JSDoc and extend it to better work in our case.

[nadavsinai]

Typescript definitions would greatly help our cause of developing with ckeditor5 platform

[ma2ciek]

I've found only one good looking tool - https://github.com/englercj/tsd-jsdoc, but it doesn't support the module: syntax and we use it in a custom way...

And there're few problems to solve anyway.

1. Events

JSDoc provides the synthetic @event and @fires, so all events and their documentation will be lost.

From the e.g.:

/**
 * Fired after {@link #initPlugins plugins are initialized}.
 *
 * @event pluginsReady
 */

We'd have to create such declarations:

declare class Emitter<EventMap> {
	listenTo<T extends keyof EventMap>( emitter: Emitter<EventMap>, event: T, callback: ( event: EventInfo<EventMap[ T ]> ) => void, options: any ): void;
	...
}

declare class Editor extends Emitter<EditorEvents> {

}

interface EditorEvents {
	pluginsReady: PluginsReadyEvent;
}

/**
 * Fired after {@link #initPlugins plugins are initialized}.
 */
interface PluginsReadyEvent {}

interface EventInfo<T> {}

to not lose the informations about the event. (Then, with every new editor event only the EditorEvents interface needs to be changed). I don't think that any JSDoc->TS plugin can support such syntax soon.

2. Builds

We'd need to provide typings for every source file and for builds. We'd need somehow to combine type declarations, so the builds will include only one TS declaration file with all proper typings.

I agree, that these typings would be super helpful for someone using TS or IDE that supports declaration files. But it feels super hard to implement a tool for such conversion, IMO writhing declaration files by hand wisely would be easier as the API is established.

[ma2ciek]

I can see that only reasonable choice would be to use that lib: https://github.com/englercj/tsd-jsdoc. It operates on the JSDoc output, but it doesn't support many things, e.g. the module: syntax, so we'd need to somehow patch this tool and align to our needs.

[ma2ciek]

I see that I overcomplicate this issue in the #504 (comment). If we'd like to make this tool we should implement it incrementally and make the TS output backward-compatible.

[Reinmar]

@ma2ciek I know you made some work on running our source code through TypeScript compiler and using current documentation as type definitions. Could you write here a short summary? Is that feasible? How much work would it be needed?

[ma2ciek]

To sum up that thread, it's possible to use TS compiler to check our JavaScript code by taking advantage of JSDoc our comments. So once our code whole codebase will be type-checked it should be possible to generate proper TS declaration files for every file. But note that the PR that allows generating declaration files from JS code is still an open issue and the TS team is waiting for the community PRs (we can also try the mentioned dts-gen project but IMO it'd be better to wait for the official option).

According to changes needed to bring that type-checking and be somehow TS-compatible, we'd to need to work on:

• converting all module: syntax to normal imports (I assume that the ESlint might complain about unused imports, but maybe there's some plugin for that, dunno) or to the relative import() syntax and add some changes to our JSDoc plugins so it could work properly with that syntax (not sure how much work it'd be needed)
• checking whether our mixins could be understandable by TS - TS supports only single inheritance, but there could be some ways to mimic that effect.
• checking whether the caught errors from JS files are highlighted in all IDEs we use.
• fix all incorrect typedefs, interfaces, types, etc. in the existing code (like that one).

It's hard to tell exactly how much work is needed, IMO it's better to check all potential blockers first.

[jodator]

• checking whether our mixins could be understandable by TS

Shouldn't the interfaces be used for mixins? Instead of

/**
 * @mixes MixinFoo
 * @mixes MixinBar
 */

write:

/**
 * @implements InterfaceFoo
 * @implements InterfaceBar
 */

ps.: TS docs about mixins: https://www.typescriptlang.org/docs/handbook/mixins.html

[ma2ciek]

@jodator, we could use just interfaces, but then the class would need to implement all these interfaces anyway (Otherwise TS will complain). So that's not an option IMO. Yep, I've seen that part about mixins, but we can't do that in many cases as it's massive code duplication (we'd need to mock every property and method for every interface that we need to implement).