Typings for TypeScript - Githubissues

ssougnez commented 6 years ago

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 https://github.com/ckeditor/ckeditor5/issues/504#issuecomment-1499078025.

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: https://github.com/ckeditor/ckeditor5/issues/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 commented 6 years ago

Quoting myself from https://github.com/ckeditor/ckeditor5/issues/347#issuecomment-309859172:

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 commented 5 years ago

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

ma2ciek commented 5 years ago

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.

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.

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 commented 5 years ago

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 commented 5 years ago

I see that I overcomplicate this issue in the https://github.com/ckeditor/ckeditor5/issues/504#issuecomment-408404900. If we'd like to make this tool we should implement it incrementally and make the TS output backward-compatible.

Reinmar commented 5 years ago

@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 commented 5 years ago

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 commented 5 years ago

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 commented 5 years ago

@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 commented 4 years ago

it will be great to have typescript definition for ckeditor5 platform

andysanti commented 4 years ago

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

ghost commented 4 years ago

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

[...]

Just stumbled upon this. FYI the issue about allowing generation of typing from JavaScript was merged a few weeks ago, although it looks like it wasn't officially released yet. It'll probably be included in the 3.7 release. (TypeScript 3.7 Iteration Plan)

CrazyAdmin commented 4 years ago

Please/ TypeScript support is very important for use in project. Please implement base Types support

IonelLupu commented 4 years ago

Do you have any plans of rewriting this in Typescript?

ma2ciek commented 4 years ago

Hi @IonelLupu,

There're plans to either rewrite to TS or to use JSDoc annotations and generate declaration files out of them, but I can't guarantee when it happens and if it happens.

See https://github.com/ckeditor/ckeditor5/issues/1415.

SolidZORO commented 4 years ago

@Reinmar @ma2ciek

I recently developed a plugin for CKEditor5 and found that it is really inconvenient to not have TS type files. Although CKEditor5 has a very complete API manual, but the manual is not as convenient and timely as TS type. I know that rewriting CKEditor5 with TS is very difficult, but I think If you want to write a TS type, it is relatively simple, even if all types use any, so I know at least those Methods or Properties are available. thank you for developing such a good and easy-to-use Editor. Grateful！

SolidZORO commented 4 years ago

自己写 type 真的很花时间，最主要的问题还是自己不一定能写对！

下面这个 writer 蛮常用的，前后整理核对下来花了 2h。😭

// @ckeditor/ckeditor5-engine/src/model/writer
  class Writer {
    readonly batch: any;
    readonly model: model.Model;
    //
    addMarker(name: string, options: { usingOperation: boolean; range: Range; affectsData?: boolean }): Marker;
    append(item: Item | DocumentFragment, parent: Element | DocumentFragment);
    appendElement(
      name: name,
      attributes?: { [key: string]: string | RegExp | boolean },
      parent: Element | DocumentFragment,
    );
    appendText(
      text: string,
      attributes?: { [key: string]: string | RegExp | boolean },
      parent: Element | DocumentFragment,
    );
    clearAttributes(itemOrRange: Item | Range);
    createDocumentFragment(): DocumentFragment;
    createElement(name: string, attributes?: { [key: string]: string | RegExp | boolean }): Element;
    createPositionAfter(item: Item): Position;
    createPositionAt(itemOrPosition: Item | Position, offset?: number | 'end' | 'before' | 'after'): Position;
    createPositionBefore(item: Item): Position;
    createPositionFromPath(root: Element | DocumentFragment, path: number[], stickiness?: PositionStickiness): Position;
    createRange(start: Position, end?: Position): Range;
    createRangeIn(element: Element): Range;
    createRangeOn(element: Element): Range;
    createSelection(
      selectable: Selection,
      placeOrOffset?: number | 'before' | 'end' | 'after' | 'on' | 'in',
      options?: { backward?: boolean },
    ): Selection;
    createText(data: string, attributes?: { [key: string]: string | RegExp | boolean }): Text;
    insert(item: Selection, itemOrPosition: Item | Position, offset?: number | 'end' | 'before' | 'after');
    insertElement(name, attributes?: { [key: string]: string | RegExp | boolean }, itemOrPosition, [offset]);
    insertText(data, attributes?: { [key: string]: string | RegExp | boolean }, itemOrPosition, [offset]);
    merge(position: Position);
    move(range: Range, itemOrPosition: Item | Position, offset?: number | 'end' | 'before' | 'after');
    overrideSelectionGravity(): string;
    remove(itemOrRange: Item | Range);
    removeAttribute(key: string, itemOrRange: Item | Range);
    removeMarker(markerOrName: Marker | string);
    removeSelectionAttribute(keyOrIterableOfKeys: string | string[]);
    rename(element: Element, newName: string);
    restoreSelectionGravity(uid: string);
    setAttribute(key: string, value: any, itemOrRange: Item | Range);
    setAttributes(attributes: { [key: string]: string | RegExp | boolean }, itemOrRange: Item | Range);
    setSelection(
      selectable: Selection,
      placeOrOffset: number | 'before' | 'end' | 'after' | 'on' | 'in',
      options?: { backward?: boolean },
    );
    setSelectionAttribute(keyOrObjectOrIterable: any, value: any);
    setSelectionFocus(itemOrPosition: Item | Position, offset: number | 'before' | 'end' | 'after');
    split(position: Position, limitElement: Node): any;
    unwrap(element: Element);
    updateMarker(
      markerOrName: string | Marker,
      options?: { range?: Range; usingOperation?: boolean; affectsData?: boolean },
    );
    wrap(range: Range, elementOrString: Element | string);
  }

