# @proc7ts/logger

> Logging API for Node.js and browsers

Latest version **2.0.0** (published 2023-09-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install @proc7ts/logger
pnpm add @proc7ts/logger
yarn add @proc7ts/logger
bun add @proc7ts/logger
```

## Health

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

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

Warnings: low downloads.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 2.0.0 |
| Published | 2023-09-17 |
| First published | 2021-06-02 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM |
| Dependencies | 0 |
| Unpacked size | 50.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 1 |
| Author | Ruslan Lopatin |
| Maintainers | lorus |
| Keywords | log, loggable, logger, logging |

## Links

- npm: https://www.npmjs.com/package/@proc7ts/logger
- Repository: https://github.com/proc7ts/logger
- Issues: https://github.com/proc7ts/logger/issues
- npm.io page: https://npm.io/package/@proc7ts/logger

## Alternatives

- [cli-color](https://npm.io/package/cli-color.md) — 3.4M weekly downloads
- [log](https://npm.io/package/log.md) — 1.3M weekly downloads
- [logstash-client](https://npm.io/package/logstash-client.md) — 4.5K weekly downloads
- [@nocobase/plugin-logger](https://npm.io/package/@nocobase/plugin-logger.md) — 2.0K weekly downloads
- [child-process-debug](https://npm.io/package/child-process-debug.md) — 695 weekly downloads

## Recent versions

- 2.0.0 (latest) — 2023-09-17
- 1.2.0-dev.3 (dev) — 2021-06-14
- 1.3.2 — 2021-08-31
- 1.3.1 — 2021-08-02
- 1.3.0 — 2021-07-17
- 1.2.0 — 2021-06-16
- 1.2.0-dev.2 — 2021-06-14
- 1.2.0-dev.1 — 2021-06-13
- 1.2.0-dev.0 — 2021-06-12
- 1.1.0 — 2021-06-02
- 1.0.0 — 2021-06-02

## README

# Logger API

[![NPM][npm-image]][npm-url]
[![Build Status][build-status-img]][build-status-link]
[![Code Quality][quality-img]][quality-link]
[![Coverage][coverage-img]][coverage-link]
[![GitHub Project][github-image]][github-url]
[![API Documentation][api-docs-image]][api documentation]

This package contains a logging API, such as [Logger] and [Loggable] interfaces along with some tools for their
processing and very basic [logger implementations].

The [@run-z/log-z] package is a reference implementation of this API. It supports structured logs, various logging
mechanisms (e.g. log files), and customizable log formats.

[npm-image]: https://img.shields.io/npm/v/@proc7ts/logger.svg?logo=npm
[npm-url]: https://www.npmjs.com/package/@proc7ts/logger
[build-status-img]: https://github.com/proc7ts/logger/workflows/Build/badge.svg
[build-status-link]: https://github.com/proc7ts/logger/actions?query=workflow:Build
[quality-img]: https://app.codacy.com/project/badge/Grade/f33e01ece3454d2a8a613536ea4228e2
[quality-link]: https://www.codacy.com/gh/proc7ts/logger/dashboard?utm_source=github.com&utm_medium=referral&utm_content=proc7ts/logger&utm_campaign=Badge_Grade
[coverage-img]: https://app.codacy.com/project/badge/Coverage/f33e01ece3454d2a8a613536ea4228e2
[coverage-link]: https://www.codacy.com/gh/proc7ts/logger/dashboard?utm_source=github.com&utm_medium=referral&utm_content=proc7ts/logger&utm_campaign=Badge_Coverage
[github-image]: https://img.shields.io/static/v1?logo=github&label=GitHub&message=project&color=informational
[github-url]: https://github.com/proc7ts/logger
[api-docs-image]: https://img.shields.io/static/v1?logo=typescript&label=API&message=docs&color=informational
[api documentation]: https://proc7ts.github.io/logger/
[@run-z/log-z]: https://www.npmjs.com/package/@run-z/log-z

## Logger

[logger]: #logger

`Logger` interface declares methods corresponding to generic logger levels:

- `error(...args)` - Logs error.
- `warn(...args)` - Logs warning.
- `info(...args)` - Logs informational message.
- `debug(...args)` - Logs debug message.
- `trace(...args)` - Logs tracing message. This may lead to outputting of stack trace.

Each method accepts arbitrary number of arguments.

## Loggable Values

[loggable]: #loggable-values

An object passed as an argument to one of the `Logger` methods can customize how it is logged by implementing a
`toLog()` method of `Loggable` interface.

In the simple case, the `toLog()` method may return another value that will be logged instead of the original one.

It may also return an array of values that will be inserted to the log line instead of original value. This may be an
empty array to completely remove the value from the log line.

A more advanced processing is possible by directly manipulating a `DueLog` parameter passed to the `toLog()` method.
This parameter has the following properties that can be directly manipulated:

- `on` - A hint indicating the logging stage.

  A `toLog()` method may wish to conditionally process the message depending on the stage.

  Possible values are:

  - `'in'` - _input stage_. Set for the logger input. I.e., for the log line passed to the logger method.
  - `'out'` - _output stage_. Set by log writer. I.e., right before the message written to the log.
  - `undefined` - _default stage_. When set, the value should be processed unconditionally.

- `line` - Log line to process and log.

  Can be modified or replaced to change the message to log.

- `index` - An index of currently processed element of the log `line`.

  May be equal to the log line length to indicate additional value processing that may affect the message to log.

  Can be modified to specify the next element to process.

Every logger recognizes `Loggable` instances and processes them accordingly. To process the log line manually a
`dueLog()` function can be used.

## Tagged Log Line

The [Logger] methods allow to log any values. The arguments passed to one of these method called _log line_. It is up to
the logger implementation of how to format the log line.

To customize the format of the log line a template string tagged by `logline` can be used:

```typescript
import { consoleLogger, logline } from '@proc7ts/logger';

consoleLogger.error(logline`
  Request: ${request.method} ${request.path}
  Error: ${error.statusCode} (${error.statusText})
`);

// Request: GET /favicon.ico Error: 404 (Not Found)
```

The `logline`-tagged template formats the log line accordingly the following rules:

1. Template strings and values not separated by whitespace joined into single string.
2. The values separated by whitespace are added to the log line as is.
3. Template strings trimmed.
4. Any number of subsequent whitespace in template strings replaced with single space.
5. Leading and/or trailing template string removed if it became empty.

All [Loggable] values processed before being joined into string. They may be processed as many times as requested.
The final joining happens at the output (`'out'`) or default (`undefined`) logging stage.

## Logger Implementations

[logger implementations]: #logger-implementations

### Console Logger

`consoleLogger` is a [Logger] instance that logs to [console].

Note that the first parameter isn't treated in any special way. I.e., it is not a [format string].

[console]: https://developer.mozilla.org/en-US/docs/Web/API/Console
[format string]: https://developer.mozilla.org/en-US/docs/Web/API/Console#using_string_substitutions

### Processing Logger

`processingLogger()` function creates a logger that processes `Loggable` values and logs with another logger.

### Proxy Logger

`proxyLogger()` function creates a logger that proxies logging to another one.

The target logger can change dynamically.

### Silent Logger

`silentLogger` is a [Logger] instance the never logs anything.

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