uint8array-extras
v1.4.0
Published
Useful utilities for working with Uint8Array (and Buffer)
Downloads
1,703,701
Maintainers
Readme
uint8array-extras
Useful utilities for working with
Uint8Array
(andBuffer
)
It's time to transition from Buffer
to Uint8Array
, and this package helps fill in the gaps.
Note that Buffer
is a Uint8Array
subclass, so you can use this package with Buffer
too.
This package is tree-shakeable and browser-compatible.
This package also includes methods to convert a string to Base64 and back.
Note: In the browser, do not use globalThis.atob()
/ globalThis.btoa()
because they do not support Unicode. This package does.
Install
npm install uint8array-extras
Usage
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
.
Replacement for Buffer.isBuffer()
.
import {isUint8Array} from 'uint8array-extras';
console.log(isUint8Array(new Uint8Array()));
//=> true
console.log(isUint8Array(Buffer.from('x')));
//=> true
console.log(isUint8Array(new ArrayBuffer(10)));
//=> false
assertUint8Array(value: unknown)
Throw a TypeError
if the given value is not an instance of Uint8Array
.
import {assertUint8Array} from 'uint8array-extras';
try {
assertUint8Array(new ArrayBuffer(10)); // Throws a TypeError
} catch (error) {
console.error(error.message);
}
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, 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.
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.
Replacement for Buffer.concat()
.
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.
Replacement for Buffer#equals()
.
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.
Replacement for Buffer.compare()
.
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 | ArrayBuffer, encoding?: string = 'utf8'): string
Convert a Uint8Array
to a string.
- Parameter:
encoding
- The encoding to convert from.
Replacement for Buffer#toString()
. For the encoding
parameter, latin1
should be used instead of binary
and utf-16le
instead of utf16le
.
import {uint8ArrayToString} from 'uint8array-extras';
const byteArray = new Uint8Array([72, 101, 108, 108, 111]);
console.log(uint8ArrayToString(byteArray));
//=> 'Hello'
const zh = new Uint8Array([167, 65, 166, 110]);
console.log(uint8ArrayToString(zh, 'big5'));
//=> '你好'
const ja = new Uint8Array([130, 177, 130, 241, 130, 201, 130, 191, 130, 205]);
console.log(uint8ArrayToString(ja, 'shift-jis'));
//=> 'こんにちは'
stringToUint8Array(string: string): Uint8Array
Convert a string to a Uint8Array
(using UTF-8 encoding).
Replacement for Buffer.from('Hello')
.
import {stringToUint8Array} from 'uint8array-extras';
console.log(stringToUint8Array('Hello'));
//=> Uint8Array [72, 101, 108, 108, 111]
uint8ArrayToBase64(array: Uint8Array, options?: {urlSafe: boolean}): string
Convert a Uint8Array
to a Base64-encoded string.
Specify {urlSafe: true}
to get a Base64URL-encoded string.
Replacement for Buffer#toString('base64')
.
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 or Base64URL-encoded string to a Uint8Array
.
Replacement for Buffer.from('SGVsbG8=', 'base64')
.
import {base64ToUint8Array} from 'uint8array-extras';
console.log(base64ToUint8Array('SGVsbG8='));
//=> Uint8Array [72, 101, 108, 108, 111]
stringToBase64(string: string, options?: {urlSafe: boolean}): string
Encode a string to Base64-encoded string.
Specify {urlSafe: true}
to get a Base64URL-encoded string.
Replacement for Buffer.from('Hello').toString('base64')
and btoa()
.
import {stringToBase64} from 'uint8array-extras';
console.log(stringToBase64('Hello'));
//=> 'SGVsbG8='
base64ToString(base64String: string): string
Decode a Base64-encoded or Base64URL-encoded string to a string.
Replacement for Buffer.from('SGVsbG8=', 'base64').toString()
and atob()
.
import {base64ToString} from 'uint8array-extras';
console.log(base64ToString('SGVsbG8='));
//=> 'Hello'
uint8ArrayToHex(array: Uint8Array): string
Convert a Uint8Array
to a Hex string.
Replacement for Buffer#toString('hex')
.
import {uint8ArrayToHex} from 'uint8array-extras';
const byteArray = new Uint8Array([72, 101, 108, 108, 111]);
console.log(uint8ArrayToHex(byteArray));
//=> '48656c6c6f'
hexToUint8Array(hexString: string): Uint8Array
Convert a Hex string to a Uint8Array
.
Replacement for Buffer.from('48656c6c6f', 'hex')
.
import {hexToUint8Array} from 'uint8array-extras';
console.log(hexToUint8Array('48656c6c6f'));
//=> Uint8Array [72, 101, 108, 108, 111]
getUintBE(view: DataView): number
Read DataView#byteLength
number of bytes from the given view, up to 48-bit.
Replacement for Buffer#readUintBE
import {getUintBE} from 'uint8array-extras';
const byteArray = new Uint8Array([0x12, 0x34, 0x56, 0x78, 0x90, 0xab]);
console.log(getUintBE(new DataView(byteArray.buffer)));
//=> 20015998341291
indexOf(array: Uint8Array, value: Uint8Array): number
Find the index of the first occurrence of the given sequence of bytes (value
) within the given Uint8Array
(array
).
Replacement for Buffer#indexOf
. Uint8Array#indexOf
only takes a number which is different from Buffer's indexOf
implementation.
import {indexOf} from 'uint8array-extras';
const byteArray = new Uint8Array([0x12, 0x34, 0x56, 0x78, 0x90, 0xab, 0xcd, 0xef]);
console.log(indexOf(byteArray, new Uint8Array([0x78, 0x90])));
//=> 3
includes(array: Uint8Array, value: Uint8Array): boolean
Checks if the given sequence of bytes (value
) is within the given Uint8Array
(array
).
Returns true if the value is included, otherwise false.
Replacement for Buffer#includes
. Uint8Array#includes
only takes a number which is different from Buffer's includes
implementation.
import {includes} from 'uint8array-extras';
const byteArray = new Uint8Array([0x12, 0x34, 0x56, 0x78, 0x90, 0xab, 0xcd, 0xef]);
console.log(includes(byteArray, new Uint8Array([0x78, 0x90])));
//=> true