0
# UUID Generation
1

2
Comprehensive UUID generation functions supporting all RFC9562 versions, each optimized for different use cases from random generation to timestamp-based to namespace-based UUIDs.
3

4
## Capabilities
5

6
### Version 4 (Random) UUID
7

8
Generates a random UUID using cryptographically secure random values. This is the most commonly used UUID version.
9

10
```typescript { .api }
11
/**
12
 * Generate a random UUID version 4
13
 * @param options - Optional configuration for random generation
14
 * @returns UUID string in canonical format
15
 */
16
function v4(options?: Version4Options): string;
17

18
/**
19
 * Generate a random UUID version 4 into a buffer
20
 * @param options - Optional configuration for random generation
21
 * @param buf - Buffer to write UUID bytes to
22
 * @param offset - Starting offset in buffer (default: 0)
23
 * @returns The buffer with UUID bytes written
24
 */
25
function v4<TBuf extends Uint8Array>(
26
  options: Version4Options | undefined,
27
  buf: TBuf,
28
  offset?: number
29
): TBuf;
30

31
type Version4Options = {
32
  /** Custom random bytes (must be 16 bytes) */
33
  random?: Uint8Array;
34
  /** Custom random number generator function */
35
  rng?: () => Uint8Array;
36
};
37
```
38

39
**Usage Examples:**
40

41
```typescript
42
import { v4 } from "uuid";
43

44
// Basic random UUID
45
const id = v4(); // ⇨ '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'
46

47
// Custom random source
48
const customId = v4({
49
  random: crypto.getRandomValues(new Uint8Array(16))
50
});
51

52
// Write to buffer
53
const buffer = new Uint8Array(16);
54
v4(undefined, buffer);
55
```
56

57
### Version 1 (Timestamp) UUID
58

59
Generates a UUID based on timestamp and MAC address (or random node). Provides temporal ordering but may reveal information about when and where it was generated.
60

61
```typescript { .api }
62
/**
63
 * Generate a timestamp-based UUID version 1
64
 * @param options - Optional configuration for timestamp generation
65
 * @returns UUID string in canonical format
66
 */
67
function v1(options?: Version1Options): string;
68

69
/**
70
 * Generate a timestamp-based UUID version 1 into a buffer
71
 * @param options - Optional configuration for timestamp generation
72
 * @param buf - Buffer to write UUID bytes to
73
 * @param offset - Starting offset in buffer (default: 0)
74
 * @returns The buffer with UUID bytes written
75
 */
76
function v1<TBuf extends Uint8Array>(
77
  options: Version1Options | undefined,
78
  buf: TBuf,
79
  offset?: number
80
): TBuf;
81

82
type Version1Options = {
83
  /** Node ID as a 6-byte array (defaults to random) */
84
  node?: Uint8Array;
85
  /** Custom clock sequence (0-0x3fff) */
86
  clockseq?: number;
87
  /** Custom random bytes for node/clock fields */
88
  random?: Uint8Array;
89
  /** Custom random number generator */
90
  rng?: () => Uint8Array;
91
  /** Custom timestamp in milliseconds since epoch */
92
  msecs?: number;
93
  /** Custom nanoseconds (0-9999) */
94
  nsecs?: number;
95
};
96
```
97

98
**Usage Examples:**
99

100
```typescript
101
import { v1 } from "uuid";
102

103
// Basic timestamp UUID
104
const timestampId = v1(); // ⇨ '4f20936c-6e8f-11ef-8f2f-d1234567890a'
105

106
// Custom node and timestamp
107
const customId = v1({
108
  node: new Uint8Array([0x01, 0x23, 0x45, 0x67, 0x89, 0xab]),
109
  msecs: Date.now(),
110
  nsecs: 1234
111
});
112
```
113

114
### Version 6 (Reordered Timestamp) UUID
115

116
Similar to v1 but with reordered timestamp fields for better database performance and natural sorting.
117

118
```typescript { .api }
119
/**
120
 * Generate a reordered timestamp UUID version 6
121
 * @param options - Optional configuration (same as v1)
122
 * @returns UUID string in canonical format
123
 */
124
function v6(options?: Version6Options): string;
125

126
/**
127
 * Generate a reordered timestamp UUID version 6 into a buffer
128
 * @param options - Optional configuration (same as v1)
129
 * @param buf - Buffer to write UUID bytes to
130
 * @param offset - Starting offset in buffer (default: 0)
131
 * @returns The buffer with UUID bytes written
132
 */
133
function v6<TBuf extends Uint8Array>(
134
  options: Version6Options | undefined,
135
  buf: TBuf,
136
  offset?: number
137
): TBuf;
138

139
type Version6Options = Version1Options;
140
```
141

142
**Usage Examples:**
143

144
```typescript
145
import { v6 } from "uuid";
146

147
// Basic v6 UUID (better for databases)
148
const sortableId = v6(); // ⇨ '1ef6e8f0-936c-6f20-8f2f-d1234567890a'
149

150
// Same options as v1
151
const customV6 = v6({
152
  msecs: Date.now(),
153
  nsecs: 5000
154
});
155
```
156

157
### Version 7 (Unix Epoch Time) UUID
158

159
Generates UUIDs based on Unix Epoch timestamp with millisecond precision, designed for modern applications requiring time-ordered UUIDs.
160

