From 76dbc421eb5394d2ffb72b2a653a34bcb43c9338 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 20:05:22 +0800 Subject: [PATCH] :memo: document library facade conversion apis --- .../async-logger-to-library-async-logger.md | 65 +++++++++++++++++++ docs/api/index.md | 4 ++ .../library-async-logger-to-async-logger.md | 65 +++++++++++++++++++ docs/api/library-logger-to-logger.md | 65 +++++++++++++++++++ docs/api/logger-to-library-logger.md | 65 +++++++++++++++++++ 5 files changed, 264 insertions(+) create mode 100644 docs/api/async-logger-to-library-async-logger.md create mode 100644 docs/api/library-async-logger-to-async-logger.md create mode 100644 docs/api/library-logger-to-logger.md create mode 100644 docs/api/logger-to-library-logger.md diff --git a/docs/api/async-logger-to-library-async-logger.md b/docs/api/async-logger-to-library-async-logger.md new file mode 100644 index 0000000..f9b5049 --- /dev/null +++ b/docs/api/async-logger-to-library-async-logger.md @@ -0,0 +1,65 @@ +--- +name: async-logger-to-library-async-logger +group: api +category: facade +update-time: 20260613 +description: Convert a full async logger into the narrower library-facing async facade. +key-word: + - async + - library + - facade + - public +--- + +## Async-logger-to-library-async-logger + +Convert `AsyncLogger[S]` into `LibraryAsyncLogger[S]`. This keeps the same async queue and sink behavior while projecting the value onto the smaller library-facing async surface. + +### Interface + +```moonbit +pub fn[S] AsyncLogger::to_library_async_logger(self : AsyncLogger[S]) -> LibraryAsyncLogger[S] {} +``` + +#### input + +- `self : AsyncLogger[S]` - Full async logger to project into the library facade. + +#### output + +- `LibraryAsyncLogger[S]` - Narrower library-facing wrapper over the same async logger state. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This conversion does not rebuild the queue, sink, or runtime state. +- Target, min level, async config, and flush behavior are preserved. +- The returned facade keeps library-facing async operations including `log(...)`, `run()`, and `shutdown(...)`. + +### How to Use + +Here are some specific examples provided. + +#### When Need To Expose A Narrower Async Type + +When internal setup uses the full async logger API but public library code should return a smaller facade: +```moonbit +let logger = async_logger(console_sink(), target="lib.async") +let public_logger = logger.to_library_async_logger() +``` + +In this example, `public_logger` keeps the same async behavior but exposes the library-facing facade. + +### Error Case + +e.g.: +- If callers later need APIs outside the library facade, they must unwrap with `to_async_logger()`. + +- The conversion does not clear pending items or reset runtime state. + +### Notes + +1. Use this when package boundaries should avoid exposing the full async logger type. + +2. This is a projection API, not a reconfiguration step. diff --git a/docs/api/index.md b/docs/api/index.md index 30a7775..fdae07b 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -205,11 +205,15 @@ BitLogger API navigation. ## Application and library facades +- [logger-to-library-logger.md](./logger-to-library-logger.md) +- [library-logger-to-logger.md](./library-logger-to-logger.md) - [build-application-logger.md](./build-application-logger.md) - [parse-and-build-application-logger.md](./parse-and-build-application-logger.md) - [build-library-logger.md](./build-library-logger.md) - [parse-and-build-library-logger.md](./parse-and-build-library-logger.md) - [default-library-logger.md](./default-library-logger.md) +- [async-logger-to-library-async-logger.md](./async-logger-to-library-async-logger.md) +- [library-async-logger-to-async-logger.md](./library-async-logger-to-async-logger.md) - [build-application-async-logger.md](./build-application-async-logger.md) - [build-application-text-async-logger.md](./build-application-text-async-logger.md) - [parse-and-build-application-async-logger.md](./parse-and-build-application-async-logger.md) diff --git a/docs/api/library-async-logger-to-async-logger.md b/docs/api/library-async-logger-to-async-logger.md new file mode 100644 index 0000000..0f54e72 --- /dev/null +++ b/docs/api/library-async-logger-to-async-logger.md @@ -0,0 +1,65 @@ +--- +name: library-async-logger-to-async-logger +group: api +category: facade +update-time: 20260613 +description: Recover the underlying full async logger from the library-facing async facade. +key-word: + - async + - library + - facade + - public +--- + +## Library-async-logger-to-async-logger + +Recover `AsyncLogger[S]` from `LibraryAsyncLogger[S]`. This unwraps the library-facing async facade when code needs methods that are only available on the full async logger type. + +### Interface + +```moonbit +pub fn[S] LibraryAsyncLogger::to_async_logger(self : LibraryAsyncLogger[S]) -> AsyncLogger[S] {} +``` + +#### input + +- `self : LibraryAsyncLogger[S]` - Library-facing async logger facade. + +#### output + +- `AsyncLogger[S]` - The underlying full async logger. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This conversion unwraps the existing async logger instead of rebuilding it. +- Queue state, sink wiring, target, and flush policy remain the same. +- Use this when code needs wider async logger APIs outside the library facade. + +### How to Use + +Here are some specific examples provided. + +#### When Need Full Async Logger-only APIs + +When a library-facing async logger must be widened for additional async logger composition: +```moonbit +let library_logger = LibraryAsyncLogger::new(console_sink(), target="lib.async") +let full_logger = library_logger.to_async_logger().with_timestamp() +``` + +In this example, the facade is unwrapped so the caller can access the full async logger API again. + +### Error Case + +e.g.: +- If callers only need library-facing async write or lifecycle APIs, unwrapping is unnecessary. + +- Unwrapping does not start or stop the background runtime by itself. + +### Notes + +1. Use this only when the narrower async facade is no longer sufficient. + +2. This is the inverse projection of `AsyncLogger::to_library_async_logger()`. diff --git a/docs/api/library-logger-to-logger.md b/docs/api/library-logger-to-logger.md new file mode 100644 index 0000000..3a977d9 --- /dev/null +++ b/docs/api/library-logger-to-logger.md @@ -0,0 +1,65 @@ +--- +name: library-logger-to-logger +group: api +category: facade +update-time: 20260613 +description: Recover the underlying full sync logger from the library-facing sync facade. +key-word: + - logger + - library + - facade + - public +--- + +## Library-logger-to-logger + +Recover `Logger[S]` from `LibraryLogger[S]`. This unwraps the library-facing sync facade when code needs methods that are only available on the full logger type. + +### Interface + +```moonbit +pub fn[S] LibraryLogger::to_logger(self : LibraryLogger[S]) -> Logger[S] {} +``` + +#### input + +- `self : LibraryLogger[S]` - Library-facing sync logger facade. + +#### output + +- `Logger[S]` - The underlying full sync logger. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This conversion unwraps the existing logger instead of rebuilding it. +- Sink wiring, target, min level, and attached wrappers remain the same. +- Use this when code needs full-surface APIs such as `with_timestamp(...)`, `with_filter(...)`, or `with_patch(...)`. + +### How to Use + +Here are some specific examples provided. + +#### When Need Full Logger-only Composition APIs + +When a library-facing logger must be widened temporarily for additional composition: +```moonbit +let library_logger = LibraryLogger::new(console_sink(), target="lib") +let full_logger = library_logger.to_logger().with_timestamp() +``` + +In this example, the facade is unwrapped so the caller can access full logger composition APIs again. + +### Error Case + +e.g.: +- If callers only need library-oriented write APIs, unwrapping is unnecessary. + +- Unwrapping does not change the current target or sink behavior by itself. + +### Notes + +1. Use this only when the narrower facade is no longer sufficient. + +2. This is the inverse projection of `Logger::to_library_logger()`. diff --git a/docs/api/logger-to-library-logger.md b/docs/api/logger-to-library-logger.md new file mode 100644 index 0000000..eb8ed9b --- /dev/null +++ b/docs/api/logger-to-library-logger.md @@ -0,0 +1,65 @@ +--- +name: logger-to-library-logger +group: api +category: facade +update-time: 20260613 +description: Convert a full sync logger into the narrower library-facing sync facade. +key-word: + - logger + - library + - facade + - public +--- + +## Logger-to-library-logger + +Convert `Logger[S]` into `LibraryLogger[S]`. This keeps the same sink and logging behavior while projecting the value onto the smaller library-facing sync surface. + +### Interface + +```moonbit +pub fn[S] Logger::to_library_logger(self : Logger[S]) -> LibraryLogger[S] {} +``` + +#### input + +- `self : Logger[S]` - Full sync logger to project into the library facade. + +#### output + +- `LibraryLogger[S]` - Narrower library-facing wrapper over the same logger state. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This conversion does not rebuild the sink or change the logger configuration. +- Target, min level, timestamp behavior, and sink wiring are preserved. +- The returned facade keeps library-oriented write APIs such as `info(...)`, `warn(...)`, and `error(...)`. + +### How to Use + +Here are some specific examples provided. + +#### When Need To Return A Narrower Library Type + +When internal setup uses the full logger API but the exposed result should stay smaller: +```moonbit +let logger = Logger::new(console_sink(), target="lib") +let public_logger = logger.to_library_logger() +``` + +In this example, `public_logger` keeps the same logging behavior but exposes the library facade. + +### Error Case + +e.g.: +- If callers later need APIs outside the library facade, they must unwrap with `to_logger()`. + +- The conversion does not remove existing target or field bindings from the original logger. + +### Notes + +1. Use this when library boundaries should avoid exposing the full sync logger surface. + +2. This is a projection API, not a copy or rebuild step.