@hs-org/vue-browser-logger

A easy and highly customizable logging functionality.

Summary

Installation
Usage
Configuration
Features
Issues
License

Installation

To install the this package using Node Package Manager (NPM), simply type the following into a terminal window:

$ 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	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	?IVueLoggerSection[]	null	All registered sessions that will later be available for entry.

Configuration

Installing and exemplifying the configuration:

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:

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.

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.

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.

However, we are dealing with Vue, and it has reactive components that constantly change 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.

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 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.

This feature is also automatically applied if you modify the properties of the current Logger section, see 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.

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	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.

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:

const section: IVueLoggerSection = {
    id: 'GH',
    prefix: 'Github',
    color: 'black'
}

And I go to the global logger and use the join in this section.

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.

Unlike the IVueLogger#join 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.

For this we have the IVueLogger#clone method, consider that you have a gigantic logger configuration and you have your Github component that wants to have its own logger.

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 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.

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.

...
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:

const options: IVueLoggerGlobalOptions = {
    ...,
    sections: [{
        id: 'GH',
        prefix: 'Github',
        color: '#778beb'
    }]
};

we use on in our current logger:

// 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 file for more information about.