API

valueForKeyPath(obj, keyPath, [fallbackValue])

Returns a value for given key path("." separated property names) You can call this method with "setValueForKeyPath" also.

• obj : An object to get value of property.
• keyPath : "." separated property names
• fallbackValue : fallback value which will be retuned when there is no matching value or null or undefined for given key path.

var obj = {
  foo : {
    bar : "test"
  }
};

_(obj).valueForKeyPath("foo.bar"); // --> "test"
_(obj).valueForKeyPath("foo.zar.notExistingProperty", "fallback"); // --> "fallback"

Getter method

What if there is a getter for given keypath, underscore-keypath tries to use it.

var bar = {
  _name : "Hello",
  _valid : true
};

bar.getName = function(){
  return this._name;
};

bar.isValid = function(){
  return this._valid;
}

_(bar).valueForKeyPath("name"); // --> "Hello"
_(bar).valueForKeyPath("valid"); // --> true

var foo = {
  "bar" : bar
};

_(foo).valueForKeyPath("bar.name") // --> Hello
//                      ^^^ 
//                        will be passed as "this" to getter

Function property

Each segment in key path can be used to call a function of current context:

var foo = {
  bar : function(){
    return {
      zar : function(){
        return "cool!";
      }    
    }
  }
};

_(foo).valueForKeyPath("bar.zar"); // --> "cool!"

Access Array

You can access elements in array with number:

var obj = {
  data : ["foo", "bar"]
};

_(obj).valueForKeyPath("data.0"); // --> "foo"

What if current context is an instance of Array, You can use element selector(starts with "@") on your key path.

• @first : first element
• @last : last element
• @max : max value element
• @min : min value element
• @size : size of array

var elements = [
  {
     data : [1, 2, 3, 4, 5]
  },
  {
     data : [10, 20, 30, 40, 50]
  }
]

_(elements).valueForKeyPath("@first.@size"); // --> 5
_(elements).valueForKeyPath("@last.@max"); // --> 50

These element selectors are read-only for now.

setValueForKeyPath(obj, keypath, newValue)

pluckByKeyPath(list, keyPath)

Plucks and returns an array with given key path.

• list : a collection
• keyPath : keyPath to pluck

var list = [
  {
    foo : {
      bar : "first"
    }
  },
  {
    foo : {
      bar : "second"
    }
  }
];

_(list).pluckByKeyPath("foo.bar"); // --> ["first", "second"]

whereByKeyPath(list, query)

Returns a array which contains elements which are matched with given query(key-value json) object.

• list : collection to query.
• query : filter that composed with key and expected value.

var list = [
  {
    name : "foo",
    age : 1,
    company : {
      name : "nodejs"
    }
  },
  {
    name : "bar",
    age : 2,
    company : {
      name : "nodejs"
    }
  },
  {
    name : "zar",
    age : 3,
    company : {
      name : "nodejs"
    }
  }
];

_(list).whereByKeyPath({"company.name" : "nodejs"});
// --> [{name:"foo",...}, {name:"bar", ...}]

findWhereByKeyPath(list, query)

Just same as whereByKeypath but it returns only first matching element not an array.

• list : a collection to lookup
• query : key-value JSON Object to find.

var list = [
  {
    name : "foo",
    age : 1,
    company : {
      name : "nodejs"
    }
  },
  {
    name : "bar",
    age : 2,
    company : {
      name : "nodejs"
    }
  },
  {
    name : "zar",
    age : 3,
    company : {
      name : "nodejs"
    }
  }
];

_(list).whereByKeyPath({"company.name" : "nodejs"});
// --> {name:"foo",...}