Minor tweaks

Author: sindresorhus

index.d.ts

@@ -48,10 +48,25 @@ try {
 */
 export function assertUint8Array(value: unknown): asserts value is Uint8Array;
 
+/**
+Throw a `TypeError` if the given value is not an instance of `Uint8Array` or `ArrayBuffer`.
+
+Useful as a guard for functions that accept either a `Uint8Array` or `ArrayBuffer`.
+
+@example
+```
+import {assertUint8ArrayOrArrayBuffer} from 'uint8array-extras';
+
+assertUint8ArrayOrArrayBuffer(new Uint8Array());
+assertUint8ArrayOrArrayBuffer(new ArrayBuffer(8));
+```
+*/
+export function assertUint8ArrayOrArrayBuffer(value: unknown): asserts value is Uint8Array | ArrayBuffer;
+
 /**
 Convert a value to a `Uint8Array` without copying its data.
 
-This can be useful for converting a `Buffer` to a pure `Uint8Array`. `Buffer` is already an `Uint8Array` subclass, but [`Buffer` alters some behavior](https://sindresorhus.com/blog/goodbye-nodejs-buffer), so it can be useful to cast it to a pure `Uint8Array` before returning it.
+This can be useful for converting a `Buffer` to a pure `Uint8Array`. `Buffer` is already a `Uint8Array` subclass, but [`Buffer` alters some behavior](https://sindresorhus.com/blog/goodbye-nodejs-buffer), so it can be useful to cast it to a pure `Uint8Array` before returning it.
 
 Tip: If you want a copy, just call `.slice()` on the return value.
 */
@@ -183,6 +198,8 @@ export function uint8ArrayToBase64(array: Uint8Array, options?: {urlSafe: boolea
 /**
 Convert a Base64-encoded or [Base64URL](https://base64.guru/standards/base64url)-encoded string to a `Uint8Array`.
 
+Accepts Base64URL with or without padding.
+
 Replacement for [`Buffer.from('SGVsbG8=', 'base64')`](https://nodejs.org/api/buffer.html#static-method-bufferfromstring-encoding).
 
 @example
@@ -196,7 +213,7 @@ console.log(base64ToUint8Array('SGVsbG8='));
 export function base64ToUint8Array(string: string): Uint8Array<ArrayBuffer>;
 
 /**
-Encode a string to Base64-encoded string.
+Encode a string to a Base64-encoded string.
 
 Specify `{urlSafe: true}` to get a [Base64URL](https://base64.guru/standards/base64url)-encoded string.
 
@@ -215,6 +232,8 @@ export function stringToBase64(string: string, options?: {urlSafe: boolean}): st
 /**
 Decode a Base64-encoded or [Base64URL](https://base64.guru/standards/base64url)-encoded string to a string.
 
+Accepts Base64URL with or without padding.
+
 Replacement for `Buffer.from('SGVsbG8=', 'base64').toString()` and [`atob()`](https://developer.mozilla.org/en-US/docs/Web/API/atob).
 
 @example
@@ -262,7 +281,7 @@ export function hexToUint8Array(hexString: string): Uint8Array<ArrayBuffer>;
 /**
 Read `DataView#byteLength` number of bytes from the given view, up to 48-bit.
 
-Replacement for [`Buffer#readUintBE`](https://nodejs.org/api/buffer.html#bufreadintbeoffset-bytelength)
+Replacement for [`Buffer#readUIntBE`](https://nodejs.org/api/buffer.html#bufreaduintbeoffset-bytelength)
 
 @example
 ```

index.js

@@ -137,10 +137,13 @@ function base64ToBase64Url(base64) {
 }
 
 function base64UrlToBase64(base64url) {
-	return base64url.replaceAll('-', '+').replaceAll('_', '/');
+	const base64 = base64url.replaceAll('-', '+').replaceAll('_', '/');
+	const padding = (4 - (base64.length % 4)) % 4;
+	return base64 + '='.repeat(padding);
 }
 
 // Reference: https://phuoc.ng/collection/this-vs-that/concat-vs-push/
+// Important: Keep this value divisible by 3 so intermediate chunks produce no Base64 padding.
 const MAX_BLOCK_SIZE = 65_535;
 
 export function uint8ArrayToBase64(array, {urlSafe = false} = {}) {
@@ -151,7 +154,7 @@ export function uint8ArrayToBase64(array, {urlSafe = false} = {}) {
 	for (let index = 0; index < array.length; index += MAX_BLOCK_SIZE) {
 		const chunk = array.subarray(index, index + MAX_BLOCK_SIZE);
 		// Required as `btoa` and `atob` don't properly support Unicode: https://developer.mozilla.org/en-US/docs/Glossary/Base64#the_unicode_problem
-		base64 += globalThis.btoa(String.fromCodePoint.apply(this, chunk));
+		base64 += globalThis.btoa(String.fromCodePoint.apply(undefined, chunk));
 	}
 
 	return urlSafe ? base64ToBase64Url(base64) : base64;

readme.md

@@ -65,11 +65,24 @@ try {
 }
 ```
 
+### `assertUint8ArrayOrArrayBuffer(value: unknown)`
+
+Throw a `TypeError` if the given value is not an instance of `Uint8Array` or `ArrayBuffer`.
+
+Useful as a guard for functions that accept either a `Uint8Array` or `ArrayBuffer`.
+
+```js
+import {assertUint8ArrayOrArrayBuffer} from 'uint8array-extras';
+
+assertUint8ArrayOrArrayBuffer(new Uint8Array());
+assertUint8ArrayOrArrayBuffer(new ArrayBuffer(8));
+```
+
 ### `toUint8Array(value: TypedArray | ArrayBuffer | DataView): Uint8Array`
 
 Convert a value to a `Uint8Array` without copying its data.
 
-This can be useful for converting a `Buffer` to a pure `Uint8Array`. `Buffer` is already an `Uint8Array` subclass, but [`Buffer` alters some behavior](https://sindresorhus.com/blog/goodbye-nodejs-buffer), so it can be useful to cast it to a pure `Uint8Array` before returning it.
+This can be useful for converting a `Buffer` to a pure `Uint8Array`. `Buffer` is already a `Uint8Array` subclass, but [`Buffer` alters some behavior](https://sindresorhus.com/blog/goodbye-nodejs-buffer), so it can be useful to cast it to a pure `Uint8Array` before returning it.
 
 Tip: If you want a copy, just call `.slice()` on the return value.
 
@@ -188,6 +201,8 @@ console.log(uint8ArrayToBase64(byteArray));
 
 Convert a Base64-encoded or [Base64URL](https://base64.guru/standards/base64url)-encoded string to a `Uint8Array`.
 
+Accepts Base64URL with or without padding.
+
 Replacement for [`Buffer.from('SGVsbG8=', 'base64')`](https://nodejs.org/api/buffer.html#static-method-bufferfromstring-encoding).
 
 ```js
@@ -199,7 +214,7 @@ console.log(base64ToUint8Array('SGVsbG8='));
 
 ### `stringToBase64(string: string, options?: {urlSafe: boolean}): string`
 
-Encode a string to Base64-encoded string.
+Encode a string to a Base64-encoded string.
 
 Specify `{urlSafe: true}` to get a [Base64URL](https://base64.guru/standards/base64url)-encoded string.
 
@@ -216,6 +231,8 @@ console.log(stringToBase64('Hello'));
 
 Decode a Base64-encoded or [Base64URL](https://base64.guru/standards/base64url)-encoded string to a string.
 
+Accepts Base64URL with or without padding.
+
 Replacement for `Buffer.from('SGVsbG8=', 'base64').toString()` and [`atob()`](https://developer.mozilla.org/en-US/docs/Web/API/atob).
 
 ```js
@@ -257,7 +274,7 @@ console.log(hexToUint8Array('48656c6c6f'));
 
 Read `DataView#byteLength` number of bytes from the given view, up to 48-bit.
 
-Replacement for [`Buffer#readUintBE`](https://nodejs.org/api/buffer.html#bufreadintbeoffset-bytelength)
+Replacement for [`Buffer#readUIntBE`](https://nodejs.org/api/buffer.html#bufreaduintbeoffset-bytelength)
 
 ```js
 import {getUintBE} from 'uint8array-extras';

test.js

@@ -2,6 +2,7 @@ import test from 'ava';
 import {
 	isUint8Array,
 	assertUint8Array,
+	assertUint8ArrayOrArrayBuffer,
 	toUint8Array,
 	concatUint8Arrays,
 	areUint8ArraysEqual,
@@ -49,6 +50,12 @@ test('toUint8Array - DataView', t => {
 	t.true(isUint8ArrayStrict(toUint8Array(fixture)));
 });
 
+test('toUint8Array - unsupported value throws', t => {
+	t.throws(() => {
+		toUint8Array(123);
+	}, {instanceOf: TypeError});
+});
+
 test('concatUint8Arrays - combining multiple Uint8Arrays', t => {
 	const array1 = new Uint8Array([1, 2, 3]);
 	const array2 = new Uint8Array([4, 5, 6]);
@@ -141,6 +148,21 @@ test('uint8ArrayToString with ArrayBuffer', t => {
 	t.is(uint8ArrayToString(fixture), 'Hello');
 });
 
+test('assertUint8ArrayOrArrayBuffer', t => {
+	const u8 = new Uint8Array(0);
+	const ab = new ArrayBuffer(0);
+	// Should not throw
+	assertUint8ArrayOrArrayBuffer(u8);
+	assertUint8ArrayOrArrayBuffer(ab);
+	// Should throw on invalid types
+	t.throws(() => {
+		assertUint8ArrayOrArrayBuffer(null);
+	}, {instanceOf: TypeError});
+	t.throws(() => {
+		assertUint8ArrayOrArrayBuffer({});
+	}, {instanceOf: TypeError});
+});
+
 test('uint8ArrayToBase64 and base64ToUint8Array', t => {
 	const fixture = stringToUint8Array('Hello');
 	const base64 = uint8ArrayToBase64(fixture);
@@ -181,6 +203,18 @@ test('hexToUint8Array', t => {
 	t.deepEqual(hexToUint8Array(fixtureHex), new Uint8Array(Buffer.from(fixtureHex, 'hex'))); // eslint-disable-line n/prefer-global/buffer
 });
 
+test('hexToUint8Array - invalid length throws', t => {
+	t.throws(() => {
+		hexToUint8Array('A');
+	}, {message: 'Invalid Hex string length.'});
+});
+
+test('hexToUint8Array - invalid character throws', t => {
+	t.throws(() => {
+		hexToUint8Array('0G');
+	}, {message: /Invalid Hex character encountered at position 0|position 1/});
+});
+
 test('getUintBE', t => {
 	const fixture = [0x12, 0x34, 0x56, 0x78, 0x90, 0xab]; // eslint-disable-line unicorn/number-literal-case
 
@@ -240,3 +274,49 @@ test('includes', t => {
 	t.true(includes(new Uint8Array(fixture), new Uint8Array([0x78, 0x90])));
 	t.false(includes(new Uint8Array(fixture), new Uint8Array([0x90, 0x78])));
 });
+
+test('uint8ArrayToBase64 - empty input returns empty string', t => {
+	const empty = new Uint8Array(0);
+	t.is(uint8ArrayToBase64(empty), '');
+	// And decode back
+	t.deepEqual(base64ToUint8Array(''), empty);
+});
+
+test('uint8ArrayToBase64 - chunk boundaries and padding are correct', t => {
+	const make = length => new Uint8Array(Array.from({length}, () => 0x41)); // 0x41 = 'A'
+	const sizes = [
+		65_534, // Chunk size - 1 (length % 3 === 2)
+		65_535, // Exact chunk size (length % 3 === 0)
+		65_536, // Chunk size + 1 (length % 3 === 1)
+		(2 * 65_535) - 2,
+		(2 * 65_535) - 1,
+		(2 * 65_535),
+		(2 * 65_535) + 1,
+	];
+
+	for (const size of sizes) {
+		const u8 = make(size);
+		const b64 = uint8ArrayToBase64(u8);
+		const roundTrip = base64ToUint8Array(b64);
+		t.deepEqual(roundTrip, u8);
+	}
+});
+
+test('base64ToUint8Array - accepts Base64URL without padding', t => {
+	const cases = [
+		['f', 'Zg'],
+		['fo', 'Zm8'],
+		['foo', 'Zm9v'],
+		['foob', 'Zm9vYg'],
+		['fooba', 'Zm9vYmE'],
+		['foobar', 'Zm9vYmFy'],
+	];
+
+	for (const [plain, base64url] of cases) {
+		const decoded = base64ToString(base64url);
+		t.is(decoded, plain);
+		// And Uint8Array path
+		const u8 = base64ToUint8Array(base64url);
+		t.is(uint8ArrayToString(u8), plain);
+	}
+});