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

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

name	group	category	update-time	description	key-word
build-library-logger	api	facade	20260613	Build the library-facing sync logger facade from a LoggerConfig by delegating to the configured runtime logger build path and then wrapping the result.	library facade logger public

Build-library-logger

Build a LibraryLogger[RuntimeSink] from LoggerConfig. This facade keeps a smaller library-oriented sync surface while still using config-driven runtime assembly underneath.

Interface

pub fn build_library_logger(config : LoggerConfig) -> LibraryLogger[RuntimeSink] {

input

• config : LoggerConfig - Fully assembled sync logger config.

output

• LibraryLogger[RuntimeSink] - Library-facing logger wrapper over the configured runtime sink.

Explanation

Detailed rules explaining key parameters and behaviors

• This API builds a configured runtime logger first and then wraps that same value as LibraryLogger[RuntimeSink].
• The embedded config still goes through the normal runtime logger build path, including runtime sink selection, optional queue wrapping, and timestamp application.
• The returned facade wraps the same underlying ConfiguredLogger value that build_logger(...) would produce directly.
• The facade intentionally exposes a smaller logging surface than the full configured runtime logger.
• Queue metrics, flush and drain helpers, and file runtime controls remain on the underlying ConfiguredLogger, not on the returned facade itself.
• Call to_logger() if a caller must recover the underlying full logger object.
• Use this builder when the boundary should preserve the configured runtime logger path but still hide broader runtime helper methods from downstream callers.

How to Use

Here are some specific examples provided.

When Need A Smaller Library-facing Logging Type

When package code should accept or produce a narrower logger facade:

let logger = build_library_logger(
  LoggerConfig::new(target="lib", sink=SinkConfig::new(kind=SinkKind::Console)),
)

In this example, the logger is built from config and then narrowed to the library facade.

When Need Runtime Helpers After Library-oriented Construction

When config-built runtime queue or file controls are still needed internally:

let logger = build_library_logger(config)
let full = logger.to_logger()
ignore(full.pending_count())

In this example, the library facade is unwrapped before using configured runtime helper methods.

And the unwrapped value still carries the same RuntimeSink pipeline built from the original config.

Error Case

e.g.:

• If backend-specific sink limitations exist, they still apply after the facade is built.

• If code later needs queue metrics, flush or drain helpers, or file runtime controls, it must unwrap with to_logger().

Notes

1. Prefer this facade when library APIs should not expose the full configured runtime logger type.

2. Use parse_and_build_library_logger(...) when starting from JSON text.

3. Use to_logger() when internal code later needs configured-runtime helpers or broader logger composition without changing the public facade type.