0
# UUID Conversion
1

2
Bidirectional conversion utilities between ULIDs and standard UUIDs, enabling interoperability with existing systems that use UUID formats.
3

4
## Capabilities
5

6
### ULID to UUID Conversion
7

8
Converts a ULID to a standard UUID format (8-4-4-4-12 hexadecimal pattern).
9

10
```typescript { .api }
11
/**
12
 * Convert a ULID to a UUID
13
 * @param ulid - The ULID to convert
14
 * @returns A UUID string in standard format
15
 * @throws ULIDError if the ULID is invalid
16
 */
17
function ulidToUUID(ulid: ULID): UUID;
18
```
19

20
**Usage Examples:**
21

22
```typescript
23
import { ulidToUUID, ulid } from "ulid";
24

25
// Convert generated ULID to UUID
26
const id = ulid(); // "01HNZX8JGFACFA36RBXDHEQN6E"
27
const uuid = ulidToUUID(id); // "0191E9A4-8F21-7516-B3F1-4D6C5E7F8A9B"
28

29
// Convert existing ULID
30
const existingUlid = "01ARYZ6S41TSV4RRFFQ69G5FAV";
31
const convertedUuid = ulidToUUID(existingUlid); // "0158AFDC-C3E3-7A3A-FFFB-1A5C9E5FAF5F"
32

33
// Use in database operations
34
function storeInLegacySystem(ulidString: string) {
35
  try {
36
    const uuidFormat = ulidToUUID(ulidString);
37
    // Store in system that expects UUID format
38
    return database.insert({ id: uuidFormat, ...data });
39
  } catch (error) {
40
    console.error("Invalid ULID for conversion:", error.message);
41
  }
42
}
43

44
// Batch conversion
45
const ulids = ["01HNZX8JGFACFA36RBXDHEQN6E", "01ARYZ6S41TSV4RRFFQ69G5FAV"];
46
const uuids = ulids.map(ulidToUUID);
47
```
48

49
**Error Conditions:**
50

51
- Throws `ULIDError` with code `ULIDInvalid` if the input ULID is malformed
52
- Performs validation before conversion to ensure data integrity
53

54
### UUID to ULID Conversion
55

56
Converts a standard UUID to ULID format.
57

58
```typescript { .api }
59
/**
60
 * Convert a UUID to a ULID
61
 * @param uuid - The UUID to convert (with or without hyphens)
62
 * @returns A ULID string
63
 * @throws ULIDError if the UUID is invalid
64
 */
65
function uuidToULID(uuid: string): ULID;
66
```
67

68
**Usage Examples:**
69

70
```typescript
71
import { uuidToULID } from "ulid";
72

73
// Convert standard UUID to ULID
74
const uuid = "0191E9A4-8F21-7516-B3F1-4D6C5E7F8A9B";
75
const ulid = uuidToULID(uuid); // "01HNZX8JGFACFA36RBXDHEQN6E"
76

77
// Convert UUID without hyphens
78
const uuidWithoutHyphens = "0191E9A48F217516B3F14D6C5E7F8A9B";
79
const ulidFromPlain = uuidToULID(uuidWithoutHyphens); // Same result
80

81
// Migrate legacy data
82
async function migrateToULID(legacyRecords: { id: string }[]) {
83
  return legacyRecords.map(record => ({
84
    ...record,
85
    id: uuidToULID(record.id)
86
  }));
87
}
88

89
// Handle mixed case UUIDs
90
const mixedCaseUuid = "0191e9a4-8f21-7516-b3f1-4d6c5e7f8a9b";
91
const convertedUlid = uuidToULID(mixedCaseUuid); // Works with any case
92
```
93

94
**Error Conditions:**
95

96
- Throws `ULIDError` with code `UUIDInvalid` if the input UUID format is invalid
97
- Throws `ULIDError` with code `Unexpected` if UUID parsing fails unexpectedly
98

99
**UUID Format Support:**
100

101
The conversion functions support standard UUID formats:
102

103
- **Standard format**: `XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX`
104
- **Case insensitive**: Both uppercase and lowercase hexadecimal digits
105
- **With hyphens**: Standard UUID format with separating hyphens
106
- **Without hyphens**: Plain 32-character hexadecimal string (for `uuidToULID` only)
107

108
**Conversion Properties:**
109

110
- **Bijective**: Converting ULID→UUID→ULID preserves the original value
111
- **Deterministic**: Same input always produces same output
112
- **128-bit preservation**: Full bit precision maintained during conversion
113
- **Lexicographic ordering**: ULIDs maintain chronological ordering, UUIDs do not
114

115
**Interoperability Examples:**
116

117
```typescript
118
import { ulid, ulidToUUID, uuidToULID, isValid } from "ulid";
119

120
// Round-trip conversion verification
121
const originalUlid = ulid();
122
const uuid = ulidToUUID(originalUlid);
123
const backToUlid = uuidToULID(uuid);
124

125
console.log(originalUlid === backToUlid); // true - perfect round-trip
126

127
// Integration with existing UUID-based systems
128
class LegacyAdapter {
129
  // Store as ULID, expose as UUID for legacy compatibility
130
  store(data: any) {
131
    const id = ulid();
132
    const legacyId = ulidToUUID(id);
133
    return { ...data, id, legacyId };
134
  }
135
  
136
  // Accept UUID from legacy system, convert to ULID internally
137
  retrieve(legacyId: string) {
138
    const internalId = uuidToULID(legacyId);
139
    return database.findByULID(internalId);
140
  }
141
}
142
```
143

144
## Types
145

146
```typescript { .api }
147
type UUID = string;
148
type ULID = string;
149
```