Buffer.prototype.slice is incompatible with Uint8Array.prototype.slice; it's documented but tends to cause bugs

[gfx]

• Version: v12.4.0 (official binary)
• Platform: macOS 10.14.5 (Darwin Kernel Version 18.6.0)

The documentation says Buffer has an incompatibility with Uint8rray and I believe it is considered to a bug, or at least tends to cause bugs.

https://nodejs.org/api/buffer.html

Buffer instances are also Uint8Array instances. However, there are subtle incompatibilities with TypedArray. For example, while ArrayBuffer#slice() creates a copy of the slice, the implementation of Buffer#slice() creates a view over the existing Buffer without copying, making Buffer#slice() far more efficient.

This incompatibility is problematic when a code expects Uint8Array as a parameter and it distinguishes the semantics of Uint8Array.prototype.slice() and Uint8Array.prototype.subarray().

Unfortunately, TypeScript can't help this problem because function f(b: Uint8Array) can take Buffer without notice:

// typtescript
const a: Uint8Array = Buffer.from([]); // OK because Buffer extends Uint8Array

const b: Int8Array = Buffer.from([]); // NG, of course

I think this incompatibility should be fixed in the long-term perspective, so firstly I propose to mark slice() as deprecated.

What do you think of it?

[BridgeAR]

The Node.js buffers existed before Uint8Array became part of ECMAScript. Changing this behavior now would be a significant breaking change and would likely cause a big disruption in the ecosystem. We could in theory introduce a new function that works like our current .slice() and add the deprecation notice but changing all occurrences is very hard (the buffer constructor is still used frequently even though it's deprecated since years and we made a huge effort to change it. This would probably be similar).

There is a simple work around that would work for both, Uint8Array and Buffer: Uint8Array.prototype.slice.call(buffer, begin, end).

Due to that possibility I do not think that we should change this.

[bnoordhuis]

firstly I propose to mark slice() as deprecated

Depends on what you mean by "deprecated".

As @BridgeAR mentions, it's used very extensively in the ecosystem so deprecating it as in "printing warnings" is probably out of the question.

Some kind of documentation-only "soft deprecation" in the sense of "don't use this, use that" might be acceptable.

You could start by adding a note to doc/api/buffer.md that explains how and why Buffer#slice() is different from TypedArray#slice(). That seems like a useful addition regardless of the outcome of this discussion.

[gfx]

As you said, deprecating methods is difficult but compatibility with Uint8Array is worth considering in the long-term perspective.

Fortunately, I think, it is easier than deprecating new Buffer because Buffer#subarray() is the same as the current slice() and compatible with Uint8Array, although subarray() is not documented.

[bnoordhuis]

Closing now that #28101 has been merged.