0
# unique-slug
1

2
unique-slug generates unique 8-character hexadecimal strings suitable for use in filenames and URLs. It offers two modes of operation: random generation using Math.random() for unpredictable identifiers, and deterministic generation using MurmurHash3 algorithm for consistent hashes from input strings.
3

4
## Package Information
5

6
- **Package Name**: unique-slug
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install unique-slug`
10

11
## Core Imports
12

13
```javascript
14
var uniqueSlug = require('unique-slug');
15
```
16

17
For ES modules:
18

19
```javascript
20
import uniqueSlug from 'unique-slug';
21
```
22

23
## Basic Usage
24

25
```javascript
26
var uniqueSlug = require('unique-slug');
27

28
// Generate random slug
29
var randomSlug = uniqueSlug();
30
console.log(randomSlug); // e.g., "a1b2c3d4"
31

32
// Generate deterministic slug from string
33
var fileSlug = uniqueSlug('/etc/passwd');
34
console.log(fileSlug); // Always produces same output for same input
35
```
36

37
## Capabilities
38

39
### Unique Slug Generation
40

41
Generates a unique 8-character hexadecimal string using either random generation or deterministic hashing.
42

43
```javascript { .api }
44
/**
45
 * Generate a unique character string suitable for use in files and URLs
46
 * @param {string} [uniq] - Optional string to hash deterministically
47
 * @returns {string} 8-character hexadecimal string
48
 */
49
function uniqueSlug(uniq);
50
```
51

52
**Parameters:**
53
- `uniq` (optional): String - If provided, generates a deterministic hash using MurmurHash3. If omitted, generates a random 8-character hex string.
54

55
**Returns:**
56
- `string`: Always returns exactly 8 hexadecimal characters (0-9, a-f)
57

58
**Behavior:**
59
- **With `uniq` parameter**: Uses MurmurHash3 to create a consistent hash from the input string, padded with leading zeros to ensure 8 characters
60
- **Without `uniq` parameter**: Uses Math.random() to generate random bytes, converted to hexadecimal and padded to 8 characters
61

62
**Usage Examples:**
63

64
```javascript
65
var uniqueSlug = require('unique-slug');
66

67
// Random generation - different each time
68
var slug1 = uniqueSlug();
69
var slug2 = uniqueSlug();
70
console.log(slug1); // e.g., "7f3a9b2c"
71
console.log(slug2); // e.g., "d4e5f6a7"
72

73
// Deterministic generation - same input produces same output
74
var pathSlug1 = uniqueSlug('/path/to/file');
75
var pathSlug2 = uniqueSlug('/path/to/file');
76
console.log(pathSlug1); // e.g., "1a2b3c4d"
77
console.log(pathSlug2); // e.g., "1a2b3c4d" (identical)
78

79
// Different inputs produce different outputs
80
var slug3 = uniqueSlug('/different/path');
81
console.log(slug3); // e.g., "9e8d7c6b" (different from pathSlug1)
82

83
// Common use cases
84
var tempFile = '/tmp/cache-' + uniqueSlug() + '.json';
85
var consistentId = uniqueSlug(userEmail + timestamp);
86
```
87

88
**Common Use Cases:**
89
- Temporary file naming
90
- Cache key generation
91
- URL-safe unique identifiers
92
- Consistent hashing for reproducible builds
93
- File system operations requiring unique names