0
# Constants and Conversions
1

2
Predefined UUID constants and conversion functions for working with different UUID formats and versions.
3

4
## Capabilities
5

6
### UUID Constants
7

8
Predefined UUID constants for special values and common use cases.
9

10
```typescript { .api }
11
/**
12
 * The nil UUID string (all zeros)
13
 * Represents a UUID that explicitly indicates "no value" or "null UUID"
14
 */
15
const NIL: string; // '00000000-0000-0000-0000-000000000000'
16

17
/**
18
 * The max UUID string (all ones)  
19
 * Represents the maximum possible UUID value
20
 */
21
const MAX: string; // 'ffffffff-ffff-ffff-ffff-ffffffffffff'
22
```
23

24
**Usage Examples:**
25

26
```typescript
27
import { NIL, MAX, validate } from "uuid";
28

29
// Use NIL UUID as default/empty value
30
let currentSessionId: string = NIL;
31

32
function startSession() {
33
  currentSessionId = v4(); // Generate new session ID
34
}
35

36
function endSession() {
37
  currentSessionId = NIL; // Reset to nil value
38
}
39

40
function hasActiveSession(): boolean {
41
  return currentSessionId !== NIL;
42
}
43

44
// Use MAX UUID for range operations
45
function isUuidInRange(uuid: string, min: string = NIL, max: string = MAX): boolean {
46
  return validate(uuid) && uuid >= min && uuid <= max;
47
}
48

49
// Constants are valid UUIDs
50
console.log(validate(NIL)); // ⇨ true
51
console.log(validate(MAX)); // ⇨ true
52
```
53

54
### Namespace Constants
55

56
Predefined namespace UUIDs for v3 and v5 generation, available both as properties on the respective functions and as direct exports.
57

58
```typescript { .api }
59
/**
60
 * DNS namespace UUID for v3 generation
61
 * Standard namespace for domain names
62
 */
63
v3.DNS: string; // '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
64

65
/**
66
 * URL namespace UUID for v3 generation  
67
 * Standard namespace for URLs
68
 */
69
v3.URL: string; // '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
70

71
/**
72
 * DNS namespace UUID for v5 generation (same as v3.DNS)
73
 * Standard namespace for domain names
74
 */
75
v5.DNS: string; // '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
76

77
/**
78
 * URL namespace UUID for v5 generation (same as v3.URL)
79
 * Standard namespace for URLs  
80
 */
81
v5.URL: string; // '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
82

83
/**
84
 * DNS namespace UUID (direct export)
85
 * Same value as v3.DNS and v5.DNS
86
 */
87
const DNS: string; // '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
88

89
/**
90
 * URL namespace UUID (direct export)
91
 * Same value as v3.URL and v5.URL
92
 */
93
const URL: string; // '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
94
```
95

96
**Usage Examples:**
97

98
```typescript
99
import { v3, v5, DNS, URL } from "uuid";
100

101
// DNS-based UUIDs for domain names
102
const domainId = v5('example.com', v5.DNS);
103
const subdomainId = v5('api.example.com', v5.DNS);
104

105
// URL-based UUIDs for web resources
106
const pageId = v5('https://example.com/page', v5.URL);
107
const apiId = v5('https://api.example.com/users', v5.URL);
108

109
// Use direct exports (equivalent to function properties)
110
const directDnsId = v5('example.com', DNS);
111
const directUrlId = v5('https://example.com/page', URL);
112

113
// All equivalent ways to access namespace constants
114
console.log(v3.DNS === v5.DNS); // ⇨ true
115
console.log(v3.URL === v5.URL); // ⇨ true
116
console.log(DNS === v3.DNS);    // ⇨ true
117
console.log(URL === v3.URL);    // ⇨ true
118

119
// Generate consistent IDs across runs
120
function getResourceId(url: string): string {
121
  return v5(url, v5.URL); // Always returns same UUID for same URL
122
}
123
```
124

125
### Version Conversion Functions
126

127
Functions to convert between UUID version 1 and version 6, which have compatible timestamp information but different field ordering.
128

