[![npm][npm]][npm-url]
[![node][node]][node-url]
[![devdeps][devdeps]][devdeps-url]
[![tests][tests]][tests-url]
[![coverage][cover]][cover-url]
# loglevelnext
`loglevelnext` is a modern logging library for Node.js and modern browsers,
written with modern patterns and practices which provides log level mapping of the
`console` object.
## Getting Started
First thing's first, install the module:
```console
npm install loglevelnext --save
```
## Usage
Users can choose to use `loglevelnext` in Node.js or in the client (browser).
```js
// Node.js
const log = require('loglevelnext');
log.info('bananas!');
```
```html
```
## Log Levels
By default `loglevelnext` ships supporting the following log level name-value
pairs:
```js
{
TRACE: 0,
DEBUG: 1,
INFO: 2,
WARN: 3,
ERROR: 4,
SILENT: 5
}
```
## Default Logger
When requiring `loglevelnext` in Node.js the default export will be an instance
of [`LogLevel`](docs/LogLevel.md) wrapped with some extra sugar.
When loading the `loglevelnext.js` script in the client (browser), the script
will assign `window.log` to an instance of [`LogLevel`](docs/LogLevel.md),
wrapped with that same extra sugar.
### Methods
Please see [`LogLevel`](docs/LogLevel.md) for documentation of all methods and
properties of every log instance, including the default instance.
#### `trace`, `debug`, `info`, `warn`, `error`
These methods correspond to the available log levels and accept parameters
identical to their `console` counterparts. eg.
```js
console.info('...');
console.info('...');
// ... etc
```
#### `getLogger(options)`
Returns a new `LogLevel` instance. The `options` parameter should be an `Object`
matching the options for the [`LogLevel`](docs/LogLevel.md) constructor.
_Note: the logger returned is cached, and subsequent requests for a logger of
the same name will return the same logger instance. If you require multiple
unique loggers of the same name, pass an `id` property with a unique identifier
and `getLogger` will use that over the `name`._
#### `noConflict()`
When using `loglevelnext` in a browser environment, you may encounter a scenario
in which `window.log` is already assigned when the script loads, resulting in
`window.log` being reassigned to `loglevelnext`. This method will restore
`window.log` to it's original value and return the default logger.
### Properties
#### `factories`
Type: `Array [ Class ]`
Gets an `Array` containing the factory classes available within `loglevelnext`
to outside modules. Particularily useful when creating plugins. eg.
```js
const log = require('loglevelnext');
const { MethodFactory } = log.factories;
class MyFactory extends MethodFactory { ... }
```
#### `loggers`
Type: `Array [ LogLevel ]`
Gets an `Array` containing references to the currently instantiated loggers.
## Factories aka Plugins
If you're used to using plugins with `loglevel`, fear not. The same capabilities
are available in `loglevelnext`, but in a much more straightforward and structured
way. `loglevelnext` supports by way of "Factories." A `Factory` is nothing more
than a class which defines several base methods that operate on the `console`
and provide functionality to a `LogLevel` instance. All factories must inherit from the
[`MethodFactory`][methodFactory] class, and may override any defined class functions.
For an example factory, please have a look at the [`PrefixFactory`][prefixFactory]
which provides similar functionality as the [loglevel-prefix](loglevelpre) plugin,
and is the factory which is used when a user passes the `prefix` option to a
`LogLevel` instance.
## Persisting the Level
Persisting the level of a log between sessions in a browser isn't the job of a
logging library. Primarily because working with `localStorage` these days is a
breeze. If you need to store and retrieve a log level value between sessions,
please look into leveraging the excellent and very tiny [`store2`](https://github.com/nbubna/store)
library.
## Browser Support
As mentioned, `loglevelnext` is a logging library for Node.js and _modern_
browsers, which means the latest versions of the major browsers. Unfortunately
"oldIE" versions aren't officially supported. The minimum Internet Exploder
version supported is IE10, though [Microsoft no longer supports it][oldie].
If you're in need of support for old or outdated browser versions, please use
the older [loglevel][loglevel], which supports browsers as old as IE6.
_Note: This library's distribution file is compiled in a way that will
technically work all the way back to IE8 - as that version and above support
`localStorage`. However, IE8 and IE9 require that the developer tools be open
prior to invoking this library._
## Contributing
We welcome your contributions! Please have a read of [CONTRIBUTING.md](CONTRIBUTING.md) for more information on how to get involved.
## Attribution
_This project is a fork of the much-loved [loglevel](loglevel) module._
Base Log SVG by [Freepik](http://www.freepik.com/) from [www.flaticon.com](http://www.flaticon.com).
## License
#### [MIT](./LICENSE)
[npm]: https://img.shields.io/npm/v/loglevelnext.svg
[npm-url]: https://npmjs.com/package/loglevelnext
[node]: https://img.shields.io/node/v/loglevelnext.svg
[node-url]: https://nodejs.org
[deps]: https://david-dm.org/shellscape/loglevelnext.svg
[deps-url]: https://david-dm.org/shellscape/loglevelnext
[devdeps]: https://david-dm.org/shellscape/loglevelnext/dev-status.svg
[devdeps-url]: https://david-dm.org/shellscape/loglevelnext
[tests]: http://img.shields.io/travis/shellscape/loglevelnext.svg
[tests-url]: https://travis-ci.org/shellscape/loglevelnext
[cover]: https://codecov.io/gh/shellscape/loglevelnext/branch/master/graph/badge.svg
[cover-url]: https://codecov.io/gh/shellscape/loglevelnext
[loglevel]: https://githhub.com/pimterry/loglevel
[loglevelpre]: https://github.com/kutuluk/loglevel-plugin-prefix
[oldie]: https://www.microsoft.com/en-us/windowsforbusiness/end-of-ie-support
[methodFactory]: lib/MethodFactory.js
[prefixFactory]: factory/PrefixFactory.js
