Node.js Touch Utility

Common errors

• Error: EACCES: permission denied, open 'file.txt'

  cause The Node.js process lacks the necessary write permissions for the specified file or directory.
  fix Verify and adjust file/directory permissions for the user running the Node.js application. On Unix-like systems, `chmod` or `chown` can be used. Consider running the process with appropriate user privileges.

• TypeError: Cannot read properties of undefined (reading 'sync')

  cause The `touch` object was not correctly imported or initialized, often due to incorrect CommonJS `require` or ESM `import` syntax, or the module failed to load.
  fix Ensure you are importing the module correctly: `const touch = require('touch')` for CommonJS or `import touch from 'touch'` for ESM. Verify that `touch` is the default export and its methods are accessed correctly.

• Error: Invalid Date: 'SomeInvalidDateString'

  cause The `time` option (or `atime`, `mtime`) was provided with a string that `Date.parse()` cannot interpret as a valid date.
  fix Provide a valid `Date` object, a string parseable by `Date.parse()` (e.g., ISO 8601 format), or an epoch millisecond number for time options.

Warnings

• gotcha When `atime` or `mtime` are specified, only the specified time is updated. If neither is set, both access and modification times are updated. This can be a source of confusion if only one time is intended for update but no specific option is passed.
  Fix: Explicitly set `atime: false` or `mtime: false` if you intend to only update one timestamp, or pass a specific `Date` object to the desired option.
• gotcha Mixing callbacks and Promises: The async functions return a Promise, but if a callback is provided, it's attached to the Promise. This can lead to dual handling or confusion if both patterns are used simultaneously.
  Fix: Choose either callback-based or Promise-based error handling and success notification consistently. Avoid providing a callback if you intend to `await` the Promise or use `.then().catch()`.
• gotcha File permission errors: Operations might fail with `EACCES` or similar permission errors if Node.js does not have the necessary write permissions to the target directory or file.
  Fix: Ensure the Node.js process has appropriate file system permissions for the target path. Run the application with elevated privileges if necessary (e.g., `sudo node app.js`) or change directory/file permissions using `chmod`.

Install

• npm install touch npm
• yarn add touch yarn
• pnpm add touch pnpm

Imports

• touch
  wrong:

  import { touch } from 'touch'

  correct:

  import touch from 'touch'

  The primary API surface is exported as the default, making functions like `touch.sync` available as properties on the imported object. Named imports are not used.
• touch (CommonJS)

  const touch = require('touch')

  This is the documented and historically common way to import the library, especially in older Node.js projects. The `touch` object then exposes all methods.
• touch.sync
  wrong:

  import { sync } from 'touch'

  correct:

  import touch from 'touch'; touch.sync('file.txt')

  `sync` is a method on the default-exported `touch` object, not a named export itself.

Quickstart

Demonstrates both asynchronous (Promise-based) and synchronous usage of the `touch` library to create files and update their timestamps, including specific modification times.

import touch from 'touch';
import { promises as fs } from 'fs';

const filename = 'my-file.txt';
const existingFilename = 'existing.txt';

async function runTouchExamples() {
  console.log('--- Async Touch Example ---');
  try {
    // Create a new file or update timestamp if it exists
    await touch(filename, { nocreate: false });
    console.log(`Touched (or created) ${filename}`);

    // Update only modification time of an existing file
    await fs.writeFile(existingFilename, 'Some content.');
    console.log(`Created ${existingFilename} for modification example.`);

    const newModTime = new Date('2023-01-15T10:00:00Z');
    await touch(existingFilename, { mtime: newModTime });
    console.log(`Updated modification time of ${existingFilename} to ${newModTime.toISOString()}`);

  } catch (error) {
    console.error(`Async operation failed: ${error.message}`);
  }

  console.log('\n--- Sync Touch Example ---');
  try {
    const syncFilename = 'sync-file.txt';
    touch.sync(syncFilename, { time: new Date() });
    console.log(`Touched (or created) ${syncFilename} synchronously.`);
  } catch (error) {
    console.error(`Sync operation failed: ${error.message}`);
  }
}

runTouchExamples().finally(async () => {
  // Clean up created files
  try {
    await fs.unlink(filename).catch(() => {});
    await fs.unlink(existingFilename).catch(() => {});
    await fs.unlink('sync-file.txt').catch(() => {});
    console.log('\nCleaned up example files.');
  } catch (err) {
    console.error(`Cleanup failed: ${err.message}`);
  }
});