0
# Touch
1

2
Touch is a Node.js implementation of the Unix touch(1) command functionality for creating empty files and updating access/modification timestamps. It provides both synchronous and asynchronous APIs with comprehensive options for controlling file timestamp behavior.
3

4
## Package Information
5

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

11
## Core Imports
12

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

17
For ES modules:
18

19
```javascript
20
import touch from "touch";
21
```
22

23
## Basic Usage
24

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

28
// Create or update a file's timestamps to current time
29
await touch("path/to/file.txt");
30

31
// Create with specific options
32
await touch("path/to/file.txt", {
33
  atime: true,     // Update access time only
34
  nocreate: false, // Create file if it doesn't exist
35
  time: new Date("2023-01-01") // Set specific time
36
});
37

38
// Synchronous version
39
touch.sync("path/to/file.txt");
40
```
41

42
## Capabilities
43

44
### Main Touch Function
45

46
Creates or updates a file's access and modification timestamps asynchronously.
47

48
```javascript { .api }
49
/**
50
 * Touch a file to update its access and modification times
51
 * @param {string} f - Path to the file to touch
52
 * @param {TouchOptions} [options] - Configuration options
53
 * @param {Function} [callback] - Optional callback function
54
 * @returns {Promise<undefined>} Promise that resolves to undefined when operation completes
55
 */
56
function touch(f, options, callback);
57
```
58

59
### Synchronous Touch
60

61
Synchronous version of the main touch function.
62

63
```javascript { .api }
64
/**
65
 * Synchronously touch a file to update its timestamps
66
 * @param {string} f - Path to the file to touch
67
 * @param {TouchOptions} [options] - Configuration options
68
 * @returns {undefined}
69
 */
70
function touchSync(f, options);
71

72
// Also available as:
73
touch.sync(f, options);
74
```
75

76
### File Descriptor Touch
77

78
Touch a file using an existing file descriptor instead of a path.
79

80
```javascript { .api }
81
/**
82
 * Touch a file using file descriptor
83
 * @param {number} fd - File descriptor
84
 * @param {TouchOptions} [options] - Configuration options
85
 * @param {Function} [callback] - Optional callback function
86
 * @returns {Promise<undefined>} Promise that resolves to undefined when operation completes
87
 */
88
function ftouch(fd, options, callback);
89

90
// Available as:
91
touch.ftouch(fd, options, callback);
92
```
93

94
### Synchronous File Descriptor Touch
95

96
Synchronous version of file descriptor touch.
97

98
```javascript { .api }
99
/**
100
 * Synchronously touch a file using file descriptor
101
 * @param {number} fd - File descriptor
102
 * @param {TouchOptions} [opt] - Configuration options
103
 * @returns {undefined}
104
 */
105
function ftouchSync(fd, opt);
106

107
// Available as:
108
touch.ftouchSync(fd, opt);
109
```
110

111
### Command Line Interface
112

113
Touch provides a CLI binary that mimics Unix touch(1) behavior.
114

115
```bash { .api }
116
# Install globally to use CLI
117
npm install -g touch
118

119
# Basic usage
120
nodetouch file1 file2 file3
121

122
# Update access time only
123
nodetouch -a file.txt
124

125
# Update modification time only  
126
nodetouch -m file.txt
127

128
# Don't create file if it doesn't exist
129
nodetouch -c file.txt
130

131
# Force operation
132
nodetouch -f file.txt
133

134
# Use reference file's timestamps
135
nodetouch -r reference.txt target.txt
136

137
# Set specific time (format: [[CC]YY]MMDDhhmm[.SS])
138
nodetouch -t 202301011200.00 file.txt
139
```
140

141
## Types and Options
142

143
```javascript { .api }
144
/**
145
 * Configuration options for touch operations
146
 */
