0
# uniqid
1

2
A unique hexatridecimal ID generator based on timestamp, process ID, and MAC address. Creates unique identifiers for distributed systems with three variants optimized for different environment constraints.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const uniqid = require('uniqid');
15

16
// Access specific methods
17
const { process, time } = require('uniqid');
18
```
19

20
ES6/ES2015 modules:
21

22
```javascript
23
import uniqid from 'uniqid';
24

25
// Access specific methods
26
import { process, time } from 'uniqid';
27
```
28

29
## Basic Usage
30

31
```javascript
32
const uniqid = require('uniqid');
33

34
// Generate full unique IDs (18 bytes) - works across machines and processes
35
console.log(uniqid()); // -> "4n5pxq24kpiob12og9"
36
console.log(uniqid()); // -> "4n5pxq24kriob12ogd"
37

38
// Add prefix and suffix
39
console.log(uniqid('user-')); // -> "user-4n5pxq24kpiob12og9"
40
console.log(uniqid('order-', '-temp')); // -> "order-4n5pxq24kpiob12og9-temp"
41

42
// Generate process-specific IDs (12 bytes) - works within single machine
43
console.log(uniqid.process()); // -> "0te82iob0ucoj"
44

45
// Generate time-based IDs (8 bytes) - works within single process
46
console.log(uniqid.time()); // -> "iob0ucoj"
47
```
48

49
## Capabilities
50

51
### Full Unique ID Generation
52

53
Generates 18-byte unique hexatridecimal IDs that are unique across multiple machines and processes. Combines MAC address, process ID, and timestamp for maximum uniqueness.
54

55
```javascript { .api }
56
/**
57
 * Generate 18 byte unique IDs based on time, process ID and MAC address
58
 * @param {string} [prefix] - Optional string to prepend to the generated ID
59
 * @param {string} [suffix] - Optional string to append to the generated ID
60
 * @returns {string} Unique hexatridecimal ID
61
 */
62
function uniqid(prefix, suffix);
63
```
64

65
**Usage Examples:**
66

67
```javascript
68
// Basic generation
69
uniqid() // -> "4n5pxq24kpiob12og9"
70

71
// With prefix only
72
uniqid('hello-') // -> "hello-4n5pxq24kpiob12og9"
73

74
// With both prefix and suffix
75
uniqid('hello-', '-goodbye') // -> "hello-4n5pxq24kpiob12og9-goodbye"
76

77
// With suffix only (prefix as empty string or undefined)
78
uniqid('', '-goodbye') // -> "4n5pxq24kpiob12og9-goodbye"
79
uniqid(undefined, '-goodbye') // -> "4n5pxq24kpiob12og9-goodbye"
80
```
81

82
### Process-Specific ID Generation
83

84
Generates 12-byte unique IDs based on process ID and timestamp. Suitable for multi-process applications on a single machine where MAC address uniqueness is not required.
85

86
```javascript { .api }
87
/**
88
 * Generate 12 byte unique IDs based on time and process ID
89
 * @param {string} [prefix] - Optional string to prepend to the generated ID
90
 * @param {string} [suffix] - Optional string to append to the generated ID
91
 * @returns {string} Process-specific unique hexatridecimal ID
92
 */
93
uniqid.process(prefix, suffix);
94
```
95

96
**Usage Examples:**
97

98
```javascript
99
// Basic process ID generation
100
uniqid.process() // -> "24ieiob0te82"
101

102
// With prefix and suffix
103
uniqid.process('task-', '-pending') // -> "task-24ieiob0te82-pending"
104
```
105

106
### Time-Based ID Generation
107

108
Generates 8-byte unique IDs based solely on timestamp. Recommended for single-process applications where process and machine uniqueness is not required.
109

110
```javascript { .api }
111
/**
112
 * Generate 8 byte unique IDs based on current time only
113
 * @param {string} [prefix] - Optional string to prepend to the generated ID
114
 * @param {string} [suffix] - Optional string to append to the generated ID
115
 * @returns {string} Time-based unique hexatridecimal ID
116
 */
117
uniqid.time(prefix, suffix);
118
```
119

120
**Usage Examples:**
121

122
```javascript
123
// Basic time-based generation
124
uniqid.time() // -> "iob0ucoj"
125

126
// With prefix and suffix
127
uniqid.time('event-', '-log') // -> "event-iob0ucoj-log"
128
```
129

130
## Environment-Specific Behavior
131

132
### Node.js Environment
133
- **Full functionality**: MAC address detection, process ID access, timestamp generation
134
- **ID Components**: MAC address + process ID + timestamp
135
- **Uniqueness**: Guaranteed across multiple machines and processes
136

137
### Browser/Webpack Environment
138
- **Limited functionality**: No MAC address or process ID available
139
- **Fallback behavior**: All methods (`uniqid()`, `uniqid.process()`, `uniqid.time()`) fall back to time-based generation
140
- **ID Components**: Timestamp only
141
- **Uniqueness**: Guaranteed within single browser tab/process
142

143
### Browserify Environment
144
- **Limited functionality**: Similar to browser/webpack behavior
145
- **Fallback behavior**: All methods fall back to time-based generation
146
- **ID Components**: Timestamp only
147

148
## Uniqueness Guarantees
149

150
The library provides different levels of uniqueness based on available system information:
151

152
1. **Machine + Process + Time**: Full `uniqid()` method in Node.js environments
153
   - Unique across multiple machines and processes
154
   - 18-byte hexatridecimal strings
155
   - Components: MAC address + process ID + monotonic timestamp
156

157
2. **Process + Time**: `uniqid.process()` method
158
   - Unique across multiple processes on single machine
159
   - 12-byte hexatridecimal strings
160
   - Components: process ID + monotonic timestamp
161

162
3. **Time Only**: `uniqid.time()` method or fallback behavior
163
   - Unique within single process
164
   - 8-byte hexatridecimal strings
165
   - Components: monotonic timestamp only
166

167
## Internal Implementation Notes
168

169
- **Monotonic Time**: Uses internal `now()` helper that ensures strictly increasing timestamps even when called rapidly
170
- **MAC Address Detection**: Automatically detects first available non-zero MAC address from network interfaces
171
- **Process ID Encoding**: Converts process ID to base36 for compact representation
172
- **Webpack Detection**: Automatically detects webpack environments and disables MAC/process detection
173
- **Zero Dependencies**: No external runtime dependencies