Type definitions

frederik · December 10, 2015, 8:28pm

Hi all,

I was wondering whether anyone else would be interested in maintaining typings for ProseMirror (in the definitely typed repo I suppose).

I started using ProseMirror in a typescript project this month and am slowly typing the parts of the API I touch (though typings should be helpful for folks with ES6 as well, providing intellisense and all).

Regards Frederik

p.s.: I am sure these will breaks a lot during the next months as Marijn is changing the API, but we’ll have to adapt existing code anyways

adarshaj · March 25, 2016, 7:28pm

I am about to do this, do you already have some typings done? I did google but couldn’t find any.

thanks,

frederik · March 29, 2016, 2:33pm

I do not have anything (publicly) online yet. It could make sense to start a shared repo with the 0.6 release. What parts of the API are you planning to cover?

adarshaj · March 30, 2016, 9:31am

I am just starting out, so basic editor, menubar, some ui related ones - tooltip, update, etc. Mostly its going to grow gradually as I use features and may be some weekends try to complete rest of apis. I like idea of having a shared repo from 0.6 onward. Do you know the projected release timeline for 0.6?

frederik · March 30, 2016, 9:46am

Not sure, but there will be a developer meeting tomorrow at 2 P.M (UTC). I guess a timeline will come up.

alexandresalome · July 16, 2016, 10:37am

I’m working on typings for ProseMirror too. That’s a little bit tricky for me, since I’m really new to Typings…

Here is the minimal thing I got to make hello-world example work:

declare module "prosemirror/dist/edit" {

    export class ProseMirror {
        doc:any;
        on:any;
        constructor(options: any);
    }
}

declare module "prosemirror/dist/schema-basic" {
    export var schema: any;
}

If anyone has a smarter version than mine, could he publish his current state of work? I’ll publish mine as soon as I progress on it.

frederik · July 16, 2016, 12:03pm

Hi, this is basically what I have done as well…

But with TypeScript 2 (with non-nullables, shorthand ambient modules, etc.) coming out soonish and the discussion over here RFC: Splitting the library into packages I have chosen to wait a bit before I start any greater efforts.

I am also still considering to programatically extract definitions from Marijns source files though I currently do not have the time to start efforts on this either. Maybe someone else wants to pick this up?

marijn · July 16, 2016, 7:46pm

I will eventually get to this myself (but there’s a looong list of stuff like that), but if someone else wants to tackle this, note that the getdocs library which I’m using to generate the docs can be used to easily extract the type information from the source files. In many cases (though not 100% of them), creating .d.ts files could just be a matter of running getdocs JSON output through a template.

alexandresalome · July 17, 2016, 11:21am

Thank you for for feedback.

For people coming back later here, here is how website generates the documentation: https://github.com/ProseMirror/website/blob/master/src/build/ref.js

I started a branch on github to do as you said, here is my current work: https://github.com/ProseMirror/prosemirror/compare/master...alexandresalome:typings

Feedbacks would be appreciated, especially:

Does it make sense to version generated files?
Is the typings.json at the root of the package enough for TypeScript to recognize it?
Is mold templating a good choice for generation of files?
Is script/ folder a good place for templates and script location?
Is the syntax in the .d.ts file on a good way? I’m pretty new to TypeScript, I’m not sure about the “best” syntax to use for definitions

Thank you for your help.

frederik · July 18, 2016, 5:52pm

This could probably be generated during npm publish (in case it is ever shipped with the code). Otherwise it should probably go into the typed typings repo on github so everyone can find them.

Have a look at this link. If we can change the package.json then this should be enough. In case Marijn decides to publish the d.ts files alongside the npm package then even having the .d.ts file next to the original JS file should be enough.

I have done some digging on the topic of .d.ts generation - there seems to be a library written in F# that generates definition files from XML (not really what we need).

