Filesystem watcher with Signal-based event delivery.

Watch a single file:

local fsWatch = require("@eryx/fs_watch")

local watcher = fsWatch.watchFile("config.json")
watcher.changed:connect(function(eventType)
	print("config.json:", eventType) -- "change" or "rename"
end)

-- later:
watcher:stop()

Watch a directory (with debounce to coalesce rapid OS events):

local watcher = fsWatch.watchDir("src/", { recursive = true, debounce = 0.1 })
watcher.changed:connect(function(filename, eventType)
	print(filename, eventType)
end)

watcher:stop()

Summary

Classes

Functions

API Reference

Classes

FileWatcher

Properties

changed: Signal<string>

Fires when the watched file changes. Receives (eventType) where eventType is "change" or "rename".

FileWatcher:stop

Stops the watcher and disconnects all signal handlers.

FileWatcher:stop() → ()

FileWatcher:ref

Makes this watcher keep the event loop alive (watchers are unref'd by default).

FileWatcher:ref() → ()

FileWatcher:unref

Allows the event loop to exit while this watcher is active (the default).

FileWatcher:unref() → ()

DirWatcher

Properties

changed: Signal<string, string>

Fires when any file in the watched directory changes. Receives (filename, eventType). filename is the path of the changed file relative to the watched directory.

DirWatcher:stop

Stops the watcher and disconnects all signal handlers.

DirWatcher:stop() → ()

DirWatcher:ref

Makes this watcher keep the event loop alive (watchers are unref'd by default).

DirWatcher:ref() → ()

DirWatcher:unref

Allows the event loop to exit while this watcher is active (the default).

DirWatcher:unref() → ()

Functions

fs_watch.watchFile

Watches a single file for changes. Returns a FileWatcher whose changed signal fires with (eventType).

fs_watch.watchFile(path: string, options: WatchOptions?) → FileWatcher

fs_watch.watchDir

Watches a directory for changes. Returns a DirWatcher whose changed signal fires with (filename, eventType).

fs_watch.watchDir(path: string, options: WatchOptions?) → DirWatcher

Types

WatchOptions

recursive: boolean?

Watch subdirectories recursively (supported on Windows and macOS; on Linux you may need individual watchers per subdirectory).

debounce: number?

Debounce interval in seconds. When set, rapid-fire OS events for the same file are coalesced - only the last event fires after the interval elapses with no new events. Set to 0 or nil to disable.