object-catalog

Catalog the execution context object

Synopsis

function(options)

Description

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 resultant object has no prototype
• The catalog excludes:
  • Members that reference the catalog function itself (e.g., as a result of having been mixed in)
  • Members of Object.prototype

Options

options.own

If truthy, the resultant catalog is restricted to the execution context object only (excluding the prototype chain).

options.greylist

See greylist for more details, but basically:

options.greylist.white

A whitelist. Only listed object members are cataloged can pass. If undefined, all members are included. If an empty array, all members are excluded.

options.greylist.black

A blacklist. Listed strings are blocked. If undefined or an empty array, all members are included.

Example

A. Default behavior

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 }

B. The own behavior

Proceeding from Example A:

var options = { own: true };
myAPI.catalog(options); // { b:myAPI, c:myAPI }

C. The greylist behavior

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 }

D. Lacking class

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 }

E. Without mixing in

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 }