0
# ULID
1

2
ULID provides a high-performance generator for Universally Unique Lexicographically Sortable Identifiers. ULIDs are 26-character identifiers that offer lexicographic sortability, case insensitivity, URL safety, and 128-bit UUID compatibility, making them ideal for distributed systems where chronological ordering is important.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```typescript
14
import { 
15
  ulid, 
16
  monotonicFactory, 
17
  isValid, 
18
  decodeTime, 
19
  encodeTime,
20
  ulidToUUID,
21
  uuidToULID,
22
  fixULIDBase32,
23
  incrementBase32,
24
  ULIDError,
25
  ULIDErrorCode,
26
  MAX_ULID,
27
  MIN_ULID,
28
  TIME_LEN,
29
  TIME_MAX
30
} from "ulid";
31
```
32

33
For CommonJS:
34

35
```javascript
36
const { 
37
  ulid, 
38
  monotonicFactory, 
39
  isValid, 
40
  decodeTime, 
41
  encodeTime,
42
  ulidToUUID,
43
  uuidToULID,
44
  fixULIDBase32,
45
  incrementBase32,
46
  ULIDError,
47
  ULIDErrorCode,
48
  MAX_ULID,
49
  MIN_ULID,
50
  TIME_LEN,
51
  TIME_MAX
52
} = require("ulid");
53
```
54

55
## Basic Usage
56

57
```typescript
58
import { ulid, monotonicFactory, isValid } from "ulid";
59

60
// Generate a single ULID
61
const id = ulid(); // "01HNZXD07M5CEN5XA66EMZSRZW"
62

63
// Create a monotonic factory for ordering within the same millisecond
64
const factory = monotonicFactory();
65
const id1 = factory(); // "01HNZXD07M5CEN5XA66EMZSRZA"  
66
const id2 = factory(); // "01HNZXD07M5CEN5XA66EMZSRZB"
67

68
// Validate a ULID
69
if (isValid(id)) {
70
  console.log("Valid ULID");
71
}
72

73
// Extract timestamp from ULID
74
const timestamp = decodeTime(id);
75
console.log(new Date(timestamp));
76
```
77

78
## Architecture
79

80
ULID is built around several core components:
81

82
- **ID Generation**: Core `ulid()` function and `monotonicFactory()` for ordered generation
83
- **Time Encoding**: Timestamp encoding/decoding utilities with millisecond precision
84
- **Validation**: ULID format validation and error handling  
85
- **UUID Interop**: Bidirectional conversion between ULIDs and UUIDs
86
- **Base32 Utilities**: Crockford Base32 encoding with error correction
87
- **PRNG Detection**: Automatic detection of cryptographically-secure random number generators
88

89
## Capabilities
90

91
### ULID Generation
92

93
Core functionality for generating ULIDs with optional monotonic ordering to ensure lexicographic sortability within the same millisecond.
94

95
```typescript { .api }
96
function ulid(seedTime?: number, prng?: PRNG): ULID;
97
function monotonicFactory(prng?: PRNG): ULIDFactory;
98

99
type ULID = string;
100
type ULIDFactory = (seedTime?: number) => ULID;
101
type PRNG = () => number;
102
```
103

104
[ULID Generation](./generation.md)
105

106
### Time Utilities
107

108
Functions for encoding and decoding timestamps in ULID format, allowing extraction of creation time from any ULID.
109

110
```typescript { .api }
111
function encodeTime(now: number, len?: number): string;
112
function decodeTime(id: ULID): number;
113
```
114

115
[Time Utilities](./time-utilities.md)
116

117
### Validation
118

119
ULID format validation to ensure proper structure and encoding.
120

121
```typescript { .api }
122
function isValid(id: string): boolean;
123
```
124

125
[Validation](./validation.md)
126

127
### UUID Conversion
128

129
Bidirectional conversion utilities between ULIDs and standard UUIDs for interoperability with existing systems.
130

131
```typescript { .api }
132
function ulidToUUID(ulid: ULID): UUID;
133
function uuidToULID(uuid: string): ULID;
134

135
type UUID = string;
136
```
137

138
[UUID Conversion](./uuid-conversion.md)
139

140
### Base32 Utilities
141

142
Utilities for working with Crockford Base32 encoding, including error correction and string manipulation for ULID components.
143

144
```typescript { .api }
145
function fixULIDBase32(id: string): string;
146
function incrementBase32(str: string): string;
147
```
148

149
[Base32 Utilities](./base32-utilities.md)
150

151
## Constants
152

153
```typescript { .api }
154
const MAX_ULID: string; // "7ZZZZZZZZZZZZZZZZZZZZZZZZZ"
155
const MIN_ULID: string; // "00000000000000000000000000"
156
const TIME_LEN: number; // 10
157
const TIME_MAX: number; // 281474976710655 (2^48 - 1)
158
```
159

160
## Error Handling
161

162
```typescript { .api }
163
class ULIDError extends Error {
164
  code: ULIDErrorCode;
165
  constructor(errorCode: ULIDErrorCode, message: string);
166
}
167

168
enum ULIDErrorCode {
169
  Base32IncorrectEncoding = "B32_ENC_INVALID",
170
  DecodeTimeInvalidCharacter = "DEC_TIME_CHAR",
171
  DecodeTimeValueMalformed = "DEC_TIME_MALFORMED", 
172
  EncodeTimeNegative = "ENC_TIME_NEG",
173
  EncodeTimeSizeExceeded = "ENC_TIME_SIZE_EXCEED",
174
  EncodeTimeValueMalformed = "ENC_TIME_MALFORMED",
175
  PRNGDetectFailure = "PRNG_DETECT",
176
  ULIDInvalid = "ULID_INVALID",
177
  Unexpected = "UNEXPECTED",
178
  UUIDInvalid = "UUID_INVALID"
179
}
180
```
181

182
## CLI Tool
183

184
The package includes a command-line tool for generating ULIDs:
185

186
```bash
187
# Install globally for CLI usage
188
npm install -g ulid
189

190
# Generate a single ULID
191
ulid
192

193
# Generate multiple ULIDs
194
ulid --count=5
195
```
196

197
The CLI uses the monotonic factory to ensure proper ordering when generating multiple ULIDs in sequence.