mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-25 17:32:20 +00:00
Nanaloveyuki
86 lines
3.0 KiB
Markdown
86 lines
3.0 KiB
Markdown
---
|
|
name: parse-and-build-library-async-logger
|
|
group: api
|
|
category: facade
|
|
update-time: 20260614
|
|
description: Parse JSON async build config text and build the library-facing async logger facade while intentionally hiding direct async state helpers.
|
|
key-word:
|
|
- library
|
|
- async
|
|
- parse
|
|
- public
|
|
---
|
|
|
|
## Parse-and-build-library-async-logger
|
|
|
|
Parse raw JSON async build config text and build a `LibraryAsyncLogger[RuntimeSink]` in one step. This facade is the text-driven library counterpart to the general async config parser plus builder flow.
|
|
|
|
### Interface
|
|
|
|
```moonbit
|
|
pub fn parse_and_build_library_async_logger(
|
|
input : String,
|
|
) -> LibraryAsyncLogger[RuntimeSink] raise {
|
|
```
|
|
|
|
#### input
|
|
|
|
- `input : String` - Raw JSON async logger build config text.
|
|
|
|
#### output
|
|
|
|
- `LibraryAsyncLogger[RuntimeSink]` - Library-facing async runtime logger wrapper.
|
|
|
|
### Explanation
|
|
|
|
Detailed rules explaining key parameters and behaviors
|
|
|
|
- This API parses async build config text, validates it, builds the async runtime logger, and narrows it to the library facade.
|
|
- The embedded `LoggerConfig` still goes through the normal synchronous config path first, so sink shape and any optional synchronous queue layer are already applied before the outer async layer is wrapped and then narrowed.
|
|
- The resulting facade keeps async lifecycle helpers while exposing a smaller public surface.
|
|
- Async state helpers such as `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, and failure-status inspection stay on the underlying `AsyncLogger`, not on the returned facade itself.
|
|
- `to_async_logger()` can recover the underlying async logger when a wider API is required.
|
|
|
|
### How to Use
|
|
|
|
Here are some specific examples provided.
|
|
|
|
#### When Need Text-driven Async Library Bootstrapping
|
|
|
|
When a package accepts raw config text but wants a narrower async facade output:
|
|
```moonbit
|
|
let logger = parse_and_build_library_async_logger(
|
|
"{\"logger\":{\"target\":\"lib.async\",\"sink\":{\"kind\":\"console\"}},\"async_config\":{\"max_pending\":4,\"overflow\":\"DropNewest\",\"max_batch\":1,\"linger_ms\":0,\"flush\":\"Never\"}}",
|
|
)
|
|
```
|
|
|
|
In this example, parsing and library-facade construction happen together.
|
|
|
|
#### When Need Async State Helpers After Text-driven Library Bootstrapping
|
|
|
|
When JSON-driven construction should still allow internal async state inspection later:
|
|
```moonbit
|
|
let logger = parse_and_build_library_async_logger(raw) catch {
|
|
err => return
|
|
}
|
|
let full = logger.to_async_logger()
|
|
ignore(full.pending_count())
|
|
```
|
|
|
|
In this example, the caller unwraps the library async facade before using async state helpers.
|
|
|
|
### Error Case
|
|
|
|
e.g.:
|
|
- If the JSON text is malformed, parsing raises an error.
|
|
|
|
- If the embedded config is invalid, parsing raises before the library facade is returned.
|
|
|
|
- If callers assume async state or idle-wait helpers are available directly on the returned facade, they must unwrap first with `to_async_logger()`.
|
|
|
|
### Notes
|
|
|
|
1. This is the narrow async library parse-and-build facade.
|
|
|
|
2. Use `build_library_async_logger(...)` when the config is already typed.
|