0
# Directory Operations
1

2
Temporary directory creation and management with configurable cleanup policies including recursive removal of non-empty directories.
3

4
## Capabilities
5

6
### Asynchronous Directory Creation
7

8
Creates a temporary directory asynchronously.
9

10
```javascript { .api }
11
/**
12
 * Creates a temporary directory
13
 * @param {Options|Function} options - Configuration options or callback function  
14
 * @param {Function} callback - Callback function (err, path, cleanupCallback) => void
15
 */
16
function dir(options, callback);
17
```
18

19
**Callback Parameters:**
20
- `err` (Error|null): Error object or null if successful
21
- `path` (string): Full path to the created temporary directory
22
- `cleanupCallback` (Function): Function to manually remove the directory
23

24
**Usage Examples:**
25

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

29
// Basic directory creation
30
tmp.dir(function(err, path, cleanupCallback) {
31
  if (err) throw err;
32
  
33
  console.log("Temp directory:", path);
34
  
35
  // Use the directory - create files, subdirectories, etc.
36
  const fs = require("fs");
37
  fs.writeFileSync(path + "/test.txt", "test content");
38
  
39
  // Clean up when done
40
  cleanupCallback();
41
});
42

43
// Directory creation with custom options
44
tmp.dir({ 
45
  mode: 0o755, 
46
  prefix: "myapp-workspace-",
47
  unsafeCleanup: true  // Allow removal even if not empty
48
}, function(err, path, cleanupCallback) {
49
  if (err) throw err;
50
  
51
  console.log("Custom temp directory:", path);
52
  
53
  // Create nested structure
54
  const fs = require("fs");
55
  fs.mkdirSync(path + "/subdir");
56
  fs.writeFileSync(path + "/subdir/file.txt", "nested content");
57
  
58
  // This will work because unsafeCleanup is true
59
  cleanupCallback();
60
});
61

62
// Template-based directory naming
63
tmp.dir({ template: "build-XXXXXX" }, function(err, path, cleanupCallback) {
64
  if (err) throw err;
65
  
66
  console.log("Template directory:", path);
67
  // Path will be like: /tmp/build-abc123
68
  
69
  cleanupCallback();
70
});
71
```
72

73
### Synchronous Directory Creation
74

75
Creates a temporary directory synchronously.
76

77
```javascript { .api }
78
/**
79
 * Creates a temporary directory synchronously
80
 * @param {Options} options - Configuration options
81
 * @returns {DirSyncObject} Object with name and removeCallback
82
 * @throws {Error} If directory creation fails
83
 */
84
function dirSync(options);
85
```
86

87
**Return Value:**
88
```javascript { .api }
89
interface DirSyncObject {
90
  name: string;                // Full path to the temporary directory
91
  removeCallback: Function;    // Cleanup function
92
}
93
```
94

95
**Usage Examples:**
96

97
```javascript
98
const tmp = require("tmp");
99
const fs = require("fs");
100

101
// Basic synchronous directory creation
102
const tmpDir = tmp.dirSync();
103
console.log("Temp directory:", tmpDir.name);
104

105
// Use the directory
106
fs.writeFileSync(tmpDir.name + "/data.json", JSON.stringify({test: true}));
107

108
// Clean up
109
tmpDir.removeCallback();
110

111
// Directory with custom permissions and naming
112
const workDir = tmp.dirSync({
113
  mode: 0o750,
114
  prefix: "workspace-",
115
  postfix: "-tmp"
116
});
117

118
console.log("Work directory:", workDir.name);
119

120
// Create project structure
121
fs.mkdirSync(workDir.name + "/src");
122
fs.mkdirSync(workDir.name + "/dist");
123
fs.writeFileSync(workDir.name + "/package.json", "{}");
124

125
workDir.removeCallback();
126

127
// Template directory in custom location
128
const buildDir = tmp.dirSync({
129
  template: "build-XXXXXX",
130
  dir: "builds",  // Create in /tmp/builds/build-XXXXXX
131
  unsafeCleanup: true
132
});
133

134
// Create build artifacts
135
fs.writeFileSync(buildDir.name + "/output.js", "// generated code");
136
fs.mkdirSync(buildDir.name + "/assets");
137

138
buildDir.removeCallback(); // Will remove even with contents due to unsafeCleanup
139
```
140

141
### Directory Cleanup Behavior
142

143
By default, directories can only be removed if they are empty. Use the `unsafeCleanup` option for recursive removal:
144

145
#### Safe Cleanup (Default)
146

147
```javascript
148
tmp.dir(function(err, path, cleanupCallback) {
149
  const fs = require("fs");
150
  
151
  // Create some content
152
  fs.writeFileSync(path + "/file.txt", "content");
153
  
154
  // This will fail because directory is not empty
155
  cleanupCallback(function(err) {
156
    if (err) {
157
      console.log("Cleanup failed:", err.message);
158
      // You need to manually empty the directory first
159
      fs.unlinkSync(path + "/file.txt");
160
      cleanupCallback(); // Now this will work
161
    }
162
  });
163
});
164
```
165

166
#### Unsafe Cleanup (Recursive)
167

168
```javascript
169
tmp.dir({ unsafeCleanup: true }, function(err, path, cleanupCallback) {
170
  const fs = require("fs");
171
  
172
  // Create nested content
173
  fs.mkdirSync(path + "/subdir");
174
  fs.writeFileSync(path + "/subdir/file.txt", "content");
175
  
176
  // This will succeed and remove everything recursively
177
  cleanupCallback();
178
});
179
```
180

181
### Directory Options
182

183
All directory operations support the following options:
184

185
```javascript { .api }
186
interface DirectoryOptions {
187
  mode?: number;               // Directory permissions (default: 0o700)
188
  prefix?: string;             // Directory name prefix (default: "tmp")  
189
  postfix?: string;            // Directory name postfix
190
  template?: string;           // Template with XXXXXX (e.g., "temp-XXXXXX")
191
  name?: string;               // Fixed directory name (relative to dir/tmpdir)
192
  dir?: string;                // Parent directory within tmpdir  
193
  tmpdir?: string;             // Override system temp directory
194
  tries?: number;              // Max naming attempts (default: 3)
195
  keep?: boolean;              // Skip automatic cleanup
196
  unsafeCleanup?: boolean;     // Allow recursive removal of non-empty directories
197
}
198
```
199

200
**Important Notes:**
201

202
- Directory permissions default to `0o700` (owner access only) for security
203
- Without `unsafeCleanup: true`, cleanup will fail if the directory contains any files or subdirectories
204
- The `unsafeCleanup` option uses recursive removal similar to `rm -rf`
205
- When using `unsafeCleanup`, be very careful as it will remove all contents without confirmation
206
- Template patterns work the same as with files - exactly one `XXXXXX` sequence gets replaced
207
- Fixed names via the `name` option must not contain path separators and cannot be absolute paths