fix: be specific about returned backing array

interface.ts

@@ -21,7 +21,7 @@ export type TokenTypeEncoder = {
 
 export type MapSorter = (e1: (Token | Token[])[], e2: (Token | Token[])[]) => number
 
-export type QuickEncodeToken = (token: Token) => Uint8Array | undefined
+export type QuickEncodeToken = (token: Token) => Uint8Array<ArrayBuffer> | undefined
 
 export interface DecodeTokenizer {
   done(): boolean,

lib/bl.js

@@ -34,10 +34,10 @@ export class Bl {
     this.cursor = 0
     /** @type {number} */
     this.maxCursor = -1
-    /** @type {(Uint8Array|number[])[]} */
+    /** @type {(Uint8Array<ArrayBuffer>|number[])[]} */
     this.chunks = []
     // keep the first chunk around if we can to save allocations for future encodes
-    /** @type {Uint8Array|number[]|null} */
+    /** @type {Uint8Array<ArrayBuffer>|number[]|null} */
     this._initReuseChunk = null
   }
 
@@ -54,7 +54,7 @@ export class Bl {
   }
 
   /**
-   * @param {Uint8Array|number[]} bytes
+   * @param {Uint8Array<ArrayBuffer>|number[]} bytes
    */
   push (bytes) {
     let topChunk = this.chunks[this.chunks.length - 1]
@@ -96,7 +96,7 @@ export class Bl {
 
   /**
    * @param {boolean} [reset]
-   * @returns {Uint8Array}
+   * @returns {Uint8Array<ArrayBuffer>}
    */
   toBytes (reset = false) {
     let byts
@@ -128,15 +128,15 @@ export class Bl {
  */
 export class U8Bl {
   /**
-   * @param {Uint8Array} dest
+   * @param {Uint8Array<ArrayBuffer>} dest
    */
   constructor (dest) {
     this.dest = dest
     /** @type {number} */
     this.cursor = 0
     // chunks is for interface compatibility with Bl - encode.js checks chunks.length
     // as a sanity check for pre-calculated sizes. For U8Bl this is always [dest].
-    /** @type {Uint8Array[]} */
+    /** @type {Array<Uint8Array<ArrayBuffer>>} */
     this.chunks = [dest]
   }
 
@@ -157,7 +157,7 @@ export class U8Bl {
 
   /**
    * @param {boolean} [reset]
-   * @returns {Uint8Array}
+   * @returns {Uint8Array<ArrayBuffer>}
    */
   toBytes (reset = false) {
     const byts = this.dest.subarray(0, this.cursor)

lib/byte-utils.js

@@ -23,13 +23,28 @@ function isBuffer (buf) {
 
 /**
  * @param {Uint8Array|number[]} buf
- * @returns {Uint8Array}
+ * @returns {Uint8Array<ArrayBuffer>}
  */
 export function asU8A (buf) {
   if (!(buf instanceof Uint8Array)) {
     return Uint8Array.from(buf)
   }
-  return isBuffer(buf) ? new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength) : buf
+  const output = isBuffer(buf) ? new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength) : buf
+
+  if (isArrayBufferBacked(output)) {
+    return output
+  }
+
+  return output.slice()
+}
+
+/**
+ *
+ * @param {Uint8Array} arr
+ * @returns {arr is Uint8Array<ArrayBuffer>}
+ */
+function isArrayBufferBacked (arr) {
+  return arr.buffer instanceof ArrayBuffer
 }
 
 // Threshold for manual UTF-8 encoding vs native methods.
@@ -61,7 +76,7 @@ export const fromString = useBuffer
 /**
  * Buffer variant not fast enough for what we need
  * @param {number[]} arr
- * @returns {Uint8Array}
+ * @returns {Uint8Array<ArrayBuffer>}
  */
 export const fromArray = (arr) => {
   return Uint8Array.from(arr)
@@ -96,7 +111,7 @@ export const concat = useBuffer
     /**
      * @param {Uint8Array[]} chunks
      * @param {number} length
-     * @returns {Uint8Array}
+     * @returns {Uint8Array<ArrayBuffer>}
      */
     (chunks, length) => {
       // might get a stray plain Array here
@@ -112,7 +127,7 @@ export const concat = useBuffer
     /**
      * @param {Uint8Array[]} chunks
      * @param {number} length
-     * @returns {Uint8Array}
+     * @returns {Uint8Array<ArrayBuffer>}
      */
     (chunks, length) => {
       const out = new Uint8Array(length)
@@ -132,7 +147,7 @@ export const alloc = useBuffer
   ? // eslint-disable-line operator-linebreak
     /**
      * @param {number} size
-     * @returns {Uint8Array}
+     * @returns {Uint8Array<ArrayBuffer>}
      */
     (size) => {
       // we always write over the contents we expose so this should be safe
@@ -142,7 +157,7 @@ export const alloc = useBuffer
   : // eslint-disable-line operator-linebreak
     /**
      * @param {number} size
-     * @returns {Uint8Array}
+     * @returns {Uint8Array<ArrayBuffer>}
      */
     (size) => {
       return new Uint8Array(size)
@@ -177,8 +192,8 @@ export const toHex = useBuffer
 export const fromHex = useBuffer
   ? // eslint-disable-line operator-linebreak
   /**
-   * @param {string|Uint8Array} hex
-   * @returns {Uint8Array}
+   * @param {string|Uint8Array<ArrayBuffer>} hex
+   * @returns {Uint8Array<ArrayBuffer>}
    */
     (hex) => {
       if (hex instanceof Uint8Array) {
@@ -189,8 +204,8 @@ export const fromHex = useBuffer
     }
   : // eslint-disable-line operator-linebreak
   /**
-   * @param {string|Uint8Array} hex
-   * @returns {Uint8Array}
+   * @param {string|Uint8Array<ArrayBuffer>} hex
+   * @returns {Uint8Array<ArrayBuffer>}
    */
     (hex) => {
       if (hex instanceof Uint8Array) {
@@ -206,8 +221,8 @@ export const fromHex = useBuffer
     }
 
 /**
- * @param {Uint8Array|ArrayBuffer|ArrayBufferView} obj
- * @returns {Uint8Array}
+ * @param {Uint8Array<ArrayBuffer>|ArrayBuffer|ArrayBufferView<ArrayBuffer>} obj
+ * @returns {Uint8Array<ArrayBuffer>}
  */
 function toBytes (obj) {
   if (obj instanceof Uint8Array && obj.constructor.name === 'Uint8Array') {

lib/encode.js

@@ -461,7 +461,7 @@ function rfc8949MapSorter (e1, e2) {
 
 /**
  * @param {any} data
- * @returns {Uint8Array}
+ * @returns {Uint8Array<ArrayBuffer>}
  */
 function encodeRfc8949 (data) {
   return encodeCustom(data, cborEncoders, rfc8949EncodeOptions)
@@ -620,8 +620,8 @@ function directEncode (writer, data, options, refStack) {
  * @param {any} data
  * @param {TokenTypeEncoder[]} encoders
  * @param {EncodeOptions} options
- * @param {Uint8Array} [destination]
- * @returns {Uint8Array}
+ * @param {Uint8Array<ArrayBuffer>} [destination]
+ * @returns {Uint8Array<ArrayBuffer>}
  */
 function encodeCustom (data, encoders, options, destination) {
   // arg ordering is different to encodeInto for backward compatibility
@@ -661,7 +661,7 @@ function encodeCustom (data, encoders, options, destination) {
 /**
  * @param {any} data
  * @param {EncodeOptions} [options]
- * @returns {Uint8Array}
+ * @returns {Uint8Array<ArrayBuffer>}
  */
 function encode (data, options) {
   options = Object.assign({}, defaultEncodeOptions, options)
@@ -678,7 +678,7 @@ function encode (data, options) {
 
 /**
  * @param {any} data
- * @param {Uint8Array} destination
+ * @param {Uint8Array<ArrayBuffer>} destination
  * @param {EncodeOptions} [options]
  * @returns {{ written: number }}
  */

lib/json/encode.js

@@ -291,7 +291,7 @@ const defaultEncodeOptions = { addBreakTokens: true, mapSorter }
 /**
  * @param {any} data
  * @param {EncodeOptions} [options]
- * @returns {Uint8Array}
+ * @returns {Uint8Array<ArrayBuffer>}
  */
 function encode (data, options) {
   options = Object.assign({}, defaultEncodeOptions, options)

lib/jump.js

@@ -162,7 +162,7 @@ quick[0xf6] = new Token(Type.null, null, 1)
 
 /**
  * @param {Token} token
- * @returns {Uint8Array|undefined}
+ * @returns {Uint8Array<ArrayBuffer>|undefined}
  */
 export function quickEncodeToken (token) {
   switch (token.type) {

types/interface.d.ts

@@ -13,7 +13,7 @@ export type TokenTypeEncoder = {
     encodedSize?(token: Token, options?: EncodeOptions): number;
 };
 export type MapSorter = (e1: (Token | Token[])[], e2: (Token | Token[])[]) => number;
-export type QuickEncodeToken = (token: Token) => Uint8Array | undefined;
+export type QuickEncodeToken = (token: Token) => Uint8Array<ArrayBuffer> | undefined;
 export interface DecodeTokenizer {
     done(): boolean;
     next(): Token;

types/lib/bl.d.ts

@@ -8,44 +8,44 @@ export class Bl {
     cursor: number;
     /** @type {number} */
     maxCursor: number;
-    /** @type {(Uint8Array|number[])[]} */
-    chunks: (Uint8Array | number[])[];
-    /** @type {Uint8Array|number[]|null} */
-    _initReuseChunk: Uint8Array | number[] | null;
+    /** @type {(Uint8Array<ArrayBuffer>|number[])[]} */
+    chunks: (Uint8Array<ArrayBuffer> | number[])[];
+    /** @type {Uint8Array<ArrayBuffer>|number[]|null} */
+    _initReuseChunk: Uint8Array<ArrayBuffer> | number[] | null;
     reset(): void;
     /**
-     * @param {Uint8Array|number[]} bytes
+     * @param {Uint8Array<ArrayBuffer>|number[]} bytes
      */
-    push(bytes: Uint8Array | number[]): void;
+    push(bytes: Uint8Array<ArrayBuffer> | number[]): void;
     /**
      * @param {boolean} [reset]
-     * @returns {Uint8Array}
+     * @returns {Uint8Array<ArrayBuffer>}
      */
-    toBytes(reset?: boolean): Uint8Array;
+    toBytes(reset?: boolean): Uint8Array<ArrayBuffer>;
 }
 /**
  * U8Bl is a buffer list that writes directly to a user-provided Uint8Array.
  * It provides the same interface as Bl but writes to a fixed destination.
  */
 export class U8Bl {
     /**
-     * @param {Uint8Array} dest
+     * @param {Uint8Array<ArrayBuffer>} dest
      */
-    constructor(dest: Uint8Array);
-    dest: Uint8Array<ArrayBufferLike>;
+    constructor(dest: Uint8Array<ArrayBuffer>);
+    dest: Uint8Array<ArrayBuffer>;
     /** @type {number} */
     cursor: number;
-    /** @type {Uint8Array[]} */
-    chunks: Uint8Array[];
+    /** @type {Array<Uint8Array<ArrayBuffer>>} */
+    chunks: Array<Uint8Array<ArrayBuffer>>;
     reset(): void;
     /**
      * @param {Uint8Array|number[]} bytes
      */
     push(bytes: Uint8Array | number[]): void;
     /**
      * @param {boolean} [reset]
-     * @returns {Uint8Array}
+     * @returns {Uint8Array<ArrayBuffer>}
      */
-    toBytes(reset?: boolean): Uint8Array;
+    toBytes(reset?: boolean): Uint8Array<ArrayBuffer>;
 }
 //# sourceMappingURL=bl.d.ts.map

types/lib/byte-utils.d.ts

@@ -1,8 +1,8 @@
 /**
  * @param {Uint8Array|number[]} buf
- * @returns {Uint8Array}
+ * @returns {Uint8Array<ArrayBuffer>}
  */
-export function asU8A(buf: Uint8Array | number[]): Uint8Array;
+export function asU8A(buf: Uint8Array | number[]): Uint8Array<ArrayBuffer>;
 /**
  * @param {Uint8Array} b1
  * @param {Uint8Array} b2
@@ -19,7 +19,7 @@ export const useBuffer: any;
  * @param {string} string
  */
 export function fromString(string: string): any;
-export function fromArray(arr: number[]): Uint8Array;
+export function fromArray(arr: number[]): Uint8Array<ArrayBuffer>;
 /**
  * @param {Uint8Array} bytes
  * @param {number} start
@@ -29,22 +29,22 @@ export function slice(bytes: Uint8Array, start: number, end: number): Uint8Array
 /**
  * @param {Uint8Array[]} chunks
  * @param {number} length
- * @returns {Uint8Array}
+ * @returns {Uint8Array<ArrayBuffer>}
  */
-export function concat(chunks: Uint8Array[], length: number): Uint8Array;
+export function concat(chunks: Uint8Array[], length: number): Uint8Array<ArrayBuffer>;
 /**
  * @param {number} size
- * @returns {Uint8Array}
+ * @returns {Uint8Array<ArrayBuffer>}
  */
-export function alloc(size: number): Uint8Array;
+export function alloc(size: number): Uint8Array<ArrayBuffer>;
 /**
  * @param {Uint8Array} d
  * @returns {string}
  */
 export function toHex(d: Uint8Array): string;
 /**
- * @param {string|Uint8Array} hex
- * @returns {Uint8Array}
+ * @param {string|Uint8Array<ArrayBuffer>} hex
+ * @returns {Uint8Array<ArrayBuffer>}
  */
-export function fromHex(hex: string | Uint8Array): Uint8Array;
+export function fromHex(hex: string | Uint8Array<ArrayBuffer>): Uint8Array<ArrayBuffer>;
 //# sourceMappingURL=byte-utils.d.ts.map