feat: typedCopyBytes

Author: ChALkeR

array.d.ts

@@ -47,16 +47,48 @@ export type Uint32ArrayBuffer = ReturnType<typeof Uint32Array.from>;
  */
 export type OutputFormat = 'uint8' | 'buffer';
 
+/**
+ * Output format for typed array copy conversions
+ */
+export type OutputCopyFormat = 'uint8' | 'arraybuffer' | 'buffer';
+
 /**
  * Create a view of a TypedArray in the specified format (`'uint8'` or `'buffer'`)
  *
  * > [!IMPORTANT]
  * > Does not copy data, returns a view on the same underlying buffer
  *
+ * > [!WARNING]
+ * > Viewing `Uint16Array` (or other with `BYTES_PER_ELEMENT > 1`) as bytes
+ * > is platform endianness-dependent.
+ *
  * @param arr - The input TypedArray
  * @param format - The desired output format (`'uint8'` or `'buffer'`)
  * @returns A view on the same underlying buffer
  */
 export function typedView(arr: ArrayBufferView, format: 'uint8'): Uint8Array;
 export function typedView(arr: ArrayBufferView, format: 'buffer'): Buffer;
 export function typedView(arr: ArrayBufferView, format: OutputFormat): Uint8Array | Buffer;
+
+/**
+ * Create a copy of TypedArray underlying bytes in the specified format (`'uint8'`, `'buffer'`, or `'arraybuffer'`)
+ *
+ * This does not copy _values_, but copies the underlying bytes.
+ * The result is similar to that of `typedView()`, but this function provides a copy, not a view of the same memory.
+ *
+ * > [!WARNING]
+ * > Copying underlying bytes from `Uint16Array` (or other with `BYTES_PER_ELEMENT > 1`)
+ * > is platform endianness-dependent.
+ *
+ * > [!NOTE]
+ * > Buffer might be pooled.
+ * > Uint8Array return values are not pooled and match their underlying ArrayBuffer.
+ *
+ * @param arr - The input TypedArray
+ * @param format - The desired output format (`'uint8'`, `'buffer'`, or `'arraybuffer'`)
+ * @returns A copy of the underlying buffer
+ */
+export function typedCopyBytes(arr: ArrayBufferView, format: 'uint8'): Uint8Array;
+export function typedCopyBytes(arr: ArrayBufferView, format: 'arraybuffer'): ArrayBuffer;
+export function typedCopyBytes(arr: ArrayBufferView, format: 'buffer'): Buffer;
+export function typedCopyBytes(arr: ArrayBufferView, format: OutputCopyFormat): Uint8Array | ArrayBuffer | Buffer;

array.js

@@ -15,3 +15,17 @@ export function typedView(arr, format) {
 
   throw new TypeError('Unexpected format')
 }
+
+export function typedCopyBytes(arr, format) {
+  assertTypedArray(arr)
+  switch (format) {
+    case 'uint8':
+      return Uint8Array.from(arr) // never pooled
+    case 'buffer':
+      return Buffer.from(arr)
+    case 'arraybuffer':
+      return Uint8Array.from(arr).buffer
+  }
+
+  throw new TypeError('Unexpected format')
+}

tests/array.test.js

@@ -1,4 +1,4 @@
-import { typedView } from '@exodus/bytes/array.js'
+import { typedView, typedCopyBytes } from '@exodus/bytes/array.js'
 import { describe, test } from 'node:test'
 
 const raw = [new Uint8Array(), new Uint8Array([0]), new Uint8Array([1]), new Uint8Array([255])]
@@ -40,3 +40,53 @@ describe('typedView', () => {
     }
   })
 })
+
+describe('typedCopyBytes', () => {
+  test('invalid input', (t) => {
+    for (const input of [null, undefined, [], [1, 2], 'string']) {
+      t.assert.throws(() => typedCopyBytes(input))
+      for (const form of ['uint8', 'buffer']) {
+        t.assert.throws(() => typedCopyBytes(input, form))
+      }
+    }
+  })
+
+  test('uint8', (t) => {
+    for (const { buffer, uint8 } of pool) {
+      for (const arg of [buffer, uint8]) {
+        const a = typedCopyBytes(arg, 'uint8')
+        t.assert.deepStrictEqual(a, uint8)
+        t.assert.notEqual(a, arg)
+        t.assert.strictEqual(a.byteLength, arg.byteLength)
+        // Non-pooled
+        t.assert.notEqual(a.buffer, arg.buffer)
+        t.assert.strictEqual(a.byteLength, a.buffer.byteLength)
+      }
+    }
+  })
+
+  test('arraybuffer', (t) => {
+    for (const { buffer, uint8 } of pool) {
+      for (const arg of [buffer, uint8]) {
+        const a = typedCopyBytes(arg, 'arraybuffer')
+        t.assert.deepStrictEqual(a, Uint8Array.from(arg).buffer)
+        t.assert.notEqual(a, arg)
+        t.assert.strictEqual(a.byteLength, arg.byteLength)
+        t.assert.notEqual(a, arg.buffer)
+      }
+    }
+  })
+
+  test('buffer', (t) => {
+    for (const { uint8, buffer } of pool) {
+      for (const arg of [buffer, uint8]) {
+        const a = typedCopyBytes(arg, 'buffer')
+        t.assert.deepStrictEqual(a, buffer)
+        t.assert.notEqual(a, arg)
+        t.assert.strictEqual(a.byteLength, arg.byteLength)
+        // Might be pooled
+        t.assert.ok(a.buffer !== arg.buffer || a.byteOffset !== arg.byteOffset)
+      }
+    }
+  })
+})