Skip to content

node: API docs never mention NodeBuffer, remove the definition#25500

Merged
2 commits merged intoDefinitelyTyped:masterfrom
thw0rted:node-remove-nodebuffer
May 4, 2018
Merged

node: API docs never mention NodeBuffer, remove the definition#25500
2 commits merged intoDefinitelyTyped:masterfrom
thw0rted:node-remove-nodebuffer

Conversation

@thw0rted
Copy link
Copy Markdown
Contributor

@thw0rted thw0rted commented May 3, 2018

Please fill in this template.

  • Use a meaningful title for the pull request. Include the name of the package modified.
  • Test the change in your own code. (Compile and run.)
  • Add or edit tests to reflect the change. (Run with npm test.)
  • Follow the advice from the readme.
  • Avoid common mistakes.
  • Run npm run lint package-name (or tsc if no tslint.json is present).

If changing an existing definition:

  • Provide a URL to documentation or source code which provides context for the suggested changes:
  • Increase the version number in the header if appropriate. N/A
  • If you are making substantial changes, consider adding a tslint.json containing { "extends": "dtslint/dt.json" }. N/A

I asked in #25327 if any maintainers thought this was appropriate and didn't hear back, so I'm putting in a PR. If this interface is actually needed, feel free to close it out.

@typescript-bot typescript-bot added Popular package This PR affects a popular package (as counted by NPM download counts). The Travis CI build failed labels May 3, 2018
@typescript-bot
Copy link
Copy Markdown
Contributor

typescript-bot commented May 3, 2018

@thw0rted Thank you for submitting this PR!

🔔 @midknight41 @jasonswearingen @HiromiShikata @geoffreak @CodeAnimal @swook @Wind-rider @shantanubhadoria @LukeL99 @bioball @keton @thegecko @parambirs @tellnes @WilcoBakker @octo-sniffle @smac89 @Flarna @mwiktorczyk @wwwy3y3 @DeividasBakanas @kjin @alvis @OliverJAsh @eps1lon @Hannes-Magnusson-CK @jkomyno @ajafff @hoo29 @n-e @soywiz @bonnici @Bartvds @joeskeen @ccurrens @lookfirst @mastermatt - please review this PR in the next few days. Be sure to explicitly select Approve or Request Changes in the GitHub UI so I know what's going on.

If no reviewer appears after a week, a DefinitelyTyped maintainer will review the PR instead.

@typescript-bot
Copy link
Copy Markdown
Contributor

typescript-bot commented May 3, 2018

@thw0rted The Travis CI build failed! Please review the logs for more information.

Once you've pushed the fixes, the build will automatically re-run. Thanks!

@Flarna
Copy link
Copy Markdown
Contributor

Flarna commented May 3, 2018

@thw0rted I can remember that I started typing a response to your question in #25327 but it seems I haven't finished or it got lost by some other reason...

Anyhow, I can't tell why this deprecated interface is there and I see also no use for it. It was already there when I started using them ~2 years ago. There are quite some other relics in the typings (search for // compat for TypeScript 1.8) where I can't tell if they are still needed.
I remember that I earned complains during adding class URLSearchParams which uses iterators - an ES6 feature - as there were users out there still using lib es5 as they had no need to change. Result was forward declarations in NodeJs typings.

Similar I fear that removing NodeBuffer causes issues in dependent modules (CI already showed some). If its not to hard to fix these issues it's maybe worth to give it a try.

@thw0rted
Copy link
Copy Markdown
Contributor Author

thw0rted commented May 3, 2018

