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 · 39 comments
Open

Typings for TypeScript #504

ssougnez opened this issue Jul 17, 2017 · 39 comments

Comments

@ssougnez
Copy link

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


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

@Reinmar
Copy link
Member

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

Loading

@nadavsinai
Copy link

@nadavsinai nadavsinai commented Jun 26, 2018

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

Loading

@ma2ciek

This comment has been hidden.

@ma2ciek

This comment has been hidden.

@ma2ciek

This comment has been hidden.

@Reinmar
Copy link
Member

@Reinmar Reinmar 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?

Loading

@ma2ciek
Copy link
Member

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

Loading

@jodator
Copy link
Contributor

@jodator jodator 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

Loading

@ma2ciek
Copy link
Member

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

Loading

@medmor

This comment was marked as off-topic.

@andysanti

This comment was marked as off-topic.

@Reinmar Reinmar removed this from the backlog milestone Oct 11, 2019
@Reinmar Reinmar added this to the nice-to-have milestone Oct 11, 2019
@JonasSchade
Copy link

@JonasSchade JonasSchade commented Oct 17, 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).

[...]

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)

Loading

@CrazyAdmin
Copy link

@CrazyAdmin CrazyAdmin commented Oct 23, 2019

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

Loading

@IonelLupu
Copy link

@IonelLupu IonelLupu commented Jan 23, 2020

Do you have any plans of rewriting this in Typescript?

Loading

@ma2ciek
Copy link
Member

@ma2ciek ma2ciek commented Jan 23, 2020

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 #1415.

Loading

@SolidZORO
Copy link

@SolidZORO SolidZORO commented Feb 14, 2020

@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!

Loading

@SolidZORO
Copy link

@SolidZORO SolidZORO commented Feb 22, 2020

自己写 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);
  }

Loading

@pierre-H
Copy link

@pierre-H pierre-H commented Mar 30, 2020

Any news ? 😃

Loading

@Anamican
Copy link

@Anamican Anamican commented Apr 22, 2020

We want typings, we want typings, we want Typings

Loading

@burtonator
Copy link

@burtonator burtonator commented May 28, 2020

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.

Loading

@ma2ciek
Copy link
Member

@ma2ciek ma2ciek commented May 28, 2020

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.

Loading

@burtonator
Copy link

@burtonator burtonator commented May 28, 2020

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

Loading

@pounard
Copy link

@pounard pounard commented May 28, 2020

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

Loading

@Reinmar
Copy link
Member

@Reinmar Reinmar commented Jun 16, 2020

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.

Loading

@rooby
Copy link

@rooby rooby commented Jun 16, 2020

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:

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.

Loading

@wosevision
Copy link

@wosevision wosevision commented Jun 18, 2020

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.

Loading

@Reinmar
Copy link
Member

@Reinmar Reinmar commented Jun 19, 2020

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

Loading

@wosevision
Copy link

@wosevision wosevision commented Jun 19, 2020

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.

Loading

@rooby
Copy link

@rooby rooby commented Jun 21, 2020

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.

Loading

@burtonator
Copy link

@burtonator burtonator commented Jun 22, 2020

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?

Loading

@ParrotStone
Copy link

@ParrotStone ParrotStone commented Dec 23, 2020

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

Loading

@kidzen
Copy link

@kidzen kidzen commented Jan 5, 2021

2021...yet still

Loading

@vbomfim
Copy link

@vbomfim vbomfim commented Jan 20, 2021

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

Loading

@BoringDays
Copy link

@BoringDays BoringDays commented Apr 11, 2021

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

Loading

@IonelLupu
Copy link

@IonelLupu IonelLupu commented Apr 11, 2021

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

Loading

@Laxusgee
Copy link

@Laxusgee Laxusgee commented Aug 1, 2021

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

Loading

@popuguytheparrot
Copy link

@popuguytheparrot popuguytheparrot commented Aug 5, 2021

Hi. What about react typings?

Loading

@mmichaelis
Copy link

@mmichaelis mmichaelis commented Aug 5, 2021

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.

Loading

fedemp added a commit to fedemp/ckeditor5 that referenced this issue Aug 9, 2021
After reading the comment at ckeditor#504 (comment) about properties that are marked as `readonly` when they should be writable, I realized that what you people meant `protected` when you used `readonly` here. _Protected_ properties are writable but should be modified by its own parent, not from the outside e.g. `isEnabled` that should be modified by `refresh()`.
@0biWanKenobi
Copy link

@0biWanKenobi 0biWanKenobi commented Nov 5, 2021

Hi, what about Vue typings?

Loading

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet