Merge with Pixi.js

[bigtimebuddy]

Issue brought up in #58, moving forward, we should move the PIXI typings to the main pixi.js repo. That way the typings get locked to the distributed version of the library. Also, would ensure that when developers make PR against pixi.js that change the API, they would also need to make the corresponding API change in the typings. Thoughts?

[clark-stevenson]

Hey!

I would really appreciate guidance on this one from yourself and those of us here. I have almost no exposure to the mechanisms involved with typing's or anything else so I have very little opinion to offer.

@staff0rd @whizzkid @webbiesdk ?

[bigtimebuddy]

The mechanism is pretty simple in newer versions of TypeScript: basically you add a typings field in the package.json which is used when building with TypeScript to resolve all the module's types.

This could be achieved with a simple PR to Pixi.js. The tricky thing here is that we'd need to add typings for all the plugins into their respective plugins (e.g. pixi-spine, pixi-particles, etc). Would require a little coordinate, but could be ace at resolving versioning issues moving forward.

Anyways, I'm pro-TypeScript and would love to see it become a first-class workflow for Pixi.js developers.

[englercj]

If we are talking about the future of this repo, I vote for tool-generated typings instead of manually managed ones!

A start: https://github.com/englercj/tsd-jsdoc

[staff0rd]

Tool-generated typings (hopefully including comments) is a definite plus, however it should be a separate issue to this one (which it is).

Regarding repo-merging, specifically the plugin merges, to my knowledge this would only be possible via Typescript 2.0 (ie; definition augmentation?). If so, the question is should this issue then be put on hold until Typescript 2.0 is out of beta, and, are there any cases (backwards compatibility or otherwise) where users would not update to Typescript 2.0 thereby still requiring access to non-augmented type definitions?

[webbiesdk]

Don't know if this belongs here or in #70, but the discussion seems to be happening here, so I'm writing it here.

I don't think tool generated declaration files are the way to go.
Generated declarations are certainly cool, and can be used as a helpful tool when writing declaration files. (As an example, it could be used to generate a complete list of changes between two versions)
But JSDoc and TypeScript cannot handle every situation (although TypeScript seems to be trying hard lately), and sometimes things are best if handled slightly different in JSDoc and TypeScript.

(examples are from v.4).

TL;DR: JSDoc and TypeScript are not the same. Treat them as such.

First example, one-time use interfaces (look at the BitmapText constructor).
In JSDoc, if you have a function which takes an object with some fields. You normally write the documentation for the object directly in the documentation for the function.
But in TypeScript this is usually exported into a separate interface, because inline object-definitions look ugly in TypeScript.
If the documentation was generated by a tool, this tool would only generate a good looking declaration file if it knows to "export" the object into a separate interface, and knows what name to give the interface (where would that come from?).

Second example, the CONST module.
In the current declaration file, CONST is documented as a module inside the PIXI module.
But since the properties are actually all accessed directly on the PIXI module, the fields are duplicated in the PIXI module (using typeof to type the properties).

There are two alternatives to this:
1: Not have a CONST module, and only have the fields on the PIXI module.
This would work, but then the documentation would no longer contain a CONST module.

2: Actually use mixins.
But this requires that the PIXI object is an instance of an interface. In which case we would lose the pretty tree-structure of the current declaration file. Which makes the declaration file harder to navigate.

The current JSDoc documents it like the first alternative, and this is also the best way to document it using JSDoc.
And a tool converting JSDoc into TypeScript would therefore use the first alternative. Removing any choice.

Third example: TilingSprite.fromImage and TilingSprite.fromFrame (@clark-stevenson should know this one)
TypeScript likes to think that classes inherit static methods (which is the case in TypeScript, but not in all of JavaScript).
But when you have a class structure where this isn't the case (like in PIXI), this generates problems.

In this case the problem was solved in a really unclean way, but with a comment stating so, which means a reader of the declaration file shouldn't be confused as to what the actual meaning is.
And I think it is better to have a human make these choices.

