           # can't return a value from constructor, so, throw Error
           throw new Error 'Elements must be functions. Invalid #'+index+':'+element
 
+    # an array of functions, so simple, until you wrap a Chain around it...
     @array = array
 
+  # add functions to the array:
+  #  chain.add fn
+  #  chain.add fn1, fn2, fn3, ...
+  #  chain.add [ fn1, fn2, ... ]
   add: (fns...) ->
 
     # unwrap array

    # it's all good
    return success:true

  remove: (fn) ->
    index = @array.indexOf fn
    result = {}
    if index > -1
      result.removed = @array.splice index, 1
      @emit 'remove', fn
    return result

  clear: ->
    if @array.length > 0      # only operate when there's some content
      array = @array          # remember the array
      @array = []             # new empty array = clear
      @emit 'remove', array   # emit a remove event with the array

  run: (options, done) ->
    context = options?.context ? {}                # get context or default to {}
    done = options?.done ? done                    # look for `done`
    control = new Control @, @array, context, done # create controller
    @emit 'start', control:control, chain:this
    result = control._execute()                    # starts the chain
    if control.paused?                             # a paused chain isn't done
      results = paused:control.paused              # return only paused info

Control = require './control'

###
  Chain holds an array of functions to execute in sequence managed by a Control.
###
module.exports = class Chain extends require('events').EventEmitter

  constructor: (options) ->

    # if module's builder function already validated the array then use it
    # and avoid redoing that same work
    if options?.__validated
      array = options.array

    # otherwise, let's be safe, must find the array and validate it
    else
      array =
        if Array.isArray options then options                    # new Chain [...]
        else if typeof options is 'function' then [ options ]    # new Chain fn
        else if Array.isArray options?.array then options.array  # new Chain array:[]
        else []                                                  # new Chain()

      # validate array's contents: must be functions
      for element,index in array