pierre-H commented 4 years ago

Any news ? 😃

Anamican commented 4 years ago

We want typings, we want typings, we want Typings

burtonator commented 4 years ago

Holy obvious omission batman!

This is a pretty big flaw to not address this as of 2020... For a professional package, that I'm expecting to pay for, typescript types are feature #1 that I would need.

It's also a sniff test... if you guys are missing this feature it's not a good sign for other features that I would expect.

ma2ciek commented 4 years ago

It's also a sniff test... if you guys are missing this feature it's not a good sign for other features that I would expect.

Going to TypeScript is a HUGE architectural change. And typing all packages by hand is irrational. I know that typings is a cool feature and I'm super happy while using other packages shipping their typings but it's only a DX feature and the cost of changing thousands of source files, thousands of tests, aligning 50+ internal script and tools are a little bigger than our capacity right now (considering the fact that the some parts of the codebase would need to be frozen at some points, even if we go package by package).

The only way to provide typings right now is by extending the current ones on https://github.com/DefinitelyTyped/DefinitelyTyped and install them from the @types/ scope packages later.

burtonator commented 4 years ago

@ma2ciek is there a @types package? I couldn't find it... pointer?

I agree WRT to rewriting the code base and typing ALL code... but it's not necessary for external developers for 90% of the use cases.

You could provide high level types for the react component btw and that would solve 99% of my use case.

I'm going to eval ckeditor5 and should be able to just write basic types for the react component by developing my own types in the module.

The main issue is that types provide a MASSIVE amount of productivity gain by external developers.

It's like the difference of being in a cave in the dark and having a flashlight (or not).

I'm basically suggesting that the pareto principle (80/20) rule be used here. Any edge types, for now, could just be 'any'... or you could just create an interim project that we could all contribute to over time. Pretty quickly you'd have 95% of use cases solved.

pounard commented 4 years ago

@ma2ciek

Going to TypeScript is a HUGE architectural change.

Whereas I'm huge TypeScript fan (spoiler alert: I flee JS like the pest) I think that people don't necessarily want that you switch to TypeScript (although it sure would help you making more stable/robust code) they only want to have working up-to-date definition files for them.

If people that write ckeditor could also provide up to date typings along the way, it would be a huge win.

Reinmar commented 3 years ago

If people that write ckeditor could also provide up to date typings along the way, it would be a huge win.

We understand that.

But, we can't reliably provide typings of couple hundred classes and thousand methods if we won't be actually using TypeScript. In order to have typings for the editor, we'd also need to redesign some APIs with TS's limitations in mind.

There's also an option of manually providing typings for a smaller subset of editor API just like @burtonator proposed. This is something that also crossed our minds. However, what subset are we talking about? @burtonator mention React component. We could also consider some top-level integration API like the `.create()` method, the config object, etc. But then @SolidZORO mentions the writer, so a plugin-level API.

HELP NEEDED 💗

What I'm actually interested (and let's treat this as a poll) – what subset would be sufficient for you? Can you all list classes/props/methods/typedefs that your implementation use? That would be of real help for us. Perhaps there's indeed something that we could do relatively cheaply and still satisfy a significant number of cases.

rooby commented 3 years ago

I was a person who was originally frustrated by the lack of types, but I don’t understand why people are still complaining here.

Since there are types in the DefinitelyTyped package this should be a non-issue.

The DefinitelyTyped project is intended to provide types for packages that don’t have types. This project is not a typescript project and has no type definitions, therefore it makes sense that the types be in DefinitelyTyped.

