0
# Short UUID
1

2
Short UUID is a Node.js library that generates and translates RFC4122 v4-compliant UUIDs into shorter, more compact formats and back again. It supports multiple encoding alphabets and provides both simple quick-start functionality and advanced translator creation for custom alphabets.
3

4
## Package Information
5

6
- **Package Name**: short-uuid
7
- **Package Type**: npm
8
- **Language**: JavaScript with TypeScript definitions
9
- **Installation**: `npm install short-uuid`
10

11
## Core Imports
12

13
```javascript
14
const short = require('short-uuid');
15
```
16

17
For ES modules:
18

19
```javascript
20
import short from 'short-uuid';
21
```
22

23
## Basic Usage
24

25
```javascript
26
const short = require('short-uuid');
27

28
// Quick start - generate a short UUID with default flickrBase58 encoding
29
const shortId = short.generate(); // '73WakrfVbNJBaAmhQtEeDv'
30

31
// Create a custom translator
32
const translator = short(); // defaults to flickrBase58
33
const customTranslator = short(short.constants.cookieBase90);
34

35
// Generate and translate UUIDs
36
const shortUuid = translator.generate(); // 'mhvXdrZT4jP5T8vBxuvm75'
37
const fullUuid = translator.toUUID(shortUuid); // 'a44521d0-0fb8-4ade-8002-3385545c3318'
38
const backToShort = translator.fromUUID(fullUuid); // 'mhvXdrZT4jP5T8vBxuvm75'
39

40
// Validate short UUIDs
41
translator.validate(shortUuid); // true - format validation
42
translator.validate(shortUuid, true); // true - format + UUID validity check
43
```
44

45
## Architecture
46

47
Short UUID is built around three key components:
48

49
- **Main Constructor**: Creates translator instances with custom alphabets and options
50
- **Static Methods**: Convenience functions for quick UUID generation and access to constants
51
- **Translator Instance**: Provides methods for UUID generation, conversion, and validation with a specific alphabet
52

53
## Capabilities
54

55
### Main Constructor Function
56

57
Creates a UUID translator with custom alphabet and options.
58

59
```javascript { .api }
60
/**
61
 * Creates a UUID translator with custom alphabet and options
62
 * @param {string} [toAlphabet] - Custom alphabet for encoding (defaults to flickrBase58)
63
 * @param {Options} [options] - Configuration options
64
 * @returns {Translator} Translator instance with encoding methods
65
 * @throws {Error} Throws error if alphabet contains duplicate characters
66
 */
67
function shortUUID(toAlphabet, options);
68

69
interface Options {
70
  /** Controls padding on shortened values for consistent length (default: true) */
71
  consistentLength?: boolean;
72
}
73
```
74

75
### Static Constants
76

77
Predefined alphabet constants for common encoding schemes.
78

79
```javascript { .api }
80
const constants = {
81
  /** Safe for HTTP cookie values - 90 character alphabet */
82
  cookieBase90: "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ!#$%&'()*+-./:<=>?@[]^_`{|}~",
83
  /** Flickr-style base58 - avoids similar characters (0/O, 1/I/l, etc.) */
84
  flickrBase58: "123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ",
85
  /** UUID25 standard - 36 character alphabet for 25-character UUIDs */
86
  uuid25Base36: "0123456789abcdefghijklmnopqrstuvwxyz"
87
};
88
```
89

90
### Static UUID Generation
91

92
Generate RFC4122 v4-compliant UUIDs without creating a translator.
93

94
```javascript { .api }
95
/**
96
 * Generate a new RFC4122 v4-compliant UUID
97
 * @returns {string} Standard UUID with dashes
98
 */
99
function uuid();
100
```
101

102
### Static Short UUID Generation
103

104
Generate a short UUID using default flickrBase58 encoding.
105

106
```javascript { .api }
107
/**
108
 * Generate a short UUID using flickrBase58 encoding
109
 * @returns {string} Shortened UUID
110
 */
111
function generate();
112
```
113

114
### Translator Instance Methods
115

116
The translator instance returned by the main constructor provides these methods:
117

118
#### Generate Short UUIDs
119

120
```javascript { .api }
121
/**
122
 * Generate a new short UUID using this translator's alphabet
123
 * @returns {string} Shortened UUID
124
 */
125
generate();
126

127
/**
128
 * Generate a new short UUID using this translator's alphabet (alias for generate)
129
 * @returns {string} Shortened UUID  
130
 */
131
new();
132
```
133

134
#### UUID Conversion
135

136
```javascript { .api }
137
/**
138
 * Convert standard UUID to short format using this translator's alphabet
139
 * @param {string} regularUUID - Standard UUID with or without dashes
140
 * @returns {string} Shortened UUID
141
 */
