---
name: build-library-logger
group: api
category: facade
update-time: 20260613
description: Build the library-facing sync logger facade from a LoggerConfig by delegating to the configured runtime logger build path and then wrapping the result.
key-word:
    - 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

```moonbit
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:
```moonbit
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:
```moonbit
let logger = build_library_logger(config)
let full = logger.to_logger()
ignore(full.sink.pending_count())
```

In this example, the library facade is unwrapped before using runtime-specific helpers through the preserved `RuntimeSink` value.

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 broader logger composition or direct access to the preserved `RuntimeSink` value without changing the public facade type.