0
# Unique Filename
1

2
Unique Filename is a lightweight JavaScript library that generates unique filenames for use in temporary directories or caches. It combines directory paths with optional prefixes and unique identifiers to create collision-free filenames, supporting both random and deterministic filename generation.
3

4
## Package Information
5

6
- **Package Name**: unique-filename
7
- **Package Type**: npm
8
- **Language**: JavaScript (CommonJS)
9
- **Installation**: `npm install unique-filename`
10
- **Node.js**: Requires Node.js ^18.17.0 || >=20.5.0
11

12
## Core Imports
13

14
```javascript
15
const uniqueFilename = require('unique-filename');
16
```
17

18
**Note**: This package uses CommonJS and does not provide ES modules (ESM) support.
19

20
## Basic Usage
21

22
```javascript
23
const uniqueFilename = require('unique-filename');
24
const os = require('os');
25

26
// Random filename in temp directory
27
// Returns something like: '/tmp/7ddd44c0' (on Unix) or 'C:\\Users\\...\\7ddd44c0' (on Windows)
28
const randomTmpfile = uniqueFilename(os.tmpdir());
29

30
// Random filename with prefix
31
// Returns something like: '/tmp/my-app-51a7b48d'
32
const prefixedTmpfile = uniqueFilename(os.tmpdir(), 'my-app');
33

34
// Deterministic filename (same input produces same output)
35
// Returns something like: '/tmp/cache-7ddd44c0'
36
const deterministicTmpfile = uniqueFilename(os.tmpdir(), 'cache', '/path/to/unique/data');
37
```
38

39
## Capabilities
40

41
### Unique Filename Generation
42

43
Generates unique filenames by combining directory paths with optional prefixes and unique identifiers.
44

45
```javascript { .api }
46
/**
47
 * Generate a unique filename for use in temporary directories or caches
48
 * @param {string} filepath - The directory path where the unique filename should be located
49
 * @param {string} [prefix] - Optional prefix to prepend to the unique part (with hyphen separator)
50
 * @param {string} [uniq] - Optional string for deterministic unique filename generation. If not provided, generates random unique part
51
 * @returns {string} Full path to a unique filename in the format 'filepath/[prefix-]uniquepart'
52
 */
53
function uniqueFilename(filepath, prefix, uniq);
54
```
55

56
**Parameters:**
57

58
- `filepath` (string, required): The directory path where the unique filename should be located. Use `os.tmpdir()` for system temporary directory.
59
- `prefix` (string, optional): An optional prefix to prepend to the unique part. If provided and not empty, it's added with a hyphen separator (`prefix-uniquepart`).
60
- `uniq` (string, optional): Optional string for deterministic unique filename generation. If provided, the same input will always produce the same filename. If omitted, generates a random unique filename.
61

62
**Return Value:**
63

64
- Returns a string containing the full path to a unique filename
65
- Format: `filepath/[prefix-]uniquepart` where `uniquepart` is an 8-character hexadecimal string
66
- Random generation produces different filenames on each call
67
- Deterministic generation produces consistent filenames for the same `uniq` input
68

69
**Usage Examples:**
70

71
```javascript
72
const uniqueFilename = require('unique-filename');
73
const os = require('os');
74
const path = require('path');
75

76
// Random filename generation
77
const tempFile1 = uniqueFilename(os.tmpdir());
78
// → '/tmp/a1b2c3d4' (Unix) or 'C:\\Users\\...\\a1b2c3d4' (Windows)
79

80
const tempFile2 = uniqueFilename(os.tmpdir());
81
// → '/tmp/e5f6g7h8' (different from tempFile1)
82

83
// Prefixed random filename
84
const logFile = uniqueFilename('/var/log', 'myapp');
85
// → '/var/log/myapp-9i0j1k2l'
86

87
// Deterministic filename generation
88
const cacheFile1 = uniqueFilename('/tmp/cache', 'data', '/path/to/source/file.json');
89
// → '/tmp/cache/data-7ddd44c0'
90

91
const cacheFile2 = uniqueFilename('/tmp/cache', 'data', '/path/to/source/file.json');
92
// → '/tmp/cache/data-7ddd44c0' (same as cacheFile1)
93

94
// Different source produces different filename
95
const cacheFile3 = uniqueFilename('/tmp/cache', 'data', '/path/to/other/file.json');
96
// → '/tmp/cache/data-a8b9c0d1' (different from cacheFile1)
97

98
// Using with path operations
99
const outputDir = '/tmp/build';
100
const outputFile = uniqueFilename(outputDir, 'bundle');
101
// → '/tmp/build/bundle-m3n4o5p6'
102
```
103

104
## Dependencies
105

106
This package depends on:
107

108
- **unique-slug** (^5.0.0): Provides the underlying unique identifier generation functionality