doc: add documentation for buffer.byteOffset

Also document a common issue when casting a Buffer object to a
TypedArray object.

Fixes: https://github.com/nodejs/node/issues/19301

PR-URL: https://github.com/nodejs/node/pull/21718
Reviewed-By: Vse Mozhet Byt <vsemozhetbyt@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Reviewed-By: Trivikram Kamat <trivikr.dev@gmail.com>

1 files changed, 25 insertions, 0 deletions

diff --git a/doc/api/buffer.md b/doc/api/buffer.md
index c219f00e4a..8e1d1c325b 100644
--- a/doc/api/buffer.md
+++ b/doc/api/buffer.md
@@ -992,6 +992,31 @@ console.log(buffer.buffer === arrayBuffer);
 // Prints: true
 ```
 
+### buf.byteOffset
+
+* {integer} The `byteOffset` on the underlying `ArrayBuffer` object based on
+  which this `Buffer` object is created.
+
+When setting `byteOffset` in `Buffer.from(ArrayBuffer, byteOffset, length)`
+or sometimes when allocating a buffer smaller than `Buffer.poolSize` the
+buffer doesn't start from a zero offset on the underlying `ArrayBuffer`.
+
+This can cause problems when accessing the underlying `ArrayBuffer` directly
+using `buf.buffer`, as the first bytes in this `ArrayBuffer` may be unrelated
+to the `buf` object itself.
+
+A common issue is when casting a `Buffer` object to a `TypedArray` object,
+in this case one needs to specify the `byteOffset` correctly:
+
+```js
+// Create a buffer smaller than `Buffer.poolSize`.
+const nodeBuffer = new Buffer.from([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]);
+
+// When casting the Node.js Buffer to an Int8 TypedArray remember to use the
+// byteOffset.
+new Int8Array(nodeBuffer.buffer, nodeBuffer.byteOffset, nodeBuffer.length);
+```
+
 ### buf.compare(target[, targetStart[, targetEnd[, sourceStart[, sourceEnd]]]])
 <!-- YAML
 added: v0.11.13