161
```typescript { .api }
162
/**
163
 * Generate a Unix Epoch time-based UUID version 7
164
 * @param options - Optional configuration for time-based generation
165
 * @returns UUID string in canonical format
166
 */
167
function v7(options?: Version7Options): string;
168

169
/**
170
 * Generate a Unix Epoch time-based UUID version 7 into a buffer
171
 * @param options - Optional configuration for time-based generation
172
 * @param buf - Buffer to write UUID bytes to
173
 * @param offset - Starting offset in buffer (default: 0)
174
 * @returns The buffer with UUID bytes written
175
 */
176
function v7<TBuf extends Uint8Array>(
177
  options: Version7Options | undefined,
178
  buf: TBuf,
179
  offset?: number
180
): TBuf;
181

182
type Version7Options = {
183
  /** Custom random bytes for randomness fields */
184
  random?: Uint8Array;
185
  /** Custom timestamp in milliseconds since Unix epoch */
186
  msecs?: number;
187
  /** Custom sequence counter for same-millisecond ordering */
188
  seq?: number;
189
  /** Custom random number generator */
190
  rng?: () => Uint8Array;
191
};
192
```
193

194
**Usage Examples:**
195

196
```typescript
197
import { v7 } from "uuid";
198

199
// Basic v7 UUID (time-ordered)
200
const timeId = v7(); // ⇨ '01912e9a-b123-7456-9abc-def012345678'
201

202
// Custom timestamp and sequence
203
const customV7 = v7({
204
  msecs: Date.now(),
205
  seq: 12345
206
});
207
```
208

209
### Version 3 (Namespace + MD5) UUID
210

211
Generates deterministic UUIDs based on a namespace UUID and a name using MD5 hashing.
212

213
```typescript { .api }
214
/**
215
 * Generate a namespace-based UUID version 3 using MD5
216
 * @param value - The name to hash (string or bytes)
217
 * @param namespace - Namespace UUID (string or bytes)
218
 * @returns UUID string in canonical format
219
 */
220
function v3(value: string | Uint8Array, namespace: UUIDTypes): string;
221

222
/**
223
 * Generate a namespace-based UUID version 3 into a buffer
224
 * @param value - The name to hash (string or bytes)
225
 * @param namespace - Namespace UUID (string or bytes)
226
 * @param buf - Buffer to write UUID bytes to
227
 * @param offset - Starting offset in buffer (default: 0)
228
 * @returns The buffer with UUID bytes written
229
 */
230
function v3<TBuf extends Uint8Array>(
231
  value: string | Uint8Array,
232
  namespace: UUIDTypes,
233
  buf: TBuf,
234
  offset?: number
235
): TBuf;
236
```
237

238
**Namespace Constants:**
239

240
```typescript { .api }
241
// Predefined namespace UUIDs
242
v3.DNS: string;    // '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
243
v3.URL: string;    // '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
244
```
245

246
**Usage Examples:**
247

248
```typescript
249
import { v3 } from "uuid";
250

251
// DNS namespace
252
const dnsId = v3('example.com', v3.DNS);
253
// ⇨ '9073926b-929f-31c2-abc9-fad77ae3e8eb'
254

255
// URL namespace
256
const urlId = v3('https://example.com/page', v3.URL);
257
// ⇨ '3d813cbb-47fb-32ba-91df-831e1593ac29'
258

259
// Custom namespace
260
const customNamespace = '550e8400-e29b-41d4-a716-446655440000';
261
const customId = v3('my-resource', customNamespace);
262
```
263

264
### Version 5 (Namespace + SHA-1) UUID
265

266
Similar to v3 but uses SHA-1 instead of MD5 for stronger cryptographic hashing.
267

268
```typescript { .api }
269
/**
270
 * Generate a namespace-based UUID version 5 using SHA-1
271
 * @param value - The name to hash (string or bytes)
272
 * @param namespace - Namespace UUID (string or bytes)
273
 * @returns UUID string in canonical format
274
 */
275
function v5(value: string | Uint8Array, namespace: UUIDTypes): string;
276

277
/**
278
 * Generate a namespace-based UUID version 5 into a buffer
279
 * @param value - The name to hash (string or bytes)
280
 * @param namespace - Namespace UUID (string or bytes)
281
 * @param buf - Buffer to write UUID bytes to
282
 * @param offset - Starting offset in buffer (default: 0)
283
 * @returns The buffer with UUID bytes written
284
 */
285
function v5<TBuf extends Uint8Array>(
286
  value: string | Uint8Array,
287
  namespace: UUIDTypes,
288
  buf: TBuf,
289
  offset?: number
290
): TBuf;
291
```
292

293
**Namespace Constants:**
294

295
```typescript { .api }
296
// Predefined namespace UUIDs (same as v3)
297
v5.DNS: string;    // '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
298
v5.URL: string;    // '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
299
```
300

301
**Usage Examples:**
302

303
```typescript
304
import { v5 } from "uuid";
305

306
// DNS namespace (recommended over v3)
307
const dnsId = v5('example.com', v5.DNS);
308
// ⇨ '2ed6657d-e927-568b-95e1-2665a8aea6a2'
309

310
// URL namespace
311
const urlId = v5('https://example.com/page', v5.URL);
312
// ⇨ '3bbcee75-cecc-5b56-8031-b6641c1ed1f1'
313

314
// Generate from bytes
315
const nameBytes = new TextEncoder().encode('my-name');
316
const bytesId = v5(nameBytes, v5.DNS);
317
```
318

319
## Buffer Operations
320

321
All UUID generation functions support writing directly to buffers for performance-critical applications:
322

323
```typescript
324
import { v4, v1, v7 } from "uuid";
325

326
// Pre-allocated buffer
327
const buffer = new Uint8Array(16);
328

329
// Write different UUID versions to the same buffer
330
v4(undefined, buffer);        // Random UUID
331
v1(undefined, buffer);        // Timestamp UUID
332
v7(undefined, buffer);        // Unix Epoch UUID
333

334
// Custom buffer types
335
const nodeBuffer = Buffer.alloc(16);
336
v4(undefined, nodeBuffer);    // Works with Node.js Buffer
337
```