keypather

keypather

Get or set a object values from a keypath string. Supports bracket notation, dot notation, and functions. Ignores errors for deep-keypaths by default.

Safely handles string expressions - No eval or new Function code here!

installation

npm install keypather

Examples

GET

dot notation, bracket notation, and functions (even with arguments) all supported:

var keypath = require('keypather')();
var obj = {
  foo: {
    bar: {
      baz: 'val'
    }
  }
};
keypath.get(obj, "foo.bar.baz"); // val
keypath.get(obj, "['foo']['bar']['baz']"); // val

var keypath = require('keypather')();
var obj = {
  foo: function () {
    return function () {
      return function () {
        return 'val';
      };
    };
  }
};
keypath.get(obj, "foo()()()"); // val

var keypath = require('keypather')();
var obj = {
  foo: function () {
    return {
      bar: {
        baz: 'val'
      }
    };
  }
};
keypath.get(obj, "foo()['bar'].baz"); // val

functions with arguments

var keypath = require('keypather')();
var obj = {
  create: function (data) {
    var data = data;
    return {
      get: function (key) {
        return data[key];
      }
    };
  }
};
keypath.get(obj, "create(%).get(%)", [{foo:1, bar:2}], ['foo']); // 1
keypath.get(obj, "create(%).get(%)", {foo:1, bar:2}, 'foo'); // 1, single args are automatically placed in arrays
// technically you can use anything (except dots, parens, brackets, or empty string)
// between the parens of functions that accept args (in place of %)

Get returns null for keypaths that do not exist by default, but can also throw errors with { force: false }

var keypath = require('keypather')(); // equivalent to { force:true }
var obj = {};
keypath.get(obj, "foo.bar.baz"); // null

var keypath = require('keypather')({ force: false });
var obj = {};
keypath.get(obj, "foo.bar.baz");
// throw's an error
// Error: Cannot get 'foo' of undefined

SET

mixed notation, dot notation, and bracket notation all supported:

var keypath = require('keypather')();
var obj = {
  foo: {
      bar: {
        baz: 'val'
      }
    }
  }
};
keypath.set(obj, "foo['bar'].baz", 'value'); // value
keypath.set(obj, "foo.bar.baz", 'value'); // value
keypath.set(obj, "['foo']['bar']['baz']", 'value'); // value

Set forces creation by default:

var keypath = require('keypather')(); // equivalent to { force:true }
var obj = {};
keypath.set(obj, "foo.bar.baz", 'val'); // value
// obj = {
//   foo: {
//     bar: {
//       baz: 'val'
//     }
//   }
// };

var keypath = require('keypather')({ force: false });
var obj = {};
keypath.set(obj, "foo.bar.baz", 'val');
// throw's an error
// Error: Cannot get 'foo' of undefined

IN

Equivalent to key in obj

var keypath = require('keypather')();
var obj = {
  foo: {
      bar: {
        baz: 'val'
      }
    }
  }
};
keypath.in(obj, "foo['bar'].baz");        // true
keypath.in(obj, "foo.bar.baz");           // true
keypath.in(obj, "['foo']['bar']['baz']"); // true
// obj:
// {
//   foo: {
//     bar: {}
//   }
// }

HAS

Equivalent to obj.hasOwnProperty

var keypath = require('keypather')();
var obj = {
  foo: {
      bar: {
        baz: 'val'
      }
    }
  }
};
keypath.has(obj, "foo['bar'].baz");        // true
keypath.has(obj, "foo.bar.baz");           // true
keypath.has(obj, "['foo']['bar']['baz']"); // true
// obj:
// {
//   foo: {
//     bar: {}
//   }
// }

DEL

Equivalent to delete obj.key

var keypath = require('keypather')();
var obj = {
  foo: {
      bar: {
        baz: 'val'
      }
    }
  }
};
keypath.del(obj, "foo['bar'].baz");        // true
keypath.del(obj, "foo.bar.baz");           // true
keypath.del(obj, "['foo']['bar']['baz']"); // true
// obj:
// {
//   foo: {
//     bar: {}
//   }
// }

FLATTEN

Flatten an object or array into a keypath object

var keypath = require('keypather')();

keypath.flatten({
  foo: {
    qux: 'hello'
  },
  bar: [
    1,
    {
      yolo: [1]
    }
  ]
});
// returns:
// {
//   'foo.qux': 'hello',
//   'bar[0]': 1,
//   'bar[1].yolo[0]': 1
// }

/* accepts a delimiter other than '.' as second arg */

keypath.flatten({
  foo: {
    qux: 'hello'
  }
}, '__');
// returns:
// {
//   'foo__qux': 'hello',
// }

EXPAND

Expand a flattened object back into an object or array

var keypath = require('keypather')();

keypath.expand({
  'foo.qux': 'hello',
  'bar[0]': 1,
  'bar[1].yolo[0]': 1
});
// returns:
// {
//   foo: {
//     qux: 'hello'
//   },
//   bar: [
//     1,
//     {
//       yolo: [1]
//     }
//   ]
// }

/* expand will assume the object is an array if all the keys are numbers */

keypath.expand({
  '[0]': 1,
  '[1].yolo[0]': 1
});
// returns:[
//   1,
//   {
//     yolo: [1]
//   }
// ]

/* accepts a delimiter other than '.' as second arg */

keypath.flatten({
  foo: {
    qux: 'hello'
  }
}, '__');
// returns:
// {
//  'foo__qux': 'hello'
// }

License

MIT