randombytes

randombytes provides cryptographically secure random byte generation that works identically in both Node.js and browser environments. It offers a simple, unified API that transparently uses Node.js crypto.randomBytes or browser Web Crypto API depending on the runtime environment.

Package Information

• Package Name: randombytes
• Package Type: npm
• Language: JavaScript
• Installation: npm install randombytes

Core Imports

const randomBytes = require('randombytes');

For ES modules:

import randomBytes from 'randombytes';

Basic Usage

const randomBytes = require('randombytes');

// Generate 16 random bytes synchronously
const bytes = randomBytes(16);
console.log(bytes); // <Buffer a1 b2 c3 ...>

// Generate 32 random bytes asynchronously
randomBytes(32, (err, bytes) => {
  if (err) throw err;
  console.log(bytes); // <Buffer d4 e5 f6 ...>
});

Capabilities

Random Byte Generation

Generates cryptographically secure random bytes with both synchronous and asynchronous interfaces.

/**
 * Generate cryptographically secure random bytes
 * @param {number} size - Number of bytes to generate (0 to 4294967295)
 * @param {function} [callback] - Optional callback function (err, bytes)
 * @returns {Buffer} Random bytes buffer (sync mode) or undefined (async mode)
 * @throws {RangeError} When size > 4294967295
 * @throws {Error} When size is negative or non-numeric
 * @throws {Error} In unsupported browsers
 */
function randomBytes(size, callback);

Parameters:

• size (number): Number of random bytes to generate
  • Must be a non-negative integer
  • Maximum value: 4,294,967,295 (MAX_UINT32)
  • Throws RangeError for values exceeding maximum
  • Throws error for negative values or non-numeric types

Optional Parameters:

• callback (function): Callback with signature (err, bytes)
  • When provided: Function operates asynchronously, returns undefined
  • When omitted: Function operates synchronously, returns Buffer

Return Value:

• Synchronous mode: Returns a Buffer containing random bytes
• Asynchronous mode: Returns undefined, passes result via callback as (null, Buffer)

Error Handling:

• RangeError: Thrown when size exceeds 4,294,967,295
• Error: Thrown for negative size or non-numeric size parameter
• Error: In browsers lacking Web Crypto API support with message: "Secure random number generation is not supported by this browser. Use Chrome, Firefox or Internet Explorer 11"

Platform Implementation:

• Node.js: Direct wrapper around crypto.randomBytes
• Browser: Uses crypto.getRandomValues() or legacy msCrypto.getRandomValues()
• Large requests: Browser automatically handles requests > 65,536 bytes through chunking

Usage Examples:

const randomBytes = require('randombytes');

// Synchronous usage
const syncBytes = randomBytes(16);
console.log('Sync bytes:', syncBytes.toString('hex'));

// Asynchronous usage
randomBytes(32, (err, asyncBytes) => {
  if (err) {
    console.error('Error generating bytes:', err);
    return;
  }
  console.log('Async bytes:', asyncBytes.toString('hex'));
});

// Large byte generation (automatically chunked in browsers)
const largeBytes = randomBytes(100000);
console.log('Generated', largeBytes.length, 'bytes');

// Error handling for invalid inputs
try {
  randomBytes(-1); // Throws error
} catch (err) {
  console.error('Invalid size:', err.message);
}

try {
  randomBytes(4294967296); // Throws RangeError
} catch (err) {
  console.error('Size too large:', err.message);
}

Browser Compatibility

randombytes requires a modern browser with Web Crypto API support:

• Chrome: 37+
• Firefox: 34+
• Safari: 7.1+
• Internet Explorer: 11+
• Edge: All versions

In unsupported browsers, the function throws an error with guidance to upgrade to a supported browser.

Dependencies

• safe-buffer: Used for cross-platform Buffer operations in browser environments
• Node.js crypto module: Used automatically in Node.js environments
• Web Crypto API: Used automatically in browser environments