BitLogger/docs/api/build-library-async-text-logger.md

name, group, category, update-time, description, key-word

name	group	category	update-time	description	key-word
build-library-async-text-logger	api	facade	20260614	Build the library-facing text-console async logger facade from an AsyncLoggerBuildConfig using the concrete text-console builder path.	library async text public

Build-library-async-text-logger

Build a LibraryAsyncLogger[FormattedConsoleSink] from AsyncLoggerBuildConfig. This facade is the library-oriented async builder for the concrete text-console sink shape returned by build_async_text_logger(...).

Interface

pub fn build_library_async_text_logger(
  config : AsyncLoggerBuildConfig,
) -> LibraryAsyncLogger[FormattedConsoleSink] {

input

• config : AsyncLoggerBuildConfig - Combined sync logger config and async queue/runtime config.

output

• LibraryAsyncLogger[FormattedConsoleSink] - Library-facing async logger backed by formatted console output.

Explanation

Detailed rules explaining key parameters and behaviors

• This API delegates to build_async_text_logger(...) and then narrows the result to LibraryAsyncLogger[@bitlogger.FormattedConsoleSink].
• It always produces a concrete FormattedConsoleSink from config.logger.sink.text_formatter instead of branching on sink kinds.
• Unlike build_library_async_logger(...), this facade does not go through the full synchronous configured-logger build path first.
• It uses the selected text-oriented LoggerConfig fields directly and therefore does not apply LoggerConfig.queue or preserve sync runtime sink controls.
• A sync queue configured on LoggerConfig.queue is therefore ignored by this builder instead of being preserved behind the wrapped text-console async logger.
• The returned facade wraps the same underlying AsyncLogger[@bitlogger.FormattedConsoleSink] value that build_async_text_logger(...) would return directly, so run(), shutdown(), and queue or failure-state behavior are unchanged under the narrower public type.
• The configured flush_policy is still carried by that underlying async logger, but this text-specific builder path does not provide the explicit sink flush callback used by build_library_async_logger(...) through build_async_logger(...).
• As a result, Batch and Shutdown only invoke the default no-op async flush callback on this text-console path unless downstream code unwraps and adds different behavior elsewhere.
• Async state helpers such as pending_count(), dropped_count(), state(), wait_idle(), and failure-status inspection remain on the underlying AsyncLogger[@bitlogger.FormattedConsoleSink], not on the returned facade itself.
• to_async_logger() can recover the underlying full async logger if needed.
• Use this builder when the boundary should preserve the concrete text-console sink type while still hiding broader async inspection and helper APIs from downstream callers.

How to Use

Here are some specific examples provided.

When Need A Narrow Async Text Logger For Libraries

When a library wants text-console async output and a narrower public type:

let logger = build_library_async_text_logger(
  AsyncLoggerBuildConfig::new(
    logger=text_console(target="lib.text.async"),
    async_config=AsyncLoggerConfig::new(max_pending=4),
  ),
)

In this example, the async text sink shape is preserved under the library facade.

When Need Async State Helpers After Library Text Construction

When library-facing text-console construction should still allow internal async inspection later:

let logger = build_library_async_text_logger(config)
let full = logger.to_async_logger()
ignore(full.pending_count())

In this example, the facade is unwrapped before using async state helpers.

Error Case

e.g.:

• If callers need sink-kind-driven branching such as JSON console or file-backed async output, they should use build_library_async_logger(...) instead.

• If callers expect async state or idle-wait helpers directly on the returned facade, they must unwrap first with to_async_logger().

• Normal async lifecycle expectations still apply if the logger is never run.

Notes

1. This is the library-side counterpart to build_application_text_async_logger(...).

2. It is most useful when a concrete text-console async sink type matters to the caller boundary.

3. Use build_library_async_logger(...) instead when the library-facing async type should keep the broader RuntimeSink build path, including sync queue application through build_logger(config.logger).