147
interface TouchOptions {
148
  /** Force operation like touch -f */
149
  force?: boolean;
150
  
151
  /** Set specific time - Date object, parseable string, or epoch ms */
152
  time?: Date | string | number;
153
  
154
  /** Update access time only (like touch -a) - boolean, Date, or epoch seconds */
155
  atime?: boolean | Date | number;
156
  
157
  /** Update modification time only (like touch -m) - boolean, Date, or epoch seconds */
158
  mtime?: boolean | Date | number;
159
  
160
  /** Reference file path to copy timestamps from (like touch -r) */
161
  ref?: string;
162
  
163
  /** Don't create file if it doesn't exist (like touch -c) */
164
  nocreate?: boolean;
165
  
166
  /** Close file descriptor after operation (only for ftouch/ftouchSync) */
167
  closeAfter?: boolean;
168
}
169
```
170

171
## Usage Examples
172

173
### Basic File Creation and Updates
174

175
```javascript
176
const touch = require("touch");
177

178
// Create a new file or update existing file to current time
179
await touch("new-file.txt");
180

181
// Create multiple files
182
await Promise.all([
183
  touch("file1.txt"),
184
  touch("file2.txt"),
185
  touch("file3.txt")
186
]);
187

188
// Synchronous version
189
touch.sync("sync-file.txt");
190
```
191

192
### Timestamp Control
193

194
```javascript
195
// Set specific timestamps
196
await touch("file.txt", {
197
  time: new Date("2023-06-15T10:30:00Z")
198
});
199

200
// Update only access time
201
await touch("file.txt", {
202
  atime: true
203
});
204

205
// Update only modification time
206
await touch("file.txt", {
207
  mtime: true
208
});
209

210
// Set different times for access and modification
211
await touch("file.txt", {
212
  atime: new Date("2023-01-01"),
213
  mtime: new Date("2023-06-01")
214
});
215
```
216

217
### Reference File Timestamps
218

219
```javascript
220
// Copy timestamps from another file
221
await touch("new-file.txt", {
222
  ref: "reference-file.txt"
223
});
224
```
225

226
### File Descriptor Operations
227

228
```javascript
229
const fs = require("fs");
230

231
// Open file and touch using file descriptor
232
const fd = fs.openSync("file.txt", "w");
233
await touch.ftouch(fd, {
234
  time: new Date()
235
});
236
fs.closeSync(fd);
237

238
// Synchronous version
239
const fd2 = fs.openSync("file2.txt", "w");
240
touch.ftouchSync(fd2, {
241
  atime: true,
242
  mtime: true
243
});
244
fs.closeSync(fd2);
245

246
// Using closeAfter option to automatically close the file descriptor
247
const fd3 = fs.openSync("file3.txt", "w");
248
await touch.ftouch(fd3, {
249
  time: new Date(),
250
  closeAfter: true // Automatically closes fd3 after operation
251
});
252
```
253

254
### Advanced Options
255

256
```javascript
257
// Don't create file if it doesn't exist
258
await touch("maybe-exists.txt", {
259
  nocreate: true
260
});
261

262
// Force operation
263
await touch("readonly-file.txt", {
264
  force: true
265
});
266

267
// Combined options
268
await touch("complex-file.txt", {
269
  force: true,
270
  nocreate: false,
271
  atime: new Date("2023-01-01"),
272
  mtime: true  // Will use current time
273
});
274
```
275

276
### Error Handling
277

278
```javascript
279
// With callback
280
touch("file.txt", { time: new Date() }, (err) => {
281
  if (err) {
282
    console.error("Touch failed:", err.message);
283
  } else {
284
    console.log("File touched successfully");
285
  }
286
});
287

288
// With Promise
289
try {
290
  await touch("file.txt");
291
  console.log("Success");
292
} catch (err) {
293
  console.error("Touch failed:", err.message);
294
}
295

296
// Common error scenarios:
297
// - ENOENT: File doesn't exist and nocreate is true
298
// - EACCES: Permission denied
299
// - EISDIR: Target is a directory (handled gracefully)
300
```
301

302
## CLI Usage Patterns
303

304
```bash
305
# Create empty files
306
nodetouch file1.txt file2.txt
307

308
# Update existing files to current time
309
nodetouch existing-file.txt
310

311
# Set specific timestamp
312
nodetouch -t 202312251200.00 christmas-file.txt
313

314
# Copy timestamps from reference file
315
nodetouch -r source.txt target1.txt target2.txt
316

317
# Update access time only, don't create if missing
318
nodetouch -ac important-file.txt
319

320
# Force update on read-only file
321
nodetouch -f readonly-file.txt
322
```