# @notera/terminal

> Terminal transport for Notera

Latest version **1.0.0** (published 2023-10-17) · GPL-3.0 license · 0 weekly downloads

## Install

```sh
npm install @notera/terminal
pnpm add @notera/terminal
yarn add @notera/terminal
bun add @notera/terminal
```

## Health

**Score 25/100 (F)** — status: abandoned.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 1.0.0 |
| Published | 2023-10-17 |
| First published | 2022-07-07 |
| Weekly downloads | 0 |
| License | GPL-3.0 |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 5 |
| Unpacked size | 15.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Johan Kanefur |
| Maintainers | zappen999 |

## Links

- npm: https://www.npmjs.com/package/@notera/terminal
- npm.io page: https://npm.io/package/@notera/terminal

## Dependencies (5)

- [@types/node](https://npm.io/package/@types/node.md) ^17.0.35
- [ansi-styles](https://npm.io/package/ansi-styles.md) ^5.2.0
- [@notera/core](https://npm.io/package/@notera/core.md) *
- [json-stringify-safe](https://npm.io/package/json-stringify-safe.md) ^5.0.1
- [@types/json-stringify-safe](https://npm.io/package/@types/json-stringify-safe.md) ^5.0.0

## Recent versions

- 1.0.0 (latest) — 2023-10-17
- 0.1.3 — 2022-10-19
- 0.1.2 — 2022-07-07

## README

# Notera Terminal Transport

This package provides a customizable terminal transport for the
[Notera](https://github.com/zappen999/notera) package. This transport
atomically writes to stdout like console.log, which makes it ideal for
development purposes.

![Notera terminal output](img/output-example.png)

## Installation
- `npm install @notera/core @notera/terminal`
- `yarn add @notera/core @notera/terminal`

## Usage

```ts
import notera from '@notera/core';
import terminalTransport from '@notera/terminal;

const logger = notera({
    levels: {
        err: 0,
        info: 1,
    },
});

logger.addTransport(terminalTransport({
    // Options
}))

logger.ctx('SERVER').info('Something is up', { some: 'meta' });
```

## Options

### Terminology

- **Segment** - Each logging line can be divided into segments:
  `date`, `ctx`, `msg`, `level` and `meta`.
- **Entry** - A logging entry generated by a call to one of the log functions in
  the Notera package.

```ts
type Opts<LevelsT extends string> = {
	// Disable colored/styled output. Defaults to false
	disableStyle?: boolean;

	// Never use more than one line for one log entry. This will hide
	// stack traces when logging errors, and only show the message
	// instead. Defaults to false
	singleLine?: boolean;

	// Colors to use for the different logging levels
	colors?: {
		[K in LevelsT]?: Style;
	};

	stream?: Writable;

	// Configuration used when handling each segment. Please see the
	// section "Configuring segments" for more information on how to
	// configure these.
	segment?: {
		time?: SegmentConfig<LevelsT>;
		ctx?: SegmentConfig<LevelsT>;
		level?: SegmentConfig<LevelsT>;
		msg?: SegmentConfig<LevelsT>;
		meta?: SegmentConfig<LevelsT>;
	};
};

type SegmentConfig<LevelsT extends string> = {
	// How this segment should be ordered amongst the other, defaults to 1
	index?: number;

	// Default false
	disabled?: boolean;

	// Function to format the segment
	format?: ((entry: LogEntry<LevelsT>, opts: Opts<LevelsT>) => string) | null;

	// Function to determine the style of this segment this specific log entry.
	style?:
		| Style
		| ((entry: LogEntry<LevelsT>, opts: Opts<LevelsT>) => Style)
		| null;
};
```

### Configuring segments

Example configuration:

```ts
{
    disableStyle: false,
    singleLine: false,
    colors: {
        emerg: 'red',
        alert: 'magenta',
        crit: 'red',
        err: 'red',
        warning: 'yellow',
        notice: 'white',
        info: 'green',
        debug: 'cyan',
    },
    segment: {
        time: {
            index: 10,
            format: _ => new Date().toISOString(),
            style: 'gray',
        },
        ctx: {
            index: 20,
            format: ({ ctx }) => ` [${ctx}]`,
        },
        level: {
            index: 30,
            style: ({ level }, opts) => opts.colors[level],
            format: ({ level }) => ' ' + level.toUpperCase(),
        },
        msg: {
            index: 40,
            format: ({ msg }) => `: ${msg}`,
        },
        meta: {
            index: 60,
            format: ({ meta }, opts) =>
                ` | ${JSON.stringify(meta, ...(opts.singleLine ? [] : [null, 2]))}`,
            style: 'gray',
        },
    },
};
```

#### Changing a segment

To change segment settings, you can simply overwrite them. Note that the
settings will be merged with the default settings at feature-level. See
the configuration examples below.

```ts
const config = {
    // ...
    segment: {
        ctx: {
            // Turns off formatting for the 'ctx' segment. Resulting in a simple
            // append from the previous segment.
            format: null,

            // Reset the default style of the 'ctx' segment
            style: null,

            // Reorder the 'ctx' segment to be placed after all other segments
            index: 100,
        },
    },
};
```


#### Disable a segment

```ts
const config = {
    segment: {
        ctx: {
            disabled: true,
        },
    },
};
```

### Colors

This package is using
[ansi-styles](https://github.com/chalk/ansi-styles) under the hood to
colorize the terminal output. Please refer to their readme to see what
colors are available.

---
_Source: https://npm.io/package/@notera/terminal · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._