0
# randombytes
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: randombytes
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install randombytes`
10

11
## Core Imports
12

13
```javascript
14
const randomBytes = require('randombytes');
15
```
16

17
For ES modules:
18

19
```javascript
20
import randomBytes from 'randombytes';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const randomBytes = require('randombytes');
27

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

32
// Generate 32 random bytes asynchronously
33
randomBytes(32, (err, bytes) => {
34
  if (err) throw err;
35
  console.log(bytes); // <Buffer d4 e5 f6 ...>
36
});
37
```
38

39
## Capabilities
40

41
### Random Byte Generation
42

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

45
```javascript { .api }
46
/**
47
 * Generate cryptographically secure random bytes
48
 * @param {number} size - Number of bytes to generate (0 to 4294967295)
49
 * @param {function} [callback] - Optional callback function (err, bytes)
50
 * @returns {Buffer} Random bytes buffer (sync mode) or undefined (async mode)
51
 * @throws {RangeError} When size > 4294967295
52
 * @throws {Error} When size is negative or non-numeric
53
 * @throws {Error} In unsupported browsers
54
 */
55
function randomBytes(size, callback);
56
```
57

58
**Parameters:**
59
- `size` (number): Number of random bytes to generate
60
  - Must be a non-negative integer
61
  - Maximum value: 4,294,967,295 (MAX_UINT32)
62
  - Throws `RangeError` for values exceeding maximum
63
  - Throws error for negative values or non-numeric types
64

65
**Optional Parameters:**
66
- `callback` (function): Callback with signature `(err, bytes)`
67
  - When provided: Function operates asynchronously, returns `undefined`
68
  - When omitted: Function operates synchronously, returns `Buffer`
69

70
**Return Value:**
71
- **Synchronous mode**: Returns a `Buffer` containing random bytes
72
- **Asynchronous mode**: Returns `undefined`, passes result via callback as `(null, Buffer)`
73

74
**Error Handling:**
75
- `RangeError`: Thrown when size exceeds 4,294,967,295
76
- `Error`: Thrown for negative size or non-numeric size parameter
77
- `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"
78

79
**Platform Implementation:**
80
- **Node.js**: Direct wrapper around `crypto.randomBytes`
81
- **Browser**: Uses `crypto.getRandomValues()` or legacy `msCrypto.getRandomValues()`
82
- **Large requests**: Browser automatically handles requests > 65,536 bytes through chunking
83

84
**Usage Examples:**
85

86
```javascript
87
const randomBytes = require('randombytes');
88

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

93
// Asynchronous usage
94
randomBytes(32, (err, asyncBytes) => {
95
  if (err) {
96
    console.error('Error generating bytes:', err);
97
    return;
98
  }
99
  console.log('Async bytes:', asyncBytes.toString('hex'));
100
});
101

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

106
// Error handling for invalid inputs
107
try {
108
  randomBytes(-1); // Throws error
109
} catch (err) {
110
  console.error('Invalid size:', err.message);
111
}
112

113
try {
114
  randomBytes(4294967296); // Throws RangeError
115
} catch (err) {
116
  console.error('Size too large:', err.message);
117
}
118
```
119

120
## Browser Compatibility
121

122
randombytes requires a modern browser with Web Crypto API support:
123

124
- **Chrome**: 37+
125
- **Firefox**: 34+
126
- **Safari**: 7.1+
127
- **Internet Explorer**: 11+
128
- **Edge**: All versions
129

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

132
## Dependencies
133

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