npm package: @hs-org/vue-browser-logger
Description: A easy and highly customizable logging functionality.
Author: Natan V.
Latest version: 0.1.42

# @hs-org/vue-browser-logger
A easy and highly customizable logging functionality.

## Summary
* [Installation](#installation)
* [Usage](#usage)
* [Configuration](#configuration)
* [Features](#features)
    * [Levels](#levels)
    * [Parameters](#parameters)
        * [Reactivity](#reactivity)
        * [Customization](#customization)
    * [Sections](#sections)
        * [Available sections](#creating-sections)
        * [Joining](#joining)
        * [Cloning](#cloning)
        * [Fast travel: "on"](#fast-travel-on-014)
* [Issues](#issues)
* [License](#license)

## Installation
To install the this package using [Node Package Manager (NPM)](https://www.npmjs.com/), simply type the following into a terminal window:
```bash
$ npm install @hs-org/vue-browser-logger
```

## Usage
To start using the logger you will need to install it on the Vue instance, as a plugin.\
We can explore some of the options available for the logger, such as:

| Name            | Type                                                                                                              | Default Value | Description                                                                                      |
| --------------- | ----------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------------------------ |
| showLogLevel    | boolean                                                                                                           | false         | If enabled it will show the log level before the message, example: "**[INFO]** My message."      |
| defaultLogLevel | [EnumLogLevels](https://github.com/hs-org/vue-browser-logger/blob/master/src/enums/log-level.ts)                  | INFO          | The default level that will be used in messages.                                                 |
| defaultSection  | ?string                                                                                                           | *null*        | The standard session in which the logger will work, you can learn more in [Sections](#sections). |
| sections        | ?[IVueLoggerSection[]](https://github.com/hs-org/vue-browser-logger/blob/master/src/interfaces/logger-section.ts) | *null*        | All registered sessions that will later be available for entry.                                  |

## Configuration
Installing and exemplifying the configuration:
```typescript
import Vue from 'vue'
import VueBrowserLoggerPlugin, {
    IVueLoggerGlobalOptions,
    EnumLogLevels
} from '@hs-org/vue-browser-logger';

/**
 * These are the available configurations listed above.
 * Those starting with `?` By default are null or undefined and not mandatory.
 */
const options: IVueLoggerGlobalOptions = {
    showLogLevel: true,
    defaultLogLevel: EnumLogLevels.INFO,
};

// Then install the plugin with desired options.
Vue.use(VueBrowserLoggerPlugin, options);
```
Now, the Logger will be available for you to use in any Vue instance,\
use either of the two alternatives:
```typescript
const logger = this.$log;
const logger = Vue.prototype.$log;
```
Consider the following options above and send a message using the logger.\
And below will be the form in which it will be displayed.
```typescript
this.$log.log("Hello Github!");
```
Output:
> [INFO] Hello Github!

## Features
### Levels
There are several log levels available for you to use, some correspond to the standard JavaScript `console` log, others from the Vue Logger itself so that you can control your messages accordingly.\
Inherited from the JavaScript console: **ERR, WARN, TRACE**.\
From the Vue Logger: **INFO, DEBUG**.
<br><br>
The **INFO** level is the standard message used by `console.log` but, customizable by Vue Logger.

### Parameters
#### Reactivity
Parameters are available in the standard console of our browser, you can pass an object for example in addition to your message and display it instead of a flat line, the object itself displayable and exploitable.\
<br>
However, we are dealing with Vue, and it has **[reactive components that constantly change](https://vuejs.org/guide/reactivity.html)** and if we want, for example, to log an object that we know will change, but we want its current state, when we use the log, it will also it will change there and we will have no information whatsoever.
<br>
<br>
Luckily for us, Vue Logger can help us work around this situation. It automatically detects if the component is reactive and if it is, it displays it as JSON, in its current state so it will not be modified in any situation and changed in the console. This option can be enabled when [installing](#installation) the plugin.

#### Customization
This part is easy, as in the standard console you can customize your messages with colors, formats and other things by passing them in CSS form after the message, in Vue Logger we support this option so that you can make your messages more stylish.
<br>
<br>
This feature is also automatically applied if you modify the properties of the current Logger section, see [Sections](#sections)

### Sections
If you like to style your console messages, keep them organized and know where they're coming from, Sections are just what you need.\
<br>
Basically, sections are places where your messages are kept, for example:
> You are in the **Github** component and you send a message on the console, due to the nature of Vue you will not know that it comes from **Github**.

and then you will be looking for your project files until you find the message, this is not cool, right.
for that, create a session in this component, it will have its own reservation of messages and you will always know that they are coming from there because they will be prefixed with your name, Github. For example:
> [Github] [INFO] Hey, I'm here, don't lose sight of me!

#### Available sections
Sections have basic and simple structures, you can create predefined sections to enter them later when installing the plugin, with this structure in the `sections` property.

| Name | Type | Required | Default Value | Description |
| ---- | ---- | -------- | ------------- | ----------- |
| id | string | true | | The section id, use something simple like a symbol or the first two letters of the section name, for example: AG for AuthenticationGateway. |
| prefix | string | true | | The prefix that will be displayed before the custom message, usually the name, for example: AuthenticationGateway or Github. |
| color | ?string | false | *null* | With this option you can define a color for your section `prefix`, which will be displayed in messages (RGB(A), HEX or HSL). |
| options | ?[IVueLoggerOptions](https://github.com/hs-org/vue-browser-logger/blob/master/src/interfaces/logger-options.ts#L4) | false | *null* | Options that you can optionally assign to the session. |

When installing the plugin, you can create a permanent section in his settings to enter it later.
```typescript
const options: IVueLoggerGlobalOptions = {
    ...,
    sections: [{
        id: 'AG',
        prefix: 'AuthenticationGateway',
        color: '#778beb'
    }]
};
```

#### Joining
The function of entering a section is basically to define the current section of that section you entered.\
That way all messages sent by that section will follow the pattern of the section you entered. Consider that I have the section:
```typescript
const section: IVueLoggerSection = {
    id: 'GH',
    prefix: 'Github',
    color: 'black'
}
```
And I go to the global logger and use the join in this section.
```typescript
Vue.prototype.$log.join('GH');
```

All messages sent by the global logger from now on will be prefixed with "Github", following the pattern in that section.\
But now imagine if every time you need to change the section **all messages in the entire application change**, it would be a mess, right, for that we have cloning.

#### Cloning
By default, only one singleton instance is passed to the entire Vue instance that inherits the plugin's installation settings.\
But when we have, for example, components like Github that we will create our own logger for, we don't want to redo the entire configuration of 0 to use it, or create a new instance of Vue Logger and configure it right there, we also need the permanent sections that we created initially.\
<br>
Unlike the *[`IVueLogger#join`](https://github.com/hs-org/vue-browser-logger/blob/master/src/interfaces/logger.ts#L6)* method, from now on we will have our own instance with our own sections and we will be able to enter and exit it without harming the rest of the application.
<br><br>
For this we have the *[`IVueLogger#clone`](https://github.com/hs-org/vue-browser-logger/blob/master/src/interfaces/logger.ts#L8)* method, consider that you have a gigantic logger configuration and you have your Github component that wants to have its own logger.
```typescript
import {Component, Vue} from 'vue-property-decorator'
import {IVueLogger} from '@hs-org/vue-browser-logger'

@Component
export default class Github extends Vue {
    
    private readonly logger!: IVueLogger = this.$log.clone()

    onMemberJoin(member: any): void {
        this.logger.log("A member joined", member);
    }

}
```
We can also create a different section for each action we perform.\
For us not to have a [boilerplate](https://pt.wikipedia.org/wiki/Boilerplate_code) and also not having to declare every time we need our own loggers in components, we create a mixins and then extend it wherever we want.\
<br>
The Vue's `mounted` function is rarely used, it generally uses more `created` so we can use it here. Or, you can use no `created` as well.
```typescript
...
export default class LoggerMixin extends Vue {
    
    protected readonly logger: IVueLogger = this.$log.clone();

    mounted(): void {
        setupLogger();
    }

    protected setupLogger(): void {}

}

export default class SomeClass extends mixins(LoggerMixin) {

    protected setupLogger(): void {
        super.setupLogger();
        this.logger.createSection({ id: 'MEMBER_JOIN', prefix: '->', color: 'green' });
        this.logger.createSection({ id: 'MEMBER_QUIT', prefix: '<-', color: 'red' });
    }

    onMemberJoin(member: string): void {
        this.logger.join('MEMBER_JOIN').log(`Member ${member} entered`);
        // "[INFO] (->) Member ? entered"
    }
   
    onMemberQuit(member: string): void {
        this.logger.join('MEMBER_QUIT').log(`Member ${member} left`);
        // "[INFO] (<-) Member ? left."
    }

}
```

### Fast travel: "on" (0.1.4+)
We already have functions like `join` and` clone` that help us to send logs in specific sections, but in situations where we just need a log and in a section it’s not cool that we need to clone creating a new instance and send the message in that section of that logger.
Therefore, starting with version 0.1.4 we introduced the `on` method, which consists of specifying the section you want to send the message before the parameters, it is very simple:

Imagine that this is your section configuration:
```typescript
const options: IVueLoggerGlobalOptions = {
    ...,
    sections: [{
        id: 'GH',
        prefix: 'Github',
        color: '#778beb'
    }]
};
```

we use on in our current logger:
```typescript
// the first parameter is the section id
this.$log.on('GH', 'Hello', 'everyone', '!')
```

###### Output
```
> [Github] Hello everyone !
```

> **Attention:** the sections available in `on` are only those currently in the Logger, not those configured globally. 

## Issues
If you encounter a bug with the Vue Browser Logger for we would like to hear about it.\
Search the existing issues and try to make sure your problem doesn't already exist before opening a new issue.\
It’s helpful if you include the version of the Node.js or browser environment and VueJS version you’re using.\
Please include a stack trace and reduced repro case when appropriate, too.\
The GitHub issues are intended for bug reports and feature requests.

## License
This project is distributed under the MIT License, see the [LICENSE](https://github.com/hs-org/vue-browser-logger/blob/master/LICENSE) file for more information about.