yves 1.0.99 → 1.1.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2017 Joris Röling
+Copyright (c) 2017-2026 Joris Röling
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,69 +1,163 @@
-yves
-====
+# yves
 
-a customizable value inspector for Node.js inspired by [eyes](https://github.com/cloudhead/eyes.js/)
+A customizable value inspector for Node.js, inspired by [eyes](https://github.com/cloudhead/eyes.js/).
 
-synopsis
---------
+Handles circular objects, pretty-prints object literals, and supports ANSI color output, HTML output, and [debug](https://github.com/visionmedia/debug) integration.
 
-I was tired of looking at cluttered output in the console -- something needed to be done,
-`sys.inspect()` didn't display regexps correctly, and was too verbose, and I had an hour or two to spare. 
-So I decided to have some fun. _yves_ were born.
+## Install
 
-*yves* also deals with circular objects in an intelligent way, and can pretty-print object literals.
+```
+npm install yves
+```
 
-usage
------
+Requires Node.js >= 18.
 
-    var inspect = require('yves').inspector({styles: {all: 'magenta'}});
+## Usage
 
-    inspect(something); // inspect with the settings passed to `inspector`
+```js
+import yves from 'yves'
 
-or
+yves.inspect(something)
+```
 
-    var yves = require('yves');
+With a label:
 
-    yves.inspect(something); // inspect with the default settings
+```js
+yves.inspect(something, 'my value')
+```
 
-you can pass a _label_ to `inspect()`, to keep track of your inspections:
+With a custom inspector:
 
-    yves.inspect(something, "a random value");
+```js
+const inspect = yves.inspector({ styles: { all: 'magenta' } })
 
-If you want to return the output of yves without printing it, you can set it up this way:
+inspect(something)
+```
 
-    var inspect = require('yves').inspector({ stream: null });
+To return the string instead of printing to stdout:
 
-    sys.puts(inspect({ something: 42 }));
+```js
+const inspect = yves.inspector({ stream: null })
 
-customization
--------------
+console.log(inspect({ something: 42 }))
+```
 
-These are the default styles and settings used by _yves_.
+## Options
 
-    styles: {                 // Styles applied to stdout
-        all:     'cyan',      // Overall style applied to everything
-        label:   'underline', // Inspection labels, like 'array' in `array: [1, 2, 3]`
-        other:   'inverted',  // Objects which don't have a literal representation, such as functions
-        key:     'bold',      // The keys in object literals, like 'a' in `{a: 1}`
-        special: 'grey',      // null, undefined...
-        string:  'green',
-        number:  'magenta',
-        bool:    'blue',      // true false
-        regexp:  'green',     // /\d+/
-    },
-    
-    pretty: true,             // Indent object literals
-    hideFunctions: false,     // Don't output functions at all
-    stream: process.stdout,   // Stream to write to, or null
-    maxLength: 2048           // Truncate output if longer
+Pass options to `inspector()` or as the third argument to `inspect()`.
 
-You can overwrite them with your own, by passing a similar object to `inspector()` or `inspect()`.
+### Styles
 
-    var inspect = require('yves').inspector({
-        styles: {
-            all: 'magenta',
-            special: 'bold'
-        },
-        maxLength: 512
-    });
+```js
+styles: {
+    all:     'cyan',      // Overall style applied to everything
+    label:   'underline', // Inspection labels, like 'array' in `array: [1, 2, 3]`
+    other:   'inverted',  // Objects without a literal representation (functions)
+    key:     'bold',      // Object keys, like 'a' in `{a: 1}`
+    special: 'grey',      // null, undefined
+    string:  'green',
+    number:  'magenta',
+    bool:    'blue',
+    regexp:  'green',
+}
+```
 
+Available styles: `bold`, `underline`, `inverse`, `cyan`, `magenta`, `blue`, `yellow`, `green`, `red`, `grey`.
+
+Set `styles: false` to disable all styling. Set `colors: false` to disable ANSI codes.
+
+### Formatting
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `pretty` | `true` | Indent object literals and arrays |
+| `indent` | `4` | Spaces per indentation level |
+| `singleLineMax` | `2` | Max keys before an object is printed multiline |
+| `trailingComma` | `true` | Add trailing commas in multiline output |
+| `templateStrings` | `true` | Use backtick syntax for strings containing newlines/tabs |
+| `escape` | `true` | Escape invisible characters in strings |
+| `json` | `false` | Use JSON-style output (double-quoted keys and strings) |
+| `sortKeys` | `false` | Sort object keys alphabetically |
+| `sorted` | `false` | Deep-sort the input object before inspecting |
+
+### Truncation
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `maxLength` | `-1` | Max output length in characters (`-1` for unlimited) |
+| `maxStringLength` | - | Truncate strings beyond this length |
+| `maxArrayLength` | - | Show at most N array elements |
+| `maxObjectKeys` | - | Show at most N object keys |
+
+### Filtering
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `includes` | `null` | Only show keys matching these strings/regexps |
+| `excludes` | `null` | Hide keys matching these strings/regexps |
+| `obfuscates` | `null` | Replace values of matching keys with `<<obfuscated>>` |
+| `hideFunctions` | `false` | Omit function-valued properties |
+
+```js
+yves.inspect(obj, 'filtered', {
+    includes: ['name', /^user/],
+    obfuscates: ['password', /secret/],
+})
+```
+
+### Output
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `stream` | `process.stdout` | Writable stream, or `null` to return the string |
+| `colors` | auto-detected | Enable ANSI color codes |
+| `html` | `false` | Output HTML `<span>` tags instead of ANSI codes |
+| `decycle` | `true` | Safely handle circular references |
+
+## HTML output
+
+```js
+const inspect = yves.inspector({ stream: null, html: true, colors: true })
+
+const html = inspect({ hello: 'world' })
+// Returns a <pre> block with <span> color styling
+```
+
+## Debug integration
+
+yves integrates with the [debug](https://github.com/visionmedia/debug) module. Use the `%y` formatter for compact output or `%Y` for sorted, function-free output:
+
+```js
+import debug from 'debug'
+const log = debug('app')
+
+log('user data: %y', userData)
+```
+
+## Console hijacking
+
+Replace `console.log` / `console.dir` etc. with yves-powered output routed through `debug`:
+
+```js
+yves.console('myapp')
+
+console.log('hello')   // now outputs via debug('myapp:console:log')
+console.dir({ a: 1 })  // pretty-printed via yves
+
+yves.console_unset()   // restore original console
+```
+
+## API
+
+- **`yves.inspect(obj, label?, options?)`** -- inspect and print to stream
+- **`yves.inspector(options?)`** -- returns a reusable inspect function
+- **`yves.options(opts)`** -- update global defaults
+- **`yves.stylize(str, style, options)`** -- apply a single ANSI/HTML style
+- **`yves.typeOf(value)`** -- enhanced `typeof` (distinguishes array, regexp, date, buffer, null, bigint)
+- **`yves.debugger(namespace)`** -- create a [debug](https://github.com/visionmedia/debug) logger
+- **`yves.console(namespace?)`** -- hijack console with debug-powered output
+- **`yves.console_unset()`** -- restore original console methods
+
+## License
+
+MIT