docs/README.md
# ๐ต๏ธ Consono ๐ต๏ธโโ๏ธ
The most correct, informative, appealing, and configurable variable inspector for JavaScript.
[](https://www.npmjs.com/package/consono)
[](https://github.com/r37r0m0d3l/consono)
[](https://github.com/r37r0m0d3l/consono)
[](https://github.com/r37r0m0d3l/consono)
[](https://github.com/r37r0m0d3l/consono)
[](https://github.com/r37r0m0d3l/consono)
---
## ๐ Motivation
Motivation and differences from other libraries.
- โ๏ธ **Light** and ๐ **dark** themes for terminal output.
- [prefers-color-scheme: Hello darkness, my old friend](https://web.dev/prefers-color-scheme/)
- ๐๏ธ **Configurable coloring** of variables.
- Can print to terminal or ๐ **return formatted and colored** string for later use.
- [How to get result string of console.log in javascript code? You can't.](https://stackoverflow.com/questions/17904957/how-to-get-result-string-of-console-log-in-javascript-code)
- ๐ **Turn on/off** output colorization.
- It even works on Windows - use [Windows Terminal](https://github.com/microsoft/terminal).
- **Configurable indent** - tabs ๐ spaces holy war ๐ผ๐ป โ๏ธ ๐ป๐ฆ.
- Availability to set the ๐ณ๏ธ **depth** for *object* inspection.
- Configurable #๏ธโฃ **max items** for *array*, *map*, *object*, *set*.
- โ๏ธ**Limit string length** when printing for better readability.
- Inspect both string ๐ **character count** and ๐ **string length**.
- [Itโs Not Wrong that "๐คฆ๐ผโโ๏ธ".length == 7](https://hsivonen.fi/string-length/).
- Inspect โ0๏ธ **positive zeroes** and โ0๏ธ **negative zeroes**.
- [JavaScriptโs two zeros](https://2ality.com/2012/03/signedzero).
- Inspect ๐ **items count** for collection-like variables *array*, *map*, *object*, *set*.
- Actually ๐ฌ **can inspect** *arguments*, *set* and *map*.
- Can print ๐ **function names** or mark them as **anonymous**.
- Handles ๐ **circular references**.
- Has ๐ **TypeScript** declaration file.
- [Writing Declaration Files for @types](https://devblogs.microsoft.com/typescript/writing-dts-files-for-types/).
- Avoids ๐ฑ๐๐ฅ **dependency hell**.
- [Wikipedia article](https://en.wikipedia.org/wiki/Dependency_hell).
- Can ๐งน **clear terminal** before output.
- Can ๐ฅ **exit** Node.js process after output.
- Import as ๐ **ECMAScript module**.
- And so on and so forth โพ๏ธ.
## ๐งฌ Examples
<table><thead><tr><td width="33%">
```javascript
consono(undefined);
consono(null);
```
</td><td width="67%">
</td></tr></thead><tbody></table>
---
<table><thead><tr><td width="33%">
```javascript
consono(true);
consono(false);
```
</td><td width="67%">
</td></tr></thead><tbody></table>
---
<table><thead><tr><td width="33%">
```javascript
consono(Infinity);
consono(Number.NEGATIVE_INFINITY);
consono(NaN);
consono(1);
consono(1.5);
consono(BigInt(9007199254740991));
```
</td><td width="67%">
</td></tr></thead><tbody></table>
---
<table><thead><tr><td width="100%">
```javascript
consono(new Date());
```
</td></tr><tr><td width="100%">
</td></tr></thead><tbody></table>
---
<table><thead><tr><td width="100%">
```javascript
consono("Hello, world ๐๐๐๐คฃ๐๐๐
๐๐๐", { stringMaxLength: 17 });
consono(Symbol("๐"));
```
</td></tr><tr><td width="100%">
</td></tr></thead><tbody></table>
---
<table><thead><tr><td width="33%">
```javascript
consono(/[0-9]+/);
consono(/\w+/giu);
```
</td><td width="67%">
</td></tr></thead><tbody></table>
---
<table><thead><tr><td width="33%">
```javascript
consono(function() {});
consono(function helloWorld() {});
consono(() => {});
```
</td><td width="67%">
</td></tr></thead><tbody></table>
---
<table><thead><tr><td width="33%">
```javascript
consono(new Promise(() => {}));
consono(async function helloWorld() {});
consono(async () => {});
consono(function* gen() { yield 1; });
```
</td><td width="67%">
</td></tr></thead><tbody></table>
---
<table><thead><tr><td width="33%">
```javascript
consono([1, 2, 3]);
consono(Int8Array.from([1, 2, 3]));
```
</td><td width="67%">
</td></tr></thead><tbody></table>
---
<table><thead><tr><td width="33%">
```javascript
consono(new ArrayBuffer(8));
consono(new SharedArrayBuffer(16));
```
</td><td width="67%">
</td></tr></thead><tbody></table>
---
<table><thead><tr><td width="33%">
```javascript
consono(new Set(["a", true, { prop: 1 }]));
consono(new WeakSet());
```
</td><td width="67%">
</td></tr></thead><tbody></table>
---
<table><thead><tr><td width="33%">
```javascript
consono(new Map([["first", "a"], [true, "b"]]));
consono(new WeakMap());
```
</td><td width="67%">
</td></tr></thead><tbody></table>
---
<table><thead><tr><td width="33%">
```javascript
consono({});
class MyClass {} const myClass = new MyClass(); myClass.deeper = new
MyClass(); consono(myClass);
```
</td><td width="67%">
</td></tr></thead><tbody></table>
---
<table><thead><tr><td width="33%">
```javascript
consono(new Error("Standard error"));
consono(new EvalError("Unable to run this code"));
consono(new RangeError("Must be less than 10 and greater than 0"));
consono(new ReferenceError("This is error from try/catch"));
consono(new SyntaxError("Not a source code"));
consono(new TypeError("Value is not of the expected type"));
```
</td><td width="67%">
</td></tr></thead><tbody></table>
---
<table><thead><tr><td width="33%">
```javascript
(function(a, b) { consono(arguments); })(true, false);
```
</td><td width="67%">
</td></tr></thead><tbody></table>
---
<table><thead><tr><td width="100%">
```javascript
consono(global || globalThis, { objectMaxProps: 3 });
```
</td></tr><tr><td width="100%">
</td></tr></thead><tbody></table>
---
## ๐ฆ Installation
```bash
npm -s install consono
```
## โจ๏ธ Include
The default is a function for printing variable.
```javascript
import { consono } from "consono";
```
Import multiple items: function, constructor, options object, theme objects.
```javascript
import {
Consono,
consono,
options,
THEME_DARK,
THEME_LIGHT,
} from "consono";
```
UNPKG CDN.
> Note that the web browser version has no theme support, limited color palette, and only support chromium based browsers.
```html
<script src="https://unpkg.com/consono/dist/consono.js"></script>
```
## โ๏ธ Options
```javascript
import { Consono } from "consono";
const options = {
clear: true,
quotesEnd: `โ`,
quotesStart: `โ`,
stringMaxLength: 54,
};
const theme = "light"; // default is "dark"
const consono = new Consono(options, theme);
consono.log("Cleared before output. Different quotes. And cut to 54!");
// string โข "Cleared before output. Different quotes. And cut to 54"
// (length=55, shown=54)
```
```javascript
import { Consono } from "consono";
const theme = {
argument: [253, 151, 31],
boolean: [174, 129, 255],
comment: [117, 113, 94],
keyword: [249, 38, 114],
name: [230, 219, 116],
number: [174, 129, 255],
plain: [255, 255, 255],
property: [102, 217, 239],
string: [166, 226, 46],
};
const consono = new Consono(null, theme);
consono.log("Themed");
```
```javascript
import { Consono, options } from "consono";
options.colorize = false;
const consono = new Consono(options);
consono.log("Text without colorization");
```
```javascript
import { consono } from "consono";
console.debug(
consono("Outputs a message only at the debug log level.", false)
);
```
## ๐ท๏ธ Instance
```javascript
const consono = Consono.factory(options, theme);
consono("This is log function with your own options");
```
## ๐ Log function
```javascript
import { consono } from "consono";
const map = new Map();
map.add("key", true);
consono(map);
```
Return string with variable description.
```javascript
const variableAsString = consono({}, false);
```
or
```javascript
const variableAsString = consono({}, { console: false });
```
```javascript
const defaultOptions = {
// Maximum number of elements in array to show
arrayMaxElements: 99,
// Assign symbol
assignSymbol: "โ",
// Clear console before output
clear: false,
// Colorize the output
colorize: true,
// Output to console
console: true,
// Default depth of object
depth: 20,
// 'false' - do nothing. 'true' - exit status ok.
// Number greater than zero - exit status with passed error code.
exit: false,
// Call console.log immediately
immediate: false,
// Print indentation
indent: "หห",
// Maximum number of entries in map to show
mapMaxEntries: 99,
// Maximum number of properties in object to show
objectMaxProps: 99,
// Quote start
quotesEnd: `"`,
// Quote end
quotesStart: `"`,
// Return inspected variable as string
returns: true,
// Maximum number of values in set to show
setMaxValues: 99,
// Call `process.stdout.write` instead of `console.log`.
stdout: false,
// Maximum length of string to show
stringMaxLength: 360,
};
consono("Some variable", defaultOptions);
```
## ๐ฎ Shortcuts
```javascript
// Exit code - 15
consonoExit("Some value", null, null, 15);
// No colorization, no description, only printing with `console.dir`
consonoJSON("Some value");
// No colorization, no description, only printing with `process.stdout.write`
consonoOut("Some value");
// No colorization
consonoPlain("Some value");
// Return only, no `console.log`
consonoReturn("Some value");
```
## ๐ Discover more
[My other projects](https://r37r0m0d3l.icu/open_source_map)
<img src="https://raw.githubusercontent.com/r37r0m0d3l/r37r0m0d3l/master/osmap.svg?sanitize=true" width="960" height="520" style="display:block;height:auto;margin-left:auto;margin-right:auto;min-height:520px;min-width:960px;width:100%;">