Parse-and-build-application-async-logger

Parse raw JSON async build config text and build an ApplicationAsyncLogger in one step. This is the application-oriented counterpart to parse_async_logger_build_config_text(...) plus build_application_async_logger(...).

Interface

pub fn parse_and_build_application_async_logger(
  input : String,
) -> ApplicationAsyncLogger raise {

input

• input : String - Raw JSON async logger build config text.

output

• ApplicationAsyncLogger - Application-facing async runtime logger.

Explanation

Detailed rules explaining key parameters and behaviors

• This API parses async build config text first, then builds the application async logger through build_application_async_logger(...).
• Both the embedded sync logger config and async queue/runtime config are validated by the parser layer.
• The embedded LoggerConfig is then built through the normal synchronous config path before the outer async layer is applied.
• Any optional synchronous queue layer and runtime-sink controls from the parsed logger section remain active under the returned async logger.
• That includes preserving a parsed sync queue configuration inside the resulting RuntimeSink variant rather than collapsing it away during application-alias construction.
• It also means the parsed logger.sink.kind had already selected the concrete RuntimeSink variant before the application alias reused that built async logger value.
• Because the result is the ApplicationAsyncLogger alias over AsyncLogger[@bitlogger.RuntimeSink], this parse-and-build path returns the same underlying async logger value that parse_async_logger_build_config_text(...) plus build_async_logger(...) would produce, without narrowing the helper surface.
• That preserved async helper surface also remains directly exposed on the returned alias rather than being rebuilt or hidden behind an unwrap step.
• The returned logger keeps the full async lifecycle and state helpers directly.
• The returned logger also keeps the ordinary async logger target rules unchanged: log(..., target=...) can override the target for one call, while severity helpers such as info(...), warn(...), and error(...) continue to use the stored logger target unless a derived logger was created first with with_target(...) or child(...).
• In the current parsed-builder coverage, that direct equivalence also holds for serialized async state snapshots, runtime-sink variant choice, queue counters, lifecycle flags, and later failure fields after worker execution.
• Parsed file-backed runtime helpers remain available on the returned logger with the same behavior as the direct build_async_logger(parse_async_logger_build_config_text(input)) path.
• Use parse_and_build_library_async_logger(...) instead when the same parsed runtime-sink result should be wrapped and narrowed for a library boundary.

How to Use

Here are some specific examples provided.

When Need App Async Boot Directly From JSON

When async config is sourced as text and should become a running-capable facade immediately:

let logger = parse_and_build_application_async_logger(
  "{\"logger\":{\"target\":\"app.async\",\"sink\":{\"kind\":\"console\"}},\"async_config\":{\"max_pending\":4,\"overflow\":\"DropNewest\",\"max_batch\":1,\"linger_ms\":0,\"flush\":\"Never\"}}",
)

In this example, text parsing and async logger construction happen in one facade call.

And any configured synchronous runtime sink controls remain available through the returned RuntimeSink-backed async logger.

And unlike parse_and_build_library_async_logger(...), no to_async_logger() unwrap is required to reach queue, lifecycle, or file-backed runtime helpers.

When Need Async State Helpers After JSON-driven App Construction

When application boot should parse JSON text and still keep direct access to async helper APIs:

let logger = parse_and_build_application_async_logger(raw) catch {
  err => return
}
ignore(logger.pending_count())
ignore(logger.state())

In this example, no unwrap step is needed because the application result is an alias, not a narrowing facade.

When Need A Per-call Target Override After JSON Boot

When parsed app configuration should keep the same direct target override behavior as the ordinary async logger:

let logger = parse_and_build_application_async_logger(raw) catch {
  err => return
}
logger.log(@bitlogger.Level::Error, "boom", target="app.audit")

In this example, the emitted record uses app.audit for that call.

And later info(...), warn(...), or error(...) calls still use the logger's stored target unless code derives another logger first with with_target(...) or child(...).

Error Case

e.g.:

• If the JSON text is malformed, parsing raises an error.

• If the embedded config is invalid, parsing raises before the async facade is returned.

• If callers depend on file-backed runtime helpers, they can use them directly on the returned logger because this parse/build alias does not replace the underlying runtime-sink helper surface.

• If callers depend on queued or file-backed runtime behavior, they should read this facade as preserving the already-built RuntimeSink result from the parsed sync-first builder path, not as recomputing sink selection at the alias layer.

Notes

1. Use this facade when application boot starts from JSON text.

2. Use build_application_async_logger(...) when config is already typed as AsyncLoggerBuildConfig.

3. Use parse_and_build_library_async_logger(...) instead when text-driven construction should narrow the public async surface for a library boundary.