Node: [DOC] Buffer.from / new Buffer accept Uint8Array (missing)

[reviewher]

Both can accept a Uint8Array. Buffer.from explicitly checks for Uint8Array

It looks like a documentation omission. If so, I can send a PR.

[Trott]

@nodejs/documentation

[benjamingr]

@reviewher the docs already specify it takes a TypedArray - the fact that the implementation does a shortcut should not be an issue.

Was the unclear part the fact it's not obvious that a UInt8Array is a TypedArray?

[reviewher]

@benjamingr The documentation lists 4 signatures for Buffer.from:

• Buffer.from(array) -- Array of bytes
• Buffer.from(arrayBuffer[, byteOffset[, length]]) -- ArrayBuffer or the .buffer property of a TypedArray.
• Buffer.from(buffer) -- Buffer
• Buffer.from(string[, encoding]) -- string

None of those cases cover an actual Uint8Array object! We are not talking about "the .buffer property" but rather the actual Uint8Array object. An example would be useful:

> var x = new Uint8Array([1,2,3,4,5])
> x
Uint8Array [ 1, 2, 3, 4, 5 ]

> Buffer.from(x.buffer) // <-- this is from the docs
<Buffer 01 02 03 04 05>
> x.buffer instanceof ArrayBuffer // <-- x.buffer is an ArrayBuffer, not a typed array
true
> x.buffer instanceof Uint8Array // <-- x.buffer is definitely not a Uint8Array
false

> Buffer.from(x) // <-- this is the case that works and is not covered in the docs
<Buffer 01 02 03 04 05>
> Buffer.isBuffer(x) // <-- x is definitely not a buffer
false
> x instanceof ArrayBuffer // <-- x is definitely not an ArrayBuffer
false
> x instanceof Uint8Array // <-- x is definitely a Uint8Array
true

To contrast with other areas of the documentation:

• Buffer.compare explicitly states that both arguments can be Uint8Arrays
• Buffer.concat explicitly calls out Uint8Array
• Buffer#equals also calls out Uint8Array

@benjamingr it's also possible you took a cursory glance at https://nodejs.org/dist/latest-v8.x/docs/api/buffer.html#buffer_buffers_and_typedarray and assumed it was covered, but alas it is not. The ending of that section does discuss typed arrays, but it is merely contrasting the signatures of Buffer.from and TypedArray.from.

@Trott to be consistent with the other areas of the documentation, assuming that Buffer.from and the new Buffer constructor were intended to take Uint8Array, the simplest fix would add a few words the Buffer cases in new Buffer and Buffer.from in doc/api/buffer.md :

-* `buffer` {Buffer} An existing `Buffer` to copy data from
+* `buffer` {Buffer|Uint8Array} An existing `Buffer` or [`Uint8Array`] to copy data from

[apapirovski]

@nodejs/documentation This has been around for a while and looks like a valid bug report for the docs.

[reviewher]

This is a one-line change to /doc/api/buffer.md, included in my comment in this issue. I'll gladly send a PR, but @benjamingr seemed to have some concern that isn't obvious, and it may make sense to wait for a reply before making a doc change

[apapirovski]

@reviwher I think they had the same first look thought which is that it mentions TypedArray but of course on closer inspection it refers to the .buffer property. Much like you already highlighted above. I think if someone can come up with a sensible PR then this could get fixed quickly.