UNPKG

loglevelnext/README.md

Version:

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('loglevelnext');
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

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('loglevelnext');`
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`