@xylabs/logger/README.md

XYLabs Logger Library

# @xylabs/logger

[![npm][npm-badge]][npm-link]
[![license][license-badge]][license-link]

> XYLabs Logger Library

## Install

Using npm:

```sh
npm install {{name}}
```

Using yarn:

```sh
yarn add {{name}}
```

Using pnpm:

```sh
pnpm add {{name}}
```

Using bun:

```sh
bun add {{name}}
```


## License

See the [LICENSE](LICENSE) file for license rights and limitations (LGPL-3.0-only).

## Reference

### packages

  ### logger

    ### .temp-typedoc

      ### classes

        ### <a id="ConsoleLogger"></a>ConsoleLogger

[**@xylabs/logger**](#../README)

***

A LevelLogger that delegates to the global `console` object.

## Extends

- [`LevelLogger`](#LevelLogger)

## Constructors

### Constructor

```ts
new ConsoleLogger(level?): ConsoleLogger;
```

### Parameters

#### level?

[`LogLevelValue`](#../type-aliases/LogLevelValue) = `LogLevel.warn`

### Returns

`ConsoleLogger`

### Overrides

[`LevelLogger`](#LevelLogger).[`constructor`](LevelLogger.md#constructor)

## Properties

### level

```ts
readonly level: LogLevelValue;
```

### Inherited from

[`LevelLogger`](#LevelLogger).[`level`](LevelLogger.md#level)

***

### logger

```ts
readonly logger: Logger;
```

### Inherited from

[`LevelLogger`](#LevelLogger).[`logger`](LevelLogger.md#logger)

## Accessors

### debug

### Get Signature

```ts
get debug(): LogFunction;
```

#### Returns

[`LogFunction`](#../type-aliases/LogFunction)

### Inherited from

[`LevelLogger`](#LevelLogger).[`debug`](LevelLogger.md#debug)

***

### error

### Get Signature

```ts
get error(): LogFunction;
```

#### Returns

[`LogFunction`](#../type-aliases/LogFunction)

### Inherited from

[`LevelLogger`](#LevelLogger).[`error`](LevelLogger.md#error)

***

### info

### Get Signature

```ts
get info(): LogFunction;
```

#### Returns

[`LogFunction`](#../type-aliases/LogFunction)

### Inherited from

[`LevelLogger`](#LevelLogger).[`info`](LevelLogger.md#info)

***

### log

### Get Signature

```ts
get log(): LogFunction;
```

#### Returns

[`LogFunction`](#../type-aliases/LogFunction)

### Inherited from

[`LevelLogger`](#LevelLogger).[`log`](LevelLogger.md#log)

***

### trace

### Get Signature

```ts
get trace(): LogFunction;
```

#### Returns

[`LogFunction`](#../type-aliases/LogFunction)

### Inherited from

[`LevelLogger`](#LevelLogger).[`trace`](LevelLogger.md#trace)

***

### warn

### Get Signature

```ts
get warn(): LogFunction;
```

#### Returns

[`LogFunction`](#../type-aliases/LogFunction)

### Inherited from

[`LevelLogger`](#LevelLogger).[`warn`](LevelLogger.md#warn)

        ### <a id="IdLogger"></a>IdLogger

[**@xylabs/logger**](#../README)

***

A logger wrapper that prefixes every log message with a bracketed identifier.
Useful for distinguishing log output from different components or instances.

## Implements

- [`Logger`](#../interfaces/Logger)

## Constructors

### Constructor

```ts
new IdLogger(logger, id?): IdLogger;
```

### Parameters

#### logger

[`Logger`](#../interfaces/Logger)

#### id?

() => `string`

### Returns

`IdLogger`

## Accessors

### id

### Set Signature

```ts
set id(id): void;
```

#### Parameters

##### id

`string`

#### Returns

`void`

## Methods

### debug()

```ts
debug(...data): void;
```

### Parameters

#### data

...`unknown`[]

### Returns

`void`

### Implementation of

```ts
Logger.debug
```

***

### error()

```ts
error(...data): void;
```

### Parameters

#### data

...`unknown`[]

### Returns

`void`

### Implementation of

```ts
Logger.error
```

***

### info()

```ts
info(...data): void;
```

### Parameters

#### data

...`unknown`[]

### Returns

`void`

### Implementation of

```ts
Logger.info
```

***

### log()

```ts
log(...data): void;
```

### Parameters

#### data

...`unknown`[]

### Returns

`void`

### Implementation of

```ts
Logger.log
```

***

### trace()

```ts
trace(...data): void;
```

### Parameters

#### data

...`unknown`[]

### Returns

`void`

### Implementation of

```ts
Logger.trace
```

***

### warn()

```ts
warn(...data): void;
```

### Parameters

#### data

...`unknown`[]

### Returns

`void`

### Implementation of

```ts
Logger.warn
```

        ### <a id="LevelLogger"></a>LevelLogger

[**@xylabs/logger**](#../README)

***

A logger that filters messages based on a configured log level.
Methods for levels above the configured threshold return a no-op function.

## Extended by

- [`ConsoleLogger`](#ConsoleLogger)

## Implements

- [`Logger`](#../interfaces/Logger)

## Constructors

### Constructor

```ts
new LevelLogger(logger, level?): LevelLogger;
```

### Parameters

#### logger

[`Logger`](#../interfaces/Logger)

#### level?

[`LogLevelValue`](#../type-aliases/LogLevelValue) = `LogLevel.warn`

### Returns

`LevelLogger`

## Properties

### level

```ts
readonly level: LogLevelValue;
```

***

### logger

```ts
readonly logger: Logger;
```

## Accessors

### debug

### Get Signature

```ts
get debug(): LogFunction;
```

#### Returns

[`LogFunction`](#../type-aliases/LogFunction)

### Implementation of

[`Logger`](#../interfaces/Logger).[`debug`](../interfaces/Logger.md#debug)

***

### error

### Get Signature

```ts
get error(): LogFunction;
```

#### Returns

[`LogFunction`](#../type-aliases/LogFunction)

### Implementation of

[`Logger`](#../interfaces/Logger).[`error`](../interfaces/Logger.md#error)

***

### info

### Get Signature

```ts
get info(): LogFunction;
```

#### Returns

[`LogFunction`](#../type-aliases/LogFunction)

### Implementation of

[`Logger`](#../interfaces/Logger).[`info`](../interfaces/Logger.md#info)

***

### log

### Get Signature

```ts
get log(): LogFunction;
```

#### Returns

[`LogFunction`](#../type-aliases/LogFunction)

### Implementation of

[`Logger`](#../interfaces/Logger).[`log`](../interfaces/Logger.md#log)

***

### trace

### Get Signature

```ts
get trace(): LogFunction;
```

#### Returns

[`LogFunction`](#../type-aliases/LogFunction)

### Implementation of

[`Logger`](#../interfaces/Logger).[`trace`](../interfaces/Logger.md#trace)

***

### warn

### Get Signature

```ts
get warn(): LogFunction;
```

#### Returns

[`LogFunction`](#../type-aliases/LogFunction)

### Implementation of

[`Logger`](#../interfaces/Logger).[`warn`](../interfaces/Logger.md#warn)

        ### <a id="SilentLogger"></a>SilentLogger

[**@xylabs/logger**](#../README)

***

A logger that does not log anything.
This is useful when you want to disable logging
like when running unit tests or in silent mode.
It implements the `Logger` interface but all methods
are no-op functions.

## Implements

- [`Logger`](#../interfaces/Logger)

## Constructors

### Constructor

```ts
new SilentLogger(): SilentLogger;
```

### Returns

`SilentLogger`

## Properties

### debug

```ts
readonly debug: (..._data) => undefined = NoOpLogFunction;
```

A log function that silently discards all arguments.

### Parameters

#### \_data

...`unknown`[]

### Returns

`undefined`

### Implementation of

[`Logger`](#../interfaces/Logger).[`debug`](../interfaces/Logger.md#debug)

***

### error

```ts
readonly error: (..._data) => undefined = NoOpLogFunction;
```

A log function that silently discards all arguments.

### Parameters

#### \_data

...`unknown`[]

### Returns

`undefined`

### Implementation of

[`Logger`](#../interfaces/Logger).[`error`](../interfaces/Logger.md#error)

***

### info

```ts
readonly info: (..._data) => undefined = NoOpLogFunction;
```

A log function that silently discards all arguments.

### Parameters

#### \_data

...`unknown`[]

### Returns

`undefined`

### Implementation of

[`Logger`](#../interfaces/Logger).[`info`](../interfaces/Logger.md#info)

***

### log

```ts
readonly log: (..._data) => undefined = NoOpLogFunction;
```

A log function that silently discards all arguments.

### Parameters

#### \_data

...`unknown`[]

### Returns

`undefined`

### Implementation of

[`Logger`](#../interfaces/Logger).[`log`](../interfaces/Logger.md#log)

***

### trace

```ts
readonly trace: (..._data) => undefined = NoOpLogFunction;
```

A log function that silently discards all arguments.

### Parameters

#### \_data

...`unknown`[]

### Returns

`undefined`

### Implementation of

[`Logger`](#../interfaces/Logger).[`trace`](../interfaces/Logger.md#trace)

***

### warn

```ts
readonly warn: (..._data) => undefined = NoOpLogFunction;
```

A log function that silently discards all arguments.

### Parameters

#### \_data

...`unknown`[]

### Returns

`undefined`

### Implementation of

[`Logger`](#../interfaces/Logger).[`warn`](../interfaces/Logger.md#warn)

      ### functions

        ### <a id="NoOpLogFunction"></a>NoOpLogFunction

[**@xylabs/logger**](#../README)

***

```ts
function NoOpLogFunction(..._data): undefined;
```

A log function that silently discards all arguments.

## Parameters

### \_data

...`unknown`[]

## Returns

`undefined`

        ### <a id="getFunctionName"></a>getFunctionName

[**@xylabs/logger**](#../README)

***

```ts
function getFunctionName(depth?): string;
```

Retrieves the name of the calling function by inspecting the stack trace.

## Parameters

### depth?

`number` = `2`

The stack frame depth to inspect (default: 2, the caller's caller).

## Returns

`string`

The function name, or '<unknown>' if it cannot be determined.

      ### interfaces

        ### <a id="Logger"></a>Logger

[**@xylabs/logger**](#../README)

***

Interface to handle overlap between Winston &
`console` with as much congruency as possible.

## Properties

### debug

```ts
debug: LogFunction;
```

***

### error

```ts
error: LogFunction;
```

***

### info

```ts
info: LogFunction;
```

***

### log

```ts
log: LogFunction;
```

***

### trace

```ts
trace: LogFunction;
```

***

### warn

```ts
warn: LogFunction;
```

      ### type-aliases

        ### <a id="LogFunction"></a>LogFunction

[**@xylabs/logger**](#../README)

***

```ts
type LogFunction = (...data) => void;
```

A generic logging function that accepts any number of arguments.

## Parameters

### data

...`unknown`[]

## Returns

`void`

        ### <a id="LogLevelKey"></a>LogLevelKey

[**@xylabs/logger**](#../README)

***

```ts
type LogLevelKey = EnumKey<typeof LogLevel>;
```

String key for a log level (e.g. 'error', 'warn', 'info').

        ### <a id="LogLevelValue"></a>LogLevelValue

[**@xylabs/logger**](#../README)

***

```ts
type LogLevelValue = EnumValue<typeof LogLevel>;
```

Numeric value of a log level (1 through 6).

        ### <a id="LogVerbosity"></a>LogVerbosity

[**@xylabs/logger**](#../README)

***

```ts
type LogVerbosity = LogLevelKey;
```

Alias for LogLevelKey, representing the verbosity setting as a string.

      ### variables

        ### <a id="LogLevel"></a>LogLevel

[**@xylabs/logger**](#../README)

***

```ts
const LogLevel: Enum<{
  error: 1;
  warn: 2;
  info: 3;
  log: 4;
  debug: 5;
  trace: 6;
}>;
```

Numeric log level values, from least verbose (error=1) to most verbose (trace=6).


[npm-badge]: https://img.shields.io/npm/v/@xylabs/logger.svg
[npm-link]: https://www.npmjs.com/package/@xylabs/logger
[license-badge]: https://img.shields.io/npm/l/@xylabs/logger.svg
[license-link]: https://github.com/xylabs/sdk-js/blob/main/LICENSE