The best would probably be to use the TypeScript Compiler API (e.g. build an AST from JavaScript+Annotations and then compile a ts/d.ts file from it. I’ve read about some libraries that try to do this for flow but again, did not find anything that could be adapted right away.

Your template approach seems to be the most straight forward and quickest to a solution.

mitermayer · July 19, 2016, 9:47am

Thanks for looking into that! We also tried to generate definitions for prosemirror. We attempted doing the following approach:

runing lebab to convert src/**/*.js to es6 on a separate folder
renaming all ‘.js’ to '.ts’
running tsc(typescript compiler) with some sane default settings to generate definitions
running dts-bundle(type definition bundler) to merge all the .d.ts files into a single one with the declared modules.

We got an almost perfect representation. We however had to clean by hand, the problems we found were:

Not able to generate definitions for this.foo=bar type of assignments inside the constructor
Not able to generate definitions for modules that used the copyObj() to mingle the exports

Our approach was to have a CI build that will attempt to check compatibility with latest prosemirror and this type definitions file and fix by hand from there on.

Would be great if prosemirror itself could export its definitions files. Otherwise we could add the current definitions file that we have to either definitelyTyped or a typings repository so that we could leverage from the community contribution.

Mobiletainment · July 28, 2016, 7:05pm

Would anyone be so kind to share their typings? Preferably via a public github repo, so that it can be easily installed via typings

I don’t even need to have a .d.ts that is feature-complete or on a par with the latest releases, just enough to start playing with ProseMirror in TypeScript and not having the IDE complain about the imports and missing modules…

mitermayer · July 28, 2016, 11:03pm

HI @Mobiletainment will talk to the team here and see if we can open it up to a public repo

Mobiletainment · August 1, 2016, 12:04pm

Hello @mitermayer, thank you very much for your help. Did you already have a chance to clarify if you’re able to share your typings?

Kind regards, David

Mobiletainment · August 22, 2016, 2:13pm

In the meanwhile, I found this npm package with the type definitions: atlassian-prosemirror-type-definitions

Thumbs up and thank you!

mitermayer · August 28, 2016, 5:51am

Yeah @Mobiletainment, forgot to mention, we published the type definitions to NPM, we have not moved the repo yet to a public repository to allow contributions but we should be doing that soon. Feel free to use our npm package https://www.npmjs.com/package/atlassian-prosemirror-type-definitions however there are still chances that some definitions are broken, we are fixing as we go during our development. Will talk to the team this week to see if we can open the repository to the public to allow external contributions

kookster · December 7, 2016, 1:34am

I’ve also been working on a prosemirror.d.ts file for the latest version, and have something that is mostly working (though not complete, it covers all the parts of pm we’re interacting with and then some). Happy to share it, but also trying to make it a bit more finished first.

davidka · February 9, 2017, 8:29am

Hi @kookster, have you made any progress in generating the type definitions? If yes could you please share them?

kookster · February 9, 2017, 4:40pm

Here’s what we’re using, have a look:

github.com

PRX/publish.prx.org/blob/master/src/app/shared/wysiwyg/prosemirror.d.ts

/* tslint:disable */
declare module 'prosemirror-commands' {
  export { isWordChar, charCategory } from 'prosemirror-commands/char';
  export { autoJoin, baseKeymap, chainCommands, createParagraphNear, deleteCharAfter, deleteCharBefore, deleteSelection, deleteWordAfter, deleteWordBefore, joinBackward, joinDown, joinForward, joinUp, lift, liftEmptyBlock, moveBackward, moveForward, newlineInCode, selectParentNode, setBlockType, splitBlock, toggleMark, wrapIn } from 'prosemirror-commands/commands';
  export { ios, mac } from 'prosemirror-commands/platform';
}

declare module 'prosemirror-commands/char' {
  function isWordChar(ch: any): boolean;
  export { isWordChar }
  function charCategory(ch: any): string;
  export { charCategory }
}

declare module 'prosemirror-commands/commands' {
  function deleteSelection(state: any, onAction?: any): boolean;
  export { deleteSelection }
  function joinBackward(state: any, onAction?: any): boolean;
  export { joinBackward }
  function joinForward(state: any, onAction?: any): boolean;

This file has been truncated. show original

kookster · February 9, 2017, 4:45pm

I suppose I should put them in the typings registry (https://github.com/DefinitelyTyped/DefinitelyTyped or https://github.com/typings/registry), especially to make them easier for others to use. Let me know how these work for ya @davidka!