From 554318a7b07863b2c9c3e3e236d02facc81a0149 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 20:48:22 +0800 Subject: [PATCH] :memo: document application logger aliases --- docs/api/application-async-logger.md | 74 +++++++++++++++++++++++ docs/api/application-logger.md | 72 ++++++++++++++++++++++ docs/api/application-text-async-logger.md | 74 +++++++++++++++++++++++ docs/api/index.md | 3 + 4 files changed, 223 insertions(+) create mode 100644 docs/api/application-async-logger.md create mode 100644 docs/api/application-logger.md create mode 100644 docs/api/application-text-async-logger.md diff --git a/docs/api/application-async-logger.md b/docs/api/application-async-logger.md new file mode 100644 index 0000000..5e60bb7 --- /dev/null +++ b/docs/api/application-async-logger.md @@ -0,0 +1,74 @@ +--- +name: application-async-logger +group: api +category: facade +update-time: 20260613 +description: Application-facing alias for the runtime-sink async logger surface. +key-word: + - application + - async + - alias + - public +--- + +## Application-async-logger + +`ApplicationAsyncLogger` is the application-facing async logger alias. It currently maps directly to `AsyncLogger[@bitlogger.RuntimeSink]` and keeps the same async lifecycle, state, and queue helper surface. + +### Interface + +```moonbit +pub type ApplicationAsyncLogger = AsyncLogger[@bitlogger.RuntimeSink] +``` + +#### output + +- `ApplicationAsyncLogger` - Application-facing name for the runtime-sink async logger shape. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This alias does not introduce a new runtime type or wrapper layer. +- It preserves the same async lifecycle helpers such as `run()`, `shutdown()`, `pending_count()`, and `state()`. +- The alias exists to give application boot code a clearer public type name for the standard runtime-sink async logger. +- Builders such as `build_application_async_logger(...)` and `parse_and_build_application_async_logger(...)` return this alias. + +### How to Use + +Here are some specific examples provided. + +#### When Need An App-level Name For The Standard Async Runtime Logger + +When application code wants a stable public type name for the runtime-sink async logger: +```moonbit +let logger : ApplicationAsyncLogger = build_application_async_logger( + AsyncLoggerBuildConfig::new(logger=LoggerConfig::new(target="app.async")), +) +``` + +In this example, the application alias keeps the same underlying async logger behavior while presenting an app-facing type name. + +#### When Pass The Async Logger Through App-level APIs + +When top-level boot code or services should expose an application-oriented async logger type: +```moonbit +fn start_async(logger : ApplicationAsyncLogger) -> Unit { + logger.run() +} +``` + +In this example, callers see the app-facing alias instead of the more explicit generic async logger spelling. + +### Error Case + +e.g.: +- Because this is only an alias, any runtime-sink limitations or target-specific async behavior still apply unchanged. + +- If code needs a narrower public surface than the full async logger API, `LibraryAsyncLogger` is the better facade. + +### Notes + +1. This alias is about naming and public intent, not a different async implementation. + +2. Use `build_application_async_logger(...)` or `parse_and_build_application_async_logger(...)` for the usual construction paths. diff --git a/docs/api/application-logger.md b/docs/api/application-logger.md new file mode 100644 index 0000000..a6736c7 --- /dev/null +++ b/docs/api/application-logger.md @@ -0,0 +1,72 @@ +--- +name: application-logger +group: api +category: facade +update-time: 20260613 +description: Application-facing alias for the configured sync runtime logger surface. +key-word: + - application + - facade + - alias + - public +--- + +## Application-logger + +`ApplicationLogger` is the application-facing sync logger alias. It currently maps directly to `ConfiguredLogger` and keeps the same runtime helper surface for sync logging, queue inspection, and file controls. + +### Interface + +```moonbit +pub type ApplicationLogger = ConfiguredLogger +``` + +#### output + +- `ApplicationLogger` - Application-facing name for the configured sync runtime logger shape. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This alias does not introduce a new runtime type or wrapper layer. +- It preserves the same logging, queue, and file helper APIs exposed by `ConfiguredLogger`. +- The alias exists to give application boot code a clearer public entry name. +- Builders such as `build_application_logger(...)` and `parse_and_build_application_logger(...)` return this alias. + +### How to Use + +Here are some specific examples provided. + +#### When Need An App-level Name For The Configured Runtime Logger + +When application code wants a stable public type name for the configured sync logger: +```moonbit +let logger : ApplicationLogger = build_application_logger(LoggerConfig::new(target="app")) +``` + +In this example, the application alias keeps the same underlying runtime logger behavior while presenting an app-facing type name. + +#### When Pass The Configured Logger Through App-level APIs + +When top-level boot code or services should expose an application-oriented logger type: +```moonbit +fn start(logger : ApplicationLogger) -> Unit { + logger.info("started") +} +``` + +In this example, callers see the app-facing alias instead of the lower-level `ConfiguredLogger` name. + +### Error Case + +e.g.: +- Because this is only an alias, any backend limitations of `ConfiguredLogger` still apply unchanged. + +- If code needs a narrower public surface than the full configured runtime logger, `LibraryLogger` is the better facade. + +### Notes + +1. This alias is about naming and public intent, not a different runtime implementation. + +2. Use `build_application_logger(...)` or `parse_and_build_application_logger(...)` for the usual construction paths. diff --git a/docs/api/application-text-async-logger.md b/docs/api/application-text-async-logger.md new file mode 100644 index 0000000..ff0afe9 --- /dev/null +++ b/docs/api/application-text-async-logger.md @@ -0,0 +1,74 @@ +--- +name: application-text-async-logger +group: api +category: facade +update-time: 20260613 +description: Application-facing alias for the text-console async logger surface. +key-word: + - application + - async + - text + - public +--- + +## Application-text-async-logger + +`ApplicationTextAsyncLogger` is the application-facing async logger alias for text-console output. It currently maps directly to `AsyncLogger[@bitlogger.FormattedConsoleSink]` and keeps the same async lifecycle and queue helper surface while preserving the concrete text sink shape. + +### Interface + +```moonbit +pub type ApplicationTextAsyncLogger = AsyncLogger[@bitlogger.FormattedConsoleSink] +``` + +#### output + +- `ApplicationTextAsyncLogger` - Application-facing name for the text-console async logger shape. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This alias does not introduce a new runtime type or wrapper layer. +- It preserves the same async lifecycle helpers as other async logger aliases. +- The alias exists to give application code a clearer public name when it wants the concrete text-console sink shape explicitly. +- `build_application_text_async_logger(...)` returns this alias. + +### How to Use + +Here are some specific examples provided. + +#### When Need An App-level Name For Text-console Async Output + +When application code wants a stable type name for a text-console async logger: +```moonbit +let logger : ApplicationTextAsyncLogger = build_application_text_async_logger( + AsyncLoggerBuildConfig::new(logger=text_console(target="app.text.async")), +) +``` + +In this example, the application alias keeps the same underlying async logger behavior while preserving the text sink shape explicitly. + +#### When Pass A Text-console Async Logger Through App-level APIs + +When caller code should know it is working with the text-console variant: +```moonbit +fn start_text_async(logger : ApplicationTextAsyncLogger) -> Unit { + logger.run() +} +``` + +In this example, the app-facing alias communicates the concrete text-console async shape directly. + +### Error Case + +e.g.: +- Because this is only an alias, any async target limitations or runtime behavior still apply unchanged. + +- If code does not need the concrete text-console sink shape, `ApplicationAsyncLogger` is the broader runtime-sink async alias. + +### Notes + +1. This alias is about naming and public intent, not a different async implementation. + +2. Use `build_application_text_async_logger(...)` when callers want the `FormattedConsoleSink`-backed async type explicitly. diff --git a/docs/api/index.md b/docs/api/index.md index f3bcc14..0634e9f 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -217,6 +217,7 @@ BitLogger API navigation. - [library-logger-info.md](./library-logger-info.md) - [library-logger-warn.md](./library-logger-warn.md) - [library-logger-error.md](./library-logger-error.md) +- [application-logger.md](./application-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) @@ -236,6 +237,8 @@ BitLogger API navigation. - [library-async-logger-error.md](./library-async-logger-error.md) - [library-async-logger-run.md](./library-async-logger-run.md) - [library-async-logger-shutdown.md](./library-async-logger-shutdown.md) +- [application-async-logger.md](./application-async-logger.md) +- [application-text-async-logger.md](./application-text-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)