als-watcher

als-watcher is a Node.js file system watcher which monitors a specific folder and emits events for file actions such as adding, deleting, changing, or renaming files. It allows filtering by file types and controls the depth of directory monitoring. It's compatible with ES Modules and CommonJS.

Install

npm install als-watcher

Basic usage

import watchDirectory from 'als-watcher';
// const watchDirectory = require('als-watcher');
const srcDir = 'path_to_your_directory';
const extensions = ['js','html']; // watch only js and html files
const depth = 4; // watch maximum to 4th level depth
const watcher = watchDirectory(srcDir,extensions,depth);

watcher.emitter.on('rename', (oldName, newName) => console.log(`Renamed: ${oldName} -> ${newName}`));
watcher.emitter.on('change', filename => console.log(`Changed: ${filename}`));
watcher.emitter.on('add', filename => console.log(`Added: ${filename}`));
watcher.emitter.on('unlink', filename => console.log(`Removed: ${filename}`));
watcher.emitter.on('operation', (event,...params) => console.log(event,...params));
watcher.emitter.on('error', error => console.log('Error',error));

Events

als-watcher Events Explanation

• rename Event

  • Trigger: When a file or directory is renamed.
  • Parameters: oldName, newName.
  • Usage: Track when a file or directory gets a new name, useful for updating references in databases or file indexes.

• change Event

  • Trigger: When the contents of a file are modified.
  • Parameters: filename.
  • Usage: Detect edits or updates to a file, trigger backups, logging, or real-time file synchronization.

• add Event

  • Trigger: When a new file or directory is added.
  • Parameters: filename.
  • Usage: Monitor new files creation, automate file processing, indexing, or notify users of new content.

• unlink Event

  • Trigger: When a file or directory is deleted.
  • Parameters: filename.
  • Usage: Maintain accurate file system state, remove references to deleted files, or trigger cleanup processes.

• operation Event

  • Trigger: A generic event for all operations (all events except error).
  • Parameters: event, ...params.
  • Usage: A catch-all for different file system events, provides flexibility in handling with a single handler.

• error Event

  • Trigger: In case of any errors during file watching.
  • Parameters: error.
  • Usage: Essential for error handling and logging, identifies issues with the file watching process for corrective actions or alerts.

Examples

Example 1: Automated Backup on File Change

Scenario:You want to create backups of certain files whenever they change, ensuring that you always have a recent version saved.

Implementation

import watchDirectory from 'als-watcher';
const srcDir = 'path_to_documents';
const extensions = ['docx', 'xlsx']; // Watch only Word and Excel files
const watcher = watchDirectory(srcDir, extensions);

watcher.emitter.on('change', (filename) => {
  // Logic to create a backup of the modified file
  console.log(`Backup created for changed file: ${filename}`);
});

Example2: Monitoring and Logging File System Activities

Scenario: For security or management purposes, you need to monitor a directory and log every file addition, deletion, or renaming activity.

Implementation

import watchDirectory from 'als-watcher';
const srcDir = 'path_to_monitored_directory';
const watcher = watchDirectory(srcDir);
watcher.emitter.on('add', (filename) => console.log(`File added: ${filename}`))
watcher.emitter.on('unlink', (filename) => console.log(`File removed: ${filename}`))
watcher.emitter.on('rename', (oldName, newName) => console.log(`File renamed from ${oldName} to ${newName}`));

Limitations of the File Watcher

This program does not support the tracking of symbolic links in the file system.

1. Recursive Monitoring

• Platform Dependency: The recursive option in fs.watch is not consistently supported across all platforms. For instance, it works well on Windows, but may not be available on other operating systems like Linux. Users should be aware of this limitation when running the watcher on different systems.
• Limited Depth: On platforms where recursive monitoring is supported, the depth of the recursion (i.e., how many subdirectories deep the monitoring is effective) might be limited and inconsistent.

2. Performance and Scalability

• Resource Intensive: Continuously monitoring a directory, especially one with a large number of files, can be resource-intensive. The performance may degrade as the size of the directory or the frequency of file updates increases.

3. Handling Concurrent Events

• Event Overlap: Rapid, concurrent file events might not be accurately captured or might lead to race conditions. The system might struggle to correctly differentiate between various types of events (like add, change, and rename) when they occur in quick succession.
• Delay in Detection: There can be a delay between the occurrence of file changes and their detection by the watcher, leading to potential issues in real-time applications.
• Order of Events: The order in which events are received and processed might not always reflect the actual order of file changes, especially during high file activity.

4. General Usage Notes

• Designed for Basic Monitoring: This implementation is intended for basic file change monitoring. It may not be suitable for complex scenarios requiring high accuracy or real-time processing.