console-probe

Inspect JavaScript object methods and properties in the console.

[![Maintainability][cc-maintain-badge]][cc-maintain-url]
[![Build Status][travisci-image]][travisci-url]
[![js-standard-style][js-standard-image]][js-standard-url]
[![Patreon Donation][patreon-image]][patreon-url]

![Event Emitter Example][example-eventemitter-image]

[![NPM][nodei-npm-image]][nodei-npm-url]

Provides colourful functions to inspect JavaScript objects.

* The probe() function outputs a prototype hierarchy tree to the console.
* The json() function safely writes a stringified object output to the console.
* The yaml() function converts objects into yaml format and outputs to the console.
* The ls() function converts objects into a colourful format and outputs to the console.

Installing

* Node: v6.0.0 or later.
* Browser: Not tested

``sh
npm install --save-dev console-probe
`

Quick Start

__Not recommended for production environments__


`js

const cp = require('./console-probe')
const arrLen = 2

const aussieSlang = {
'name': 'Aussie Slang Words',
'gday': Infinity,
'maccas': Number.NaN,
'arvo': undefined,
'straya': null,
'footy': {specky: true},
'biccy': (size, toppings) => {},
'servo': true,
'choccy': Symbol('Mmmmm...'),
'bottle-o': Error('Cheers mate! My shout next'),
'tinny': 42,
'coppa': new Date(),
'tradie': 'She\'ll be right mate?',
'postie': /a.long.regexp.that.keeps.giving/,
'garbo': [1, 2, 3],
'muso': new Int8Array(arrLen),
'cabbie': new Uint8Array(arrLen),
'ambo': new Uint8ClampedArray(arrLen),
'prezzie': new Int16Array(arrLen),
'chrissie': new Uint16Array(arrLen),
'cuppa': new Int32Array(arrLen),
'mate': new Uint32Array(arrLen),
'snag': new Float32Array(arrLen),
'drongo': new Float64Array(arrLen),
'fairDinkum': new Map([['foo', 'bar']]),
'bonza': new Set([['foo', 'bar']]),
'tooRight': new WeakMap(),
'dunny': new WeakSet(),
'cobber': new ArrayBuffer(arrLen),
'barbie': new SharedArrayBuffer(arrLen),
'stickybeak': Atomics,
'stoked': new DataView(new ArrayBuffer(arrLen)),
'ripper': Promise.resolve(),
'mongrel': (function * () {})(),
'holyDooley': function * (foo, bar) {},
'roo': async function (foo, bar) {}
}
const secret = Symbol('Hidden Property')
aussieSlang[secret] = 'Bogan'

// Calling console-probe functions.
cp.probe(aussieSlang) // Writes a prototype tree to the console
cp.json(aussieSlang) // Writes a JSON formatted object to the console
cp.yaml(aussieSlang) // Writes a YAML formatted object to the console
cp.ls(aussieSlang) // Writes a formatted object to the console

// Adding console-probe functions to the console.
console.probe(aussieSlang) // Throws exception 'console.probe is not a function'
console.json(aussieSlang) // Throws exception 'console.json is not a function'
console.yaml(aussieSlang) // Throws exception 'console.yaml is not a function'
console.ls(aussieSlang) // Throws exception 'console.ls is not a function'
cp.apply()
console.probe(aussieSlang) // Writes a prototype tree to the console
console.json(aussieSlang) // Writes a JSON formatted object to the console
console.yaml(aussieSlang) // Writes a YAML formatted object to the console
console.ls(aussieSlang) // Writes a formatted object to the console

// Adding console-probe functions to an object.
const foo = {}
cp.apply(foo)
foo.probe(aussieSlang) // Writes prototype tree to the console
foo.json(aussieSlang) // Writes a JSON formatted object to the console
foo.yaml(aussieSlang) // Writes a YAML formatted object to the console
foo.ls(aussieSlang) // Writes a formatted object to the console