Fourth example, look at PIXI.GroupD8
In the JavaScript file, most of the methods and fields are left undocumented.
Most likely because it would clutter up the .js file, it one had to write a detailed description for every single field.
And this is OK.
But if a tool was introduced, then in order to have any documentation of GroupD8, the JavaScript file would have to include detailed type descriptions of every field, which would only help the tool but not anyone else.

There are more examples (like the pixi (in lowercase) object), but this is long enough already.

These could most likely be fixed by some custom annotations in the JSDoc.
But then one would be writing documentation for the tool, and not for the human.

But this is not my repo, and in the end it is your decision.
I'm trying to say that using tool-generated declarations might make publishing new versions easier.
I just think that the end result would suffer.

[clark-stevenson]

Move Pixi to TypeScript would work.... lol 😛

I am moving at a Glacial pace on this front. Last couple of weeks, I have no build and no errors so progress is pretty much zero. Anyway aside from all of that, I have future concerns. Most of them are highlighted above. Interfaces are not real things, Dependencies can be a problem too. PIXI without EventEmitter sucks. Either dependencies would magically work, they would need to be maintained, or there might actually be 2 styles of JSDoc. (Everyone appears to use a different style/guideline for how to comment code) .

I really hate the primitive task of sitting on Github reviewing every PR tho. I was really enticed by #70

[clark-stevenson]

• TypeScript 2.0 was released yesterday. . Especially the part on Simplified Declaration File.
• Other various Q's on Hacker News

It is likely going to be the case that these definitions for v4 will be for TypeScript 2.0 only since I see no reason to wait around now that it is final.

Need to spend some time wrapping my head around all this but just thought I would share.

[paralin]

I'm happy to help with this, I just downloaded this repo to start working on v4 definitions, but if you guys have a better plan I'd love to help us get there asap (using Pixi in a project right now)

[webbiesdk]

The TypeScript 2 release is very interesting, but unfortunately it is not something this repository will necessarily gain from.
As i understand it, the @types package on npm pulls mainly from DefinitelyTyped, so people running npm install -s @types/pixi.js will get the version on DefinitelyTyped, and not the one from this repository.

So now there is a greater need for the DefinitelyTyped version of pixi.js.d.ts` to be updated (any volunteers for that merge?).

One solution is to include the declaration file with the main repository by using the typings field (as suggested further up). Then there is no need for developers to download the version of @types.
And I believe it doesn't require any modifications to the declaration file. As long as people loads one of the pre-build versions of PixiJS.

Another solution is to delete this repository, and move everything to the DefinitelyTyped project (you can have versioned declarations, like the hammerjs declaration has).
I'm guessing that is not an option.

The best solution would be to somehow get the @types package to point to this rep, but that seems impossible.

[paralin]

If you merge an official typescript definitions file into the pixi repo the definitely typed people will mark pixi as deprecated so users get a warning that they don't need it anymore. Also, users would automatically get the typescript definitions working when they updated pixi to the latest, which would produce warnings if they had the old @types installed.

Best approach remains merging this into pixi and/or rewriting pixi in typescript.

[webbiesdk]

We don't need to merge the TypeScript declaration into the pixi repo, some build-script could fetch the latest version from this repository, that way the two repositories could remain separate.

[paralin]

Makes no sense to do that, what's the advantage over just merging?

[webbiesdk]

This repository has a couple of branches, one for each major version of PixiJS.
If people are using an old version of PixiJS and want to get a declaration file for it, then they can get it here.
Moving the development of the declaration file into the main repo would somewhat remove that.

Keeping things in separate repositories also helps keeping the two things separate. Everything related to PixiJS and TypeScript is in this repository, while the main repo deals exclusively with JavaScript.

[andrewstart]

Moving all further Typescript definitions (keeping old versions here) into the main repo would have other benefits, like being able to easily develop a feature branch with its typings, and anyone that checks out that branch and symlinks it will get the full typings.