docs: add user guide, cookbook, and rewrite README

README.md

@@ -1,33 +1,89 @@
 # esm-logging
 
-> This README is a stub. Working on it. Currently stabilizing the build
-  environment after that I'll make it nice around here.
+A quasi-port of the Python standard library
+[logging](https://docs.python.org/3/library/logging.html) module to
+ECMAScript. Browser-compatible, zero dependencies.
 
-A quasi-port of the Python standard library logging module to ECMAScript.
+## Why?
 
-# Why?
-
-First of, because 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
+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]() module, which is part of the standard library and
-has been since 2002. It was originally authored by Vinay Sajip
+([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.
 
-# Roadmap
+## Installation
 
-- do a quasi-port of the logging module with minimal amount of adaption
-- add documentation
-- add support for asynchronous calls
-- implement Open Cybersecurity Framework (OCSF) formatter
-- implement (Browser) local storage handler as a replacement for file handler
+```bash
+npm install @administratrix/esm-logging
+```
 
-# Usage
+## Quick start
 
-For the time being, please check out my [CI
-service](https://bitbucket.org/byteb4rb1e/esm-logging/pipelines), for an idea on
-how to build this.
+```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