0
# ULID Generation
1

2
Core functionality for generating ULIDs with support for both simple generation and monotonic factories that ensure lexicographic ordering within the same millisecond.
3

4
## Capabilities
5

6
### ULID Function
7

8
Generates a single ULID with optional custom timestamp and PRNG.
9

10
```typescript { .api }
11
/**
12
 * Generate a ULID
13
 * @param seedTime - Optional time seed (default: Date.now())
14
 * @param prng - Optional PRNG function (default: auto-detected)
15
 * @returns A ULID string
16
 */
17
function ulid(seedTime?: number, prng?: PRNG): ULID;
18
```
19

20
**Usage Examples:**
21

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

25
// Generate with current timestamp
26
const id1 = ulid(); // "01HNZXD07M5CEN5XA66EMZSRZW"
27

28
// Generate with specific timestamp
29
const customTime = Date.now();
30
const id2 = ulid(customTime); // "01HNZXD07M5CEN5XA66EMZSRZ0"
31

32
// Generate with custom PRNG
33
const customPrng = () => Math.random();
34
const id3 = ulid(undefined, customPrng);
35
```
36

37
### Monotonic Factory
38

39
Creates a factory function that generates monotonically increasing ULIDs within the same millisecond, ensuring proper lexicographic ordering.
40

41
```typescript { .api }
42
/**
43
 * Create a ULID factory to generate monotonically-increasing ULIDs
44
 * @param prng - Optional PRNG to use (default: auto-detected)
45
 * @returns A ULID factory function
46
 */
47
function monotonicFactory(prng?: PRNG): ULIDFactory;
48

49
/**
50
 * ULID factory function type
51
 * @param seedTime - Optional time seed (default: Date.now())
52
 * @returns A ULID string
53
 */
54
type ULIDFactory = (seedTime?: number) => ULID;
55
```
56

57
**Usage Examples:**
58

59
```typescript
60
import { monotonicFactory } from "ulid";
61

62
// Create a monotonic factory
63
const factory = monotonicFactory();
64

65
// Generate ordered ULIDs within the same millisecond  
66
const id1 = factory(); // "01HNZXD07M5CEN5XA66EMZSRZA"
67
const id2 = factory(); // "01HNZXD07M5CEN5XA66EMZSRZB" 
68
const id3 = factory(); // "01HNZXD07M5CEN5XA66EMZSRZC"
69

70
// Use with specific timestamp
71
const timestamp = Date.now();
72
const id4 = factory(timestamp);
73
const id5 = factory(timestamp); // Will increment random portion
74

75
// Create factory with custom PRNG
76
const customFactory = monotonicFactory(() => 0.5);
77
```
78

79
**Monotonic Behavior:**
80

81
When multiple ULIDs are generated with the same timestamp (either explicitly or within the same millisecond), the monotonic factory ensures lexicographic ordering by:
82

83
1. Using the same timestamp for the time portion
84
2. Incrementing the random portion using Base32 arithmetic
85
3. Maintaining the increment across subsequent calls until the timestamp changes
86

87
### PRNG Type
88

89
Pseudo-random number generator function type used throughout the library.
90

91
```typescript { .api }
92
/**
93
 * Pseudo-random number generator function
94
 * Should return a number between 0 (inclusive) and 1 (exclusive)
95
 */
96
type PRNG = () => number;
97
```
98

99
The library automatically detects the best available PRNG in the current environment:
100

101
- **Browser**: `crypto.getRandomValues()` or `msCrypto.getRandomValues()`
102
- **Node.js**: `crypto.randomBytes()`
103
- **Web Workers**: `self.crypto.getRandomValues()`
104

105
## Types
106

107
```typescript { .api }
108
type ULID = string;
109
type ULIDFactory = (seedTime?: number) => ULID;
110
type PRNG = () => number;
111
```