[![Gem Version](https://badge.fury.io/rb/delogger.svg)](https://badge.fury.io/rb/delogger)

# Delogger

This gem is a wrapper for browser's `window.console` object. It makes your console convenient and
pretty.

![Demo](/images/demo.png?raw=true)

## Features

- [Output visibility control](#initialization-options)
- [A different take on groups](#groups)
- [Markdown-like output formatting](#formatting)

## Why?

### Output visibility control

As your JS logic becomes more and more complex, it's getting harder do debug it. And clearing out
all those `console.log` calls from your files can be really annoying. Besides, you might want to
leave those messages in your code because you know you'll likely need to write them again when
you'll work on the next feature. But at same time you don't want to flood your clients' consoles
when they are browsing your production website.

Delogger solves this problem by letting you turn it on or off.
See [initialization options](#initialization-options).

### Console groups and asynchronous scripts

Most browsers let you organize your console output by creating [groups](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#consolegroupobject_object).
You can even nest them! However, when you're dealing with asynchronous code, it can get very messy.

Consider this example:
```js
async function f1() {
    console.group('group 1');
    console.log('function 1 start');
    await sleep(1000);
    console.log('function 1 end');
    console.groupEnd();
}

async function f2() {
    console.group('group 2');
    console.log('function 2 start');
    await sleep(500);
    console.log('function 2 end');
    console.groupEnd();
}

f1(); f2()
```

Result:

![Async groups result](/images/async_bad_result.png?raw=true)

This is an extreme example, but groups fail to work in the same way when you're dealing with real code.

Delogger provides a different implementation of groups that solves this problem. See [groups](#groups).

## Getting Started

### Rails:

Add the gem to your Gemfile:
```ruby
gem 'delogger', '~> 0.3.0'
```

Add this to your `application.js`:
```
//= require delogger
```

And `application.css`:
```
*= require delogger
```

### Without Rails:

Include `vendor/assets/javascripts/delogger.js` and `vendor/assets/stylesheets/delogger.css` into
your application.

## Usage

First, Delogger has to be initialized:
```js
logger = new Delogger
```
See also: [initialization options](#initialization-options).

By default, Delogger is **enabled**. You can use `logger.disable()` and `logger.enable()` to disable
or enable the logger respectively. Delogger is storing its settings in browser's `localStorage`, so
you only have to enable/disable it once. **It's strongly recommended to
[disable Delogger](#initialization-options) on your production website!**

Delogger supports following methods (most of them work similarly or exactly like their
`window.console`'s counterparts'):
- [`assert`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#assert)
- [`count`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#count)
- [`debug`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#consoledebugobject_object)
- [`dir`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#dir)
- [`dirxml`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#consoledirxmlobject)
- [`error`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#error)
- [`group`](#groups)
- [`info`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#consoleinfoobject_object)
- [`log`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#log)
- [`profile` and `profileEnd`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#profile)
- [`time` and `timeEnd`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#time)
- [`timeStamp`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#timestamp)
- [`trace`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#trace)
- [`warn`](https://developers.google.com/web/tools/chrome-devtools/console/console-reference#warn)

### Initialization options

You can pass options to Delogger upon initialization:
```js
logger = new Delogger({ enabledByDefault: true, enableFormatting: true, collapseGroups: true })
```
- `enabledByDefault`: Defines whether to enable or disable the logger if it has not been enabled
locally with `logger.enable()`. It is *highly recommended* to set this option to `false` for
production. Default: `true`.
- `enableFormatting`: Defines whether [formatting](#formatting) should be enabled. Default: `true`.
- `collapseGroups`: Defines whether [groups](#groups) created with `logger.group()` should be
collapsed or not. Default: `true` (collapsed).

### Groups

Groups in Delogger don't behave like `window.console`'s groups do. In Delogger, groups work kind of
like *namespaces*.

```js
logger.group('my group').log('inside my group')
logger.group('other group', 'a nested group!').log('i\'m a bird in a nest')
logger.group('other group').log('inside another group')
logger.log('outside')
```

Result:

![Group example](/images/group_example.png?raw=true)

Let's take a look at our example with asynchronous code now:

```js
async function f1() {
    logger.group('group 1').log('function 1 start');
    await sleep(1000);
    logger.group('group 1').log('function 1 end');
}

async function f2() {
    logger.group('group 2').log('function 2 start');
    await sleep(1500);
    logger.group('group 2').log('function 2 end');
}

f1(); f2()
```

Result:

![Async groups success](/images/async_good_result.png?raw=true)

### Formatting

Delogger supports Markdown-like string formatting. Here's the options:
- `**bold**`
- `*italic*`
- `~strikethrough~`
- `_underline_`
- `[custom text].classOne.classTwo...`. This syntax allows you to apply CSS classes to text in
square brackets. Available classes are: `badge`, `bold`, `italic`, `strikethrough`, `underline`,
`focus` and [color classes](#color-classes).

At the moment, you cannot nest formatting options into each other.

#### Color classes

Delogger supports following color classes (both for badges and normal text):
- `.blue`
- `.orange`
- `.red`
- `.green`
- `.cyan`
- `.purple`

#### Adding custom / overriding existing styles

All styles are declared in a stylesheet and thus are easily extensible.
See [`assets/stylesheets/delogger.scss`](assets/stylesheets/delogger.scss).
At the moment, only these attributes are supported: `margin`, `color`, `background-color`,
`border-radius`, `padding`, `font-weight`, `font-style`, `text-decoration`.

### Focus mode

If you want to debug a certain block of code, but your console is flooded with messages, you can
enter the Focus mode with `logger.focus()`. In this mode, you will only see "focused" output. To
produce "focused" output, use `logger.focus('my text')`. To leave Focus mode, use `logger.unfocus()`.

## Development

Modify files in the `assets` folder, compile them afterwards using `./bin/compile`.

### TODO:

- `{ custom styles }`
- Nested formatting
- Browser support
- Add an option to add supported CSS attributes
- Object formatting, function formatting...

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/akxcv/delogger.

## License

The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).