With r126 TypeScript type declaration files are located at DefinitelyTyped

Discussion
#1

With the next release r126 TypeScript type declaration files will be moved from the official repository to DefinitelyTyped.

What does that mean for me?

If you are developing with JavaScript, this change has no effect on you. If you are developing with TypeScript, you have to perform a migration task to restore language support in your project.

Migrating

You have to install the following npm package to restore the typings:

Motivation

The motivation behind this change is explained in the respective PR at GitHub. The relevant part is:

TypeScript definitions were originally maintained in DefinitelyTyped but 2 years ago we decided to include them in the repo hoping that it would ensue they would be in sync.

The side effect of that decision was a considerable increase on maintenance burden and made things harder for new contributors too. For the sake of continuity of the project I think it’s best to move them back to DefinitelyTyped (or any other repo interested in maintaining them).

During the 2 years that these files were in the repo I think we did a good job at bringing them in sync but it’s time to delegate the maintenance.

6 Likes
#2
#3

Sad about this, but I understand the reasoning behind it.

Does @types/three have a versioning system? Let’s say the latest version of Three is r130, but if I install three@0.126, will there be a DefinitelyTyped definition version that’s targeted to work with r126?

Edit: I just realized versioning does work. For example, this old version targets Three r93.

1 Like
#4

I’d just like to add, in the interest of accessibility for people, myself & @Methuselah96 understand how daunting the DefiniteltyTyped repo can be. So we’ve ported the whole thing down to a new repository three-ts-types. It will still be hosted under @types namespace as it will still be on DefinitelyTyped but we hope that this will enable us to track three's fast-paced development style and react to issues quickly and involve the wider community.

3 Likes
#5

So we’ve ported the whole thing down to a new repository three-ts-types .

Love it – is there a reason you didn’t put the types in the three.js Github group? I guess three.js isn’t in that group either, though, so maybe it’s not as official as I think it is…

1 Like
#6

There’s that, but tbh we have more autonomy and we want to do some GitHub bot stuff to automate the transition between the repo & DT. We felt if it’s all in own repo, it’s a bit easier for us to manage.

2 Likes
#7

We felt if it’s all in own repo, it’s a bit easier for us to manage.

I didn’t mean that the types wouldn’t still be in their own repo or that you wouldn’t have full control over the repo to add bots and CI. My impression was that the “threejs” Github group was intended to be for official / semi-official three.js-related packages to be maintained by the community (such as the three.js dev tools) and would just place the types under a common three.js umbrella so they’re more easily found. Though tbh I’m not sure if there’s any real plan for the threejs Github group at this point. I was hoping to see it be used more but it doesn’t seem to have really been adopted by the project.

#8

That’s a great idea! One of the reasons I’m not a huge fan of DT is that it’s so enormous that it has 3,599 open issues which is very cumbersome. But with its own unique repo, the issues would be much easier to navigate.

#9

Why don’t you just convert three.js to TypeScript instead?

Just put your repo on pause (temporary interaction limits) for one month or two and make the switch to a better language?

2 Likes
#10

This was already discussed at GitHub:

1 Like
#11

I support this decision and hope THREE is getting better and better!

4 Likes
#12

What if, (and I haven’t read the history here) there was a way that there wouldn’t be the disconnect and the possible API problems associated with separation and didn’t have the burden of maintenance.
Could it be possible to tighten up the jsdoc API comments (a good thing in itself) and add to the build a tsc emit declarations only step?

#13

This was considered but the consensus is not add JSDoc to the code. Documentation and source code are decoupled in three.js.

#14

Without challenging previously made decisions, could the jsdoc comments be just enough for type information? I’m just thinking that it might be overall less work and less error prone for type information to be coupled.

#15

Sorry, but it’s a bit tiring to copy/paste discussions from GitHub. I suggest you read the existing threads and the respective conclusions. E.g.

#16

Well, I wasn’t trying to challenge previous conclusions, sorry if there was overlap to what I was brainstorming and previous conversations about jsdoc.
My thoughts are only around the current topic - is it possible to alleviate the concerns people have about type definitions getting out of sync with the code, at the same time as keeping the maintenance burden to a minimum.

#17

Why though switch to js doc if everything was already typed with TS?

#18

I perceive it as slightly less maintenance to require APIs to have JSDocs than to have hand-made parallel type definitions. I’d be interested in hearing alternate viewpoints on that. I’m not a maintainer or a contributor, so I am merely guessing that was what Mugen meant by maintenance burden when it comes to new contributors. To me as a user of THREE I rely on intellisense being accurate, which is dependent on the type definitions being up-to-date.
Mugen pointed out that there was already a decision not to go with JSDocs for documentation, but I was thinking less about documentation and more about type checking / d.ts generation.

It sounds to me that there was an important reason for the change two years ago to get away from DefinitelyTyped, and there are important reasons for the reversion in r126. I’d love to see a solution that’s the best of both worlds. Additionally, as a user, I’d like to claim that the user experience is more important than new-contributor friction.

#19

And sorry for more guess-work, but I’m also imagining that the mentioned new-contributor friction is a little less about the amount of work to make a change and more to do with how easy it is to make a mistake with parallel type definitions (even though this work must be done at some point regardless, DefinitelyTyped isn’t automatic.) With ESLint you can require jsdoc comments for all methods, and require that all parameters are listed. Add in a pre-commit step for npm and right there you’ve guaranteed that all commits at least mostly conform to correct and synchronized type definitions.

All this being said, a disclaimer that I don’t have any experience using typescript’s emit declarations from JS, I don’t know how well it works at all. :sweat_smile:

#20

We added type definitions to the repository in the hope that the burden on three.js maintainers would be manageable. Unfortunately, it was not. By moving the type definitions back outside the repository, we are removing that burden from the maintainers; contributors who use TypeScript are encouraged to contribute to the type definitions and keep them up to date.

JSDoc has been discussed at great length in multiple issues, and does not make a good substitute for TypeScript type definitions except as a starting point for generating type definitions that must later be maintained by hand.

2 Likes