#i5ting/chokidar

#Getting started

moon add i5ting/chokidar

fn main {
  let watcher = @chokidar.watch(@chokidar.One("."))
  watcher
    .on(@chokidar.Add,    event => println("added:   " + event.path))
    .on(@chokidar.Change, event => println("changed: " + event.path))
    .on(@chokidar.Unlink, event => println("removed: " + event.path))
    .on(@chokidar.Ready,  _     => println("ready"))
  |> ignore

  // Drive the watcher in your application loop
  while true {
    watcher.process() catch { _ => () }
  }
}

#How it works

#API

#watch

pub fn watch(
  paths : WatchPaths,
  options? : Options,
) -> Watcher raise ChokidarError

#Watcher

#Events

pub struct Event {
  name  : EventName
  path  : String
  stats : FileStats?      // size, mode, modified_nanos
  raw   : RawEvent?       // underlying OS event (Raw only)
  error : ChokidarError?  // (Error only)
}

pub struct FileStats {
  size           : Int64
  mode           : Int
  modified_nanos : Int64
}

pub enum FileKind {
  File
  Directory
  Symlink
  Other   // sockets, pipes, device nodes
}

#Options

let watcher = @chokidar.watch(
  @chokidar.One("src"),
  options={
    ..@chokidar.Options::default(),
    ignored: [
      // exact path
      @chokidar.MatchPath("src/generated.mbt"),
      // recursive subtree
      @chokidar.MatchRecursivePath("src/vendor"),
      // regex
      @chokidar.MatchRegex(@regexp.compile("\\.log$") |> Result::unwrap),
      // function
      @chokidar.MatchFunction((path, _stats) => path.has_suffix(".tmp")),
    ],
    ignore_initial: true,
    follow_symlinks: true,
    cwd: Some("/project/root"),
    use_polling: false,
    interval: 100,
    binary_interval: 300,
    always_stat: false,
    depth: 2147483647,      // Int::max_value — unlimited
    ignore_permission_errors: false,
    atomic_option: @chokidar.AtomicDefault,
    await_write_finish: @chokidar.AwaitWriteFinishOff,
  }
)

#Path filtering

• ignored — Array of Matcher values; a path is ignored if any matcher matches.
  • MatchPath(s) — exact path equality
  • MatchRecursivePath(s) — s or any path underneath s
  • MatchRegex(re) — matches via @regexp.Regexp
  • MatchFunction((path, stats?) -> Bool) — custom predicate
• ignore_initial (default false) — suppress add/addDir events during the initial scan.
• follow_symlinks (default true) — traverse symlinked directories.
• cwd — base directory; emitted paths will be relative to it.

#Performance

• use_polling (default false) — force directory polling instead of native OS events. Required for network filesystems. Also overridable via CHOKIDAR_USEPOLLING=true|1|false|0.
• interval (default 100 ms) — polling interval. Also overridable via CHOKIDAR_INTERVAL=<ms>.
• binary_interval (default 300 ms) — polling interval for binary files (option accepted; uniform interval used for all files).
• always_stat (default false) — always attach FileStats to Add, AddDir, and Change events.
• depth (default unlimited) — maximum directory depth to scan.

#Correctness

• ignore_permission_errors (default false) — silently skip unreadable files instead of raising.
• atomic_option:
  • AtomicDefault — detect editor atomic-write patterns (vim swapfiles, ~ backups, Sublime .tmp); suppress the intermediate Unlink and convert Unlink+Add pairs to Change.
  • AtomicWindow(ms) — explicit window in milliseconds.
  • AtomicOff — disable atomic handling.
• await_write_finish:
  • AwaitWriteFinishOff (default) — emit immediately.
  • AwaitWriteFinishOn({ stability_threshold: Int, poll_interval: Int }) — hold Add/Change until file size is stable for stability_threshold ms; re-check every poll_interval ms.
  • AwaitWriteFinish::default_on() — { stability_threshold: 2000, poll_interval: 100 }.

#Differences from chokidar-main (Node.js v5)

#Name mapping (JS → MoonBit)

#Examples

#Watch a directory, ignore node_modules

let watcher = @chokidar.watch(
  @chokidar.One("src"),
  options={
    ..@chokidar.Options::default(),
    ignore_initial: true,
    ignored: [@chokidar.MatchRecursivePath("src/node_modules")],
  },
)
watcher.on(@chokidar.All, event => {
  println(event.name.to_string() + " " + event.path)
}) |> ignore

#Watch multiple paths

let watcher = @chokidar.watch(
  @chokidar.Many(["src", "test"]),
  options={
    ..@chokidar.Options::default(),
    ignore_initial: true,
  },
)

#Await write finish for large files

let watcher = @chokidar.watch(
  @chokidar.One("uploads"),
  options={
    ..@chokidar.Options::default(),
    await_write_finish: @chokidar.AwaitWriteFinish::default_on(),
  },
)

#Force polling (e.g. for network drives)

let watcher = @chokidar.watch(
  @chokidar.One("/mnt/share"),
  options={
    ..@chokidar.Options::default(),
    use_polling: true,
    interval: 500,
  },
)

#Attach stats to every change event

watcher.on(@chokidar.Change, event => {
  match event.stats {
    Some(s) => println("size: " + s.size.to_string())
    None => ()
  }
}) |> ignore

#Unsubscribe a listener

let cb : (@chokidar.Event) -> Unit = event => println(event.path)
watcher.on(@chokidar.Add, cb) |> ignore
// later...
watcher.off(@chokidar.Add, cb) |> ignore

#Stop watching

watcher.close()

#Environment variable overrides

#License