Uint8Array Utilities for JavaScript

Common errors

• TypeError: concat expects an array of Uint8Arrays

  cause The `concat` function was called with individual `Uint8Array` arguments instead of a single array containing them, which is the expected format since v5.0.0.
  fix Wrap the individual `Uint8Array` arguments within an array: `concat([array1, array2, array3])`.

• Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'uint8arrays' imported from ...

  cause This typically indicates a CommonJS (`require()`) compatibility issue or incorrect module resolution, especially in versions prior to `5.1.1` where ESM subpath exports might not have been correctly handled in all environments.
  fix Upgrade to `uint8arrays@5.1.1` or newer. If you must use an older version with CommonJS, ensure your environment supports ESM interop or explicitly use ESM `import` statements if possible.

• RangeError: Array buffer allocation failed

  cause This error occurs when the system runs out of available memory to allocate a `Uint8Array` (or `Buffer` internally), often due to requesting a very large size or continuous memory pressure.
  fix Reduce the requested size for the `Uint8Array` or optimize your application's memory usage. For Node.js, ensure you are running on a 64-bit system, which generally allows for a larger memory heap.

Warnings

• breaking The `concat` function signature changed significantly in `v5.0.0`. It now explicitly expects an array of `Uint8Array`s as its first argument (e.g., `concat([buf1, buf2])`), rather than accepting multiple `Uint8Array` arguments directly (e.g., `concat(buf1, buf2)`). This change was implemented to optimize performance in Node.js by leveraging `Buffer.concat` internally.
  Fix: Update all calls to `concat` to pass an array of `Uint8Array`s: `concat([array1, array2, ...])`.
• gotcha Versions of `uint8arrays` prior to `v5.1.1` could exhibit compatibility issues when used with CommonJS `require()`, especially in certain Node.js environments or with specific bundler configurations. The library's reliance on ESM subpath exports could lead to module resolution errors.
  Fix: Upgrade to `uint8arrays@5.1.1` or newer to ensure full CommonJS `require()` compatibility. If upgrading is not feasible, use explicit ESM `import` statements (e.g., `import { concat } from 'uint8arrays/concat'`).
• gotcha Using `allocUnsafe` can introduce security vulnerabilities or lead to undefined behavior if the allocated memory is not immediately and completely overwritten. The memory allocated by `allocUnsafe` is not initialized and may contain residual sensitive data from previous operations in the process's memory space.
  Fix: Always use `alloc` for creating new `Uint8Array`s unless you have a critical performance bottleneck and can guarantee immediate, full initialization of the `allocUnsafe` buffer. If `allocUnsafe` is necessary, immediately fill the buffer with zeros or your intended data, for example, `allocUnsafe(size).fill(0);`.
• gotcha The library is designed around subpath imports (e.g., `import { concat } from 'uint8arrays/concat'`). Attempting to import all utilities from the root path (`import { concat } from 'uint8arrays'`) may not work as intended or could result in larger bundle sizes if your tooling does not optimize tree-shaking effectively for non-subpath imports.
  Fix: Adhere to the documented pattern of explicit subpath imports for individual functions: `import { functionName } from 'uint8arrays/function-subpath'` to ensure correct module resolution and optimal bundle size.

Install

• npm install uint8arrays npm
• yarn add uint8arrays yarn
• pnpm add uint8arrays pnpm

Imports

• concat
  wrong:

  import { concat } from 'uint8arrays'

  correct:

  import { concat } from 'uint8arrays/concat'

  The library primarily uses subpath exports, requiring specific imports for each utility. In v5.0.0, the `concat` signature changed to expect an array of `Uint8Array`s. CommonJS `require()` support was improved in v5.1.1, addressing issues in earlier v5.x versions.
• fromString
  wrong:

  const fromString = require('uint8arrays/from-string')

  correct:

  import { fromString } from 'uint8arrays/from-string'

  Each utility like `fromString` is exported as a named export from its specific subpath. CommonJS `require()` had compatibility issues in `v5.0.x` versions, resolved in `v5.1.1`. This function supports `utf8` and `multibase` encodings.
• alloc
  wrong:

  import { alloc } from 'uint8arrays'

  correct:

  import { alloc } from 'uint8arrays/alloc'

  The `alloc` function is imported from its dedicated subpath. It creates a new `Uint8Array` and uses Node.js `Buffer` internally for performance when available. For uninitialized memory, `allocUnsafe` is available from the same subpath.

Quickstart

This quickstart demonstrates key utility functions: `alloc` (and `allocUnsafe` with caution), `fromString` with different encodings, `concat` for joining byte arrays, `toString` for decoding, and `equals` for comparison.

import { alloc, allocUnsafe } from 'uint8arrays/alloc';
import { concat } from 'uint8arrays/concat';
import { fromString } from 'uint8arrays/from-string';
import { toString } from 'uint8arrays/to-string';
import { equals } from 'uint8arrays/equals';

// Allocate a zero-filled Uint8Array
const bufferA: Uint8Array = alloc(10);
console.log('Allocated (zero-filled):', bufferA);

// Allocate an uninitialized Uint8Array (use with caution!)
const bufferUnsafe: Uint8Array = allocUnsafe(5);
console.log('Allocated (potentially uninitialized):', bufferUnsafe);
bufferUnsafe.fill(0xFF); // Always initialize unsafe buffers immediately
console.log('Unsafe buffer after fill:', bufferUnsafe);

// Convert a string to Uint8Array using UTF-8 encoding
const helloBytes: Uint8Array = fromString('Hello', 'utf8');
console.log('"Hello" as UTF-8 bytes:', helloBytes);

// Convert a string to Uint8Array using base64 encoding
const base64Input = 'SGVsbG8gV29ybGQ='; // 'Hello World' in base64
const helloWorldBytes: Uint8Array = fromString(base64Input, 'base64');
console.log(`"${base64Input}" as base64 bytes:`, helloWorldBytes);

// Concatenate multiple Uint8Arrays
const spaceBytes: Uint8Array = fromString(' ', 'utf8');
const worldBytes: Uint8Array = fromString('World', 'utf8');
const combinedBytes: Uint8Array = concat([helloBytes, spaceBytes, worldBytes]);
console.log('Concatenated bytes:', combinedBytes);

// Convert Uint8Array back to string
const decodedString: string = toString(combinedBytes, 'utf8');
console.log('Decoded string:', decodedString); // Expected: 'Hello World'

// Compare two Uint8Arrays for equality
const sameHelloBytes: Uint8Array = fromString('Hello', 'utf8');
const areEqual = equals(helloBytes, sameHelloBytes);
const areNotEqual = equals(helloBytes, worldBytes);
console.log('Are "Hello" and "Hello" equal?', areEqual); // Expected: true
console.log('Are "Hello" and "World" equal?', areNotEqual); // Expected: false