FileWatcher

View source
Entity → ceramic.FileWatcher (Class)

Cross-platform file monitoring system for hot-reloading and file change detection.

FileWatcher provides a unified API for monitoring file changes across different platforms including native (sys), Node.js, and Electron environments. It periodically checks for file modifications and notifies registered callbacks when changes are detected.

The watcher can operate in two modes:

  • Content checking mode (default): Compares actual file content to detect changes
  • Timestamp mode: Only checks modification time (faster but less reliable)

This implementation is compatible with the interpret.Watcher interface, allowing it to be used with scripting and hot-reload systems.

Example:

var watcher = new FileWatcher();
var stopWatching = watcher.watch("config.json", function(content) {
    trace("Config file changed: " + content);
});

// Later, to stop watching:
stopWatching();
See: Entity

Static Members

UPDATE_INTERVAL: Float

The interval in seconds between file checks. Lower values provide faster detection but use more CPU. Default: 1.0 second

Instance Members

canWatch(): Bool

Checks if file watching is supported on the current platform.

Returns Description
Bool True if the platform supports file watching, false otherwise
watch(path: String, onUpdate: Function): Function

Starts watching a file for changes.

Multiple callbacks can be registered for the same file. Each callback receives the new file content when a change is detected.

Example:

var stop = watcher.watch("data.txt", function(content) {
    trace("File updated with content: " + content);
});
Name Type Description
path String The file path to watch
onUpdate Function Callback function that receives the new file content
Returns Description
Function A function that stops watching when called
destroy(): Void
new(): Void

Private Members

checkContent: Bool

Whether to compare actual file content or just modification times.

When true (default), the watcher reads and compares file content to detect changes, which is more reliable but slower. When false, only modification timestamps are checked, which is faster but may miss some changes.

watched: Map

Map of file paths to their watched state information.

timeSinceLastCheck: Float

Accumulator for time since last file check.

tick(delta: Float): Void

Update tick called by the app's update loop. Checks all watched files for changes at the configured interval.

Name Type
delta Float
isFile(path: String): Bool

Checks if a path points to a regular file (not a directory).

Name Type Description
path String The path to check
Returns Description
Bool True if the path is a file, false otherwise
lastModified(path: String): Float

Gets the last modification time of a file.

Name Type Description
path String The file path
Returns Description
Float Modification time in milliseconds since epoch, or -1 if unavailable
getContent(path: String): String

Reads the content of a file as a string.

Name Type Description
path String The file path
Returns Description
String The file content, or null if unavailable

Metadata

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