Init

.editorconfig

@@ -0,0 +1,12 @@
+root = true
+
+[*]
+indent_style = tab
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.yml]
+indent_style = space
+indent_size = 2

.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

.github/workflows/main.yml

@@ -0,0 +1,21 @@
+name: CI
+on:
+  - push
+  - pull_request
+jobs:
+  test:
+    name: Node.js ${{ matrix.node-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        node-version:
+          - 20
+          - 18
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+      - run: npm install
+      - run: npm test

.gitignore

@@ -0,0 +1,2 @@
+node_modules
+yarn.lock

.npmrc

@@ -0,0 +1 @@
+package-lock=false

index.d.ts

@@ -0,0 +1,88 @@
+/**
+Check if the given value is an instance of `Uint8Array`.
+
+@example
+````
+import {isUint8Array} from 'uint8array-extras';
+
+console.log(isUint8Array(new Uint8Array()));
+//=> true
+
+console.log(isUint8Array(new ArrayBuffer(10)));
+//=> false
+````
+*/
+export function isUint8Array(value: unknown): value is Uint8Array;
+
+/**
+Throw a `TypeError` if the given value is not an instance of `Uint8Array`.
+
+@example
+````
+import {assertUint8Array} from 'uint8array-extras';
+
+try {
+	assertUint8Array(new ArrayBuffer(10)); // Throws a TypeError
+} catch (error) {
+	console.error(error.message);
+}
+````
+*/
+export function assertUint8Array(value: unknown): asserts Uint8Array;
+
+/**
+Concatenate the given arrays into a new array.
+
+If `arrays` is empty, it will return a zero-sized `Uint8Array`.
+
+If `totalLength` is not specified, it is calculated from summing the lengths of the given arrays.
+
+@example
+````
+import {concatUint8Arrays} from 'uint8array-extras';
+
+const a = new Uint8Array([1, 2, 3]);
+const b = new Uint8Array([4, 5, 6]);
+
+console.log(concatUint8Arrays([a, b]));
+//=> Uint8Array [1, 2, 3, 4, 5, 6]
+````
+*/
+export function concatUint8Arrays(arrays: Uint8Array[], totalLength?: number): Uint8Array;
+
+/**
+Check if two arrays are identical by verifying that they contain the same bytes in the same sequence.
+
+@example
+```
+import {areUint8ArraysEqual} from 'uint8array-extras';
+
+const a = new Uint8Array([1, 2, 3]);
+const b = new Uint8Array([1, 2, 3]);
+const c = new Uint8Array([4, 5, 6]);
+
+console.log(areUint8ArraysEqual(a, b));
+//=> true
+
+console.log(areUint8ArraysEqual(a, c));
+//=> false
+```
+*/
+export function areUint8ArraysEqual(a: Uint8Array, b: Uint8Array): boolean;
+
+/**
+Compare two arrays and indicate their relative order or equality. Useful for sorting.
+
+@example
+```
+import {compareUint8Arrays} from 'uint8array-extras';
+
+const array1 = new Uint8Array([1, 2, 3]);
+const array2 = new Uint8Array([4, 5, 6]);
+const array3 = new Uint8Array([7, 8, 9]);
+
+[array3, array1, array2].sort(compareUint8Arrays);
+//=> [1, 2, 3], [4, 5, 6], [7, 8, 9]
+```
+*/
+export function compareUint8Arrays(a: Uint8Array, b: Uint8Array): 0 | 1 | -1;

index.js

@@ -0,0 +1,81 @@
+const objectToString = Object.prototype.toString;
+
+export function isUint8Array(value) {
+	return value && objectToString.call(value) === '[object Uint8Array]';
+}
+
+export function assertUint8Array(value) {
+	if (!isUint8Array(value)) {
+		throw new TypeError(`Expected \`Uint8Array\`, got \`${typeof value}\``);
+	}
+}
+
+export function concatUint8Arrays(arrays, totalLength) {
+	if (arrays.length === 0) {
+		return new Uint8Array(0);
+	}
+
+	totalLength ??= arrays.reduce((accumulator, currentValue) => accumulator + currentValue.length, 0);
+
+	const returnValue = new Uint8Array(totalLength);
+
+	let offset = 0;
+	for (const array of arrays) {
+		assertUint8Array(array);
+		returnValue.set(array, offset);
+		offset += array.length;
+	}
+
+	return returnValue;
+}
+
+export function areUint8ArraysEqual(a, b) {
+	assertUint8Array(a);
+	assertUint8Array(b);
+
+	if (a === b) {
+		return true;
+	}
+
+	if (a.length !== b.length) {
+		return false;
+	}
+
+	// eslint-disable-next-line unicorn/no-for-loop
+	for (let index = 0; index < a.length; index++) {
+		if (a[index] !== b[index]) {
+			return false;
+		}
+	}
+
+	return true;
+}
+
+export function compareUint8Arrays(a, b) {
+	assertUint8Array(a);
+	assertUint8Array(b);
+
+	const length = Math.min(a.length, b.length);
+
+	for (let index = 0; index < length; index++) {
+		if (a[index] < b[index]) {
+			return -1;
+		}
+
+		if (a[index] > b[index]) {
+			return 1;
+		}
+	}
+
+	// At this point, all the compared elements are equal.
+	// The shorter array should come first if the arrays are of different lengths.
+	if (a.length > b.length) {
+		return 1;
+	}
+
+	if (a.length < b.length) {
+		return -1;
+	}
+
+	return 0;
+}

license

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package.json

@@ -0,0 +1,46 @@
+{
+	"name": "uint8array-extras",
+	"version": "0.0.0",
+	"description": "Useful utilities for working with Uint8Array (and Buffer)",
+	"license": "MIT",
+	"repository": "sindresorhus/uint8array-extras",
+	"funding": "https://github.com/sponsors/sindresorhus",
+	"author": {
+		"name": "Sindre Sorhus",
+		"email": "sindresorhus@gmail.com",
+		"url": "https://sindresorhus.com"
+	},
+	"type": "module",
+	"exports": {
+		"types": "./index.d.ts",
+		"default": "./index.js"
+	},
+	"engines": {
+		"node": ">=18"
+	},
+	"sideEffects": false,
+	"scripts": {
+		"test": "xo && ava"
+	},
+	"files": [
+		"index.js",
+		"index.d.ts"
+	],
+	"keywords": [
+		"uint8array",
+		"uint8",
+		"typedarray",
+		"buffer",
+		"typedarray",
+		"arraybuffer",
+		"is",
+		"assert",
+		"concat",
+		"equals",
+		"compare"
+	],
+	"devDependencies": {
+		"ava": "^5.3.1",
+		"xo": "^0.56.0"
+	}
+}

readme.md

@@ -0,0 +1,53 @@
+# uint8array-extras
+
+> Useful utilities for working with [`Uint8Array`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) (and [`Buffer`](https://nodejs.org/api/buffer.html))
+
+This package tries to fill in the gaps when moving from Node.js `Buffer` to `Uint8Array`.
+
+Note that `Buffer` is a `Uint8Array` subclass, so you can use this package with `Buffer` too.
+
+This package is tree-shakeable.
+
+## Install
+
+```sh
+npm install uint8array-extras
+```
+
+## Usage
+
+```js
+import {concatUint8Arrays} from 'uint8array-extras';
+
+const a = new Uint8Array([1, 2, 3]);
+const b = new Uint8Array([4, 5, 6]);
+
+console.log(concatUint8Arrays([a, b]));
+//=> Uint8Array [1, 2, 3, 4, 5, 6]
+```
+
+## API
+
+### `isUint8Array(value: unknown): boolean`
+
+Check if the given value is an instance of `Uint8Array`.
+
+### `assertUint8Array(value: unknown)`
+
+Throw a `TypeError` if the given value is not an instance of `Uint8Array`.
+
+### `concatUint8Arrays(arrays: Uint8Array[], totalLength?: number): Uint8Array`
+
+Concatenate the given arrays into a new array.
+
+If `arrays` is empty, it will return a zero-sized `Uint8Array`.
+
+If `totalLength` is not specified, it is calculated from summing the lengths of the given arrays.
+
+### `areUint8ArraysEqual(a: Uint8Array, b: Uint8Array): boolean`
+
+Check if two arrays are identical by verifying that they contain the same bytes in the same sequence.
+
+### `compareUint8Arrays(a: Uint8Array, b: Uint8Array): 0 | 1 | -1`
+
+Compare two arrays and indicate their relative order or equality. Useful for sorting.