1 |
|
2 | <div align="center">
|
3 | <img width="150" height="150" src="http://shellscape.org/assets/images/external/loglevelnext-icon.svg">
|
4 | </div>
|
5 |
|
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,
|
16 | written with modern patterns and practices which provides log level mapping of the
|
17 | `console` object.
|
18 |
|
19 | ## Getting Started
|
20 |
|
21 | First thing's first, install the module:
|
22 |
|
23 | ```console
|
24 | npm install loglevelnext --save
|
25 | ```
|
26 |
|
27 | ## Usage
|
28 |
|
29 | Users can choose to use `loglevelnext` in Node.js or in the client (browser).
|
30 |
|
31 | ```js
|
32 | // Node.js
|
33 | const log = require('loglevel');
|
34 |
|
35 | log.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 |
|
56 | By default `loglevelnext` ships supporting the following log level name-value
|
57 | pairs:
|
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 |
|
72 | When requiring `loglevelnext` in Node.js the default export will be an instance
|
73 | of [`LogLevel`](docs/LogLevel.md) wrapped with some extra sugar.
|
74 |
|
75 | When loading the `loglevelnext.js` script in the client (browser), the script
|
76 | will assign `window.log` to an instance of [`LogLevel`](docs/LogLevel.md),
|
77 | wrapped with that same extra sugar.
|
78 |
|
79 | ### Methods
|
80 |
|
81 | Please see [`LogLevel`](docs/LogLevel.md) for documentation of all methods and
|
82 | properties of every log instance, including the default instance.
|
83 |
|
84 | #### `trace`, `debug`, `info`, `warn`, `error`
|
85 |
|
86 | These methods correspond to the available log levels and accept parameters
|
87 | identical to their `console` counterparts. eg.
|
88 |
|
89 | ```js
|
90 | console.info('...');
|
91 | console.info('...');
|
92 | // ... etc
|
93 | ```
|
94 |
|
95 | #### `getLogger(options)`
|
96 |
|
97 | Returns a new `LogLevel` instance. The `options` parameter should be an `Object`
|
98 | matching the options for the [`LogLevel`](docs/LogLevel.md) constructor.
|
99 |
|
100 | _Note: the logger returned is cached, and subsequent requests for a logger of
|
101 | the same name will return the same logger instance. If you require multiple
|
102 | unique loggers of the same name, pass an `id` property with a unique identifier
|
103 | and `getLogger` will use that over the `name`._
|
104 |
|
105 | #### `noConflict()`
|
106 |
|
107 | When using `loglevelnext` in a browser environment, you may encounter a scenario
|
108 | in 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 |
|
116 | Type: `Array [ Class ]`
|
117 |
|
118 | Gets an `Array` containing the factory classes available within `loglevelnext`
|
119 | to outside modules. Particularily useful when creating plugins. eg.
|
120 |
|
121 | ```js
|
122 | const log = require('loglevelnext');
|
123 | const { MethodFactory } = log.factories;
|
124 | class MyFactory extends MethodFactory { ... }
|
125 | ```
|
126 |
|
127 | #### `loggers`
|
128 |
|
129 | Type: `Array [ LogLevel ]`
|
130 |
|
131 | Gets an `Array` containing references to the currently instantiated loggers.
|
132 |
|
133 | ## Factories aka Plugins
|
134 |
|
135 | If you're used to using plugins with `loglevel`, fear not. The same capabilities
|
136 | are available in `loglevelnext`, but in a much more straightforward and structured
|
137 | way. `loglevelnext` supports by way of "Factories." A `Factory` is nothing more
|
138 | than a class which defines several base methods that operate on the `console`
|
139 | and provide functionality to a `LogLevel` instance. All factories must inherit from the
|
140 | [`MethodFactory`][methodFactory] class, and may override any defined class functions.
|
141 |
|
142 | For an example factory, please have a look at the [`PrefixFactory`][prefixFactory]
|
143 | which provides similar functionality as the [loglevel-prefix](loglevelpre) plugin,
|
144 | and is the factory which is used when a user passes the `prefix` option to a
|
145 | `LogLevel` instance.
|
146 |
|
147 | ## Persisting the Level
|
148 |
|
149 | Persisting the level of a log between sessions in a browser isn't the job of a
|
150 | logging library. Primarily because working with `localStorage` these days is a
|
151 | breeze. If you need to store and retrieve a log level value between sessions,
|
152 | please look into leveraging the excellent and very tiny [`store2`](https://github.com/nbubna/store)
|
153 | library.
|
154 |
|
155 | ## Browser Support
|
156 |
|
157 | As mentioned, `loglevelnext` is a logging library for Node.js and _modern_
|
158 | browsers, which means the latest versions of the major browsers. Unfortunately
|
159 | "oldIE" versions aren't officially supported. The minimum Internet Exploder
|
160 | version supported is IE10, though [Microsoft no longer supports it][oldie].
|
161 |
|
162 | If you're in need of support for old or outdated browser versions, please use
|
163 | the 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
|
166 | technically 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
|
168 | prior to invoking this library._
|
169 |
|
170 | ## Contributing
|
171 |
|
172 | We 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 |
|
178 | Base 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
|