WatchDirectory

View source
Entity → ceramic.WatchDirectory (Class)

A directory watcher that monitors file changes in specified directories.

This class provides cross-platform file system monitoring, detecting when files are added, modified, or removed within watched directories. On Node.js platforms, it can use the 'chokidar' library for efficient file watching if available, otherwise it falls back to periodic polling.

Features:

  • Monitor multiple directories simultaneously
  • Detect file additions, modifications, and deletions
  • Configurable update interval for polling mode
  • Automatic cleanup when directories are unwatched

Example usage:

var watcher = new WatchDirectory(1.0); // Check every second

watcher.onDirectoryChange(this, (path, newFiles, previousFiles) -> {
    trace("Directory changed: " + path);
    // Check for new files
    for (file => mtime in newFiles) {
        if (!previousFiles.exists(file)) {
            trace("New file: " + file);
        }
    }
});

watcher.watchDirectory("/path/to/assets");

Note: File watching may have platform-specific limitations and performance characteristics. The chokidar integration provides better performance on Node.js platforms when available.

Instance Members

updateInterval: Float

The interval in seconds between directory checks when using polling mode. This is ignored when using chokidar on Node.js platforms.

watchedDirectories: ReadOnlyMap<String, ReadOnlyMap<String, Float>>

Map of watched directory paths to their current file modification times. The outer map key is the directory path, the inner map contains filenames mapped to their last modification timestamps.

watchDirectory(path: String): Void

Start watching a directory for file changes.

The initial file list is computed asynchronously. Once ready, any subsequent changes will trigger the directoryChange event.

Name Type Description
path String The absolute path to the directory to watch
stopWatchingDirectory(path: String): Bool

Stop watching a directory.

Name Type Description
path String The directory path to stop watching
Returns Description
Bool true if the directory was being watched and is now stopped, false otherwise
new(?updateInterval: Float = 1.0): Void

Create a new directory watcher.

Name Type Default Description
updateInterval Float 1.0 The interval in seconds between directory checks (default: 1.0). Only used in polling mode; chokidar provides real-time updates.

Private Members

startingToWatchDirectories: Map
emitDirectoryChange(path: String, newFiles: ReadOnlyMap<String, Float>, previousFiles: ReadOnlyMap<String, Float>): Void

Emitted when files in a watched directory have changed.

Name Type Description
path String The directory path that changed
newFiles ReadOnlyMap<String, Float> Map of current files to their modification times (Unix timestamp)
previousFiles ReadOnlyMap<String, Float> Map of files to modification times before the change
tick(): Void

Internal method called periodically to check for file changes. Only used in polling mode when chokidar is not available.

checkWatchedDirectory(path: String): Void

Check a specific watched directory for changes. In chokidar mode, processes queued change events. In polling mode, compares current files with cached state.

Name Type Description
path String The directory path to check
computeFilesModificationTime(path: String): ReadOnlyMap<String, Float>

Compute a map of all files in a directory with their modification times.

Name Type Description
path String The directory path to scan
Returns Description
ReadOnlyMap<String, Float> Map of relative file paths to modification timestamps

Metadata

Name Parameters
:build ceramic.macros.EntityMacro.buildForCompletion()
:autoBuild ceramic.macros.EntityMacro.buildForCompletion()
:build tracker.macros.EventsMacro.build()
:autoBuild tracker.macros.EventsMacro.build()