Skip to content

Commit

Permalink
Released 2nd version that features
Browse files Browse the repository at this point in the history
  - autogenerate color tag
  - change log level from number to string
  - improved documentation
  • Loading branch information
akoidan committed Nov 22, 2020
1 parent a608775 commit df2952b
Show file tree
Hide file tree
Showing 6 changed files with 344 additions and 191 deletions.
90 changes: 54 additions & 36 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,15 +6,13 @@ A simple browser logger that features:

- Colored tags
- Show origin source files
- Can be disabled for production or any other reason, even in runtime.
- Typescript support
- Renders objects as they are, instead of stringifying them
- Supports log levels that can be changed in runtime.

Make your logs look like this:

![logs example](https://raw.githubusercontent.com/Deathangel908/lines-logger/master/demo.jpeg)

# 1. Installation:
# Installation:

### With npm:

Expand All @@ -26,75 +24,92 @@ Make your logs look like this:
```
where `{{VERSION}}` is [![npm version](https://img.shields.io/npm/v/lines-logger.svg)](https://www.npmjs.com/package/lines-logger). e.g. [https://cdn.jsdelivr.net/npm/lines-logger@1.2.0/lib/browser.js](https://cdn.jsdelivr.net/npm/lines-logger@1.2.0/lib/browser.js)

# 2. Configuration
# Configuration

## 2.1 Create logger
## Create logger

### If you use javascript:
```javascript
var LoggerFactory = require('lines-logger').LoggerFactory; // import {LoggerFactory} from 'lines-logger';
var loggerFactory = new LoggerFactory();
var logger = loggerFactory.getLoggerColor('tag', 'blue');
var logger = loggerFactory.getLogger('tag');
```

### If you use Typescript:
```typescript
import {Logger, LoggerFactory} from 'lines-logger';

let factory: LoggerFactory = new LoggerFactory();
let logger: Logger = factory.getLoggerColor('tag', 'blue');
let logger: Logger = factory.getLogger('tag');
```

## 2.2 Log anywhere in your code:
## Log anywhere in your code:
```javascript
logger.log('Hello world')(); // pay attention to () in the end. `logger.log` returns a function that should be called, thus `console.log` is called from YOUR location instead of the library.
logger.debug('My array is {}, object is {}', [1,2,3], {1:1, 2:2})();
```

# 3. Documentation
# Documentation

|method|description|example|
## LoggerFactory API

|method|description|
|-|-|
| `getLogger`| Returns a logger object that has binded functions warn/error/log/debug/trace| `var logger = loggerFactory.getLogger('tag')`. Logger will have random tag color, depending on hash of the name.|
| `setLogWarnings(LEVEL)` | Sets logger level see [LogLevel](#loglevel)
| `getSingleLoggerStyle` | Returns single logger function with specified style | `var log = loggerFactory.getSingleLoggerStyle('tag', 'color: #006c00;', console.log); log('hello world')()`|
| `getSingleLogger` | Returns single logger function with random color (color persist if tag is the same) | `var log = loggerFactory.getSingleLoggerStyle('tag', console.log); log('hello world')()`|
| `getSingleLoggerColor` | Same as getSingleLogger but with predefined tag color | `loggerFactory.getSingleLoggerColor('tag', 'blue')`|
| `getLoggerColor`| Same as getLogger, but with predefined tag style| `loggerFactory.getLogger('tag', 'black')`|

## LogLevel

|name|importance|description|
|-|-|-|
| `LoggerFactory.getLogger`| Returns a logger object that has binded functions warn/error/log/debug/trace| `var logger = loggerFactory.getLogger('tag', 'background-color: black')`|
| `LoggerFactory.setLogWarnings(LOG_RAISE_ERROR)` | log everything and if params specified in string construct mismatch actual arguments, e.g. `logger.log('two params given {} {}', one_suplied)();` throw an error| `loggerFactory.setLogWarnings(1)`|
| `LoggerFactory.setLogWarnings(LOG_WITH_WARNINGS)` | log everything and if params specified in string construct mismatch actual arguments, e.g. `logger.log('one param given {}', one_suplied, two_supplied)();` warn in console about it | `loggerFactory.setLogWarnings(2)`|
| `LoggerFactory.setLogWarnings(TRACE)` | log everything but don't warn about param missmatch | `loggerFactory.setLogWarnings(3)`|
| `LoggerFactory.setLogWarnings(DEBUG)` | log everything above `DEBUG`, this doesn't log `TRACE` to console| `loggerFactory.setLogWarnings(4)`|
| `LoggerFactory.setLogWarnings(INFO)` | log everything above `INFO`, this doesn't log `TRACE` nor `DEBUG` to console| `loggerFactory.setLogWarnings(5)`|
| `LoggerFactory.setLogWarnings(WARN)` | log everything above `WARN`, this doesn't log `TRACE` nor `DEBUG` nor `INFO` to console| `loggerFactory.setLogWarnings(6)`|
| `LoggerFactory.setLogWarnings(ERROR)` | log everything above `WARN`, this doesn't log `TRACE` nor `DEBUG` nor `INFO` to console| `loggerFactory.setLogWarnings(7)`|
| `LoggerFactory.setLogWarnings(DISABLE_LOGS)` | Don't log anything at all, meaning fully disable logs| `loggerFactory.setLogWarnings(8)`|
| `LoggerFactory.getSingleLogger` | Returns single logger function | `var log = loggerFactory.getSingleLogger('tag', 'color: #006c00;', console.log); log('hello world')()`|
| `LoggerFactory.getSingleLoggerColor` | Same as getSingleLogger but with predefined tag style| `loggerFactory.getSingleLoggerColor('tag', 'blue')`|
| `LoggerFactory.getLoggerColor`| Same as getLogger, but with predefined tag style| `loggerFactory.getLogger('tag', 'black')`|
| `Logger.trace`| executes `console.debug('YOUR TEXT')` if log level is less\equal `TRACE` or `3` | `logger.log('Hello world')()`|
| `Logger.debug`| executes `console.debug('YOUR TEXT')` if log level is less\equal `DEBUG` or `4` | `logger.debug('Hello world')()`|
| `Logger.log` | executes `console.log('YOUR TEXT')` if log level is less\equal `INFO` or `5` | `logger.log('Hello world')()`|
| `Logger.warn` | executes `console.warn('YOUR TEXT')` if log level is less\equal `WARN` or `6` | `logger.warn('Hello world')()`|
| `Logger.error` | executes `console.log('YOUR TEXT')` if log level is less\equal `ERROR` or `7`| `logger.error('Hello world')()`
| `Logger.log('{}', p1)`| logger allow to print params to the middle of the line | `logger.log('Hello {}!', 'world')()`|


# 4. Best practice:
- You can turn off logs for production builds, while creating logger factory `new LoggerFactory(8);` or using method `setLogWarnings(8)`. E.g. for webpack you can use [DefinePlugin](https://stackoverflow.com/a/29851256/3872976), the example is [here](https://github.com/akoidan/vue-webpack-typescript/blob/7ff6596c502bf7185378471088c3545d903c8e38/src/utils/singletons.ts#L7)
|log_raise_error | 1 | Log everything and if params specified in string construct mismatch actual arguments, e.g. `logger.log('two params given {} {}', one_suplied)();` throw an error. |
|log_with_warnings | 2 | Log everything and if params specified in string construct mismatch actual arguments, e.g. `logger.log('one param given {}', one_suplied, two_supplied)();` warn in console about it. |
|trace | 3 | Log everything. |
|debug | 4 | Log `debug`, `info`, `warn`, `error` only. `trace` won't be printed. |
|info | 5 | Log `info`, `warn`, `error` only. `debug` and `trace` won't be printed. |
|warn | 6 | Log `warn`, `error` only. `info`, `debug` and `trace` won't be printed. |
|error | 7 | Log `error` only. `warn` `info`, `debug` and `trace` won't be printed. |
|disable | 8 | Disable all logs completely |

## Logger API
|method|description|
|-|-|
| `logger.trace('Hello world')()`| Executes `console.trace('YOUR TEXT')` if log level is less\equal `trace`, level `3` |
| `logger.debug('Hello world')()` | Executes `console.debug('YOUR TEXT')` if log level is less\equal `debug` level `4` |
| `logger.log('Hello world')()` | Executes `console.log('YOUR TEXT')` if log level is less\equal `info` level `5` |
| `logger.warn('Hello world')()` | Executes `console.warn('YOUR TEXT')` if log level is less\equal `warn` level `6`
| `logger.error('Hello world')()` | Executes `console.log('YOUR TEXT')` if log level is less\equal `error` level `7`|
| `logger.log('Hello {}!', 'world')()`| Logger allow to print params to the middle of the line, by using `{}` |

# Best practices:
- Check [vue-webpack-typescript](https://github.com/akoidan/vue-webpack-typescript) repository for an example of project structure with lines logger.
- If you need time for your logs, modern browser provide that out of the box. E.g. in chrome you can go to preferences -> console -> Show timestamps.
- You can turn off logs for production builds, while creating logger factory `new LoggerFactory('disable');` or using method `setLogWarnings('disable')`. E.g. for webpack you can use [DefinePlugin](https://stackoverflow.com/a/29851256/3872976), the example is [here](https://github.com/akoidan/vue-webpack-typescript/blob/7ff6596c502bf7185378471088c3545d903c8e38/src/utils/singletons.ts#L7)
- You would probably like to expose loggerFactory to global scope (window). Thus in case of troubleshooting you can go to production site and turn on logs during runtime.
``` js
var LoggerFactory = require('lines-logger').LoggerFactory;
var loggerFactory = new LoggerFactory();
window.loggerFactory = loggerFactory
```
Now if you need to debug your production site you can just open devtools and type `loggerFactory.setLogWarnings(2)`
Now if you need to debug your production site you can just open devtools and type `loggerFactory.setLogWarnings('trace')`
- If you want to intercept/mock logs for testing or any other purpose, you can pass object callbacks as a 2nd param to a loggerFactory constructor
``` js
import { spy } from 'sinon'
var loggerSpy = spy()
new LoggerFactory(0, {
new LoggerFactory('trace', {
error: function () {
loggerSpy(arguments)
},
warn: function () {
loggerSpy(arguments)
},
trace: function () {
loggerSpy(arguments)
},
debug: function () {
loggerSpy(arguments)
},
Expand All @@ -104,7 +119,10 @@ new LoggerFactory(0, {
})
```

# 5. Building yourself:
# Contributions

This package uses only ts with target es5. I also added babel config, but it seems like it's redundant, so it's not used.

- `yarn install` - installs devDependencies. I use `yarn.lock` but npm work as well.
- `yarn build` - compiles code to `./lib` directory. This build has:
- Type definitions in `index.d.ts`
Expand Down
5 changes: 5 additions & 0 deletions babel.config.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
{
"presets": [
["@babel/preset-env"]
]
}
7 changes: 5 additions & 2 deletions package.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"name": "lines-logger",
"version": "1.3.1",
"version": "2.0.0",
"main": "lib/index.js",
"description": "A simple browser logger that keeps origin source files location",
"scripts": {
Expand All @@ -11,7 +11,7 @@
"codecov": "codecov",
"lint:check": "gts check",
"lint:fix": "gts fix",
"posttest": "npm run check"
"posttest": "npm run lint:check"
},
"repository": {
"type": "git",
Expand All @@ -31,6 +31,9 @@
},
"homepage": "https://github.com/Deathangel908/lines-logger#readme",
"devDependencies": {
"@babel/cli": "^7.12.7",
"@babel/core": "^7.12.7",
"@babel/preset-env": "^7.12.7",
"@types/chai": "^4.1.4",
"@types/mocha": "^5.2.3",
"@types/node": "^11.11.3",
Expand Down
Loading

0 comments on commit df2952b

Please sign in to comment.