watchit.coffee

watchit.coffee

{EventEmitter} = require 'events'
fs             = require 'fs'
path           = require 'path'

¶

Options: retain means that if something is later created at the same location as the target, the new entity will be watched. debounce means that changes that occur within 1 second of each other will be treated as a single change. This also allows "echo" events that occur under OS X to be ignored. include means that if the target is a directory, files contained in that directory will be treated like targets. (Otherwise, directory events will be forwarded directly from fs.watch.) recurse means that if the target is a directory, all of its subdirectories will also be counted as targets. persistent is identical to fs.watch's persistent option. If disabled, the process may exit while files are being watched. ignore could contain RegExp pattern or function against which added files will be tested.
```
defaults =
  retain: false
  debounce: false
  include: false
  recurse: false
  persistent: true
  ignored: null
```

Main function

watchit = (target, options, callback) ->

The options argument and the callback are both optional

  if typeof options is 'function'
    callback = options
    options = {}

  options = extend {}, defaults, options ? {}

Generic function that will check if some file is ignored.

  ignored = (file) ->
    if options.ignored
      if typeof options.ignored.test is 'function'
        options.ignored.test(file)
      else
        options.ignored(file)
    else
      no

¶

emitter will be returned from the function; it emits "change", "create", and "unlink" events. It also emits "success" and "failure" events the first time a target is found or not found, respectively.
```
  emitter = options.emitter = options.emitter ? new WatchitEmitter(callback)
```
¶

emitter also keeps track of the mtime on each target. If a target is already being watched on the same emitter, we return null rather than watch the same target multiple times.
```
  emitter.targets ?= {}
  return null if emitter.targets[target]
```
¶

The emitter can also be used to stop the watching process. Because the same emitter is used for directory children (if include or recurse is enabled), a single "close" event can shut down several fswatchers.
```
  fswatcher = null
  emitter.close = -> emitter.emit 'close', target
  emitter.on 'close', -> fswatcher?.close()
```

Start watching

  do watchTarget = ->
    emitter.targets[target] = {}
    fs.stat target, (err, stats) ->
      fail = (err) ->
        if options.retain
          notifyWhenExists target, ->
            emitter.emit 'create', target
            watchTarget()
        else
          emitter.emit 'failure', target, err

      return fail err if err

      emitter.targets[target].stats = stats
      try
        if stats.isDirectory()
          fswatcher = watchTargetDir()
          scanTargetDir true if options.include or options.recurse
        else
          fswatcher = watchTargetFile()
      catch e
        return fail e

      emitter.emit 'success', target
      fswatcher.on 'error', (err) -> throw err

¶

If the target is lost and retain is enabled, we watchTarget again
```
  retainTarget = watchTarget
```

If the target is lost, we close the FSWatcher

  unwatchTarget = ->
    fswatcher.close()
    delete emitter.targets[target]

  watchTargetFile = ->
    fs.watch target, {persistent: options.persistent}, (event) ->
      if event is 'rename'

Has the target been unlinked, or merely replaced?

        fs.stat target, (err) ->
          if err
            unwatchTarget()
            retainTarget() if options.retain

TODO: Distinguish renames from unlinks, somehow

            emitter.emit 'unlink', target
          else
            emitter.emit 'change', target
      else if event is 'change'
        if options.debounce
          conditionalTimeout target, 1000, ->
            fs.stat target, (err, stats) ->
              return if err or target not of emitter.targets
              prevStats = emitter.targets[target].stats
              return if stats.mtime.getTime() is prevStats.mtime.getTime()
              emitter.targets[target].stats = stats
              emitter.emit 'change', target
        else
          emitter.emit 'change', target

  watchTargetDir = ->
    fs.watch target, {persistent: options.persistent}, (event, filename) ->
      if event is 'rename'

Is this happening to the target, or one of its children?

        fs.stat target, (err) ->
          if err
            unwatchTarget()
            retainTarget() if options.retain
            emitter.emit 'unlink', target
          else
            emitter.emit 'rename', target unless options.include
            scanTargetDir() if options.include or options.recurse
      else
        throw new Error "Unexpected directory event: #{event}"

  scanTargetDir = (initial) ->
    fs.readdir target, (err, items) ->
      return if err
      for item in items
        do (item) ->
          return if ignored item
          itemPath = path.join(target, item)
          fs.stat itemPath, (err, stats) ->
            return if err
            isDir = stats.isDirectory()
            if (isDir and options.recurse) or (!isDir and options.include)

watchit returns null if target is already watched

              if watchit itemPath, extend({emitter}, options)
                emitter.emit 'create', itemPath unless initial

  emitter

Helpers

class WatchitEmitter extends EventEmitter
  constructor: (@callback) ->
  emit: (event, filename, etc...) ->
    return if event is 'newListener'
    super event, filename, etc...
    super 'all', event, filename, etc...
    @callback? event, filename, etc...

extend = (obj, sources...) ->
  for source in sources
    for prop of source
      obj[prop] = source[prop] if prop of source
  obj

Set a timeout, unless a timeout with the same key already exists.

pendingTimeouts = {}
conditionalTimeout = (key, time, callback) ->
  return if key of pendingTimeouts
  pendingTimeouts[key] = 1
  setTimeout (->
    delete pendingTimeouts[key]
    callback()
  ), time

To be notified when target does not exist, we must watch its parent.

notifyWhenExists = (target, callback) ->
  throw new Error 'notifyWhenExists requires a callback' unless callback
  parentDir = path.join target, '..'

And if parentDir does not exist, we must watch its parent. And so on...

  levelUp = ->
    notifyWhenExists parentDir, ->
      notifyWhenExists target, callback

  fs.exists target, (exists) ->
    return callback() if exists

    try
      fswatcher = fs.watch parentDir, {persistent: options.persistent}, ->
        fs.readdir parentDir, (err, items) ->
          if err

parentDir no longer exists

            fswatcher.close()
            levelUp()
            return
          for item in items
            if path.join(parentDir, item) is target

Our target now exists

              fswatcher.close()
              return callback()
        return
    catch e
      levelUp()

While Watchit's main export is its titular function, functions which can be tested independently are attached.

module.exports = watchit
module.exports.conditionalTimeout = conditionalTimeout
module.exports.notifyWhenExists = notifyWhenExists