Add more methods

index.d.ts

@@ -2,33 +2,33 @@
 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;
+export function assertUint8Array(value: unknown): asserts value is Uint8Array;
 
 /**
 Concatenate the given arrays into a new array.
@@ -38,15 +38,15 @@ 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;
 
@@ -82,7 +82,89 @@ 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]
+//=> [[1, 2, 3], [4, 5, 6], [7, 8, 9]]
 ```
 */
 export function compareUint8Arrays(a: Uint8Array, b: Uint8Array): 0 | 1 | -1;
+
+/**
+Convert a `Uint8Array` (containing a UTF-8 string) to a string.
+
+@example
+```
+import {uint8ArrayToString} from 'uint8array-extras';
+
+const byteArray = new Uint8Array([72, 101, 108, 108, 111]);
+
+console.log(uint8ArrayToString(byteArray));
+//=> 'Hello'
+```
+*/
+export function uint8ArrayToString(array: Uint8Array): string;
+
+/**
+Convert a string to a `Uint8Array` (using UTF-8 encoding).
+
+@example
+```
+import {stringToUint8Array} from 'uint8array-extras';
+
+console.log(stringToUint8Array('Hello'));
+//=> Uint8Array [72, 101, 108, 108, 111]
+```
+*/
+export function stringToUint8Array(string: string): Uint8Array;
+
+/**
+Convert a `Uint8Array` to a Base64-encoded string.
+
+@example
+```
+import {uint8ArrayToBase64} from 'uint8array-extras';
+
+const byteArray = new Uint8Array([72, 101, 108, 108, 111]);
+
+console.log(uint8ArrayToBase64(byteArray));
+//=> 'SGVsbG8='
+```
+*/
+export function uint8ArrayToBase64(array: Uint8Array): string;
+
+/**
+Convert a Base64-encoded string to a `Uint8Array`.
+
+@example
+```
+import {base64ToUint8Array} from 'uint8array-extras';
+
+console.log(base64ToUint8Array('SGVsbG8='));
+//=> Uint8Array [72, 101, 108, 108, 111]
+```
+*/
+export function base64ToUint8Array(string: string): Uint8Array;
+
+/**
+Encode a string to Base64-encoded string.
+
+@example
+```
+import {stringToBase64} from 'uint8array-extras';
+
+console.log(stringToBase64('Hello'));
+//=> 'SGVsbG8='
+```
+*/
+export function stringToBase64(string: string): string;
+
+/**
+Decode a Base64-encoded string to a string.
+
+@example
+```
+import {base64ToString} from 'uint8array-extras';
+
+console.log(base64ToString('SGVsbG8='));
+//=> 'Hello'
+```
+*/
+export function base64ToString(string: string): string;

index.js

@@ -79,3 +79,40 @@ export function compareUint8Arrays(a, b) {
 
 	return 0;
 }
+
+export function uint8ArrayToString(array) {
+	assertUint8Array(array);
+	return (new globalThis.TextDecoder()).decode(array);
+}
+
+function assertString(value) {
+	if (typeof value !== 'string') {
+		throw new TypeError(`Expected \`string\`, got \`${typeof value}\``);
+	}
+}
+
+export function stringToUint8Array(string) {
+	assertString(string);
+	return (new globalThis.TextEncoder()).encode(string);
+}
+
+export function uint8ArrayToBase64(bytes) {
+	assertUint8Array(bytes);
+	// Required as `btoa` and `atob` don't properly support Unicode: https://developer.mozilla.org/en-US/docs/Glossary/Base64#the_unicode_problem
+	return globalThis.btoa(String.fromCodePoint(...bytes));
+}
+
+export function base64ToUint8Array(base64String) {
+	assertString(base64String);
+	return Uint8Array.from(globalThis.atob(base64String), x => x.codePointAt(0));
+}
+
+export function stringToBase64(string) {
+	assertString(string);
+	return uint8ArrayToBase64(stringToUint8Array(string));
+}
+
+export function base64ToString(base64String) {
+	assertString(base64String);
+	return uint8ArrayToString(base64ToUint8Array(base64String));
+}

package.json

@@ -37,7 +37,11 @@
 		"assert",
 		"concat",
 		"equals",
