@jumpcutking/console

@jumpcutking/console is a sophisticated console reporting system designed to provide developers with enhanced feedback, including line traces of events, multi-object reporting, event listening, and consistent logging. This module modifies the Node.js global console to deliver a seamless and informative debugging experience with unlimited object depth.

Although currently optimized for server-side Node.js, future updates may include support for web browsers. For comprehensive documentation, please visit the docs.

This open-source project originates from a console module used in @jumpcutking/threads and is a key component of The Universe platform.

Features

• Enhanced Feedback: Provides line traces of events, multi-object reporting, and event listening.
• Consistent Logging: Modifies the global console for a uniform logging experience.
• Unlimited Depth: Allows unlimited object depth for detailed inspection.
• Error Handling: Improved handling of undefined objects and safe error generation.

What's New

v1.7.0

• Added improved undefined object handling when passing objects to console.function("String", $obj).

v1.6.0

• Additional bug fixes.
• Introduced jckConsole.TruncateTopLevel for reporting top-level object properties, useful for large objects without removing nested arrays and attached objects.

v1.5.0

• jckConsole now provides generateSafeError for automatically generating safe, communicable error objects.
• Added a string variable to match the original stack trace item for easier debugging in VSCode.

Installation

Install the module using NPM:

```bash npm install @jumpcutking/console ```

Usage

Integrating @jumpcutking/console is straightforward. Add the following code at the top of your script:

```javascript const jckConsole = require('@jumpcutking/console'); jckConsole.startup({ ...options }); ```

@jumpcutking/console will not override the global console object until `startup()` is called with the specified options.

Options

| Name | Type | Description | |--------------------|------------|--------------------------------------------------| | reportToConsole | boolean | Automatically report to the terminal and console.| | generateStacktrace | boolean | Generate a stacktrace object for each log message.| | storeLogs | boolean | Store logs in memory. | | depth | number | Depth to inspect objects (0 for unlimited). |

Adding a Callback or Listening to an Event

@jumpcutking/console supports two types of callbacks: one for all console calls and another for specific console functions.

Example

```javascript jckConsole.on('entry', (type, message, args, stack, from) => { // Your code here... });

// or

console.on('entry', (type, message, args, stack, from) => { // Your code here... }); ```

```javascript jckConsole.on('warn', (message, args, stack, from) => { // Your code here... });

// or

console.on('warn', (message, args, stack, from) => { // Your code here... }); ```

Supported Methods

| Name | Type | Description | |-------|----------|-----------------------| | log | function | The log function. | | info | function | The info function. | | warn | function | The warn function. | | error | function | The error function. | | debug | function | The debug function. |

Logging Entries

@jumpcutking/console can store logs in memory for later retrieval, each stamped with DateTime and, if enabled, a stacktrace object.

Example

```javascript const entries = jckConsole.getEntries(); console.getEntries();

// Clear entries jckConsole.clearEntries(); console.clearEntries(); ```

Log Entry Object

| Name | Type | Description | |-----------|---------------------|---------------------------------------------| | type | string | The type of console message. | | message | string | The message provided to the console object. | | args | * | Additional arguments provided. | | stack | Array | Stacktrace object array. | | when | DateTime | Entry creation time. | | from | object | Stacktrace object for the original caller. |

Building Documentation

To build the documentation, run the following command:

```bash npm run docs ```

Ensure you have the `jsdoc-to-markdown` module installed:

```bash npm install jsdoc-to-markdown ```

Using Node's Console Object

You can still use the original console object by creating a new instance after overriding the global console object.

```javascript const { Console } = require('node:console'); const myConsole = new Console({ stdout: process.stdout, stderr: process.stderr }); ```

Code Overview

This module replaces Node's built-in console with one that supports event listeners, enabling child threads to communicate using console.log syntax. It is designed for server-side use and has not been tested for client-side applications.

For detailed implementation, refer to the source code and examples provided in the repository.

Notes from the Project Creator

Rewritten: I've asked ChatGPT 4o to help me rewrite the README.md file for the @jumpcutking/console module. It's based on the one I've written and provides a deep indepth view of the code. If you have any questions, or prefer the older style, please let me know. Thank you!