{"id":12271,"library":"uint8arrays","title":"Uint8Array Utilities for JavaScript","description":"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.","status":"active","version":"5.1.1","language":"javascript","source_language":"en","source_url":"https://github.com/achingbrain/uint8arrays","tags":["javascript","typescript"],"install":[{"cmd":"npm install uint8arrays","lang":"bash","label":"npm"},{"cmd":"yarn add uint8arrays","lang":"bash","label":"yarn"},{"cmd":"pnpm add uint8arrays","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides support for various multibase encodings (e.g., base16, base64) used in `fromString` and `toString` functions.","package":"multiformats","optional":false}],"imports":[{"note":"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.","wrong":"import { concat } from 'uint8arrays'","symbol":"concat","correct":"import { concat } from 'uint8arrays/concat'"},{"note":"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.","wrong":"const fromString = require('uint8arrays/from-string')","symbol":"fromString","correct":"import { fromString } from 'uint8arrays/from-string'"},{"note":"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.","wrong":"import { alloc } from 'uint8arrays'","symbol":"alloc","correct":"import { alloc } from 'uint8arrays/alloc'"}],"quickstart":{"code":"import { alloc, allocUnsafe } from 'uint8arrays/alloc';\nimport { concat } from 'uint8arrays/concat';\nimport { fromString } from 'uint8arrays/from-string';\nimport { toString } from 'uint8arrays/to-string';\nimport { equals } from 'uint8arrays/equals';\n\n// Allocate a zero-filled Uint8Array\nconst bufferA: Uint8Array = alloc(10);\nconsole.log('Allocated (zero-filled):', bufferA);\n\n// Allocate an uninitialized Uint8Array (use with caution!)\nconst bufferUnsafe: Uint8Array = allocUnsafe(5);\nconsole.log('Allocated (potentially uninitialized):', bufferUnsafe);\nbufferUnsafe.fill(0xFF); // Always initialize unsafe buffers immediately\nconsole.log('Unsafe buffer after fill:', bufferUnsafe);\n\n// Convert a string to Uint8Array using UTF-8 encoding\nconst helloBytes: Uint8Array = fromString('Hello', 'utf8');\nconsole.log('\"Hello\" as UTF-8 bytes:', helloBytes);\n\n// Convert a string to Uint8Array using base64 encoding\nconst base64Input = 'SGVsbG8gV29ybGQ='; // 'Hello World' in base64\nconst helloWorldBytes: Uint8Array = fromString(base64Input, 'base64');\nconsole.log(`\"${base64Input}\" as base64 bytes:`, helloWorldBytes);\n\n// Concatenate multiple Uint8Arrays\nconst spaceBytes: Uint8Array = fromString(' ', 'utf8');\nconst worldBytes: Uint8Array = fromString('World', 'utf8');\nconst combinedBytes: Uint8Array = concat([helloBytes, spaceBytes, worldBytes]);\nconsole.log('Concatenated bytes:', combinedBytes);\n\n// Convert Uint8Array back to string\nconst decodedString: string = toString(combinedBytes, 'utf8');\nconsole.log('Decoded string:', decodedString); // Expected: 'Hello World'\n\n// Compare two Uint8Arrays for equality\nconst sameHelloBytes: Uint8Array = fromString('Hello', 'utf8');\nconst areEqual = equals(helloBytes, sameHelloBytes);\nconst areNotEqual = equals(helloBytes, worldBytes);\nconsole.log('Are \"Hello\" and \"Hello\" equal?', areEqual); // Expected: true\nconsole.log('Are \"Hello\" and \"World\" equal?', areNotEqual); // Expected: false\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Update all calls to `concat` to pass an array of `Uint8Array`s: `concat([array1, array2, ...])`.","message":"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.","severity":"breaking","affected_versions":">=5.0.0"},{"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'`).","message":"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.","severity":"gotcha","affected_versions":">=5.0.0 <5.1.1"},{"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);`.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Wrap the individual `Uint8Array` arguments within an array: `concat([array1, array2, array3])`.","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.","error":"TypeError: concat expects an array of Uint8Arrays"},{"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.","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.","error":"Error [ERR_MODULE_NOT_FOUND]: Cannot find package 'uint8arrays' imported from ..."},{"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.","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.","error":"RangeError: Array buffer allocation failed"}],"ecosystem":"npm"}