{"id":15244,"library":"touch","title":"Node.js Touch Utility","description":"The `touch` package for Node.js provides a cross-platform implementation of the Unix `touch(1)` command, enabling programmatic modification of file access and modification times, or the creation of new, empty files. Its current stable version is 3.1.1. The package offers both asynchronous (Promise-based and callback-based) and synchronous APIs, including `touch()`, `touch.sync()`, `touch.ftouch()`, and `touch.ftouchSync()`. A key differentiator is its dual API for file path and file descriptor manipulation, alongside a `nodetouch` CLI executable that mirrors the native `touch` utility. Release cadence is not explicitly stated, but the package maintains a stable API and provides consistent functionality across Node.js versions, focusing on reliable file system interaction.","status":"active","version":"3.1.1","language":"javascript","source_language":"en","source_url":"git://github.com/isaacs/node-touch","tags":["javascript"],"install":[{"cmd":"npm install touch","lang":"bash","label":"npm"},{"cmd":"yarn add touch","lang":"bash","label":"yarn"},{"cmd":"pnpm add touch","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"import { touch } from 'touch'","symbol":"touch","correct":"import touch from 'touch'"},{"note":"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.","symbol":"touch (CommonJS)","correct":"const touch = require('touch')"},{"note":"`sync` is a method on the default-exported `touch` object, not a named export itself.","wrong":"import { sync } from 'touch'","symbol":"touch.sync","correct":"import touch from 'touch'; touch.sync('file.txt')"}],"quickstart":{"code":"import touch from 'touch';\nimport { promises as fs } from 'fs';\n\nconst filename = 'my-file.txt';\nconst existingFilename = 'existing.txt';\n\nasync function runTouchExamples() {\n  console.log('--- Async Touch Example ---');\n  try {\n    // Create a new file or update timestamp if it exists\n    await touch(filename, { nocreate: false });\n    console.log(`Touched (or created) ${filename}`);\n\n    // Update only modification time of an existing file\n    await fs.writeFile(existingFilename, 'Some content.');\n    console.log(`Created ${existingFilename} for modification example.`);\n\n    const newModTime = new Date('2023-01-15T10:00:00Z');\n    await touch(existingFilename, { mtime: newModTime });\n    console.log(`Updated modification time of ${existingFilename} to ${newModTime.toISOString()}`);\n\n  } catch (error) {\n    console.error(`Async operation failed: ${error.message}`);\n  }\n\n  console.log('\\n--- Sync Touch Example ---');\n  try {\n    const syncFilename = 'sync-file.txt';\n    touch.sync(syncFilename, { time: new Date() });\n    console.log(`Touched (or created) ${syncFilename} synchronously.`);\n  } catch (error) {\n    console.error(`Sync operation failed: ${error.message}`);\n  }\n}\n\nrunTouchExamples().finally(async () => {\n  // Clean up created files\n  try {\n    await fs.unlink(filename).catch(() => {});\n    await fs.unlink(existingFilename).catch(() => {});\n    await fs.unlink('sync-file.txt').catch(() => {});\n    console.log('\\nCleaned up example files.');\n  } catch (err) {\n    console.error(`Cleanup failed: ${err.message}`);\n  }\n});","lang":"javascript","description":"Demonstrates both asynchronous (Promise-based) and synchronous usage of the `touch` library to create files and update their timestamps, including specific modification times."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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()`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"The Node.js process lacks the necessary write permissions for the specified file or directory.","error":"Error: EACCES: permission denied, open 'file.txt'"},{"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.","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.","error":"TypeError: Cannot read properties of undefined (reading 'sync')"},{"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.","cause":"The `time` option (or `atime`, `mtime`) was provided with a string that `Date.parse()` cannot interpret as a valid date.","error":"Error: Invalid Date: 'SomeInvalidDateString'"}],"ecosystem":"npm"}