New principle: vend byte arrays as Uint8Arrays (#480)

* New principle: vend byte arrays as Uint8Arrays * Update index.bs Co-authored-by: Martin Thomson <[email protected]> * Apply suggestions from code review Co-authored-by: Martin Thomson <[email protected]> --------- Co-authored-by: Martin Thomson <[email protected]>
w3ctag · Apr 3, 2024 · ff46d8f · ff46d8f
1 parent 12d02ab
commit ff46d8f
Showing 1 changed file with 13 additions and 0 deletions.
diff --git a/index.bs b/index.bs
@@ -1856,6 +1856,19 @@ as the [Promise integration](https://github.com/WebAssembly/js-promise-integrati
 is still under development as of today.
 </div>
 
+<h3 id="uint8array">Output an array of bytes with Uint8Array</h3>
+
+If an API returns a byte array, make it a {{Uint8Array}}, not an {{ArrayBuffer}}.
+
+`ArrayBuffer`s cannot be read from directly;
+the developer would have to create a view such as a Uint8Array
+to read data.
+Providing a `Uint8Array` avoids that additional effort.
+
+If the bytes in the buffer have a natural intepretation
+as one of the other TypedArray types, provide that instead.
+For example, if the bytes represent Float32 values, use a {{Float32Array}}.
+
 <h2 id="event-design">Event Design</h2>
 
 <h3 id="one-time-events">Use promises for one time events</h3>