129
```typescript { .api }
130
/**
131
 * Convert version 1 UUID to version 6 UUID
132
 * Reorders timestamp fields for better database performance and sorting
133
 * @param uuid - Version 1 UUID (string or bytes)
134
 * @returns Version 6 UUID in same format as input
135
 */
136
function v1ToV6(uuid: string): string;
137
function v1ToV6(uuid: Uint8Array): Uint8Array;
138

139
/**
140
 * Convert version 6 UUID to version 1 UUID  
141
 * Restores original v1 timestamp field ordering
142
 * @param uuid - Version 6 UUID (string or bytes)
143
 * @returns Version 1 UUID in same format as input  
144
 */
145
function v6ToV1(uuid: string): string;
146
function v6ToV1(uuid: Uint8Array): Uint8Array;
147
```
148

149
**Usage Examples:**
150

151
```typescript
152
import { v1, v6, v1ToV6, v6ToV1, version } from "uuid";
153

154
// Generate v1 UUID and convert to v6
155
const v1Id = v1();
156
const v6Id = v1ToV6(v1Id);
157

158
console.log(version(v1Id)); // ⇨ 1
159
console.log(version(v6Id)); // ⇨ 6
160

161
// Round-trip conversion preserves timestamp information
162
const backToV1 = v6ToV1(v6Id);
163
console.log(v1Id === backToV1); // ⇨ true
164

165
// Convert binary UUIDs
166
const v1Bytes = new Uint8Array(16);
167
v1(undefined, v1Bytes);
168

169
const v6Bytes = v1ToV6(v1Bytes);
170
const backToV1Bytes = v6ToV1(v6Bytes);
171

172
console.log(v1Bytes.every((byte, i) => byte === backToV1Bytes[i])); // ⇨ true
173

174
// Database optimization: convert existing v1 UUIDs to v6 for better indexing
175
function migrateUuidsToV6(v1Uuids: string[]): string[] {
176
  return v1Uuids.map(uuid => {
177
    if (version(uuid) === 1) {
178
      return v1ToV6(uuid);
179
    }
180
    return uuid; // Leave non-v1 UUIDs unchanged
181
  });
182
}
183

184
// Performance comparison
185
const v1Uuid = v1();
186
const v6Uuid = v1ToV6(v1Uuid);
187

188
// v6 UUIDs sort chronologically better than v1
189
const timestampedIds = [
190
  v1(), v1(), v1(), v1(), v1()
191
].map(id => v1ToV6(id));
192

193
timestampedIds.sort(); // Natural chronological ordering
194
```
195

196
### Combined Usage Patterns
197

198
Common patterns using constants and conversions together:
199

200
```typescript
201
import { NIL, MAX, v1, v6, v1ToV6, v6ToV1, v5, validate } from "uuid";
202

203
// Initialize with NIL, upgrade to timestamped UUIDs
204
class SessionManager {
205
  private sessionId: string = NIL;
206
  
207
  start(): string {
208
    this.sessionId = v6(); // Use v6 for better DB performance
209
    return this.sessionId;
210
  }
211
  
212
  end(): void {
213
    this.sessionId = NIL;
214
  }
215
  
216
  isActive(): boolean {
217
    return this.sessionId !== NIL;
218
  }
219
  
220
  getId(): string {
221
    return this.sessionId;
222
  }
223
}
224

225
// UUID range operations using constants
226
function createUuidRange(start: string = NIL, end: string = MAX) {
227
  if (!validate(start) || !validate(end)) {
228
    throw new Error('Invalid UUID range bounds');
229
  }
230
  
231
  return {
232
    contains(uuid: string): boolean {
233
      return validate(uuid) && uuid >= start && uuid <= end;
234
    },
235
    
236
    toString(): string {
237
      return `${start}..${end}`;
238
    }
239
  };
240
}
241

242
// Legacy v1 to modern v6 migration
243
function modernizeTimestampUuids(uuids: string[]): {
244
  converted: string[],
245
  unchanged: string[],
246
  invalid: string[]
247
} {
248
  const result = {
249
    converted: [] as string[],
250
    unchanged: [] as string[],
251
    invalid: [] as string[]
252
  };
253
  
254
  for (const uuid of uuids) {
255
    if (!validate(uuid)) {
256
      result.invalid.push(uuid);
257
      continue;
258
    }
259
    
260
    if (version(uuid) === 1) {
261
      result.converted.push(v1ToV6(uuid));
262
    } else {
263
      result.unchanged.push(uuid);
264
    }
265
  }
266
  
267
  return result;
268
}
269
```