#Traverser#

search through a complex object (nearly) as easily as forEach

all the nitty-gritty stuff is taken care of.

including:
  # checking for repeats.
  # checking for cycles.
  # getting the path the the current object. etc!

#simple example#
collect all branches in a tree.

    var traverser = require('traverser')
      , branches = []

    function branch(props){
      if(!props.reference) //since we check for references with will work in cyclic graphs, without stackoverflows.
        branches.push(props.value)

      props.each()//continue working through the children of this object.
    }

    traverser([1,2,{},3,["x"]],{branch: branch})
    
    console.log(branches)

#simple example2#
collect all leaves in a tree. (only functions and primitives)

    var traverser = require('traverser')

    exports.leaves = leaves

    function leaves (obj){
        var leaves = []

        function leaf(props){
          leaves.push(props.value)
        }

        traverser(obj,{leaf: leaf})
        return leaves
    }

    traverser([1,2,{},3,["x"]],{leaf: leaves})

    console.log(leaves([1,2,{},3,["x"]]))
    //[1,2,3,'x']
    
#complex example#
even quite complex things like a topological sort are now achivable in ~30 lines.
see `traverser/examples/topo-sort`


#API#

  `traverser (obj, options)`
  
  obj: graph/tree to traverse
  
    options: (each of the following is optional)
    {
      branch: function to call on a branch of the tree (by default, where typeof == 'object'
    , leaf: function to call on primitives and functions
    , isBranch: return true if current value should be treated as a branch
    }
    
each function is passed one arg, a properties object which describes the state of the traverse.
  
    {
      value: this object
    , parent: object which this item is a property of. (null if your on the root object)
    , key: key of this item on parent. (null if your on the root object)
    , path: [list of keys from root object to current item]
    , reference: true if this object is a repeat
    , circular: true if this object is in the ancestors list.
    , seen: list of objects seen so far
    , ancestors: list of objects between value and root object.

    //when your in the branch function, you need to call one of the following to iterate over the children.
    //none of these require an argument.

    , each: iterate over each property
    , find: iterate untill the first truthy return, returns the item.
    , map: collects return values into an Array
    , copy: copies objects, preserving whether it's a {} or a []
    , max: iterate over all properties and return max return value
    , min: iterate over all properties and return min return value
    }

###feel free to ask me questions if you need help!###

###see https://github.com/dominictarr/trees for more examples.###

##License

Mit/Apache2