BitLogger/docs/api/library-async-logger-new.md

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

name	group	category	update-time	description	key-word
library-async-logger-new	api	facade	20260613	Create a narrower library-facing async logger facade from any sink implementation.	async library facade public

Library-async-logger-new

Create a LibraryAsyncLogger[S] from any sink implementation. This is the library-facing async constructor when you want queue-backed async logging behavior without exposing the full AsyncLogger[S] surface.

Interface

pub fn[S] LibraryAsyncLogger::new(
  sink : S,
  config~ : AsyncLoggerConfig = AsyncLoggerConfig::new(),
  min_level~ : @bitlogger.Level = @bitlogger.Level::Info,
  target~ : String = "",
  flush~ : (S) -> Int raise = fn(_) { 0 },
) -> LibraryAsyncLogger[S] {

input

• sink : S - Any sink value implementing @bitlogger.Sink, such as @bitlogger.console_sink() or a composed sink.
• config : AsyncLoggerConfig - Queue size, overflow behavior, batching, linger, and flush policy.
• min_level : Level - Minimum enabled level. Messages below this threshold are ignored before enqueue.
• target : String - Default target attached to emitted records unless later overridden.
• flush : (S) -> Int raise - Flush callback used when async batch or shutdown policy needs explicit flushing.

output

• LibraryAsyncLogger[S] - Narrow library-facing wrapper over a newly created async logger.

Explanation

Detailed rules explaining key parameters and behaviors

• This API builds a regular async_logger(...) internally and then wraps it as LibraryAsyncLogger.
• The returned facade intentionally exposes a smaller method set than the full AsyncLogger[S] type.
• Queue settings, flush policy, and runtime state are preserved inside the wrapped async logger.
• Call to_async_logger() if later code must recover the full async logger surface.

How to Use

Here are some specific examples provided.

When Need A Narrower Library-facing Async Constructor

When a package should create an async logger without exposing the full async logger API:

let logger = LibraryAsyncLogger::new(
  @bitlogger.console_sink(),
  config=AsyncLoggerConfig::new(max_pending=32),
  target="plugin.async",
)

In this example, the package creates a normal async logging pipeline but publishes only the smaller facade type.

When Need Explicit Flush Behavior In A Library Boundary

When the sink requires a flush callback for batch or shutdown policy:

let logger = LibraryAsyncLogger::new(
  @bitlogger.console_sink(),
  flush=fn(sink) { 0 },
)

In this example, the facade still keeps the queue-backed async behavior while hiding the full async logger type.

Error Case

e.g.:

• If target is empty, the returned logger remains valid and later records simply use an empty default target.

• If later code needs methods outside the facade, it must unwrap with to_async_logger().

Notes

1. This is the direct constructor counterpart to async_logger(...) for library-oriented async APIs.

2. Prefer this when public package boundaries should stay narrower than AsyncLogger[S].