0
# Tmp
1

2
Tmp is a widely-used Node.js library for creating temporary files and directories with automatic cleanup capabilities. It provides both asynchronous and synchronous APIs for secure temporary filesystem object creation using crypto-based randomness with configurable options and comprehensive cleanup control.
3

4
## Package Information
5

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

11
## Core Imports
12

13
```javascript
14
const tmp = require("tmp");
15
```
16

17
For destructured imports:
18

19
```javascript
20
const { file, fileSync, dir, dirSync, tmpName, tmpNameSync, setGracefulCleanup } = require("tmp");
21
```
22

23
## Basic Usage
24

25
```javascript
26
const tmp = require("tmp");
27

28
// Enable automatic cleanup on process exit
29
tmp.setGracefulCleanup();
30

31
// Create a temporary file asynchronously
32
tmp.file(function(err, path, fd, cleanupCallback) {
33
  if (err) throw err;
34
  
35
  console.log("Temp file created:", path);
36
  console.log("File descriptor:", fd);
37
  
38
  // Use the file...
39
  
40
  // Manual cleanup (optional - happens automatically if setGracefulCleanup was called)
41
  cleanupCallback();
42
});
43

44
// Create a temporary directory synchronously
45
const tmpDir = tmp.dirSync();
46
console.log("Temp directory:", tmpDir.name);
47

48
// Use the directory...
49

50
// Manual cleanup
51
tmpDir.removeCallback();
52
```
53

54
## Architecture
55

56
The tmp library is built around several key concepts:
57

58
- **Dual API Pattern**: Every operation has both asynchronous and synchronous versions
59
- **Crypto-based Security**: Uses crypto.randomBytes for secure name generation with fallback to pseudo-random
60
- **Automatic Cleanup**: Optional graceful cleanup on process exit via setGracefulCleanup()
61
- **Fine-grained Control**: Comprehensive options for file modes, naming patterns, and descriptor management
62
- **Zero Dependencies**: Self-contained implementation with no runtime dependencies
63

64
## Capabilities
65

66
### File Operations
67

68
Create and manage temporary files with full control over file descriptors, permissions, and cleanup behavior.
69

70
```javascript { .api }
71
function file(options, callback);
72
function fileSync(options);
73
```
74

75
[File Operations](./file-operations.md)
76

77
### Directory Operations  
78

79
Create temporary directories with configurable cleanup policies including recursive removal of non-empty directories.
80

81
```javascript { .api }
82
function dir(options, callback);
83
function dirSync(options);
84
```
85

86
[Directory Operations](./directory-operations.md)
87

88
### Name Generation
89

90
Generate unique temporary filenames without creating actual filesystem objects, useful for custom file creation workflows.
91

92
```javascript { .api }
93
function tmpName(options, callback);
94
function tmpNameSync(options);
95
```
96

97
[Name Generation](./name-generation.md)
98

99
### Cleanup Management
100

101
Control automatic cleanup behavior and access to the system temporary directory.
102

103
```javascript { .api }
104
function setGracefulCleanup();
105
```
106

107
```javascript { .api }
108
// Property getter for current temporary directory
109
tmp.tmpdir // string
110
```
111

112
[Cleanup Management](./cleanup-management.md)
113

114
## Types
115

116
```javascript { .api }
117
// Options object for all operations
118
interface Options {
119
  keep?: boolean;              // Skip garbage collection 
120
  tries?: number;              // Max attempts for name generation (default: 3)
121
  mode?: number;               // File/directory permissions (default: 0o600/0o700)
122
  template?: string;           // mkstemp-like template with XXXXXX pattern
123
  name?: string;               // Fixed name relative to tmpdir or dir
124
  dir?: string;                // Directory relative to root tmpdir
125
  prefix?: string;             // Name prefix (default: "tmp")
126
  postfix?: string;            // Name postfix
127
  tmpdir?: string;             // Override OS temp directory
128
  unsafeCleanup?: boolean;     // Recursively remove non-empty directories
129
  detachDescriptor?: boolean;  // Caller manages file descriptor
130
  discardDescriptor?: boolean; // Close file descriptor immediately
131
}
132

133
// Return object for fileSync
134
interface FileSyncObject {
135
  name: string;                // Path to temporary file
136
  fd: number;                  // File descriptor (-1 if discarded)
137
  removeCallback: Function;    // Cleanup function
138
}
139

140
// Return object for dirSync  
141
interface DirSyncObject {
142
  name: string;                // Path to temporary directory
143
  removeCallback: Function;    // Cleanup function
144
}
145
```