diff --git a/docs/api/build-application-async-logger.md b/docs/api/build-application-async-logger.md index b70c3e8..8e9a12e 100644 --- a/docs/api/build-application-async-logger.md +++ b/docs/api/build-application-async-logger.md @@ -40,6 +40,7 @@ Detailed rules explaining key parameters and behaviors - Any optional synchronous queue layer and runtime-sink controls chosen by `build_logger(config.logger)` remain active under the returned logger. - In particular, a sync queue configured on `LoggerConfig.queue` is preserved inside the wrapped `RuntimeSink` variant instead of being stripped away by the application alias. - Because the result is only the `ApplicationAsyncLogger` alias over `AsyncLogger[@bitlogger.RuntimeSink]`, this builder does not hide any async helpers or introduce a wrapper layer. +- The broader async helper surface is therefore preserved and directly exposed on the returned alias rather than being rebuilt or hidden behind an unwrap step. - The returned alias also keeps inherited async logger target behavior such as `with_target(...)`, `child(...)`, and per-call `target=` overrides on `log(...)`. - The returned logger keeps the full async lifecycle and state helper surface directly, including helpers such as `run()`, `shutdown()`, `pending_count()`, `dropped_count()`, `state()`, `wait_idle()`, `has_failed()`, and `last_error()`. - It also keeps the same queue counters, failure state, sink shape, and runtime-dependent post-close behavior as the underlying runtime-sink async logger. @@ -67,6 +68,8 @@ In this example, the app-facing async facade is built directly from typed config And any configured synchronous runtime sink controls remain available through the returned `RuntimeSink`-backed async logger. +And unlike `build_library_async_logger(...)`, no `to_async_logger()` unwrap is required to reach queue, lifecycle, or file-backed runtime helpers. + The returned value also keeps the ordinary async logger target semantics because the facade does not wrap or narrow the underlying `AsyncLogger[@bitlogger.RuntimeSink]`. #### When Need Async State Helpers Immediately After App Construction diff --git a/docs/api/build-application-logger.md b/docs/api/build-application-logger.md index b8b75e5..fb61f07 100644 --- a/docs/api/build-application-logger.md +++ b/docs/api/build-application-logger.md @@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors - This API delegates to `build_logger(...)` directly. - The embedded config still goes through the normal runtime logger build path, including runtime sink selection, optional queue wrapping, and timestamp application. - Because the result is only the `ApplicationLogger` alias over `ConfiguredLogger`, this builder does not hide any queue, drain, flush, or file runtime helper methods. +- The configured runtime helper surface is therefore preserved and directly exposed on the returned alias rather than being rebuilt or hidden behind an unwrap step. - The returned alias also keeps inherited `Logger` behavior such as `with_target(...)`, `child(...)`, and per-call `target=` overrides on `log(...)`. - That means `log(..., target=...)` can override the target for one write, 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(...)`. - Use this alias-oriented entrypoint when application boot code wants an app-specific name without changing the underlying configured runtime logger surface. @@ -57,6 +58,8 @@ In this example, the application facade builds the same configured runtime logge And any queue/file/runtime helpers selected by the config remain directly available on the returned alias value. +And unlike `build_library_logger(...)`, no `to_logger()` unwrap is required to reach that helper surface. + The returned value also keeps the ordinary logger target semantics because the facade does not wrap or narrow the underlying `ConfiguredLogger`. #### When Need A Per-call Target Override After App-oriented Build diff --git a/docs/api/parse-and-build-application-async-logger.md b/docs/api/parse-and-build-application-async-logger.md index 11c980f..c3c941b 100644 --- a/docs/api/parse-and-build-application-async-logger.md +++ b/docs/api/parse-and-build-application-async-logger.md @@ -41,6 +41,7 @@ Detailed rules explaining key parameters and behaviors - 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. - 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. @@ -64,6 +65,8 @@ In this example, text parsing and async logger construction happen in one facade 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: diff --git a/docs/api/parse-and-build-application-logger.md b/docs/api/parse-and-build-application-logger.md index 2cbc0d1..b6f94c9 100644 --- a/docs/api/parse-and-build-application-logger.md +++ b/docs/api/parse-and-build-application-logger.md @@ -39,6 +39,7 @@ Detailed rules explaining key parameters and behaviors - JSON parsing and config validation happen before the logger is built. - The parsed config still goes through the normal configured runtime logger build path, including runtime sink selection, optional queue wrapping, and timestamp application. - Because the result is only the `ApplicationLogger` alias over `ConfiguredLogger`, this parse-and-build path returns the same underlying configured runtime logger value that `parse_and_build_logger(...)` would produce directly, without hiding any queue, drain, flush, or file runtime helper methods. +- That preserved configured runtime helper surface also remains directly exposed on the returned alias rather than being rebuilt or hidden behind an unwrap step. - The returned alias also keeps inherited `Logger` behavior such as `with_target(...)`, `child(...)`, and per-call `target=` overrides on `log(...)`. - That means `log(..., target=...)` can override the target for one write, 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(...)`. - Use `parse_and_build_library_logger(...)` instead when the same parsed configured logger result should be wrapped and narrowed for a library boundary. @@ -60,6 +61,8 @@ In this example, parsing and runtime construction are combined into one facade c And any queue/file/runtime helpers selected by the parsed config remain directly available on the returned alias value. +And unlike `parse_and_build_library_logger(...)`, no `to_logger()` unwrap is required to reach that helper surface. + The returned value also keeps the ordinary logger target semantics because this facade does not wrap or narrow the configured runtime logger result. #### When Need A Per-call Target Override After JSON Boot