|
# Logger |
|
|
|
Environment-agnostic, ESM-friendly logger for simple needs. |
|
|
|
## Why does this exist? |
|
|
|
I've been using `debug` for quite some time but wanted to migrate my projects to better ESM support. Alas, `debug` doesn't ship as ESM so I went and wrote this little logger just for my needs. You will likely see it printing useful data in Mock Service Worker and beyond. |
|
|
|
## Installation |
|
|
|
```sh |
|
npm install @open-draft/logger |
|
``` |
|
|
|
## Usage |
|
|
|
This package has the same API for both browser and Node.js and can run in those environments out of the box. |
|
|
|
```js |
|
// app.js |
|
import { Logger } from '@open-draft/logger' |
|
|
|
const logger = new Logger('parser') |
|
|
|
logger.info('starting parsing...') |
|
logger.warning('found legacy document format') |
|
logger.success('parsed 120 documents!') |
|
``` |
|
|
|
Logging is disabled by default. To enable logging, provide the `DEBUG` environment variable: |
|
|
|
```sh |
|
DEBUG=1 node ./app.js |
|
``` |
|
|
|
> You can also use `true` instead of `1`. You can also use a specific logger's name to enable [logger filtering](#logger-filtering). |
|
|
|
## API |
|
|
|
- Class: `Logger` |
|
- [`new Logger(name)`](#new-loggername) |
|
- [`logger.debug(message, ...positionals)`](#loggerdebugmessage-positionals) |
|
- [`logger.info(message, ...positionals)`](#loggerinfomessage-positionals) |
|
- [`logger.success(message, ...positionals)`](#loggersuccessmessage-positionals) |
|
- [`logger.warning(message, ...positionals)`](#loggerwarningmessage-positionals) |
|
- [`logger.error(message, ...positionals)`](#loggererrormessage-positionals) |
|
- [`logger.extend(name)`](#loggerextendprefix) |
|
- [`logger.only(callback)`](#loggeronlycallback) |
|
|
|
### `new Logger(name)` |
|
|
|
- `name` `string` the name of the logger. |
|
|
|
Creates a new instance of the logger. Each message printed by the logger will be prefixed with the given `name`. You can have multiple loggers with different names for different areas of your system. |
|
|
|
```js |
|
const logger = new Logger('parser') |
|
``` |
|
|
|
> You can nest loggers via [`logger.extend()`](#loggerextendprefix). |
|
|
|
### `logger.debug(message, ...positionals)` |
|
|
|
- `message` `string` |
|
- `positionals` `unknown[]` |
|
|
|
Prints a debug message. |
|
|
|
```js |
|
logger.debug('no duplicates found, skipping...') |
|
``` |
|
|
|
``` |
|
12:34:56:789 [parser] no duplicates found, skipping... |
|
``` |
|
|
|
### `logger.info(message, ...positionals)` |
|
|
|
- `message` `string` |
|
- `positionals` `unknown[]` |
|
|
|
Prints an info message. |
|
|
|
```js |
|
logger.info('new parse request') |
|
``` |
|
|
|
``` |
|
12:34:56:789 [parser] new parse request |
|
``` |
|
|
|
### `logger.success(message, ...positionals)` |
|
|
|
- `message` `string` |
|
- `positionals` `unknown[]` |
|
|
|
Prints a success message. |
|
|
|
```js |
|
logger.success('prased 123 documents!') |
|
``` |
|
|
|
``` |
|
12:34:56:789 ✔ [parser] prased 123 documents! |
|
``` |
|
|
|
### `logger.warning(message, ...positionals)` |
|
|
|
- `message` `string` |
|
- `positionals` `unknown[]` |
|
|
|
Prints a warning. In Node.js, prints it to `process.stderr`. |
|
|
|
```js |
|
logger.warning('found legacy document format') |
|
``` |
|
|
|
``` |
|
12:34:56:789 ⚠ [parser] found legacy document format |
|
``` |
|
|
|
### `logger.error(message, ...positionals)` |
|
|
|
- `message` `string` |
|
- `positionals` `unknown[]` |
|
|
|
Prints an error. In Node.js, prints it to `process.stderr`. |
|
|
|
```js |
|
logger.error('failed to parse document') |
|
``` |
|
|
|
``` |
|
12:34:56:789 ✖ [parser] failed to parse document |
|
``` |
|
|
|
### `logger.extend(prefix)` |
|
|
|
- `prefix` `string` Additional prefix to append to the logger's name. |
|
|
|
Creates a new logger out of the current one. |
|
|
|
```js |
|
const logger = new Logger('parser') |
|
|
|
function parseRequest(request) { |
|
const requestLogger = logger.extend(`${request.method} ${request.url}`) |
|
requestLogger.info('start parsing...') |
|
} |
|
``` |
|
|
|
``` |
|
12:34:56:789 [parser] [GET https://example.com] start parsing... |
|
``` |
|
|
|
### `logger.only(callback)` |
|
|
|
Executes a given callback only when the logging is activated. Useful for computing additional information for logs. |
|
|
|
```js |
|
logger.only(() => { |
|
const documentSize = getSizeBytes(document) |
|
logger.debug(`document size: ${documentSize}`) |
|
}) |
|
``` |
|
|
|
> You can nest `logger.*` methods in the callback to `logger.only()`. |
|
|
|
## Log levels |
|
|
|
You can specify the log levels to print using the `LOG_LEVEL` environment variable. |
|
|
|
There are the following log levels: |
|
|
|
- `debug` |
|
- `info` |
|
- `success` |
|
- `warning` |
|
- `error` |
|
|
|
> Providing no log level will print all the messages. |
|
|
|
Here's an example of how to print only warnings: |
|
|
|
```js |
|
// app.js |
|
import { Logger } from '@open-draft/logger' |
|
|
|
const logger = new Logger('parser') |
|
|
|
logger.info('some info') |
|
logger.warning('some warning') |
|
logger.error('some error') |
|
``` |
|
|
|
```js |
|
LOG_LEVEL=warning node ./app.js |
|
``` |
|
|
|
``` |
|
12:34:56:789 ⚠ [parser] some warning |
|
``` |
|
|
|
## Logger filtering |
|
|
|
You can only print a specific logger by providing its name as the `DEBUG` environment variable. |
|
|
|
```js |
|
// app.js |
|
import { Logger } from '@open-draft/logger' |
|
|
|
const appLogger = new Logger('app') |
|
const parserLogger = new Logger('parser') |
|
|
|
appLogger.info('starting app...') |
|
parserLogger.info('creating a new parser...') |
|
``` |
|
|
|
```sh |
|
DEBUG=app node ./app.js |
|
``` |
|
|
|
``` |
|
12:34:56:789 [app] starting app... |
|
``` |
|
|