I got frustrated looking for specific properties and values within JavaScript object trees — so I created a utility to do it for me.
Waldo lets you search globally or within specificied objects. You can search by property name, property type or property value. You can also create your own custom search functions. Waldo can be run as an npm module, or a global file and there's also an autogenerated bookmarklet you can use for quick checks in the console.
A waldo search returns an array of Match objects...
var waldo = require('waldojs');
// find react properties named 'oneOfType'
var React = require('react');
var matches = waldo.byName('oneOfType', React);
matches[0].path; // 'SRC.PropTypes.oneOfType'
matches[0].value; // [the function]
matches[0].type; // 'function'Running log over a Match, or all matches, returns a formatted text summary.
// global search for objects with a value of 10
waldo.byValue(10).log(); // =>
GLOBAL.module.exports.repl._maxListeners -> (number) 10
GLOBAL.module.exports.repl.rli._maxListeners -> (number) 10
GLOBAL.module.exports.repl.outputStream._maxListeners -> (number) 10
GLOBAL.module.exports.repl.inputStream._maxListeners -> (number) 10If you use a transpiler like babel you could interact with waldo in ES 6. (Waldo is itself written in ES 6).
// use a destructure assignment to find a nested pattern
const obj = {a: {a: 3, b: {c: 4, a: {a: {b: 4}}}}};
const matches = find.custom(
(what, obj, prop) => {
let {a: {b: x}} = obj[prop];
return x === 4;
}, obj);
matches.log(); // 'SRC.a.b.a -> (object) {a: {b: 4}}'npm install waldojs
then
var waldo = require('waldojs'); // ES 5or
import waldo from 'waldojs'; // ES 6Clone this repo and run make to generate the standalone bundles waldobundle.js and waldobundle.min.js. The global waldo object will now be available to you.
By using the supplied bookmarklet (lib/bookmarklet.txt - you'll need to run make if it isn't there) you can type waldo commands directly in the console. When run in the console waldo auto-logs all matches.
Every time waldo finds an object that matches the search criteria, a Match object is created. Each call to waldo returns an array of Match objects.
A Match instance has the following properties
paththe property path to reach the matching object.propthe name of the matching object.valuethe value of the matching object.objthe matching objectlogfunction that returns a formatted string representation of the match (the array of matches also has alogfunction that returns a formatted string of all matches).
Waldo accepts a variety of query methods.
byNamesearch the object tree for properties with this namebyValuesearch the object tree for properties with this valuebyValueCoercedsearch the object tree for properties that == this valuebyTypesearch the object tree for properties that are an instance of the given class/constructor.customsupply a custom search function
Each method accepts up to 2 arguments:
what(required) the property, value or type to match onwhere(optional - default is the global object) the root of the search
// Find properties named 'read' anywhere
var matches = waldo.byName('read');
matches.length; // 1
matches[0].value; // [the function]
matches[0].log(); // =>
'GLOBAL.module.exports.repl.inputStream.read -> (function) [object Function]'// Global search for all properties with the value 10
var matches = waldo.byValue(10);
matches.length // => 4;
// return the results as a formatted string...
// (when running globally these logs appear in the console by default)
matches.log(); // =>
GLOBAL.module.exports.repl._maxListeners -> (number) 10
GLOBAL.module.exports.repl.rli._maxListeners -> (number) 10
GLOBAL.module.exports.repl.outputStream._maxListeners -> (number) 10
GLOBAL.module.exports.repl.inputStream._maxListeners -> (number) 10// get all falsey values globally
waldo.byValueCoerced(false); // =>
GLOBAL.deviceIsAndroid -> (boolean) false
GLOBAL.deviceIsIOS -> (boolean) false
GLOBAL.defaultstatus -> (string) ''
GLOBAL.GitHub.support.setImmediate -> (boolean) false
GLOBAL.chrome.app.isInstalled -> (boolean) false
etc..var a = {
aa: ['x', 'y', 'z'],
bb: {
bbb: [1, 2, 3],
ccc: 54
}
};
waldo.byType(Array, a); // =>
SRC.aa -> (object) x,y,z
SRC.bb.bbb -> (object) 1,2,3The custom method takes 2 arguments:
fn- function specifying match criteriawhere(optional) -where to search
// find all true values beginning with 'c'
var vegetables = {
carrots: {
chopped: false,
cleaned: true
}
leaks: {
chopped: true,
cleaned: false
}
};
waldo.custom(function(what, obj, prop) {
return (obj[prop] === true) && (!prop.indexOf('c'));
}, vegetables); // =>
SRC.leaks.chopped -> (boolean) true
SRC.carrots.cleaned -> (boolean) trueWaldo detects circular references and cites them:
var a = {x: b};
var b = {y: c};
var c = {z: a};
waldo.byName('z');will log...
GLOBAL.c.z -> (<GLOBAL.a>) {z: a}
Thanks to John-David Dalton for adding circular reference detection as well as providing some early refactor commits.
To test both module and the standalone bundles:
npm test
To run continuous tests in watch mode:
npm run testc