-		"compare"
+		"compare",
+		"base64",
+		"string",
+		"atob",
+		"btoa"
 	],
 	"devDependencies": {
 		"ava": "^5.3.1",

readme.md

@@ -32,10 +32,30 @@ console.log(concatUint8Arrays([a, b]));
 
 Check if the given value is an instance of `Uint8Array`.
 
+```js
+import {isUint8Array} from 'uint8array-extras';
+
+console.log(isUint8Array(new Uint8Array()));
+//=> true
+
+console.log(isUint8Array(new ArrayBuffer(10)));
+//=> false
+```
+
 ### `assertUint8Array(value: unknown)`
 
 Throw a `TypeError` if the given value is not an instance of `Uint8Array`.
 
+```js
+import {assertUint8Array} from 'uint8array-extras';
+
+try {
+	assertUint8Array(new ArrayBuffer(10)); // Throws a TypeError
+} catch (error) {
+	console.error(error.message);
+}
+```
+
 ### `concatUint8Arrays(arrays: Uint8Array[], totalLength?: number): Uint8Array`
 
 Concatenate the given arrays into a new array.
@@ -44,10 +64,115 @@ 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.
 
+```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]
+```
+
 ### `areUint8ArraysEqual(a: Uint8Array, b: Uint8Array): boolean`
 
 Check if two arrays are identical by verifying that they contain the same bytes in the same sequence.
 
+```js
+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
+```
+
 ### `compareUint8Arrays(a: Uint8Array, b: Uint8Array): 0 | 1 | -1`
 
 Compare two arrays and indicate their relative order or equality. Useful for sorting.
+
+```js
+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]]
+```
+
+#### `uint8ArrayToString(array: Uint8Array): string`
+
+Convert a `Uint8Array` (containing a UTF-8 string) to a string.
+
+```js
+import {uint8ArrayToString} from 'uint8array-extras';
+
+const byteArray = new Uint8Array([72, 101, 108, 108, 111]);
+
+console.log(uint8ArrayToString(byteArray));
+//=> 'Hello'
+```
+
+#### `stringToUint8Array(string: string): Uint8Array`
+
+Convert a string to a `Uint8Array` (using UTF-8 encoding).
+
+```js
+import {stringToUint8Array} from 'uint8array-extras';
+
+console.log(stringToUint8Array('Hello'));
+//=> Uint8Array [72, 101, 108, 108, 111]
+````
+
+#### `uint8ArrayToBase64(array: Uint8Array): string`
+
+Convert a `Uint8Array` to a Base64-encoded string.
+
+```js
+import {uint8ArrayToBase64} from 'uint8array-extras';
+
+const byteArray = new Uint8Array([72, 101, 108, 108, 111]);
+
+console.log(uint8ArrayToBase64(byteArray));
+//=> 'SGVsbG8='
+````
+
+#### `base64ToUint8Array(string: string): Uint8Array`
+
+Convert a Base64-encoded string to a `Uint8Array`.
+
+```js
+import {base64ToUint8Array} from 'uint8array-extras';
+
+console.log(base64ToUint8Array('SGVsbG8='));
+//=> Uint8Array [72, 101, 108, 108, 111]
+```
+
+#### `stringToBase64(string: string): string`
+
+Encode a string to Base64-encoded string.
+
+```js
+import {stringToBase64} from 'uint8array-extras';
+
+console.log(stringToBase64('Hello'));
+//=> 'SGVsbG8='
+```
+
+#### `base64ToString(string: string): string`
+
+Decode a Base64-encoded string to a string.
+
+```js
+import {base64ToString} from 'uint8array-extras';
+
+console.log(base64ToString('SGVsbG8='));
+//=> 'Hello'
+```

test.js

@@ -1,5 +1,17 @@
 import test from 'ava';
-import {isUint8Array, assertUint8Array, concatUint8Arrays, areUint8ArraysEqual, compareUint8Arrays} from './index.js';
+import {
+	isUint8Array,
+	assertUint8Array,
+	concatUint8Arrays,
+	areUint8ArraysEqual,
+	compareUint8Arrays,
+	uint8ArrayToString,
+	stringToUint8Array,
+	uint8ArrayToBase64,
+	base64ToUint8Array,
+	stringToBase64,
+	base64ToString,
+} from './index.js';
 
 test('isUint8Array', t => {
 	t.true(isUint8Array(new Uint8Array()));
@@ -79,3 +91,27 @@ test('compareUint8Arrays - with different lengths', t => {
 	t.is(compareUint8Arrays(array1, array5), -1);
 	t.is(compareUint8Arrays(array5, array1), 1);
 });
+
+test('stringToUint8Array and uint8ArrayToString', t => {
+	const fixture = 'Hello';
+	const array = stringToUint8Array(fixture);
+	t.deepEqual(array, new Uint8Array([72, 101, 108, 108, 111]));
+	t.is(uint8ArrayToString(array), fixture);
+});
+
+test('uint8ArrayToBase64 and base64ToUint8Array', t => {
+	const fixture = stringToUint8Array('Hello');
+	const base64 = uint8ArrayToBase64(fixture);
+	t.is(base64, 'SGVsbG8=');
+	t.deepEqual(base64ToUint8Array(base64), fixture);
+});
+
+test('uint8ArrayToBase64 and base64ToUint8Array #2', t => {
+	const fixture = stringToUint8Array('a Ā 𐀀 文 🦄');
+	t.deepEqual(base64ToUint8Array(uint8ArrayToBase64(base64ToUint8Array(uint8ArrayToBase64(fixture)))), fixture);
+});
+
+test('stringToBase64 and base64ToString', t => {
+	const fixture = 'a Ā 𐀀 文 🦄';
+	t.is(base64ToString(stringToBase64(base64ToString(stringToBase64(fixture)))), fixture);
+});