1 | # acho
|
2 |
|
3 | <p align="center">
|
4 | <br>
|
5 | <img src="https://i.imgur.com/qdpBpnw.gif" alt="acho">
|
6 | <br>
|
7 | </p>
|
8 |
|
9 | ![Last version](https://img.shields.io/github/tag/achohq/acho.svg?style=flat-square)
|
10 | [![Build Status](http://img.shields.io/travis/achohq/acho/master.svg?style=flat-square)](https://travis-ci.org/achohq/acho)
|
11 | [![Dependency status](http://img.shields.io/david/achohq/acho.svg?style=flat-square)](https://david-dm.org/achohq/acho)
|
12 | [![Dev Dependencies Status](http://img.shields.io/david/dev/achohq/acho.svg?style=flat-square)](https://david-dm.org/achohq/acho#info=devDependencies)
|
13 | [![NPM Status](http://img.shields.io/npm/dm/acho.svg?style=flat-square)](https://www.npmjs.org/package/acho)
|
14 | [![Donate](https://img.shields.io/badge/donate-paypal-blue.svg?style=flat-square)](https://paypal.me/kikobeats)
|
15 |
|
16 | > An extremely simple (but powerful) logging system for NodeJS and browser.
|
17 |
|
18 | # Why
|
19 |
|
20 | * Easy to use, customize and extend.
|
21 | * Expressive API with chaineable methods.
|
22 | * Mininum dependencies, just focussing on one thing.
|
23 | * Compatible with AMD/CommonJS or just global object in the browser.
|
24 |
|
25 | ## Install
|
26 |
|
27 | ```bash
|
28 | npm install acho
|
29 | ```
|
30 |
|
31 | If you want to use it in the browser (powered by [Browserify](http://browserify.org/)):
|
32 |
|
33 | ```bash
|
34 | bower install acho --save
|
35 | ```
|
36 |
|
37 | and later add it to your HTML:
|
38 |
|
39 | ```html
|
40 | <script src="bower_components/acho/dist/acho.js"></script>
|
41 | ```
|
42 |
|
43 | ## Usage
|
44 |
|
45 | ### First steps
|
46 |
|
47 | Acho exports itself according to UMD best practices, which means that no matter where you are using the library, you get a version tailored for your environment.
|
48 |
|
49 | If you're using a module loader (or Node), simple require the library as you would any other module.
|
50 |
|
51 | If you're using a browser, the library falls back to attaching itself to window as the global `Acho`.
|
52 |
|
53 | #### CommonJS
|
54 |
|
55 | ```js
|
56 | var Acho = require('acho');
|
57 | var acho = Acho();
|
58 | ```
|
59 |
|
60 | #### Global/Browser
|
61 |
|
62 | ```js
|
63 | var acho = Acho();
|
64 | ```
|
65 |
|
66 | #### AMD
|
67 |
|
68 | I don't use personally use AMD, so I can't conjure an example, but it should work fine as well.
|
69 |
|
70 | It's time to use it!
|
71 |
|
72 | <p align="center">
|
73 | <br>
|
74 | <img src="docs/images/00.png" alt="acho">
|
75 | <br>
|
76 | </p>
|
77 |
|
78 | ```js
|
79 | acho.info('hello world');
|
80 | ```
|
81 |
|
82 | All public methods are chainable:
|
83 |
|
84 | <p align="center">
|
85 | <br>
|
86 | <img src="docs/images/01.png" alt="acho">
|
87 | <br>
|
88 | </p>
|
89 |
|
90 | ```js
|
91 | acho
|
92 | .info('hello world')
|
93 | .error('something bad happens');
|
94 | ```
|
95 |
|
96 | Maybe you don't want to output the message, but store it for later use:
|
97 |
|
98 | <p align="center">
|
99 | <br>
|
100 | <img src="docs/images/02.png" alt="acho">
|
101 | <br>
|
102 | </p>
|
103 |
|
104 | ```js
|
105 | acho.push('success', 'good job', 'well done', 'great!');
|
106 | console.log(acho.messages.success);
|
107 | ```
|
108 |
|
109 | If you want to print previously stored messages, just call the method `print`:
|
110 |
|
111 | <p align="center">
|
112 | <br>
|
113 | <img src="docs/images/03.png" alt="acho">
|
114 | <br>
|
115 | </p>
|
116 |
|
117 | ```js
|
118 | acho.print()
|
119 | ```
|
120 |
|
121 | You might be thinking: Can I combine both, to store and both print a message? Absolutely!
|
122 |
|
123 | <p align="center">
|
124 | <br>
|
125 | <img src="docs/images/04.png" alt="acho">
|
126 | <br>
|
127 | </p>
|
128 |
|
129 | ```js
|
130 | acho.add('info', 'this message is printed and stored');
|
131 | console.log(acho.messages.info)
|
132 | ```
|
133 |
|
134 | ### Defining the level
|
135 |
|
136 | Establishing the loglevel is a good way to filter out undesired information from output. The available levels by default are:
|
137 |
|
138 | - `fatal` : Display calls to `.fatal()` messages.
|
139 | - `error` : Display calls to `.fatal()`, `.error()` messages.
|
140 | - `warn` : Display calls from `.fatal()`, `.error()`, `.warn()` messages.
|
141 | - `info` : Display calls from `.fatal()`, `.error()`, `.warn()`, `info()` messages.
|
142 | - `debug` : Display calls from `.fatal()`, `.error()`, `.warn()`, `info()`, `debug()` messages.
|
143 |
|
144 | Additionally exists two special levels:
|
145 |
|
146 | - `muted` : Avoid all output.
|
147 | - `all` : Allow print all message types.
|
148 |
|
149 | The default log level is `all`. You can define it in the constructor:
|
150 |
|
151 | ```js
|
152 | var acho = Acho({level: 'debug'})
|
153 | ```
|
154 |
|
155 | or at runtime:
|
156 |
|
157 | ```js
|
158 | acho.level = 'debug';
|
159 | ```
|
160 |
|
161 | ### Customization
|
162 |
|
163 | You can completely customize the library to your requirements: changes colors, add more types, sort the priorities... the internal structure of the object is public and you can edit it dynamically. **You have the power**.
|
164 |
|
165 | By default the messages structure is brief: Just the message type followed by the message itself.
|
166 |
|
167 | But you can easily modify the output. For example, let's add a timestamp to each message:
|
168 |
|
169 | <p align="center">
|
170 | <br>
|
171 | <img src="docs/images/05.png" alt="acho">
|
172 | <br>
|
173 | </p>
|
174 |
|
175 | ```js
|
176 | var acho = Acho({
|
177 | color: true,
|
178 | level: 'debug',
|
179 |
|
180 | // Customize how to print the 'type' of each message
|
181 | outputType: function(type) {
|
182 | return '[' + type + '] » ';
|
183 | },
|
184 |
|
185 | // Customize how to print the message.
|
186 | // Add things before and/or after.
|
187 | outputMessage: function(message) {
|
188 | return Date() + ' :: ' + message;
|
189 | }
|
190 | });
|
191 |
|
192 | acho.info('I am hungry');
|
193 | ```
|
194 |
|
195 | If you need customize more the output you can setup `.print` `.generateMessage` (see below) that are a more low level methods for generate and print the output message.
|
196 |
|
197 | ## API
|
198 |
|
199 | ### Acho({Object} [options])
|
200 |
|
201 | Create a logger. Available options:
|
202 |
|
203 | <img src="docs/images/07.png" align="right">
|
204 |
|
205 | ##### **{String}** keyword
|
206 |
|
207 | Default: `loglevel`
|
208 |
|
209 | Instead of print the type log level, print the keyword. By default this behavior is not activated.
|
210 |
|
211 | You can pass the special keyword `symbol` to show an unicode icon. This is special behavior for CLI programs.
|
212 |
|
213 | <img src="docs/images/08.png" align="right">
|
214 |
|
215 | ##### **{String}** align
|
216 |
|
217 | Default: ` `
|
218 |
|
219 | It adds an alignment separator between the type of the message and the message.
|
220 |
|
221 | You can provide your own separator or disable it providing a `false`.
|
222 |
|
223 | <img src="docs/images/06.png" align="right">
|
224 |
|
225 | ##### **{Boolean}** diff
|
226 |
|
227 | Default: `false`
|
228 |
|
229 | Prints timestamp between log from the same level. Specially useful to debug timmings.
|
230 |
|
231 | ##### **{Boolean}** color
|
232 |
|
233 | Default: `false`.
|
234 |
|
235 | Enable or disable colorized output.
|
236 |
|
237 | ##### **{Boolean}** upperCase
|
238 |
|
239 | Default: `false`.
|
240 |
|
241 | Enable or disable print log level in upper case.
|
242 |
|
243 | ##### **{Boolean}** timestamp
|
244 |
|
245 | Default: `false`.
|
246 |
|
247 | Prints a counter timestamp associated with each log line. Useful for debug log traces.
|
248 |
|
249 | ##### **{String}** level
|
250 |
|
251 | Default: `all`
|
252 |
|
253 | Provides the logging level. This sets from what level print logs using tranport.
|
254 |
|
255 | Additionally you can provide `muted` to express don't print logs.
|
256 |
|
257 | ##### **{Function}** transport
|
258 |
|
259 | Default: `console.log`
|
260 |
|
261 | Defines where write the log message.
|
262 |
|
263 | ##### **{Object}** types
|
264 |
|
265 | You can provide the types and priorities.
|
266 |
|
267 | ##### **{Object}** messages
|
268 |
|
269 | It provides a initial internal store state per each log level. This option is useful when you want to integrate the logger with the ouptut of a delayed function.
|
270 |
|
271 | ##### **{Function}** print
|
272 |
|
273 | Provides a function that determines how to print the messages. By default uses `.generateMessage` for generate the mesage that will be outputted.
|
274 |
|
275 | ##### **{Function}** outputType
|
276 |
|
277 | Provides a function to customize the type in the output.
|
278 |
|
279 | ##### **{Function}** outputMessage
|
280 |
|
281 | Provides a function to customize the message in the output.
|
282 |
|
283 | ##### **{Function}** generateMessage
|
284 |
|
285 | Provides a function that generate the message to be outputted. It combines other internal methods for generate the output (as `.isPrintable` or `.colorize`) and normally you are not interested in the definition of it, but you can provide it as option as well.
|
286 |
|
287 | ##### **{Function}** generateTypeMessage
|
288 |
|
289 | Provides a function used to generate the type message.
|
290 |
|
291 | ### .push({String} <type>, {String} <message>)
|
292 |
|
293 | Store a message of given `type` internally.
|
294 |
|
295 | ### .add({String} <type>, {String} <message>)
|
296 |
|
297 | Store a message of given `type` internally and also output it.
|
298 |
|
299 | For each level you have a function following the pattern:
|
300 |
|
301 | ### .print()
|
302 |
|
303 | Prints all messages internally stored.
|
304 |
|
305 | ### .\[loglevel\]({String} <message>)
|
306 |
|
307 | For each log level that you declared in the constructor (or the default log levels provides by the library if you don't declare nothing) will be created a function with the same name to output a message with these log level.
|
308 |
|
309 | ## License
|
310 |
|
311 | MIT © [Kiko Beats](http://www.kikobeats.com)
|