From 51071db17468ba63f9a2d2f3e03f5696d4aa5bfb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Linus=20Unneb=C3=A4ck?= Date: Thu, 31 May 2018 10:33:38 +0100 Subject: [PATCH 1/3] Put Buffer polyfills in a list Per discussion here: https://github.com/nodejs/nodejs.org/pull/1666/files#r191602869 The idea is to give a more equal view of all the options. Removed the drawback about the number of dependencies of `buffer-from` and `buffer-alloc` since those 4 dependencies are smaller than the 1 `safer-buffer`. --- .../guides/buffer-constructor-deprecation.md | 51 +++++++++++-------- 1 file changed, 30 insertions(+), 21 deletions(-) diff --git a/locale/en/docs/guides/buffer-constructor-deprecation.md b/locale/en/docs/guides/buffer-constructor-deprecation.md index 971a70cf764c2..f29fc97e73d03 100644 --- a/locale/en/docs/guides/buffer-constructor-deprecation.md +++ b/locale/en/docs/guides/buffer-constructor-deprecation.md @@ -87,27 +87,36 @@ your users will not observe a runtime deprecation warning when running your code ## Variant 2: Use a polyfill -Utilize [safer-buffer](https://www.npmjs.com/package/safer-buffer) as a polyfill to support older -Node.js versions. - -You would take exactly the same steps as in [Variant 1](#variant-1), but with a polyfill -`const Buffer = require('safer-buffer').Buffer` in all files where you use the new `Buffer` API. - -Make sure that you do not use old `new Buffer` API — in any files where the line above is added, -using old `new Buffer()` API will _throw_. It will be easy to notice that in CI, though. - -Alternatively, you could use [buffer-from](https://www.npmjs.com/package/buffer-from) and/or -[buffer-alloc](https://www.npmjs.com/package/buffer-alloc) [ponyfills](https://ponyfill.com/) — -those are great, the only downsides being 4 additional dependencies and slightly more code changes to -migrate off them (as you would be using e.g. `Buffer.from` under a different name). If you need only -`Buffer.from` polyfilled — `buffer-from` alone which comes with no extra dependencies. - -_Alternatively, you could use [safe-buffer](https://www.npmjs.com/package/safe-buffer) — it also -provides a polyfill, but takes a different approach which has -[its drawbacks](https://github.com/chalker/safer-buffer#why-not-safe-buffer). It will allow you -to also use the older `new Buffer()` API in your code, though — but that's arguably a benefit, as -it is problematic, can cause issues in your code, and will start emitting runtime deprecation -warnings starting with Node.js 10._ +There are three different polyfills available: + +- **[safer-buffer](https://www.npmjs.com/package/safer-buffer)** is a drop-in replacement for the + entire `Buffer` API, that will _throw_ when using `new Buffer()`. + + You would take exactly the same steps as in [Variant 1](#variant-1), but with a polyfill + `const Buffer = require('safer-buffer').Buffer` in all files where you use the new `Buffer` API. + + Make sure that you do not use old `new Buffer` API — in any files where the line above is added, + using old `new Buffer()` API will _throw_. It will be easy to notice that in CI, though. + +- **[buffer-from](https://www.npmjs.com/package/buffer-from) and/or + [buffer-alloc](https://www.npmjs.com/package/buffer-alloc)** are + [ponyfills](https://ponyfill.com/) for their respective part of the `Buffer` API. You only need + to add the package(s) corresponding to the API you are using. + + You would import the module needed with an appropriate name, e.g. + `const bufferFrom = require('buffer-from')` and then use that instead of the call to + `new Buffer`, e.g. `new Buffer('test')` becomes `bufferFrom('test')`. + + A downside with this approach is slightly more code changes to migrate off them (as you would be + using e.g. `Buffer.from` under a different name). + +- **[safe-buffer](https://www.npmjs.com/package/safe-buffer)** is also a drop in replacement for + the entire `Buffer` API, but using `new Buffer()` will still work as before. + + A downside to this approach is that it will allow you to also use the older `new Buffer()` API + in your code, which is problematic since it can cause issues in your code, and will start + emitting runtime deprecation warnings starting with Node.js 10 + ([read more here](https://github.com/chalker/safer-buffer#why-not-safe-buffer)). Note that in either case, it is important that you also remove all calls to the old Buffer API manually — just throwing in `safe-buffer` doesn't fix the problem by itself, it just provides From d12a50ba080229ca144d051e8d3b5ad7f06c21fa Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 1 Jun 2018 15:17:57 +0200 Subject: [PATCH 2/3] Update buffer-constructor-deprecation.md --- locale/en/docs/guides/buffer-constructor-deprecation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/locale/en/docs/guides/buffer-constructor-deprecation.md b/locale/en/docs/guides/buffer-constructor-deprecation.md index f29fc97e73d03..d39d1ca23f1cf 100644 --- a/locale/en/docs/guides/buffer-constructor-deprecation.md +++ b/locale/en/docs/guides/buffer-constructor-deprecation.md @@ -110,7 +110,7 @@ There are three different polyfills available: A downside with this approach is slightly more code changes to migrate off them (as you would be using e.g. `Buffer.from` under a different name). -- **[safe-buffer](https://www.npmjs.com/package/safe-buffer)** is also a drop in replacement for +- **[safe-buffer](https://www.npmjs.com/package/safe-buffer)** is also a drop-in replacement for the entire `Buffer` API, but using `new Buffer()` will still work as before. A downside to this approach is that it will allow you to also use the older `new Buffer()` API From 459a16964647f4785a1bdce957c75bbc982de0cd Mon Sep 17 00:00:00 2001 From: Rich Trott Date: Fri, 1 Jun 2018 15:20:36 +0200 Subject: [PATCH 3/3] Update buffer-constructor-deprecation.md --- locale/en/docs/guides/buffer-constructor-deprecation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/locale/en/docs/guides/buffer-constructor-deprecation.md b/locale/en/docs/guides/buffer-constructor-deprecation.md index d39d1ca23f1cf..540c1dc9825ea 100644 --- a/locale/en/docs/guides/buffer-constructor-deprecation.md +++ b/locale/en/docs/guides/buffer-constructor-deprecation.md @@ -95,8 +95,8 @@ There are three different polyfills available: You would take exactly the same steps as in [Variant 1](#variant-1), but with a polyfill `const Buffer = require('safer-buffer').Buffer` in all files where you use the new `Buffer` API. - Make sure that you do not use old `new Buffer` API — in any files where the line above is added, - using old `new Buffer()` API will _throw_. It will be easy to notice that in CI, though. + Do not use the old `new Buffer` API. In any files where the line above is added, + using old `new Buffer()` API will _throw_. - **[buffer-from](https://www.npmjs.com/package/buffer-from) and/or [buffer-alloc](https://www.npmjs.com/package/buffer-alloc)** are