mirror of
https://github.com/Nanaloveyuki/BitLogger.git
synced 2026-07-26 18:02:19 +00:00
Nanaloveyuki
85 lines
2.8 KiB
Markdown
85 lines
2.8 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 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.
|