It’s not a big deal to install types from @types/... where required. You almost certainly already do this for other packages.

So really, if the ckeditor team doesn’t have resources for, or doesn’t consider it a priority to dedicate resources to adding types here (remembering it’s not a typescript project), and if the types in DefinitelyTyped are insufficient (I’m no longer on the project where I was using creditor5 with angular so I haven’t actually tried it out) then an issue should be opened at DefinitelyTyped to improve them.

See the DefinitelyTyped package:

https://www.npmjs.com/package/@types/ckeditor__ckeditor5-core (Also installs the related -engine and -utilis packages as dependencies).

The code is at:

Also, for reference:

If the ckeditor team can help flesh out the types then great, but if not then the community will have to step up. I can understand that people might think that ckeditor is a company offering a product and they should do it, especially if you’re paying them a subscription fee, but they are not offering it as a paid typescript product so I think that’s a non-argument.

wosevision commented 3 years ago

Since there are types in the DefinitelyTyped package this should be a non-issue. ... It’s not a big deal to install types from @types/... where required. You almost certainly already do this for other packages.

Here's a counter-opinion from someone who has been using TS in large-scale projects for ~4 years now: while I respectfully acknowledge and commend the hard work of the community in making the DefinitelyTyped repo what it is, there are some areas it will always fall short in.

Having had to rely on community types for many packages over the years, one thing I constantly encounter – so often it becomes an actual time sink – is community type definitions that fall behind the actual definitions, i.e. because of minor version updates. Sometimes they're just plain wrong and it's not even a version inconsistency, it's just human error.

I've personally submitted a number of PRs to fix DefinitelyTyped type definitions – I promise I don't idly sit and complain about these things. But that doesn't stop me from recognizing that the only real 'holistic' solution is when the type definitions are generated automatically on new builds direct from the author. It just isn't sustainable to expect the community to religiously watch for every new patch.

Microsoft's dts-gen is a good place to start for incorporating type definitions into a library without rewriting it for Typescript.

Reinmar commented 3 years ago

@wosevision Exactly my thinking. Especially that if we'd offer official typings, there will be even bigger expectation that they are flawless. It's different when it's community-driven and different when it's getting official.

If we'll decide to provide official typings for at least a small subset of CKEditor 5 API, we must have automated testing for all that. Ideally, the entire extraction must be automated too. dts-gen or https://github.com/englercj/tsd-jsdoc could probably be of some help here, but my guess is that we'd end up with something customized, the same way we ended up heavily customizing JSDoc to fit our needs.

If you start estimating the amount of work needed to put up a reliable system for that, you realise that there's no quick win. Also, long-term migrating to TypeScript sounds like a better option so that makes burning days of work on a flawed, incomplete solution even worse idea.

I may be wrong thinking this. But that's how it looks to me now.

wosevision commented 3 years ago

long-term migrating to TypeScript sounds like a better option so that makes burning days of work on a flawed, incomplete solution even worse idea.

Agree 100%. The long-term solution is always the better one. I usually only put dts-gen out there when it seems like there's 0 intention of moving the codebase to TS, but if that's potentially on your roadmap, you'll have more holistic results that way for sure.

to put up a reliable system for that, you realise that there's no quick win

Not necessarily! Granted, the CKEditor codebase is no "regular" library and would definitely represent its own unique challenges simply by the sheer scale of it. But – the process of "migrating" a JS file to TS is quite literally just changing the file extension! That doesn't make it a "good" TS file by any measure, but if it was valid JS to begin with, it will compile (albeit with complaints).

Setup and tooling are obviously a whole other matter, but the basic act of changing a JS file to TS and giving it a bunch of any types will still provide a basic level of autocompletion. They have a pretty good starter guide.

rooby commented 3 years ago

I absolutely agree with what both of you are saying in the last few comments. It would definitely be preferable that types are in here instead of in the @types packages for the reasons wosevision mentioned, however I think a half-baked solution is probably not going to be much better than what we already have.