`

The above code will produce the following results when it writes to the console.

$3

_Note: Type detection errors will display as [Unknown]._

![Example Probe Output][example-probe-image]

$3

![Example Json Output][example-json-image]

$3

![Example Yaml Output][example-yaml-image]

$3

![Example ls Output][example-ls-image]

Rational

There are many amazing packages on npm. Many of those packages are not well documented. Rather than go straight to reading source code I wrote console-probe to inspect objects and discover methods and properties. Using Node.js with inspect is often a better approach however I don't always have it running; this is when console-probe comes in handy.

Function

The console-probe package provides four functions that will write to the console:

* probe(obj): The probe function uses Object.getOwnPropertyNames() and Object.getOwnPropertySymbols() to enumerate the members of an object through its prototype hierarchy. Using the type list from [MDN][jstypes-url] the types are detected. After a little formatting the result is written to the console using the [archy][archy-url] package with some colour added by [chalk][chalk-url].
* json(obj, replacer, spacer, color): Uses [fast-safe-stringify][fss-url] and [json-colorizer][json-colorizer-url] to safely write the stringified object out to the console.
* yaml(obj, options, indentation): A simple wrapper around the [prettyjson][prettyjson-url] package render function.
* ls(obj): A simple wrapper around the [jsome][jsome-url] package render function.

API

$3

__Description:__ Inspects the passed objects properties and methods, then the prototype of the passed object, and so on till the last prototype is analyzed. A tree of the properties and methods on each prototype is written to the console.

__Method Signature:__ probe(object)

__Parameter:__ object can be any JavaScript type.

__Details:__

* Passing either null or undefined will write [console-probe] Invalid Type: to the console.
* String values with newline characters are stripped from string stubs.

__Example:__

`js
const cp = require('console-probe')
cp.probe({ key: 'value' })
// Writes the object prototype hierarchy to the console
// See above for an example of the output
`

$3

__Description:__ This function simply calls [fast-safe-stringify][fss-url] and then adds color via [json-colorizer][json-colorizer-url]. Once that is done it writes the result to the console.

__Method Signature:__ json(object, replacer, spacer, color)

__Parameter:__

* object can be any object you wish to stringify.
* replacer alters the behavior of the stringification process.
* spacer inserts white space into the output JSON string for readability purposes.
* color enables customization of the colour displayed.

__Details:__

* The json function defaults to replacer = null and spacer = 2.
* See both [fast-safe-stringify][fss-url] and [JSON.stringify][json-stringify-url] for more details.
* Change the color displayed using a color object from the [json-colorizer][json-colorizer-url] options.

__Example:__

`js
const cp = require('console-probe')
cp.json({ key: 'value' })
// Outputs the following to the console:
// {
// "key": "value"
// }
`

$3

__Description:__ This function wraps the [prettyjson][prettyjson-url] render function and writes the result to the console. The result is a colorized formatted [YAML][yaml-url] representation of the object data.

__Signature:__ yaml(object, options, indentation)

__Parameter:__

* object can be any object you wish to display in [YAML][yaml-url] format.
* options should hold options for the [prettyjson][prettyjson-url] render function.
* indentation controls the indentation for the YAML output.

__Details:__

* The yaml function is simply a wrapper around the [prettyjson][prettyjson-url] package.
* See the [prettyjson][prettyjson-url] documentation and code for the options and indentation.

__Example:__

`js
const cp = require('console-probe')
cp.yaml({ key: 'value' })
// Outputs the following to the console:
// key: value
`

$3

__Description:__ This function wraps the [jsome][jsome-url] render function and writes the result to the console. The result is a colorized formatted representation of the object data.

__Signature:__ ls(object)

__Parameter:__

* object can be any object you wish to display.

__Details:__

* The ls function is simply a wrapper around the [jsome][jsome-url] package.
* See the [jsome][jsome-url] documentation for more detail.

__Example:__

`js
const cp = require('console-probe')
cp.ls({ key: 'value' })
// Outputs the following to the console:
// {
// key: "value"
// }
`


$3

__Signature:__ apply(object)

__Parameter:__ object can be any object you would like to add console-probe functions to.

__Details:__

* The apply function is a convenience method to add the console-probe functions to an object.
* If no object is passed to the apply function then the console-probe functions will be added to the console object.
* Passing an object, such as a logger, will add the console-probe functions to the object.

__Example:__

`js
const cp = require('console-probe')
cp.apply()
// console now has a probe, json, yaml, and ls functions.

