Touch

const touch = require("touch");

import touch from "touch";

const touch = require("touch");

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

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

// Synchronous version
touch.sync("path/to/file.txt");

/**
 * Touch a file to update its access and modification times
 * @param {string} f - Path to the file to touch
 * @param {TouchOptions} [options] - Configuration options
 * @param {Function} [callback] - Optional callback function
 * @returns {Promise<undefined>} Promise that resolves to undefined when operation completes
 */
function touch(f, options, callback);

/**
 * Synchronously touch a file to update its timestamps
 * @param {string} f - Path to the file to touch
 * @param {TouchOptions} [options] - Configuration options
 * @returns {undefined}
 */
function touchSync(f, options);

// Also available as:
touch.sync(f, options);

/**
 * Touch a file using file descriptor
 * @param {number} fd - File descriptor
 * @param {TouchOptions} [options] - Configuration options
 * @param {Function} [callback] - Optional callback function
 * @returns {Promise<undefined>} Promise that resolves to undefined when operation completes
 */
function ftouch(fd, options, callback);

// Available as:
touch.ftouch(fd, options, callback);

/**
 * Synchronously touch a file using file descriptor
 * @param {number} fd - File descriptor
 * @param {TouchOptions} [opt] - Configuration options
 * @returns {undefined}
 */
function ftouchSync(fd, opt);

// Available as:
touch.ftouchSync(fd, opt);

# Install globally to use CLI
npm install -g touch

# Basic usage
nodetouch file1 file2 file3

# Update access time only
nodetouch -a file.txt

# Update modification time only  
nodetouch -m file.txt

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

# Force operation
nodetouch -f file.txt

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

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

/**
 * Configuration options for touch operations
 */
interface TouchOptions {
  /** Force operation like touch -f */
  force?: boolean;
  
  /** Set specific time - Date object, parseable string, or epoch ms */
  time?: Date | string | number;
  
  /** Update access time only (like touch -a) - boolean, Date, or epoch seconds */
  atime?: boolean | Date | number;
  
  /** Update modification time only (like touch -m) - boolean, Date, or epoch seconds */
  mtime?: boolean | Date | number;
  
  /** Reference file path to copy timestamps from (like touch -r) */
  ref?: string;
  
  /** Don't create file if it doesn't exist (like touch -c) */
  nocreate?: boolean;
  
  /** Close file descriptor after operation (only for ftouch/ftouchSync) */
  closeAfter?: boolean;
}

const touch = require("touch");

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

// Create multiple files
await Promise.all([
  touch("file1.txt"),
  touch("file2.txt"),
  touch("file3.txt")
]);

// Synchronous version
touch.sync("sync-file.txt");

// Set specific timestamps
await touch("file.txt", {
  time: new Date("2023-06-15T10:30:00Z")
});

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

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

// Set different times for access and modification
await touch("file.txt", {
  atime: new Date("2023-01-01"),
  mtime: new Date("2023-06-01")
});

// Copy timestamps from another file
await touch("new-file.txt", {
  ref: "reference-file.txt"
});

const fs = require("fs");

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

// Synchronous version
const fd2 = fs.openSync("file2.txt", "w");
touch.ftouchSync(fd2, {
  atime: true,
  mtime: true
});
fs.closeSync(fd2);

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

// Don't create file if it doesn't exist
await touch("maybe-exists.txt", {
  nocreate: true
});

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

// Combined options
await touch("complex-file.txt", {
  force: true,
  nocreate: false,
  atime: new Date("2023-01-01"),
  mtime: true  // Will use current time
});

// With callback
touch("file.txt", { time: new Date() }, (err) => {
  if (err) {
    console.error("Touch failed:", err.message);
  } else {
    console.log("File touched successfully");
  }
});

// With Promise
try {
  await touch("file.txt");
  console.log("Success");
} catch (err) {
  console.error("Touch failed:", err.message);
}

// Common error scenarios:
// - ENOENT: File doesn't exist and nocreate is true
// - EACCES: Permission denied
// - EISDIR: Target is a directory (handled gracefully)

# Create empty files
nodetouch file1.txt file2.txt

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

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

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

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

# Force update on read-only file
nodetouch -f readonly-file.txt