Catalog the execution context object
function(options)
this
(the execution context) is "the module," the object to catalogoptions
is an optional options object (see below)
Creates a catalog of all members of the execution context (this
) and all visible members of all the objects along it's prototype chain.
By visible members we mean only those members not shadowed by a member of the same name in a descending object in the prototype chain.
The resultant "catalog" is a plain javascript object. For each member of the catalog:
- key — The name of a member of the execution context.
- value — A reference to the object that owns the visible member, which will either be the execution context object itself or some object along its prototype chain.
To keep things simple:
- The catalog excludes members that reference the catalog function itself (e.g., as a result of having been mixed in)
- The catalog excludes members of
Object.prototype
- The resultant catalog object has no prototype
If truthy, the resultant catalog is restricted to the execution context object only (excluding the prototype chain).
Each greylist
option below may be:
- a string; or
- a regular expression; or
- an object (i.e., its enumerable defined keys); or
- a (nested) array of a mix of any of the above; or
- an empty array; or
undefined
(which is a no-op).
A whitelist of permissible object member keys to catalog.
Only listed object members are cataloged.
If undefined
, all members are cataloged.
If an empty array, all members are blocked.
A blacklist of impermissible object member keys.
Listed object members are blocked.
If undefined
or an empty array, all members that passed the whitelist are included.
When no options are specified:
function MyAPI() { this.b = 0; this.c = 3; }
MyAPI.prototype = { a:1, b:2, catalog:catalog };
var myAPI = new MyAPI;
myAPI.catalog(); // { a:MyAPI.prototype, b:myAPI, c:myAPI }
Object.getPrototypeOf(myAPI).catalog(); // { a:MyAPI.prototype, b:MyAPI.prototype }
Proceeding from Example A:
var options = { own: true };
myAPI.catalog(options); // { b:myAPI, c:myAPI }
Proceeding from the Example A:
var options = { greylist: { white: ['a', 'c'] } };
myAPI.catalog(options); // { a:MyAPI.prototype, c:myAPI }
options = { greylist: { black: ['a', 'c'] } };
myAPI.catalog(options); // { b:myAPI }
var options = { greylist: { white: ['a', 'c'], black: 'a' } };
myAPI.catalog(options); // { c:myAPI }
The catalog
function does not care where the object (and it's prototype) came from. You will get the same results regardless of whether the object is a "class" instance (i.e., was instanced from a constructor) or was simply created. Compare the following to Example A:
var myAPI = Object.create({ a:1, b:2, catalog:require('object-catalog') }};
Object.assign(myAPI, { b:0, c:3 });
myAPI.catalog(); // { a:ancestor, b:myAPI, c:myAPI }
Object.getPrototypeOf(myAPI).catalog(); // { a:ancestor, b:ancestor }
Notice that if the catalog function is mixed into the object, it is nonetheless excluded from the output. This exclusion is by reference and is regardless of the name of the key. You do not of course need to mix the function in if you're willing to use call
. Compare the following to Example D:
var myAPI = Object.create({ a:1, b:2 }};
Object.assign(myAPI, { b:0, c:3 });
var catalog = require('object-catalog');
catalog.call(myAPI); // { a:ancestor, b:myAPI, c:myAPI }
Object.getPrototypeOf(myAPI).catalog(); // { a:ancestor, b:ancestor }