node-inspect-extracted

This library provides an as-faithful-as-possible implementation of Node.js's
util.inspect function.

It was built in such a way that it can be kept up-to-date with node's
implementation,
by taking the code directly from node's repo, and changing nothing but the
require() statements. All of the node built-in functions are emulated.
Many of the incompatibilities generated from that emulation are not
interesting for Web use cases.

Installation

``bash
npm install node-inspect-extracted
`

Use

This should work in node (for testing) and browsers, using either require, import, or as window.Inspect if you include this in your page as a script tag.

With require:

`js
const util = require('node-inspect-extracted');
console.log(util.inspect(1));
`

With import:

`mjs
import util from 'node-inspect-extracted';
console.log(util.inspect(2));
`

From the browser:

`html


`

API

The following util functions:

- [inspect(object[,showHidden|options[,depth [, colors]]])](https://nodejs.org/api/util.html#util_util_inspect_object_showhidden_depth_colors)
- [format(format[, ...args])](https://nodejs.org/api/util.html#util_util_format_format_args)
- [formatWithOptions(inspectOptions, format[, ...args])](https://nodejs.org/api/util.html#util_util_formatwithoptions_inspectoptions_format_args)

And these extras:

- Proxy(target, handler): a wrapper for the normal Proxy class that allows the showProxy option of inspect to work.
- stylizeWithColor(str, styleType): colorize str with ANSI escapes according to the styleType
- stylizeWithHTML(str, styleType): colorize str with HTML span tags

Colors

If you specify {colors: true} in the inspect options, you will get ANSI
escape codes, just as you would in Node. That's unlikely to be helpful to you
on the Web, so you might want stylizeWithHTML, which is also exported from the package:

`mjs
import { inspect, stylizeWithHTML } from 'node-inspect-extracted';
inspect({ a: 1 }, {
compact: false,
stylize: stylizeWithHTML,
});
`

which yields this ugly HTML:

`html
{
a: 1
}
`

If you want better HTML, the lightly-documented stylize option requires
a function that takes two parameters, a string, and a class name. The mappings
from class names to colors is in inspect.styles, so start with this:

`mjs
import { inspect } from 'node-inspect-extracted';
function stylizeWithHTML(str, styleType) {
const style = inspect.styles[styleType];
if (style !== undefined) {
return ${str};
}
return str;
}
inspect({ a: 1 }, {
compact: false,
stylize: stylizeWithHTML,
});
`

Known Limitations

- If you want your
Proxy
objects to have their internal object inspected, you may use the Proxy
constructor exported by this project. That was done mostly for test coverage
purposes. It is not recommended for production code.
- arguments
objects are not treated specially.
[bug]
- Several of the existing type checks (corresponding to Node's
util.types) are
weaker than the ones in Node, which has the freedom to use internal
capabilities of the runtime. This means you can fake out the type
detection to get output different than node.
[bug]
- Objects that have been mangled with Object.setPrototypeOf
do not retain their original type information.
[bug]
- Promise state is not visible. All Promises will show up as
Promise< pending > no matter what state they are in.
- Map and Set iterators will not show their internal state because that
cannot be done from unprivileged code without modifying the iterator.
Entry iterators are not distinguished from value iterators.
[bug]
- WeakMap and WeakSet will not show their contents, because those contents
cannot be iterated over in unprivileged code.
- Colorful stack traces are not completely accurate with respect to what
modules are Node-internal. This doesn't matter on the Web.

Developing

Check out NodeJS and this package next to one another:

git clone https://github.com/hildjj/node-inspect-extracted.git
git clone https://github.com/nodejs/node.git
cd node-inspect-extracted
npm install -g pnpm
pnpm install

- npm start to build, run all tests and start an auto-refreshing web server
to watch coverage change.
- npm run check to see if there have been any changes to node that need to be integrated.
- npm run check -- -d to see the diffs with node
- npm run check -- -u to indicate that we have merged the current changes

Tests run mostly against the pre-webpack source at the moment, but there are
some spot checks for the webpack output.

Supported Node.js versions

This project only supports versions of Node that the Node team is currently
supporting. Ava's
support statement
is what we will be using as well. Currently, that means Node 20`+ is
required. Older versions of node may work, but issues will not be fixed for them.

LICENSE

This code is an adaptation of the Node.js internal implementation, mostly from
the file lib/internal/util/inspect.js, which does not have the Joyent
copyright header. The maintainers of this package will not assert copyright
over this code, but will assign ownership to the Node.js contributors, with
the same license as specified in the Node.js codebase; the portion adapted
here should all be plain MIT license.