npm package: @nsmp/logger
Description: Util for pretty log
Author: kegorov@naumen.ru
Latest version: 0.1.3

# Пакет для вывода сообщений в консоль браузера

@nsmp/logger - позволяет комбинировать вызовы на разных уровнях, а также управлять "видимостью" сообщений в зависимости от пользовательских условий.

## Установка
`npm i @nsmp/logger`

## Подключение
`import logger from '@nsmp/logger';`

## Как использовать
Произвольный набор аргументов может быть залоггирован вызовом функции `logger` напрямую, это создаст в консоли сообщение уровня `log`.

```javascript
logger('Logger log call');
// [logger 01.01.2021, 01:00:00] Logger log call
```

Уровень логгирования может быть другим, например:

```javascript
logger.warn('Logger level warn call', 'warning', 'arguments');
// [logger 01.01.2021, 01:00:00] Logger level warn call warning arguments

logger.error('Logger level error  call', {message: 'error message example'});
// [logger 01.01.2021, 01:00:00] Logger level error  call {message: "error message example"} []
```

Полный список уровней приведен ниже, однако наличие того или иного уровня зависит от браузера.
```javascript
logger.debug(); // [logger 01.01.2021, 01:00:00]
logger.error(); // [logger 01.01.2021, 01:00:00]
logger.info();  // [logger 01.01.2021, 01:00:00]
logger.log();   // [logger 01.01.2021, 01:00:00]
logger.warn();  // [logger 01.01.2021, 01:00:00]
```

> Вызов будет проигнорирован и не приводит к ошибке, если уровень логгирования не доступен в браузере.

Каждый вызов возвращает ссылку на функцию logger, что позволяет вызывать логгер несколько раз через точку:

```javascript
logger
	.warn('Получен объект настройки:', received)
	.warn('Ожидаемый объект настройки:', expected)
	.warn('Результат проверки:', validationResult);
```

## Настройка

По умолчанию все вызовы будут проигнорированы, а сообщения не будут направлены в консоль браузера. Для того, чтобы отобразить сообщения в консоли - необходимо выполнить первичную настройку: вызвать функцию `initialize` и передать ей объект настроек `options`.

> Вызов функции `initialize` следует выполнять непосредственно перед всеми другими вызовами логгера, в противном случае вызовы будут происходить с настройками "по умолчанию".

Ниже приведен рекомендуемый пример вызова функции инициализации, с настройками которые позволят отобразить сообщения только в режиме разработки:

```javascript
import logger from '@nsmp/logger';

logger.initialize({
	appName: 'my-app',
	enabled: process.env.NODE_ENV === 'development'
}).log('initialized!');

// [my-app 01.01.2021, 01:00:00] initialized!
```
Допустимые свойства объекта `options`:

* `@property {string} appName` - имя приложения, которое отображается в "префиксе по умолчанию";
* `@property {boolean} enabled` - флаг для включения логгирования;
* `@property {PrefixGetter} prefixGetter` - функция, которая формирует строку "префикс" для всех уровней логгирования, например:
  ```javascript
	prefixGetter: () => `(custom-prefix ${performance.now()})`
  ```

Если, на этапе инициализации, значение флага `enabled` было установлено в `true`, то в SessionStorage будет добавлена запись, у которой в качестве ключа будет значение поля `appName` из объекта настроек `options`, а в качестве значения будет сериализованный объект `Config`.

### Изменение настроек через консоль
Управлять конфигурацией логгера можно изменяя соответствующую запись в SessionStorage.

Если на этапе инициализации, значение флага `enabled` было установлено в `false`, то для того, чтобы включить логгирование необходимо добавить запись в `SessionStorage`. В качестве `key` следует указать значение поля `appName` из объекта настроек `options`, а в качестве `value` - один из 2-х вариантов ниже:
1. Сериализованный объект настроек `Config`
 ```javascript
	window.sessionStorage.setItem('my-app', JSON.stringify({enabled: true}));
 ```
2. Булево значение `true`
 ```javascript
	window.sessionStorage.setItem('my-app', true);
 ```

Допустимые свойства объекта `Config`:
* `@property {boolean} enabled` - true если логгирование включено.

## Совместимость
IE 10 и выше.

## Планы
* добавить возможность управления выводом в зависимости от уровня;
* добавить возможность устанавливать пользовательские пространства имен, для разделения логических частей приложения.