0
# UUID
1

2
UUID is a comprehensive TypeScript library for generating RFC9562 (formerly RFC4122) compliant UUIDs. It supports all UUID versions (v1, v3, v4, v5, v6, v7) with secure random value generation, zero dependencies, and cross-platform compatibility for Node.js, browsers, and React Native.
3

4
## Package Information
5

6
- **Package Name**: uuid
7
- **Package Type**: npm
8
- **Language**: TypeScript (includes built-in types)
9
- **Installation**: `npm install uuid`
10

11
## Core Imports
12

13
```typescript
14
import { 
15
  v1, v3, v4, v5, v6, v7, 
16
  parse, stringify, unsafeStringify, stringToBytes,
17
  validate, version, v1ToV6, v6ToV1,
18
  NIL, MAX, DNS, URL 
19
} from "uuid";
20
```
21

22
For CommonJS:
23

24
```javascript
25
const { 
26
  v1, v3, v4, v5, v6, v7, 
27
  parse, stringify, unsafeStringify, stringToBytes,
28
  validate, version, v1ToV6, v6ToV1,
29
  NIL, MAX, DNS, URL 
30
} = require("uuid");
31
```
32

33
Individual imports:
34

35
```typescript
36
import { v4 as uuidv4 } from "uuid";
37
import { parse as uuidParse, unsafeStringify } from "uuid";
38
import { DNS, URL } from "uuid";
39
```
40

41
## Basic Usage
42

43
```typescript
44
import { v4, v1, validate, parse, stringify } from "uuid";
45

46
// Generate random UUID (most common)
47
const randomId = v4(); // ⇨ '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'
48

49
// Generate timestamp-based UUID
50
const timestampId = v1(); // ⇨ '4f20936c-6e8f-11ef-8f2f-d1234567890a'
51

52
// Validate UUID
53
const isValid = validate(randomId); // ⇨ true
54

55
// Convert between string and bytes
56
const bytes = parse(randomId); // ⇨ Uint8Array(16)
57
const backToString = stringify(bytes); // ⇨ '9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d'
58
```
59

60
## Architecture
61

62
The UUID package is structured around several core components:
63

64
- **UUID Generation**: Functions for creating UUIDs of different versions (v1-v7)
65
- **UUID Utilities**: Functions for parsing, stringifying, validating, and version detection
66
- **Constants**: Predefined UUID values (NIL, MAX) and namespace constants
67
- **Type System**: Complete TypeScript definitions with generic buffer support
68
- **Conversion Functions**: Convert between UUID versions (v1↔v6)
69

70
## Capabilities
71

72
### UUID Generation
73

74
Core UUID generation functions supporting all RFC9562 versions, each optimized for different use cases from timestamp-based to namespace-based to random generation.
75

76
```typescript { .api }
77
// Random UUID (most common)
78
function v4(options?: Version4Options): string;
79
function v4<TBuf extends Uint8Array>(options: Version4Options | undefined, buf: TBuf, offset?: number): TBuf;
80

81
// Timestamp-based UUIDs
82
function v1(options?: Version1Options): string;
83
function v1<TBuf extends Uint8Array>(options: Version1Options | undefined, buf: TBuf, offset?: number): TBuf;
84

85
function v6(options?: Version6Options): string;
86
function v6<TBuf extends Uint8Array>(options: Version6Options | undefined, buf: TBuf, offset?: number): TBuf;
87

88
function v7(options?: Version7Options): string;
89
function v7<TBuf extends Uint8Array>(options: Version7Options | undefined, buf: TBuf, offset?: number): TBuf;
90

91
// Namespace-based UUIDs
92
function v3(value: string | Uint8Array, namespace: UUIDTypes): string;
93
function v3<TBuf extends Uint8Array>(value: string | Uint8Array, namespace: UUIDTypes, buf: TBuf, offset?: number): TBuf;
94

95
function v5(value: string | Uint8Array, namespace: UUIDTypes): string;
96
function v5<TBuf extends Uint8Array>(value: string | Uint8Array, namespace: UUIDTypes, buf: TBuf, offset?: number): TBuf;
97
```
98

99
[UUID Generation](./uuid-generation.md)
100

101
### UUID Utilities
102

103
Essential utility functions for working with UUIDs including parsing, stringifying, validation, version detection, and string conversion.
104

105
```typescript { .api }
106
function parse(uuid: string): Uint8Array;
107
function stringify(arr: Uint8Array, offset?: number): string;
108
function unsafeStringify(arr: Uint8Array, offset?: number): string;
109
function stringToBytes(str: string): Uint8Array;
110
function validate(uuid: unknown): boolean;
111
function version(uuid: string): number;
112
```
113

114
[UUID Utilities](./uuid-utilities.md)
115

116
### Constants and Conversions
117

118
Predefined UUID constants and conversion functions for working with different UUID formats and versions.
119

120
```typescript { .api }
121
const NIL: string; // '00000000-0000-0000-0000-000000000000'
122
const MAX: string; // 'ffffffff-ffff-ffff-ffff-ffffffffffff'
123
const DNS: string; // '6ba7b810-9dad-11d1-80b4-00c04fd430c8'
124
const URL: string; // '6ba7b811-9dad-11d1-80b4-00c04fd430c8'
125

126
function v1ToV6(uuid: string): string;
127
function v1ToV6(uuid: Uint8Array): Uint8Array;
128

129
function v6ToV1(uuid: string): string;
130
function v6ToV1(uuid: Uint8Array): Uint8Array;
131
```
132

133
[Constants and Conversions](./constants-conversions.md)
134

135
## Types
136

137
Primary types used throughout the UUID package:
138

139
```typescript { .api }
140
type UUIDTypes<TBuf extends Uint8Array = Uint8Array> = string | TBuf;
141

142
type Version1Options = {
143
  node?: Uint8Array;
144
  clockseq?: number;
145
  random?: Uint8Array;
146
  rng?: () => Uint8Array;
147
  msecs?: number;
148
  nsecs?: number;
149
  _v6?: boolean; // Internal use only!
150
};
151

152
type Version4Options = {
153
  random?: Uint8Array;
154
  rng?: () => Uint8Array;
155
};
156

157
type Version6Options = Version1Options;
158

159
type Version7Options = {
160
  random?: Uint8Array;
161
  msecs?: number;
162
  seq?: number;
163
  rng?: () => Uint8Array;
164
};
165
```