@arpinum/log
Version:
Simple module to log on stdout or stderr
152 lines (106 loc) • 3.31 kB
Markdown
# @arpinum/log [](https://github.com/arpinum-oss/js-log/actions?query=workflow%3ACI)
> We are drowning in information but starved for knowledge.
> <cite>John Naisbitt</cite>
_@arpinum/log_ is a simple module to log on stdout or stderr.
## Installation
```
npm install @arpinum/log --save
```
## Default logger
Just import default logger and start yelling messages:
```ts
import { logger } from "@arpinum/log";
logger.info("Something happened");
```
Which outputs :
```
2017-01-30T09:15:04.821Z - info: [default] Something happened
```
## Logging methods
Available methods are:
- debug
- info
- warn
- error
Each level uses corresponding method on `console` global object and fallback to `console.log` if missing for runtime
environment.
## Custom logger
You can create a fine tuned logger:
```ts
import { createLogger } from "@arpinum/log";
const logger = createLogger({ level: "error" });
logger.info("Something happened");
logger.error("Some error");
```
Which outputs :
```
2017-01-30T09:23:33.417Z - error: [default] Some error
```
### Options
You can pass those options during logger creation:
- level
- minimum logging level amongst `all`, `debug`, `info`, `warn`, `error`, `off`
- default is `info`
- `ARP_LOG_LEVEL` env var may be used to set level
- category
- the category displayed in message, useful to filter logs
- default is `default`
- fileName
- a category can be created from a base name without extension of a file
- filter
- a regex to filter matching categories
- default is `.*` (open bar)
- `ARP_LOG_FILTER` env var may be used to set filter
- getDateString
- a function to get a formatted date
- default function returns `new Date().toISOString()`
- provide `null` if you do not want a date at all
- getLogInputs
- a function to get inputs given to `console` methods
- used to format message as you want
- see [Customize message](#customize-message) below
### Filtering logs
If you have multiple logger instances with various categories, you can filter logs using `filter` options
or `ARP_LOG_FILTER` env var.
Example:
```ts
// program.js
const mainLogger = createLogger({ category: "main" });
const serviceLogger = createLogger({ category: "service" });
mainLogger.info("Application started");
serviceLogger.info("Doing some stuff");
```
May be run with `LOG_FILTER=serv node program.js` to output:
```
2017-01-30T09:32:31.351Z - info: [service] Doing some stuff
```
### About category:
File name usage:
```ts
import { createLogger } from "@arpinum/log";
const logger = createLogger({ fileName: __filename });
logger.info("Something happened");
```
Which outputs :
```
2017-01-30T09:32:31.351Z - info: [MySuperClass] Something happened
```
### Customize message
`getLogInputs` will be called for each log with an object containing:
- `date`: the current date string
- `category`: the configured category
- `level`: the logger level
- `args`: all the provided args
Example:
```ts
const logger = createLogger({
getLogInputs: ({ date, category, level, args }) => [
`${date}|${category}|${level}`,
...args,
],
});
logger.info("My", "message");
// 2019-11-19T16:45:58.419Z|default|info My message
```
## License
[MIT](LICENSE)