mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 00:42:18 +00:00
Nanaloveyuki
91 lines
4.2 KiB
Markdown
91 lines
4.2 KiB
Markdown
---
|
|
name: logger-to-library-logger
|
|
group: api
|
|
category: facade
|
|
update-time: 20260614
|
|
description: Convert a full sync logger into the narrower library-facing sync facade without rebuilding or detaching the underlying logger state.
|
|
key-word:
|
|
- logger
|
|
- library
|
|
- facade
|
|
- public
|
|
---
|
|
|
|
## Logger-to-library-logger
|
|
|
|
Convert `Logger[S]` into `LibraryLogger[S]`. This keeps the same sink and logging behavior while projecting the value onto the smaller library-facing sync surface.
|
|
|
|
### Interface
|
|
|
|
```moonbit
|
|
pub fn[S] Logger::to_library_logger(self : Logger[S]) -> LibraryLogger[S] {}
|
|
```
|
|
|
|
#### input
|
|
|
|
- `self : Logger[S]` - Full sync logger to project into the library facade.
|
|
|
|
#### output
|
|
|
|
- `LibraryLogger[S]` - Narrower library-facing wrapper over the same logger state.
|
|
|
|
### Explanation
|
|
|
|
Detailed rules explaining key parameters and behaviors
|
|
|
|
- This conversion does not rebuild the sink or change the logger configuration.
|
|
- Target, min level, timestamp behavior, and sink wiring are preserved because the same underlying logger value is wrapped.
|
|
- The original `Logger[S]` handle remains the same live logger. If caller code keeps that original value, later facade calls and later unwraps still observe the same shared target, context wrappers, timestamp behavior, and sink or runtime-helper mutations.
|
|
- The returned facade keeps library-oriented write APIs such as `info(...)`, `warn(...)`, and `error(...)`.
|
|
- Broader sync composition helpers remain on the underlying `Logger[S]` and are intentionally hidden until `to_logger()` is used again.
|
|
- When `S` is `RuntimeSink`, projection also preserves queued runtime state and file-backed runtime helper behavior behind the facade instead of replacing them with a library-specific copy.
|
|
- Unwrapping later with `to_logger()` therefore exposes the same pending counts, drain or flush results, file state, and runtime file controls that the original logger already carried.
|
|
- That also means runtime or file helper mutations still alias in both directions: draining queued runtime records, flushing, or changing file helper state through a later unwrapped logger changes the same live runtime-backed logger that the original `Logger[S]` already held.
|
|
|
|
### How to Use
|
|
|
|
Here are some specific examples provided.
|
|
|
|
#### When Need To Return A Narrower Library Type
|
|
|
|
When internal setup uses the full logger API but the exposed result should stay smaller:
|
|
```moonbit
|
|
let logger = Logger::new(console_sink(), target="lib")
|
|
let public_logger = logger.to_library_logger()
|
|
```
|
|
|
|
In this example, `public_logger` keeps the same logging behavior but exposes the library facade.
|
|
|
|
#### When Need To Narrow Surface Without Resetting Logger Composition
|
|
|
|
When an already-shaped logger should be projected to a library boundary without losing its current wrappers:
|
|
```moonbit
|
|
let full = Logger::new(console_sink(), target="lib").with_timestamp()
|
|
let public_logger = full.to_library_logger()
|
|
```
|
|
|
|
In this example, the projection changes the exposed type only; it does not remove the existing timestamp behavior or other logger state.
|
|
|
|
If `full` is still kept elsewhere, it continues sharing that same live logger state with `public_logger`.
|
|
|
|
### Error Case
|
|
|
|
e.g.:
|
|
- If callers later need APIs outside the library facade, they must unwrap with `to_logger()`.
|
|
|
|
- The conversion does not remove existing target or field bindings from the original logger.
|
|
|
|
- If callers later need composition helpers such as `with_timestamp(...)`, `with_filter(...)`, or `with_patch(...)`, they must unwrap again with `to_logger()`.
|
|
|
|
- Projection does not normalize configured runtime state; if the original logger already carried queued runtime data or file-backed helper state, a later unwrap still exposes that same live state.
|
|
|
|
- Projection does not create an isolated wrapper copy. If callers keep the original `Logger[S]`, then later facade-level writes or later runtime-helper mutations through an unwrapped logger still affect that original handle too.
|
|
|
|
### Notes
|
|
|
|
1. Use this when library boundaries should avoid exposing the full sync logger surface.
|
|
|
|
2. This is a projection API, not a copy or rebuild step.
|
|
|
|
3. Use `build_library_logger(...)` or `parse_and_build_library_logger(...)` when construction and narrowing should happen together from config.
|