UNPKG

6.41 kBMarkdownView Raw
1
2<div align="center">
3 <img width="150" height="150" src="http://shellscape.org/assets/images/external/loglevelnext-icon.svg">
4</div>
5&nbsp;
6
7[![npm][npm]][npm-url]
8[![node][node]][node-url]
9[![devdeps][devdeps]][devdeps-url]
10[![tests][tests]][tests-url]
11[![coverage][cover]][cover-url]
12
13# loglevelnext
14
15`loglevelnext` is a modern logging library for Node.js and modern browsers,
16written with modern patterns and practices which provides log level mapping of the
17`console` object.
18
19## Getting Started
20
21First thing's first, install the module:
22
23```console
24npm install loglevelnext --save
25```
26
27## Usage
28
29Users can choose to use `loglevelnext` in Node.js or in the client (browser).
30
31```js
32// Node.js
33const log = require('loglevel');
34
35log.info('bananas!');
36```
37
38```html
39<!-- browser -->
40<!doctype>
41<html>
42 <head>
43 <script src="/path/to/loglevelnext.js"></script>
44 </head>
45 <body>
46 <script>
47 window.log.info('zomg');
48 </script>
49 </body>
50</html>
51
52```
53
54## Log Levels
55
56By default `loglevelnext` ships supporting the following log level name-value
57pairs:
58
59```js
60{
61 TRACE: 0,
62 DEBUG: 1,
63 INFO: 2,
64 WARN: 3,
65 ERROR: 4,
66 SILENT: 5
67}
68```
69
70## Default Logger
71
72When requiring `loglevelnext` in Node.js the default export will be an instance
73of [`LogLevel`](docs/LogLevel.md) wrapped with some extra sugar.
74
75When loading the `loglevelnext.js` script in the client (browser), the script
76will assign `window.log` to an instance of [`LogLevel`](docs/LogLevel.md),
77wrapped with that same extra sugar.
78
79### Methods
80
81Please see [`LogLevel`](docs/LogLevel.md) for documentation of all methods and
82properties of every log instance, including the default instance.
83
84#### `trace`, `debug`, `info`, `warn`, `error`
85
86These methods correspond to the available log levels and accept parameters
87identical to their `console` counterparts. eg.
88
89```js
90console.info('...');
91console.info('...');
92// ... etc
93```
94
95#### `getLogger(options)`
96
97Returns a new `LogLevel` instance. The `options` parameter should be an `Object`
98matching the options for the [`LogLevel`](docs/LogLevel.md) constructor.
99
100_Note: the logger returned is cached, and subsequent requests for a logger of
101the same name will return the same logger instance. If you require multiple
102unique loggers of the same name, pass an `id` property with a unique identifier
103and `getLogger` will use that over the `name`._
104
105#### `noConflict()`
106
107When using `loglevelnext` in a browser environment, you may encounter a scenario
108in which `window.log` is already assigned when the script loads, resulting in
109`window.log` being reassigned to `loglevelnext`. This method will restore
110`window.log` to it's original value and return the default logger.
111
112### Properties
113
114#### `factories`
115
116Type: `Array [ Class ]`
117
118Gets an `Array` containing the factory classes available within `loglevelnext`
119to outside modules. Particularily useful when creating plugins. eg.
120
121```js
122const log = require('loglevelnext');
123const { MethodFactory } = log.factories;
124class MyFactory extends MethodFactory { ... }
125```
126
127#### `loggers`
128
129Type: `Array [ LogLevel ]`
130
131Gets an `Array` containing references to the currently instantiated loggers.
132
133## Factories aka Plugins
134
135If you're used to using plugins with `loglevel`, fear not. The same capabilities
136are available in `loglevelnext`, but in a much more straightforward and structured
137way. `loglevelnext` supports by way of "Factories." A `Factory` is nothing more
138than a class which defines several base methods that operate on the `console`
139and provide functionality to a `LogLevel` instance. All factories must inherit from the
140[`MethodFactory`][methodFactory] class, and may override any defined class functions.
141
142For an example factory, please have a look at the [`PrefixFactory`][prefixFactory]
143which provides similar functionality as the [loglevel-prefix](loglevelpre) plugin,
144and is the factory which is used when a user passes the `prefix` option to a
145`LogLevel` instance.
146
147## Persisting the Level
148
149Persisting the level of a log between sessions in a browser isn't the job of a
150logging library. Primarily because working with `localStorage` these days is a
151breeze. If you need to store and retrieve a log level value between sessions,
152please look into leveraging the excellent and very tiny [`store2`](https://github.com/nbubna/store)
153library.
154
155## Browser Support
156
157As mentioned, `loglevelnext` is a logging library for Node.js and _modern_
158browsers, which means the latest versions of the major browsers. Unfortunately
159"oldIE" versions aren't officially supported. The minimum Internet Exploder
160version supported is IE10, though [Microsoft no longer supports it][oldie].
161
162If you're in need of support for old or outdated browser versions, please use
163the older [loglevel][loglevel], which supports browsers as old as IE6.
164
165_Note: This library's distribution file is compiled in a way that will
166technically work all the way back to IE8 - as that version and above support
167`localStorage`. However, IE8 and IE9 require that the developer tools be open
168prior to invoking this library._
169
170## Contributing
171
172We welcome your contributions! Please have a read of [CONTRIBUTING.md](CONTRIBUTING.md) for more information on how to get involved.
173
174## Attribution
175
176_This project is a fork of the much-loved [loglevel](loglevel) module._
177
178Base Log SVG by [Freepik](http://www.freepik.com/) from [www.flaticon.com](http://www.flaticon.com).
179
180## License
181
182#### [MIT](./LICENSE)
183
184
185[npm]: https://img.shields.io/npm/v/loglevelnext.svg
186[npm-url]: https://npmjs.com/package/loglevelnext
187
188[node]: https://img.shields.io/node/v/loglevelnext.svg
189[node-url]: https://nodejs.org
190
191[deps]: https://david-dm.org/shellscape/loglevelnext.svg
192[deps-url]: https://david-dm.org/shellscape/loglevelnext
193
194[devdeps]: https://david-dm.org/shellscape/loglevelnext/dev-status.svg
195[devdeps-url]: https://david-dm.org/shellscape/loglevelnext
196
197[tests]: http://img.shields.io/travis/shellscape/loglevelnext.svg
198[tests-url]: https://travis-ci.org/shellscape/loglevelnext
199
200[cover]: https://codecov.io/gh/shellscape/loglevelnext/branch/master/graph/badge.svg
201[cover-url]: https://codecov.io/gh/shellscape/loglevelnext
202
203[loglevel]: https://githhub.com/pimterry/loglevel
204[loglevelpre]: https://github.com/kutuluk/loglevel-plugin-prefix
205[oldie]: https://www.microsoft.com/en-us/windowsforbusiness/end-of-ie-support
206[methodFactory]: lib/MethodFactory.js
207[prefixFactory]: factory/PrefixFactory.js