Add TypeScript type definitions

[jack-guy]

Paper.js is a pretty popular module. It'd be fantastic if it had typings on DefinitelyTyped, letting people use it with frameworks like Angular 2 with greater ease.

[lehni]

W're not TypeScript users ourselves, so it's not high up on our list of priorities. There was a discussion that the required files could be generated out of our existing JSDoc comments, and I've done some preliminary testing with a separate set of JSDoc templates, but haven't gotten far. Would you be willing to help with this?

[jack-guy]

I might give it a shot. What are you currently using to parse your JSDoc comments? Or are you just generating templates with the CLI?

[lehni]

We are using a custom version of JSDoc 2 at the moment that is Java based. There's a plan to upgrade to the node-based JSDoc 3, but it's low priority: #375

The repo for it is here: https://github.com/paperjs/jsdoc

And if you run git submodule update --init --recursive, it gets checked out as a git submodule into paper.js/gulp/jsdoc.

You will find the typescript-targeted templates in jsdoc/templates/typescript, and the configuration file in jsdoc/conf/typescript.

To run it, you can execute this command in the jsdoc folder:

java -jar jsrun.jar app/run.js -c=conf/typescript.conf

Getting this right will probably involve a mixture of adjusting the files in jsdoc/templates/typescript, along with some tweaks to our existing JSdoc comments. I am happy to assist in the process, I'm just new to TypeScript and wouldn't want to do it on my own as I can't judge the quality of the result.

Are there any ways of testing / verifying the resulting paper.d.ts file?

[jack-guy]

That module.tmpl file looks like a really good start.

I'll admit I'm not overly familiar with Paper.js, but hopefully between the two of us we can get a good definition set up. There's not really any built-in testing solution for definitions, but DefinitelyTyped requires that all definitions have corresponding examples checking typings (usually taken straight from the documentation).

Is there any migration guide for JSdoc 2 to 3? Seems like a reasonable task to complete along with this one.

[lehni]

As we have added quite a few custom tags to JSDoc, the migration to JSDoc 3 might be rather complex. Some examples:

• @bean tag to mark getter / setter methods that produce accessors (e.g Item#getChildren()/ Item#setChildren() -> Item#children)
• @option tag to document option objects
• Support for constructors and methods that can be called with different signatures (internally treated as separated methods with the same name but different signatures)

I don't have the capacity currently to focus on this migration, and I don't think we need to create a sequential dilemma. It is easier to work with the current code base and translate the templates again once the switch to JSDoc 3 happens, whenever that is.

[HunterMitchell]

Honestly this would be extremely helpful, but like harangue, I also lack experience with PaperJS.

[chrisgervang]

It's 9 months old, but there exists a typing for paper.js here: https://github.com/clark-stevenson/paper.d.ts

[sqwk]

I have merged clark-stevenson's defintions into the DefinitelyTyped project a while ago (https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/paper). They can be installed using npm install @types/paper If anyone wants to help maintain the definitions, please open pull requests there.

[alexjlockwood]

@sqwk I noticed that there is a type missing (specifically the "selectedItems" property on Project). What is the fastest way to get this bug fixed?

[kareljan]

Wouldn't be easier if we had the types in the repo? DefinitelyTyped is nice. But it's easier to maintain the definition if you keep it in the project. So when you add a new feature you can add it immediately to the definition type. Otherwise you have to wait until the DT files are updated.

[lehni]

Having them in the repo means somebody needs to keep them up to date, and making sure they cover everything there is in the library. I personally don't have the time to do so, but if somebody volunteers and would keep it up to date, then we can add it to the repo, sure.

[sasensi]

I just made a PR #1612 that propose an automatic type definition generation that should resolve the problem of having an out of sync type definition when we change the API.

[Domvel]

Do I understand it correctly? The next version of paper.js will contain a built-in TypeScript d.ts file. So I do not have to install the always-obsolete and incomplete types from the separate @types repository anymore? https://www.npmjs.com/package/@types/paper If so, great! But is a release planned? Btw. I recommend to go to version 1.0.0. Because major 0 (zero) is more a unstable developer version. And I think paper.js isn't. Or what do you think?

[sasensi]

@Domvel, yes, the automatically generated definition will be placed in /dist/paper.d.ts. I don't think there is a new release planned soon (@lehni ?) and unfortunately, the prebuilt branch is temporarily deactivated so if you want to use this type definition before the release, you can build the library locally from the develop branch (see instructions in the readme file).

[lehni]

Version 0.12.1 is out now, coming with /dist/paper.d.ts. Please let us know how this is working for you!

[Domvel]

Thanks lehni and thanks sasensi for the types. It seems to work generally. The typed-file is detected and works for import. But a few definitions are missing. Here just a few examples from my project.

import * as paper from 'paper';

// Missing setup-method in global scope of paper namespace. also install-method.
paper.setup(canvas);
// Quick'n'Dirty Workaround
(paper as any).setup(canvas);

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/5344bfc80508c53a23dae37b860fb0c905ff7b24/types/paper/index.d.ts#L66

It works with setup() but maybe I should use it in another way? But setup() exists.

// Argument of Path is only a "object" not a interface with defined properties.
// It's ok, no problem, but a weak type. e.g. no autocompletion / suggestion in vs code :(
// Note: Not all properties are required. So they should be marked as optional typescript: `?`
const path = new paper.Path({
  strokeColor: '#ffff00',
  strokeWidth: 5,
  strokeCap: round
});

// Throws an error: Argument of type `number[]` is not assignable to parameter of type `Point | Segment`.
// But this is not true. It is possible to assign number[].
path.add([100, 200]);
// Quick'n'Dirty Workaround :(
(path as any).add([100, 200]);

https://github.com/DefinitelyTyped/DefinitelyTyped/blob/5344bfc80508c53a23dae37b860fb0c905ff7b24/types/paper/index.d.ts#L2418

That is interesting. The types/paper definition file also has only Segment | Point. But for sure number[] also works. I've tested it. The types/paper throws no error.

Reference: https://github.com/DefinitelyTyped/DefinitelyTyped/blob/5344bfc80508c53a23dae37b860fb0c905ff7b24/types/paper/index.d.ts

The latest (paper documentation)[http://paperjs.org/reference/global/] also has no setup-method. Don't know if the last documentation had it. I think it's just a missing declaration in the docs / comment. Update: Wait... there it is: http://paperjs.org/reference/paperscope/ But setup() also exists in global scope. 🤔 Is this maybe a predefined paperscope? It seems so, yes. This means setup and install is missing in the types.

[lehni]

@Domvel thanks for doing this research. Since this is a closed issue, could you create a fresh one about all the missing / incomplete definitions that you've encountered?