Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Typings for TypeScript #504

Open
ssougnez opened this issue Jul 17, 2017 · 11 comments

Comments

@ssougnez
Copy link

commented Jul 17, 2017

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.

@Reinmar

This comment has been minimized.

Copy link
Member

commented Jul 18, 2017

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

This comment has been minimized.

Copy link

commented Jun 26, 2018

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

@ma2ciek

This comment has been minimized.

Copy link
Member

commented Jul 27, 2018

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.

  1. 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

This comment has been minimized.

Copy link
Member

commented Sep 27, 2018

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

This comment has been minimized.

Copy link
Member

commented Sep 27, 2018

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

This comment has been minimized.

Copy link
Member

commented Jan 3, 2019

@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

This comment has been minimized.

Copy link
Member

commented Jan 3, 2019

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

This comment has been minimized.

Copy link
Contributor

commented Jan 3, 2019

  • 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

This comment has been minimized.

Copy link
Member

commented Jan 3, 2019

@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).

@medmor

This comment has been minimized.

Copy link

commented Sep 1, 2019

it will be great to have typescript definition for ckeditor5 platform

@andysanti

This comment has been minimized.

Copy link

commented Sep 5, 2019

it will be great to have typescript definition for ckeditor5 platform.
me too

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
7 participants
You can’t perform that action at this time.