# @grund/logging

> The package exposes the following things:

Latest version **0.0.85** (published 2021-05-11) · MIT license · 0 weekly downloads

## Install

```sh
npm install @grund/logging
pnpm add @grund/logging
yarn add @grund/logging
bun add @grund/logging
```

## Health

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

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.85 |
| Published | 2021-05-11 |
| First published | 2020-08-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 2 |
| Unpacked size | 321.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | schlagerkhan |

## Links

- npm: https://www.npmjs.com/package/@grund/logging
- npm.io page: https://npm.io/package/@grund/logging

## Dependencies (2)

- [@grund/tools](https://npm.io/package/@grund/tools.md) ^0.0.85
- [@grund/events](https://npm.io/package/@grund/events.md) ^0.0.85

## Recent versions

- 0.0.85 (latest) — 2021-05-11
- 0.0.84 — 2021-05-09
- 0.0.83 — 2021-05-07
- 0.0.82 — 2021-05-07
- 0.0.81 — 2021-05-02
- 0.0.80 — 2021-05-02
- 0.0.79 — 2021-05-02
- 0.0.78 — 2021-05-02
- 0.0.77 — 2021-04-19
- 0.0.76 — 2021-04-19
- 0.0.75 — 2021-04-13
- 0.0.73 — 2021-04-13
- 0.0.72 — 2021-04-11
- 0.0.71 — 2021-04-11
- 0.0.70 — 2021-04-11
- … 59 more at https://npm.io/package/@grund/logging/versions

## README

# @grund/logging

The package exposes the following things:

-   `LoggingService`
    -   The class that contains pretty much all logic. More about this further down.
-   `Logging`
    -   A singleton instance of the `LoggingService`.
-   `trace`, `debug`, `info`, `warn`, `error`, `fatal`
    -   All logging functions available in `@grund/logging`.
    -   Originates from `Logging`.

## LoggingService

This class contains pretty much all logic in the package. It has a few different purposes:

1. Store logging configuration - which controls some aspects of the logging actions.
2. Instantiate and store the logging functions
3. Expose some utility functions (e.g. `identify` and `groupArguments`)
4. Extend the `EventService` class in order to enable listener and hook functionality. This enables us to listen/hook into every logging function that is fired. Read more about this in the `@grund/events` documentation.

## Logging functions

The logging function are listed above. All of them takes in an arbitrary number of arguments and prints them with the `console.log` function - prefixed with a uppercase title depending on what logging level (trace, debug, etc) is used.

All logging function also exposes a `silent` property. This is a function that acts the exact same way as the original function, but doesn't print anything. In other words it only fires the listeners and hooks.

Internally, all log functions are wrappers around the same functions. These wrapping functions only purpose is to create a data interface called `LogOptions` which is then passed to the internal functions and guides their behaviors. This interface might be good to know exists and it looks like:

```ts
interface LogOptions {
	level: LOG_LEVEL;
	isSilent: boolean;
}
```

### Usage

```ts
import { debug, warn, error } from '@grund/logging';

debug('Hello'); // Prints "[DEBUG] Hello"
warn.silent('Foo'); // Prints nothing but fires the listeners.
error('Yolo'); // Prints "[ERROR] Yolo"
```

## Events

As mentioned above, `LoggingService` implements the `EventService`. The event schema is the following:

```ts
namespace LoggingEventSchema {
	interface Listeners {
		log: (options: LogOptions, loggingArgs: LoggingArgs) => any;

		trace: (...args: LoggingArgs) => any;
		debug: (...args: LoggingArgs) => any;
		info: (...args: LoggingArgs) => any;
		warn: (...args: LoggingArgs) => any;
		error: (...args: LoggingArgs) => any;
		fatal: (...args: LoggingArgs) => any;

		identify: (...args: IdentifyArgs) => any;
	}

	interface Hooks {
		beforeLog: (options: LogOptions, args: LoggingArgs) => any;
		beforeIdentify: (...args: IdentifyArgs) => any;
	}
}
```

Worth noting is that the `log` listener is always fired before any of the specific log function listeners.

### Usage

```ts
import { Logging } from '@grund/logging';

Logging.listeners.on('debug', () => {
	console.log('Debug fired');
});
Logging.listeners.on('log', (options, loggingArgs) => {
	console.log(`Log fired! Level: ${options.log}`);
});
Logging.hooks.on('beforeLog', (options, loggingArgs) => {
	console.log('Before log');
});

debug('Hello');

// First prints "Before log"
// Prints "Log fired! Level: debug"
// Prints "Debug fired"
```

## Identification

In order to implement some sort of production logging or error tracking one needs to be able to identify what user is generating the logs. For this we have the `identify` function which is exposed by `LoggingService` (and, in turn, the `Logging` singleton). The function itself doesn't do much, but acts more as a relay and common interface to other solutions.

For instance, this is used beautifully in collaboration with the `@grund/logging-sentry`. This package listens to whenever you call `identify` and forwards it to the Sentry library. In this way you don't need to interact with the Sentry library by yourself. This functionality can of course be extended to any third party logging package.

### Usage

```ts
import { Logging } from '@grund/logging';

Logging.listeners.on('identify', (userId) => console.log({ userId }));

Logging.identify(1); // Prints "{ userId: 1 }" through the listener
```

## Configuration

The `LoggingService` contains a "global" property called `config` that determines some of the logging behavior. The current configurations are:

-   `Logging.config.print.isEnabled`
    -   Determines if the logs should be printed with `console.log`.
    -   Defaults to `IS_DEV`.
-   `Logging.config.print.isGrouped`
    -   If true, the arguments are grouped by the types `string`, `Error` and plain object.
    -   Used by other libraries (e.g. @grund/logging-sentry).
    -   Defaults to `false`.
-   `Logging.errors.shouldObjectify`
    -   Used when grouping the arguments (by the function `Logging.groupArguments`)
    -   If true and any error argument contains the function `toObject`, call it and use the return value instead of the error itself.
    -   Defaults to `true`
-   `Logging.errors.shouldIncludeStack`
    -   Determines if to include the stacks when objectifying the errors.
    -   Defaults to `true`

### Usage

```ts
import { debug, Logging } from '@grund/logging';

Logging.config.print.isEnabled = false;

debug('Hello'); // Prints nothing
```

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