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) 10
If 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 5
or
import waldo from 'waldojs'; // ES 6
Clone 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
path
the property path to reach the matching object.prop
the name of the matching object.value
the value of the matching object.obj
the matching objectlog
function that returns a formatted string representation of the match (the array of matches also has alog
function that returns a formatted string of all matches).
Waldo accepts a variety of query methods.
byName
search the object tree for properties with this namebyValue
search the object tree for properties with this valuebyValueCoerced
search the object tree for properties that == this valuebyType
search the object tree for properties that are an instance of the given class/constructor.custom
supply 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,3
The 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) true
Waldo 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