mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-24 00:42:18 +00:00
Nanaloveyuki
86 lines
3.2 KiB
Markdown
86 lines
3.2 KiB
Markdown
---
|
|
name: build-library-logger
|
|
group: api
|
|
category: facade
|
|
update-time: 20260613
|
|
description: Build the library-facing sync logger facade from a LoggerConfig by delegating to the configured runtime logger build path and then wrapping the result.
|
|
key-word:
|
|
- library
|
|
- facade
|
|
- logger
|
|
- public
|
|
---
|
|
|
|
## Build-library-logger
|
|
|
|
Build a `LibraryLogger[RuntimeSink]` from `LoggerConfig`. This facade keeps a smaller library-oriented sync surface while still using config-driven runtime assembly underneath.
|
|
|
|
### Interface
|
|
|
|
```moonbit
|
|
pub fn build_library_logger(config : LoggerConfig) -> LibraryLogger[RuntimeSink] {
|
|
```
|
|
|
|
#### input
|
|
|
|
- `config : LoggerConfig` - Fully assembled sync logger config.
|
|
|
|
#### output
|
|
|
|
- `LibraryLogger[RuntimeSink]` - Library-facing logger wrapper over the configured runtime sink.
|
|
|
|
### Explanation
|
|
|
|
Detailed rules explaining key parameters and behaviors
|
|
|
|
- This API builds a configured runtime logger first and then wraps that same value as `LibraryLogger[RuntimeSink]`.
|
|
- The embedded config still goes through the normal runtime logger build path, including runtime sink selection, optional queue wrapping, and timestamp application.
|
|
- The returned facade wraps the same underlying `ConfiguredLogger` value that `build_logger(...)` would produce directly.
|
|
- The facade intentionally exposes a smaller logging surface than the full configured runtime logger.
|
|
- Queue metrics, flush and drain helpers, and file runtime controls remain on the underlying `ConfiguredLogger`, not on the returned facade itself.
|
|
- Call `to_logger()` if a caller must recover the underlying full logger object.
|
|
- Use this builder when the boundary should preserve the configured runtime logger path but still hide broader runtime helper methods from downstream callers.
|
|
|
|
### How to Use
|
|
|
|
Here are some specific examples provided.
|
|
|
|
#### When Need A Smaller Library-facing Logging Type
|
|
|
|
When package code should accept or produce a narrower logger facade:
|
|
```moonbit
|
|
let logger = build_library_logger(
|
|
LoggerConfig::new(target="lib", sink=SinkConfig::new(kind=SinkKind::Console)),
|
|
)
|
|
```
|
|
|
|
In this example, the logger is built from config and then narrowed to the library facade.
|
|
|
|
#### When Need Runtime Helpers After Library-oriented Construction
|
|
|
|
When config-built runtime queue or file controls are still needed internally:
|
|
```moonbit
|
|
let logger = build_library_logger(config)
|
|
let full = logger.to_logger()
|
|
ignore(full.sink.pending_count())
|
|
```
|
|
|
|
In this example, the library facade is unwrapped before using runtime-specific helpers through the preserved `RuntimeSink` value.
|
|
|
|
And the unwrapped value still carries the same `RuntimeSink` pipeline built from the original config.
|
|
|
|
### Error Case
|
|
|
|
e.g.:
|
|
- If backend-specific sink limitations exist, they still apply after the facade is built.
|
|
|
|
- If code later needs queue metrics, flush or drain helpers, or file runtime controls, it must unwrap with `to_logger()`.
|
|
|
|
### Notes
|
|
|
|
1. Prefer this facade when library APIs should not expose the full configured runtime logger type.
|
|
|
|
2. Use `parse_and_build_library_logger(...)` when starting from JSON text.
|
|
|
|
3. Use `to_logger()` when internal code later needs broader logger composition or direct access to the preserved `RuntimeSink` value without changing the public facade type.
|