# esm-logging

A quasi-port of the Python standard library
[logging](https://docs.python.org/3/library/logging.html) module to
ECMAScript. Browser-compatible, zero dependencies.

## Why?

Logging is important. It is important for debugging purposes, leading to
faster and more resilient development, for traceability leading to better
security. Most logging libraries I've discovered didn't satisfy me, introduced
weird concepts and all in all just weren't great. Other programming language
ecosystems offer way nicer logging facilities. Take Rust for example, or...
Python! Python has PEP, giving it a very structured approach towards
implementing new features and that's also how its logging facilities came to be
([PEP 282](https://peps.python.org/pep-0282/)). Python's logging facilities
are implemented by the [logging](https://docs.python.org/3/library/logging.html)
module, which is part of the standard library and has been since 2002. It was
originally authored by Vinay Sajip.

## Installation

```bash
npm install @administratrix/esm-logging
```

## Quick start

```javascript
import * as logging from '@administratrix/esm-logging';

// one-shot configuration: sets up a console handler on the root logger
logging.config.basicConfig({ level: logging.log_level.INFO });

// create a logger for this module
const logger = logging.manager.MANAGER.getLogger('myapp');

logger.info('Application started');
logger.warning('Something looks off');
logger.error('Something went wrong');
```

## Concepts

The logging system is built around four core components:

- **Loggers** expose the interface that application code uses directly.
- **Handlers** send log records to the appropriate destination (console,
  stderr, custom writable streams).
- **Formatters** control the layout of log records in the final output.
- **Filters** provide fine-grained control over which records to output.

Loggers are organized in a dot-separated hierarchy. A logger named `app.db`
is a child of the logger named `app`. Log records propagate up the hierarchy,
so a handler attached to `app` will also receive records from `app.db`.

## Log levels

| Constant   | Value | Purpose                                  |
|------------|-------|------------------------------------------|
| `CRITICAL` | 50    | A serious error, the program may not continue |
| `ERROR`    | 40    | An error that prevented some operation   |
| `WARNING`  | 30    | Something unexpected, but the software still works |
| `INFO`     | 20    | Confirmation that things work as expected |
| `DEBUG`    | 10    | Detailed diagnostic information          |
| `NOTSET`   | 0     | All messages are processed               |

## Documentation

See [docs/](docs/README.md) for the full user guide and
[docs/logging-cookbook.md](docs/logging-cookbook.md) for recipes and patterns.

API reference can be generated with TypeDoc:

```bash
npm run build/doc
```

## Roadmap

- [x] quasi-port of the logging module with minimal adaptation
- [x] add documentation
- [ ] add support for asynchronous calls
- [ ] implement Open Cybersecurity Schema Framework (OCSF) formatter
- [ ] implement browser local storage handler as a replacement for file handler

## License

UNLICENSED