I think there would be benefits for the whole package to move to development in typescript and types coming as part of that, but obviously that comes down to resourcing vs perceived benefit (and probably wouldn't happen outside of a major version increment).

That piece of work is also not really something that could easily be community driven, since it's going to touch all the code and also build tools, so needs to be sensibly fit in around other work that's going on.

burtonator commented 3 years ago

I think that if it was easier to develop types and override then this wouldn't be SUCH a major issue but the main challenge I have is that I need to override some @types but I can't really do that without setting up my own private npm repo - which is a pain.

Also, you can't define your own '@types' namespace without it having a path which then breaks when using lerna with --hoist. :-/

I've been using github for this too but that's not easier either because I can't just push to it.

Are there @types for react too?

ParrotStone commented 3 years ago

Any news/updates on this issue? When will it have typings?

kidzen commented 3 years ago

2021...yet still

vbomfim commented 3 years ago

Nice product, but I can't use it without Types.

BoringDays commented 3 years ago

Can't use ckeditor in my vue3 project for the lacking typings

IonelLupu commented 3 years ago

@vbomfim @BoringDays I ended up using TinyMCE. It's easier to use and has typyings.

I know CKEditor has a paid version but with the lack of features like typings, it is not worth the money.

Laxusgee commented 2 years ago

I have used CKEditor all my life, I can't believe i looking up alternatives because of Typings support.

popuguytheparrot commented 2 years ago

Hi. What about react typings?

mmichaelis commented 2 years ago

Short update regarding DefinitelyTyped:

You may have observed, that typings for DefinitelyTyped got updated recently by @fedemp, and a lot of more typings got added (see closed and pending PRs).

But as JSDoc of CKEditor comes with flaws, these typings carry on and enhance the flaws (like for example properties marked as readonly in JSDoc, but which require to be writeable by extending classes).

Currently, we handle this by bug-reports at DefinitelyTyped, but perhaps the better way to go is to report a bug regarding JSDoc here. This would be an immediate gain for JavaScript developers, as well as the TypeScript community, which is in need of easy to rebuilt typings from existing sources.

0biWanKenobi commented 2 years ago

Hi, what about Vue typings?

jperg2tami commented 2 years ago

Need typings!

fedemp commented 2 years ago

If you all want typings for Typescript, please help by approving PRs .e.g https://github.com/DefinitelyTyped/DefinitelyTyped/pull/57571

rsuardi commented 2 years ago

Need typings!

johnmanko commented 2 years ago

npm i --save-dev @types/ckeditor__ckeditor5-build-classic
npm i --save-dev @types/ckeditor__ckeditor5-build-balloon

nadavsinai commented 2 years ago

npm i --save-dev @types/ckeditor__ckeditor5-build-classic
npm i --save-dev @types/ckeditor__ckeditor5-build-balloon

are these official? why not add them to each package ?

mmichaelis commented 2 years ago

npm i --save-dev @types/ckeditor__ckeditor5-build-classic
npm i --save-dev @types/ckeditor__ckeditor5-build-balloon
are these official? why not add them to each package ?

IIRC, they are not official (thus, by CKEditor-team) but a contribution. Anyone could provide more packages. Unfortunately, they are also not always in sync with the actual implementation – most of the time, it is the JSdoc to blame, which provides wrong details. That's why I sometimes report such JSdoc issues to CKEditor, hoping for better generated typings next time.

fedemp commented 2 years ago

If somebody has some minutes, know enough about CKEditor, and can test some types, these PR's need approval.

https://github.com/DefinitelyTyped/DefinitelyTyped/pulls?q=is%3Aopen+is%3Apr+author%3Afedemp+draft%3Afalse

Jake-Thomas-Hall commented 2 years ago

Hey,

Following the points from this thread, I implemented an example of how to use ckeditor in Angular.

To be clear, for most scenarios you'd probably just want to use ckeditor's regular Angular component - but this shows how you can actually use the editor without needing that component, if you need that for whatever reason.

It also includes @types/ckeditor__ckeditor5-build-classic in order to allow intellisense, since that would be very helpful if you want to use ckeditor in this way.

Repo: Jake-Thomas-Hall/ckeditor-angular-example

Reinmar commented 2 years ago

Some good news, everyone: #11704 :)

Reinmar commented 1 year ago

Some status update.

We're doing a good progress migrating packages. We covered more than 50% of them, including all the core ones (that are by far the biggest ones). So in general, it feels like we're 75% done.

Once all packages are migrated, we'll start publishing the types to npm. So far, those are omitted as they would be incomplete.

Keep your fingers crossed, TS is coming :runner:

Reinmar commented 1 year ago

Some good news :)

:white_check_mark: We migrated all the code already.

:rocket: And released 37.0.0-alpha.0 of all open source CKEditor 5 packages. This version introduces typings for all these packages.

More information: https://github.com/ckeditor/ckeditor5/issues/11704#issuecomment-1446345091

ckeditor / ckeditor5

Typings for TypeScript #504

HELP NEEDED 💗