const foo = {}
cp.apply(foo)
// foo now has a probe, json, yaml, and ls functions.
`

Another approach to simply augment the console:

`js
require('console-probe').apply()
// console.probe, console.json, console.yaml, and console.ls are now ready for use.
`

About the Owner

I, Grant Carthew, am a technologist, trainer, and Dad from Queensland, Australia. I work on code in a number of personal projects and when the need arises I build my own packages.

This project exists because I wanted to inspect objects from the console.

Everything I do in open source is done in my own time and as a contribution to the open source community.

If you are using my projects and would like to thank me or support me, please click the Patreon link below.

[![Patreon Donation][patreon-image]][patreon-url]

See my other projects on NPM.

Contributing

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request :D

Change Log

- v3.3.2 [2019-10-14]: Added 'name' to the name getter.
- v3.3.1 [2019-10-14]: Fixed Getter support (#5). Removed NSP from readme.
- v3.3.0 [2018-07-05]: Added new method ls. Fixed README badges. Fixed null/undefined error.
- v3.2.1 [2018-07-05]: Added BigInt` type support. Updated dependencies.
- v3.2.0 [2018-03-02]: Multiple type support. Probe format updated.
- v3.1.0 [2018-02-19]: Added colour to json. Added yaml function.
- v3.0.0 [2018-02-18]: Added json function. Improved API. Removed newline chrs.
- v2.0.4 [2018-01-29]: Changed node label format.
- v2.0.3 [2018-01-26]: Fix example image url.
- v2.0.2 [2018-01-26]: Added support for arrays and values. Fixed sort.
- v2.0.1 [2018-01-25]: Added repository url to package.json.
- v2.0.0 [2018-01-24]: Changed API. Improved type support.
- v1.0.2 [2018-01-23]: Updated Readme.
- v1.0.1 [2018-01-23]: Updated NSP link.
- v1.0.0 [2018-01-23]: Initial release.

[cc-maintain-badge]: https://api.codeclimate.com/v1/badges/805e88a221e165ecda12/maintainability
[cc-maintain-url]: https://codeclimate.com/github/grantcarthew/node-console-probe/maintainability
[travisci-image]: https://travis-ci.org/grantcarthew/node-console-probe.svg?branch=master
[travisci-url]: https://travis-ci.org/grantcarthew/node-console-probe
[js-standard-image]: https://img.shields.io/badge/code%20style-standard-brightgreen.svg
[js-standard-url]: http://standardjs.com/
[mppg-url]: https://github.com/grantcarthew/node-console-probe
[bithound-code-image]: https://www.bithound.io/github/grantcarthew/node-console-probe/badges/code.svg
[bithound-code-url]: https://www.bithound.io/github/grantcarthew/node-console-probe
[patreon-image]: https://img.shields.io/badge/patreon-donate-yellow.svg
[patreon-url]: https://www.patreon.com/grantcarthew
[nodei-npm-image]: https://nodei.co/npm/console-probe.png?downloads=true&downloadRank=true&stars=true
[nodei-npm-url]: https://nodei.co/npm/console-probe/
[archy-url]: https://www.npmjs.com/package/archy
[chalk-url]: https://www.npmjs.com/package/chalk
[fss-url]: https://www.npmjs.com/package/fast-safe-stringify
[example-eventemitter-image]: https://cdn.rawgit.com/grantcarthew/node-console-probe/b7f56e39/images/eventemitter.png
[example-probe-image]: https://cdn.rawgit.com/grantcarthew/node-console-probe/b7f56e39/images/aussieslang-probe.png
[example-json-image]: https://cdn.rawgit.com/grantcarthew/node-console-probe/b7f56e39/images/aussieslang-json.png
[example-yaml-image]: https://cdn.rawgit.com/grantcarthew/node-console-probe/b7f56e39/images/aussieslang-yaml.png
[example-ls-image]: https://cdn.rawgit.com/grantcarthew/node-console-probe/4ea69e0c/images/aussieslang-ls.png
[json-stringify-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify
[prettyjson-url]: https://www.npmjs.com/package/prettyjson
[json-colorizer-url]: https://www.npmjs.com/package/json-colorizer
[yaml-url]: http://yaml.org/
[jsome-url]: https://www.npmjs.com/package/jsome
[jstypes-url]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects