diff --git a/docs/api/build-library-logger.md b/docs/api/build-library-logger.md index 7d0933e..0decbb9 100644 --- a/docs/api/build-library-logger.md +++ b/docs/api/build-library-logger.md @@ -2,8 +2,8 @@ name: build-library-logger group: api category: facade -update-time: 20260520 -description: Build the library-facing sync logger facade from a LoggerConfig. +update-time: 20260613 +description: Build the library-facing sync logger facade from a LoggerConfig and intentionally hide direct runtime helper methods. key-word: - library - facade @@ -33,8 +33,9 @@ pub fn build_library_logger(config : LoggerConfig) -> LibraryLogger[RuntimeSink] Detailed rules explaining key parameters and behaviors -- This API builds a configured runtime logger first and then wraps it as `LibraryLogger`. +- This API builds a configured runtime logger first and then wraps it as `LibraryLogger[RuntimeSink]`. - 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. ### How to Use @@ -52,12 +53,23 @@ let logger = build_library_logger( 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.pending_count()) +``` + +In this example, the library facade is unwrapped before using configured runtime helper methods. + ### Error Case e.g.: - If backend-specific sink limitations exist, they still apply after the facade is built. -- If code later needs methods outside the library facade, it must unwrap with `to_logger()`. +- If code later needs queue metrics, flush or drain helpers, or file runtime controls, it must unwrap with `to_logger()`. ### Notes diff --git a/docs/api/library-logger.md b/docs/api/library-logger.md index 6fe25bb..b6c4abd 100644 --- a/docs/api/library-logger.md +++ b/docs/api/library-logger.md @@ -3,7 +3,7 @@ name: library-logger group: api category: facade update-time: 20260613 -description: Public library-facing sync logger facade type used to expose a narrower surface than Logger. +description: Public library-facing sync logger facade type used to expose a narrower surface than Logger while preserving sink typing. key-word: - library - logger @@ -33,7 +33,8 @@ Detailed rules explaining key parameters and behaviors - This is a public facade struct, not a type alias. - The wrapped sink type `S` is preserved, so sink-specific typing remains available through the facade type parameter. -- The facade keeps common library-safe operations such as `new(...)`, `with_target(...)`, `child(...)`, `bind(...)`, `is_enabled(...)`, and the main write methods. +- The facade keeps common library-safe operations such as `new(...)`, `with_target(...)`, `child(...)`, `bind(...)`, `is_enabled(...)`, and the main write methods `log(...)`, `info(...)`, `warn(...)`, and `error(...)`. +- It does not expose the wider `Logger[S]` composition surface or `ConfiguredLogger` runtime helper methods directly. - Call `to_logger()` when later code must recover the full underlying `Logger[S]` surface. ### How to Use @@ -66,6 +67,8 @@ e.g.: - Runtime behavior still depends on the wrapped sink `S`, so any sink-specific limitations remain unchanged behind the facade. +- If the wrapped sink type is `RuntimeSink`, queue and file runtime helpers still exist on the underlying logger but are not callable through `LibraryLogger[RuntimeSink]` unless it is unwrapped with `to_logger()`. + ### Notes 1. Use `LibraryLogger::new(...)`, `build_library_logger(...)`, or `parse_and_build_library_logger(...)` when you need a value of this type. diff --git a/docs/api/parse-and-build-library-logger.md b/docs/api/parse-and-build-library-logger.md index 11b5268..ca1b203 100644 --- a/docs/api/parse-and-build-library-logger.md +++ b/docs/api/parse-and-build-library-logger.md @@ -2,8 +2,8 @@ name: parse-and-build-library-logger group: api category: facade -update-time: 20260520 -description: Parse JSON logger config text and build the library-facing sync logger facade. +update-time: 20260613 +description: Parse JSON logger config text and build the library-facing sync logger facade while intentionally hiding direct runtime helper methods. key-word: - library - facade @@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - This API parses config text, validates it, builds the configured logger, and wraps it as a library facade. - The returned facade keeps a narrower surface than the underlying configured logger. +- Queue metrics, flush and drain helpers, and file runtime controls stay on the underlying `ConfiguredLogger`, not on the returned facade itself. - `to_logger()` can be used to recover the underlying full logger object when necessary. ### How to Use @@ -54,6 +55,19 @@ let logger = parse_and_build_library_logger( In this example, parsing and library-facade construction happen in one call. +#### When Need Runtime Helpers After Text-driven Library Bootstrapping + +When JSON-driven construction should still allow internal runtime inspection later: +```moonbit +let logger = parse_and_build_library_logger(raw) catch { + err => return +} +let full = logger.to_logger() +ignore(full.pending_count()) +``` + +In this example, the caller unwraps the library facade before using configured runtime helper methods. + ### Error Case e.g.: @@ -61,6 +75,8 @@ e.g.: - If the parsed config is invalid, a `ConfigError` is raised before the library facade is returned. +- If callers assume configured runtime helper methods are available directly on the returned facade, they must unwrap first with `to_logger()`. + ### Notes 1. This is the narrow library-oriented parse-and-build sync entry point.