mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 00:42:18 +00:00
Nanaloveyuki
98 lines
4.4 KiB
Markdown
98 lines
4.4 KiB
Markdown
---
|
|
name: library-logger
|
|
group: api
|
|
category: facade
|
|
update-time: 20260613
|
|
description: Public library-facing sync logger facade type used to expose a narrower surface than Logger while preserving the wrapped logger state.
|
|
key-word:
|
|
- library
|
|
- logger
|
|
- facade
|
|
- public
|
|
---
|
|
|
|
## Library-logger
|
|
|
|
`LibraryLogger[S]` is the public library-facing sync logger facade type. It wraps `Logger[S]` and keeps standard logging behavior while intentionally exposing a narrower public surface for package boundaries.
|
|
|
|
### Interface
|
|
|
|
```moonbit
|
|
pub struct LibraryLogger[S] {
|
|
inner : Logger[S]
|
|
}
|
|
```
|
|
|
|
#### output
|
|
|
|
- `LibraryLogger[S]` - Public library-oriented sync logger wrapper over a concrete sink type `S`.
|
|
|
|
### Explanation
|
|
|
|
Detailed rules explaining key parameters and behaviors
|
|
|
|
- This is a public facade struct, not a type alias.
|
|
- The wrapped sink type `S` is preserved, so sink-specific typing remains available through the facade type parameter.
|
|
- The facade keeps common library-safe operations such as `new(...)`, `with_target(...)`, `child(...)`, `bind(...)`, `is_enabled(...)`, and the main write methods `log(...)`, `info(...)`, `warn(...)`, and `error(...)`.
|
|
- The facade also preserves the wrapped logger's target rules on its exposed write methods: `log(..., target=...)` can override the target for one call, while `info(...)`, `warn(...)`, and `error(...)` continue using the stored logger target unless the facade first derives another logger with `with_target(...)` or `child(...)`.
|
|
- The facade wraps the same underlying `Logger[S]` value rather than copying or rebuilding it.
|
|
- It does not expose the wider `Logger[S]` composition surface or `ConfiguredLogger` runtime helper methods directly.
|
|
- Most facade reshaping helpers keep the same visible sink type, but `with_context_fields(...)` and `bind(...)` intentionally return `LibraryLogger[ContextSink[S]]` because they extend the sink pipeline.
|
|
- Call `to_logger()` when later code must recover the full underlying `Logger[S]` surface.
|
|
- If `S` is `RuntimeSink`, queued runtime state and file-backed helper behavior also stay on that same wrapped logger value; the facade only hides direct access until `to_logger()` is used.
|
|
|
|
### How to Use
|
|
|
|
Here are some specific examples provided.
|
|
|
|
#### When Need A Narrower Public Sync Logger Type
|
|
|
|
When a package should expose logging capability without publishing the full `Logger[S]` API:
|
|
```moonbit
|
|
let logger : LibraryLogger[ConsoleSink] = LibraryLogger::new(console_sink(), target="lib")
|
|
```
|
|
|
|
In this example, the package boundary exposes the library facade instead of the full logger type.
|
|
|
|
#### When Need A One-call Target Override Through The Library Facade
|
|
|
|
When package code should keep the same library-facing sync value but emit one record under a different target:
|
|
```moonbit
|
|
logger.log(Level::Error, "boom", target="lib.audit")
|
|
```
|
|
|
|
In this example, the emitted record uses `lib.audit` only for that one call.
|
|
|
|
And later `info(...)`, `warn(...)`, or `error(...)` calls still use the facade's stored target unless code derives another facade first with `with_target(...)` or `child(...)`.
|
|
|
|
#### When Need To Recover The Full Logger Later
|
|
|
|
When a library-facing facade should later be adapted back into the ordinary sync logger surface:
|
|
```moonbit
|
|
let full = logger.to_logger()
|
|
full.info("started")
|
|
```
|
|
|
|
In this example, the facade can be unwrapped when broader logger operations are needed internally.
|
|
|
|
And the unwrapped value still carries the same target and sink pipeline that existed behind the library facade.
|
|
|
|
### Error Case
|
|
|
|
e.g.:
|
|
- `LibraryLogger[S]` itself does not have a runtime failure mode.
|
|
|
|
- Runtime behavior still depends on the wrapped sink `S`, so any sink-specific limitations remain unchanged behind the facade.
|
|
|
|
- If the wrapped sink type is `RuntimeSink`, queue and file runtime helpers still exist on the underlying logger but are not callable through `LibraryLogger[RuntimeSink]` unless it is unwrapped with `to_logger()`.
|
|
|
|
- If callers need direct composition helpers such as `with_timestamp(...)`, `with_filter(...)`, or `with_patch(...)`, they must unwrap first with `to_logger()`.
|
|
|
|
### Notes
|
|
|
|
1. Use `LibraryLogger::new(...)`, `build_library_logger(...)`, or `parse_and_build_library_logger(...)` when you need a value of this type.
|
|
|
|
2. Use `Logger[S]` directly when exposing the full sync composition surface is acceptable.
|
|
|
|
3. Use `to_logger()` when internal code later needs broader composition or runtime-helper access without changing the public facade type.
|