Document library with type definitions

[demurgos]

Hi, It would be great if this project bundled its Typescript type definitions to document its API. I am bringing this up because of the recent deprecation of gulp-util. This library is one of the recommended replacements and there are no types at the moment. By providing types directly, I hope to prevent duplicated effort in other codebases. It would be be an improvement in documentation and distribution by packaging the types next to the Javascript implementation.

• Let's start with the most obvious: it reduces friction when using this library in a Typescript project. It allows to have a single dependency on the library and get the right version of the code and types (without any mismatch issue).

• Keeping type definitions as close to the source as possible makes it easier to ensure that they are up to date. Even if they are only updated by external contributors, the library's repo is a natural place to at when they want to send improvements.

• Type definitions offer a more formal syntax to document the API. It nicely complement any manually-written documentation that may have some ambiguities. This allows to quickly pick new code by describing expectations and guarantees offered by the API.

• Publishing type definitions in the same package as the code is the recommend method. DefinitelyTyped is more of a fallback solution when there is nowhere else to put the definitions. Despite its bots, working with this huge repo is a pain because everything is tossed together. It also has some other more fundamental flaws such as not supporting namespaced packages or individual issues.

• Editors start to pull documentation for Javascript libraries from their type definitions

  Code completion and parameter info for the standard JavaScript objects and methods and Web APIs have improved, as these features are now powered by the TypeScript declaration files.

• Some other important Javascript libraries are already documenting their own API with Typescript. These projects treat their hand-written type definitions as documentation that both humans and computers can understand. Here are some examples:

  • https://github.com/hiddentao/squel
  • https://github.com/chalk/chalk
  • https://github.com/vitaly-t/pg-promise
  • https://github.com/chaijs/assertion-error
  • https://github.com/ForbesLindesay/throat

[phated]

I prefer DefinitelyTyped

[demurgos]

Hi, I wrote type definitions for gulp-util previously and I am currently extracting and updating the parts relevant to plugin-error. I would really prefer to send the PR to this repo. Even if I already listed most of my arguments above, I would like to emphasis that DefinitelyTyped offers a very subpar experience to simply having the types with the repo, both from a user and maintainer point of view. Gulp plays really well with various transpilers and has good support for Typescript through ts-node, it would be nice to extend this good experience to core plugins.

I really admire all the work you put into Gulp and am very grateful. Still, could you explain your reason? I guess that it's simply that it feels as "yet another thing to maintain"? If so, I'd just note that this library is stable, there were no changes in 2 years so it should be enough to write the types once and then there's no risk of major API/types changes. Even if I personally like Typescript, I wouldn't push it on larger components such as gulp or vinyl because of the maintenance burden, but when an occasion arises to add types progressively to smaller components it may be a good thing to try it.

Following the gulp-util deprecation/gulp4-alpha.3 release, I am opening and fixing many gulp plugins. They often have some transitive dependencies that also need to be updated and each of them has their own repos/maintainers/code styles/tests so it's a very time-consuming task. This is good from a stability point of view, but having to additionally deal with DefintelyTyped just feels like some unneeded complications if you view types as documentation. It's "yet another thing to update" when there are already dozens of plugins to patch.

Could I at least send a PR?

[phated]

Sure :) sorry, on my phone right now.

[phated]

Also, thank you for all your help. It's very appreciated.