This commit fixed the linter for the packages where things broke, so I think Travis will be happy. Of course, other consumers could be referencing the deprecated interface instead for some reason, so they'd break when updating their typings. Is there something I'm supposed to edit to flag this as a potential breaking change? (Hopefully it's not common to reference the typings for v9 / v10 while including an interface that's been deprecated since v0, but I've seen stranger things...)

@Flarna
Copy link
Copy Markdown
Contributor

Flarna commented May 3, 2018

@thw0rted I don't think there is some mechanism to avoid breaking other modules. Typings here have no semver versioning, they follow the versions of their source.
Changes look good for me but maybe the owners of the other modules should also take a look. Don't know if @typescript-bot notifies them as changes happend after PR creation.

@typescript-bot typescript-bot added Owner Approved A listed owner of this package signed off on the pull request. Merge:Express and removed Awaiting reviewer feedback labels May 3, 2018
@typescript-bot
Copy link
Copy Markdown
Contributor

A definition owner has approved this PR ⭐️. A maintainer will merge this PR shortly. If it shouldn't be merged yet, please leave a comment saying so and we'll wait. Thank you for your contribution to DefinitelyTyped!

@ghost ghost merged commit 430b5a7 into DefinitelyTyped:master May 4, 2018
@rogierschouten
Copy link
Copy Markdown
Contributor

How about you guys wait for 10.x instead removing stuff in a bugfix version?? The problem is that I have third-party typescript dependencies that in turn depend on something that uses NodeBuffer. So you guys just broke our builds for no good reason at all and I have to rely on third parties to fix it properly. At least if you did it in 10.x then we'd have a PLANNED moment to fix breaking changes

@Flarna
Copy link
Copy Markdown
Contributor

Flarna commented May 8, 2018

@rogierschouten Sorry for that.
Unfortunately there is no semver versioning of typings only. They go hand in hand with the underlying module. Additionally most modules (at least in this repo) refer to node typings via version "*" so they automatically jump to latest major version anyway.
There is also no backlog/todo list like "changes we should do on next major version change" to do this in an atomic way next time.

I think there are two options here:

  • Revert the change in NodeJS < 10 (not sure if this really helps in your case)
  • You could try to refer to a specific @types/node version in your project which could override your dependents if they use something like "*".

Just for interest: Which module is still using NodeBuffer?

@thw0rted
Copy link
Copy Markdown
Contributor Author

thw0rted commented May 8, 2018

I always kind of wondered how people kept DT updates from breaking stuff since the versions link to the library being described, rather than a semver scheme describing changes to the typings themselves. It looks like the answer is that updates just break stuff. Maybe they should do something about that, though I'm not sure npm has the vocabulary for it.

Anyway, sorry, @rogierschouten , but please be aware that I didn't submit this change in a vacuum. The type your great-grand-dependency referenced has been marked as deprecated for years (!) and should have been removed ages ago. I came across this because I was using jsweet, a Java to Typescript transpiler, and the fact that Buffer's members were all defined in a deprecated superclass caused that program to generate code where every reference to a Buffer member threw a warning. (This is because Java treats deprecated class members as deprecated themselves.)

I'm not sure how to best resolve this -- I've been using TS for about a year now but my understanding of the DT ecosystem is only so-so. If reverting v9 helps, fine, but I'm not sure I see the benefit since the type that was removed hasn't existed since at least v0 (!!!) and the deprecation warning has been in place for as far back as I can see. I mean, if the "problem" library didn't notice when they went from 7 to 8, or 8 to 9, why would they notice when going from 9 to 10?

Maybe the quick fix would be for your problem library to fix the version of @types/node it depends on to an earlier one? If I understand the npm docs properly, that should cause it to get its own copy of the earlier version while the rest of your code uses the updated typings. You could make the change locally in your own node_modules or submit a stopgap PR to the library in question.

@thw0rted thw0rted deleted the node-remove-nodebuffer branch May 8, 2018 08:12
@rogierschouten
Copy link
Copy Markdown
Contributor

Thank you for your responses guys. By now I got it fixed for my project with a PR and a fork here and there.

All I'm saying is that you can delay breaking changes until a major version change happens. Then, people expect them. They will notice when going from 9 to 10 similarly to how I noticed going from 9.6.11 to 9.6.12: the build breaks. But then it's a planned interruption, that's all. Other than that, third-party software will be in constant motion. But let's stick with semver as much as we can, especially for cosmetic changes like this

@jasonswearingen
Copy link
Copy Markdown
Contributor

jasonswearingen commented May 8, 2018 via email

@ghost
Copy link
Copy Markdown

ghost commented May 8, 2018

@types/hapi is in this repo and doesn't seem to be using NodeBuffer in its latest version.

@jasonswearingen
Copy link
Copy Markdown
Contributor

jasonswearingen commented May 9, 2018 via email

KSXGitHub pushed a commit to KSXGitHub/DefinitelyTyped that referenced this pull request May 12, 2018
…itelyTyped#25500)

* node: API docs never mention NodeBuffer, remove the definition

* Remove references to NodeBuffer from outdated packages
This pull request was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Owner Approved A listed owner of this package signed off on the pull request. Popular package This PR affects a popular package (as counted by NPM download counts).

Projects

None yet

Development

Successfully merging this pull request may close these issues.

6 participants