Registry / serialization / uint8arrays

uint8arrays

JSON →
library5.1.1jsnpmunverified

The `uint8arrays` library provides a comprehensive set of utility functions to simplify operations with `Uint8Array`s, which are fundamental for handling binary data in modern JavaScript environments. Currently at version `5.1.1`, the library maintains an active release cadence, with frequent minor and patch updates addressing bug fixes and introducing new features. Its key differentiators include optimized performance in Node.js by transparently leveraging `Buffer` where beneficial, full TypeScript support with built-in type declarations, and extensive encoding capabilities for `fromString` and `toString` functions, including UTF-8 and a wide range of multibase encodings via its integration with the `multiformats` module. This package aims to bridge the gap of missing utility methods often found on Node.js `Buffer`s, making `Uint8Array` usage more convenient across browsers and Node.js alike.

npm install uint8arrays
INSTALL
IMPORT
SIG · UINT8ARRAYS
U
uint8arrays
serializationjavascriptv5.1.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

concat
import { concat } from 'uint8arrays/concat'
import { concat } from 'uint8arrays'
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
import { fromString } from 'uint8arrays/from-string'
const fromString = require('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
import { alloc } from 'uint8arrays/alloc'
import { alloc } from 'uint8arrays'
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.

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
Debug
Known issues
breakingThe `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, ...])`.
affects: >=5.0.0
gotchaVersions 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'`).
affects: >=5.0.0 <5.1.1
gotchaUsing `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);`.
affects: >=4.0.0
gotchaThe 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.
affects: >=4.0.0
Errors
Common errors & fixes
TypeError: concat expects an array of Uint8Arrays
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 ...
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
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.
Upgrade
Version history
5.1.1latest on npm
Audit
Dependencies
multiformatsrequiredProvides support for various multibase encodings (e.g., base16, base64) used in `fromString` and `toString` functions.
Agent activity
18 hits · last 30 days
node
16
OpenAI (training)
1
Resources
uint8arrays — npm install uint8arrays · libregistry