File System Watcher

Overview

The File System Watcher provides directory and file change notifications for FreeWorld OS. It monitors filesystem changes in real-time and notifies applications when files or directories are created, modified, deleted, or renamed.

Features

Directory Watching: Monitor directories for changes with recursive support
File Watching: Monitor individual files for changes
Filtering: Filter changes by filename, extension, or event types
Buffering: Collect changes in a buffer for batch processing
Multiple Paths: Watch multiple directories simultaneously
Pause/Resume: Control watch activity dynamically
Event Types: FILE_ACTION_ADDED, FILE_ACTION_REMOVED, FILE_ACTION_MODIFIED, FILE_ACTION_RENAMED

Watching Directories

Watch a directory for changes:

const FileSystemWatcher = require('./system/filesystem-watcher');

const watcher = new FileSystemWatcher();

// Watch directory
const watchId = watcher.watchDirectory('/path/to/directory', false, (changeInfo) => {
    console.log(`File ${changeInfo.filename} was ${changeInfo.eventType}`);
});

// Stop watching
watcher.stopWatch(watchId);

Recursive Watching

Watch a directory and all subdirectories:

const watchId = watcher.watchDirectory('/path/to/directory', true, callback);

Filtering

Watch with filters to only receive specific changes:

// Watch only .txt files
const watchId = watcher.watchDirectoryFiltered(
    '/path/to/directory',
    false,
    callback,
    { extension: 'txt' }
);

// Watch only specific event types
const watchId2 = watcher.watchDirectoryFiltered(
    '/path/to/directory',
    false,
    callback,
    { eventTypes: ['FILE_ACTION_ADDED', 'FILE_ACTION_MODIFIED'] }
);

Buffered Watching

Collect changes in a buffer for batch processing:

const buffer = watcher.watchDirectoryBuffered('/path/to/directory', false, 100);

// Get all changes
const changes = buffer.getChanges();

// Clear changes
buffer.clearChanges();

File Watching

Watch a specific file for changes:

const watchId = watcher.watchFile('/path/to/file.txt', (changeInfo) => {
    console.log(`File modified: ${changeInfo.path}`);
    console.log(`Current size: ${changeInfo.current.size}`);
    console.log(`Previous size: ${changeInfo.previous.size}`);
});

Multiple Paths

Watch multiple directories simultaneously:

const watchIds = watcher.watchMultiple(
    ['/path/to/dir1', '/path/to/dir2', '/path/to/dir3'],
    false,
    callback
);

Control Functions

stopWatch(watchId) - Stop watching and cleanup
pauseWatch(watchId) - Pause watching (temporarily disable)
resumeWatch(watchId) - Resume watching
getWatchInfo(watchId) - Get watch information
cleanup() - Cleanup all watches

Event Types

The File System Watcher supports the following event types:

FILE_ACTION_ADDED: File or directory was created
FILE_ACTION_REMOVED: File or directory was deleted
FILE_ACTION_MODIFIED: File or directory was modified
FILE_ACTION_RENAMED_OLD_NAME: File or directory was renamed (old name)
FILE_ACTION_RENAMED_NEW_NAME: File or directory was renamed (new name)

Integration

The File System Watcher integrates with:

Desktop: Updates desktop icons when files change
Wanderer: Refreshes file browser when directory contents change
Applications: Notifies applications of file changes
Event System: Emits filesystem events to EventBus

Usage Example

const FileSystemWatcher = require('./system/filesystem-watcher');

const watcher = new FileSystemWatcher();

// Watch desktop directory for new files
const desktopWatch = watcher.watchDirectory(
    '/home/user/Desktop',
    false,
    (changeInfo) => {
        if (changeInfo.eventType === 'FILE_ACTION_ADDED') {
            console.log(`New file: ${changeInfo.filename}`);
            // Update desktop icon
        }
    }
);

// Watch config directory recursively
const configWatch = watcher.watchDirectory(
    '/etc/freeworld',
    true,
    (changeInfo) => {
        console.log(`Config changed: ${changeInfo.fullPath}`);
        // Reload configuration
    }
);