npm package: @northern/console
Description: A lightweight TypeScript console wrapper with support for color tags and quiet mode.
Author: northern
Latest version: 1.0.5

# @northern/console

A lightweight TypeScript console wrapper with support for color tags and quiet mode.

## Features

- **Color Tags**: Use XML-style tags to colorize console output
- **Quiet Mode**: Suppress all output when needed
- **Color Toggle**: Disable colors for CI environments or plain text output
- **Customizable Colors**: Define your own color map using Chalk
- **TypeScript Support**: Full type definitions included

## Installation

```bash
npm install @northern/console
```

## Usage

### Basic Usage

```typescript
import Console from '@northern/console';

const console = new Console();

// Use color tags to format output
console.write('Run <command>npm install</command> to get started');
console.write('This is <highlight>important</highlight>!');
console.write('Status: <success>Complete</success>');
```

### Quiet Mode

```typescript
// Create a quiet console that suppresses all output
const quietConsole = new Console(true);

quietConsole.write('This will not appear'); // No output
```

### Disable Colors

```typescript
// Create a console without colors (useful for CI environments)
const plainConsole = new Console(false, false);

plainConsole.write('Run <command>npm test</command>'); // Output: "Run npm test"
```

### Custom Color Map

```typescript
import chalk from 'chalk';

const customColors = {
  command: chalk.green,
  highlight: chalk.yellow,
  error: chalk.bgRed.whiteBright,
  warning: chalk.bgYellow.black,
  info: chalk.bgBlue.whiteBright,
  success: chalk.bgGreen.whiteBright,
  custom: chalk.magenta.bold,
};

const console = new Console(false, true, customColors);

console.write('This is <custom>custom colored</custom> text');
```

### Dumping Objects

```typescript
const console = new Console();

const data = {
  user: { name: 'John', age: 30 },
  settings: { theme: 'dark' }
};

// Dump with full depth and colors
console.dump(data);
```

## API

### Constructor

```typescript
new Console(isQuiet?: boolean, isColor?: boolean, colorMap?: Record<string, ChalkInstance>)
```

**Parameters:**
- `isQuiet` (optional): When `true`, suppresses all output. Defaults to `false`.
- `isColor` (optional): When `true`, enables color output. Defaults to `true`.
- `colorMap` (optional): Custom color mapping using Chalk instances.

### Methods

#### `write(...args: unknown[]): void`

Writes output to the console with color tag processing. Suppressed in quiet mode.

**Example:**
```typescript
console.write('Status: <success>OK</success>');
console.write('Multiple', 'arguments', 'supported');
```

#### `dump(o: unknown): void`

Dumps an object to the console with full depth and colors. Useful for debugging. Suppressed in quiet mode.

**Example:**
```typescript
console.dump({ complex: { nested: { object: true } } });
```

## Default Color Tags

The following color tags are available by default:

- `<command>text</command>` - Green text
- `<highlight>text</highlight>` - Yellow text
- `<error>text</error>` - White text on red background
- `<warning>text</warning>` - Black text on yellow background
- `<info>text</info>` - White text on blue background
- `<success>text</success>` - White text on green background

## License

MIT