142
fromUUID(regularUUID);
143

144
/**
145
 * Convert short UUID back to standard UUID format
146
 * @param {string} shortId - Shortened UUID
147
 * @returns {string} Standard UUID with dashes
148
 */
149
toUUID(shortId);
150
```
151

152
#### Standard UUID Generation
153

154
```javascript { .api }
155
/**
156
 * Generate a new RFC4122 v4-compliant UUID
157
 * @returns {string} Standard UUID with dashes
158
 */
159
uuid();
160
```
161

162
#### Validation
163

164
```javascript { .api }
165
/**
166
 * Validate short UUID format and optionally check UUID validity
167
 * @param {string} shortId - The string to check for validity
168
 * @param {boolean} [rigorous=false] - If true, also validates as proper UUID
169
 * @returns {boolean} True if valid according to specified criteria
170
 */
171
validate(shortId, rigorous);
172
```
173

174
### Translator Instance Properties
175

176
```javascript { .api }
177
interface Translator {
178
  /** The alphabet used for encoding UUIDs */
179
  alphabet: string;
180
  /** Maximum length in characters of a short ID using this translator */
181
  maxLength: number;
182
}
183
```
184

185
## Usage Examples
186

187
### Custom Alphabet with Options
188

189
```javascript
190
const short = require('short-uuid');
191

192
// Create translator with variable length output (like v3.x behavior)
193
const variableLength = short(short.constants.flickrBase58, {
194
  consistentLength: false
195
});
196

197
const shortId = variableLength.generate(); // Variable length output
198
```
199

200
### Working with Different Encodings
201

202
```javascript
203
const short = require('short-uuid');
204

205
// Create translators for different encodings
206
const cookieTranslator = short(short.constants.cookieBase90);
207
const flickrTranslator = short(short.constants.flickrBase58);  
208
const uuid25Translator = short(short.constants.uuid25Base36);
209

210
// Same UUID in different encodings
211
const originalUuid = short.uuid();
212
const cookieFormat = cookieTranslator.fromUUID(originalUuid);
213
const flickrFormat = flickrTranslator.fromUUID(originalUuid);
214
const uuid25Format = uuid25Translator.fromUUID(originalUuid);
215

216
// All translate back to the same UUID
217
console.log(cookieTranslator.toUUID(cookieFormat) === originalUuid); // true
218
console.log(flickrTranslator.toUUID(flickrFormat) === originalUuid); // true
219
console.log(uuid25Translator.toUUID(uuid25Format) === originalUuid); // true
220
```
221

222
### Validation Examples
223

224
```javascript
225
const translator = short();
226

227
// Format validation only (checks length and alphabet)
228
translator.validate('mhvXdrZT4jP5T8vBxuvm75'); // true
229
translator.validate('invalid-chars-!@#'); // false (invalid characters)
230
translator.validate('short'); // false (wrong length)
231

232
// Rigorous validation (format + UUID validity)
233
translator.validate('mhvXdrZT4jP5T8vBxuvm75', true); // true
234
translator.validate('1111111111111111111111', true); // false (valid format but invalid UUID)
235
```
236

237
### Error Handling
238

239
```javascript
240
const short = require('short-uuid');
241

242
// Invalid alphabet with duplicate characters throws an error
243
try {
244
  const invalidTranslator = short('001234567899aabcdef'); // Contains duplicates
245
} catch (error) {
246
  console.error('Invalid alphabet:', error.message);
247
  // Error: The provided Alphabet has duplicate characters resulting in unreliable results
248
}
249
```
250

251
## TypeScript Support
252

253
```typescript { .api }
254
// Type definitions - branded types for better type safety
255
type UUID = string & { _guidBrand: 'uuid' }; // Standard UUID format
256
type SUUID = string & { _guidBrand: 'short-uuid' }; // Shortened UUID format
257

258
interface Options {
259
  consistentLength?: boolean;
260
}
261

262
interface Translator {
263
  alphabet: string;
264
  maxLength: number;
265
  new(): SUUID;
266
  generate(): SUUID;
267
  uuid(): UUID;
268
  toUUID(shortId: string | SUUID): UUID;
269
  fromUUID(regularUUID: string | UUID): SUUID;
270
  validate(shortId: string | SUUID, rigorous?: boolean): boolean;
271
}
272

273
// Main function signature
274
declare function shortUUID(alphabet?: string, options?: Options): Translator;
275

276
// Static properties
277
declare namespace shortUUID {
278
  const constants: {
279
    cookieBase90: string;
280
    flickrBase58: string;
281
    uuid25Base36: string;
282
  };
283
  function uuid(): UUID;
284
  function generate(): SUUID;
285
}
286
```