From 20919618ce59e3e990bf70eac08212f7cf2c541b Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 08:50:34 +0800 Subject: [PATCH] :memo: clarify library helper visibility --- docs/api/build-library-async-logger.md | 3 +++ docs/api/build-library-logger.md | 3 +++ docs/api/parse-and-build-library-async-logger.md | 3 +++ docs/api/parse-and-build-library-logger.md | 3 +++ 4 files changed, 12 insertions(+) diff --git a/docs/api/build-library-async-logger.md b/docs/api/build-library-async-logger.md index 665cf61..def2044 100644 --- a/docs/api/build-library-async-logger.md +++ b/docs/api/build-library-async-logger.md @@ -39,6 +39,7 @@ Detailed rules explaining key parameters and behaviors - The embedded `LoggerConfig` still goes through the normal synchronous config path first, so sink shape and any optional synchronous queue layer are already applied before the outer async layer is wrapped and then narrowed. - The returned facade wraps the same underlying `AsyncLogger[@bitlogger.RuntimeSink]` value that `build_async_logger(...)` would produce directly. - The result keeps async lifecycle operations such as `run()` and `shutdown()` while narrowing the public shape. +- The broader async helper surface is preserved rather than rebuilt, but it is intentionally not directly exposed on the returned facade. Queue counters, lifecycle state, idle-wait helpers, and file-backed runtime helpers stay behind `to_async_logger()` instead of disappearing. - The narrower facade does not change the underlying runtime-sink queue counters, failure state, sink shape, or runtime-dependent post-close behavior; it only hides the broader helper surface until `to_async_logger()` is used. - The facade still preserves the underlying async target rules on its exposed write methods: `log(..., target=...)` can override the target for one call, while `info(...)`, `warn(...)`, and `error(...)` continue using the stored logger target unless the facade first derived another logger with `with_target(...)` or `child(...)`. - In the current direct builder coverage, unwrapping this facade produces the same async state snapshot, runtime-sink variant, queue counters, lifecycle flags, and failure fields as calling `build_async_logger(config)` directly. @@ -76,6 +77,8 @@ ignore(full.pending_count()) In this example, the library async facade is unwrapped before using async state helpers. +And unlike `ApplicationAsyncLogger`, the narrower builder result does not expose those broader async helpers directly on the facade surface. + #### When Need A Per-call Target Override Through The Library Async Builder Facade When typed library async config should still build a facade that allows a one-call target override without unwrapping first: diff --git a/docs/api/build-library-logger.md b/docs/api/build-library-logger.md index f2e72e3..a34a22c 100644 --- a/docs/api/build-library-logger.md +++ b/docs/api/build-library-logger.md @@ -37,6 +37,7 @@ Detailed rules explaining key parameters and behaviors - 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. +- In particular, the configured runtime helper surface is preserved rather than rebuilt, but it is intentionally not directly exposed on the returned facade. Queue metrics, flush or drain helpers, and file controls stay behind `to_logger()` instead of disappearing. - The facade still preserves the underlying logger target rules on its exposed write methods: `log(..., target=...)` can override the target for one write, while `info(...)`, `warn(...)`, and `error(...)` continue using the stored logger target unless the facade first derived another logger with `with_target(...)` or `child(...)`. - 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. @@ -70,6 +71,8 @@ In this example, the library facade is unwrapped before using runtime-specific h And the unwrapped value still carries the same `RuntimeSink` pipeline built from the original config. +And unlike `ApplicationLogger`, the narrower builder result does not expose those runtime helpers directly on the facade surface. + #### When Need A Per-call Target Override Through The Library Builder Facade When typed library config should still build a facade that allows a one-write target override without unwrapping first: diff --git a/docs/api/parse-and-build-library-async-logger.md b/docs/api/parse-and-build-library-async-logger.md index 8fa5cad..eed26ec 100644 --- a/docs/api/parse-and-build-library-async-logger.md +++ b/docs/api/parse-and-build-library-async-logger.md @@ -40,6 +40,7 @@ Detailed rules explaining key parameters and behaviors - The embedded `LoggerConfig` still goes through the normal synchronous config path first, so sink shape and any optional synchronous queue layer are already applied before the outer async layer is wrapped and then narrowed. - The returned facade wraps the same underlying `AsyncLogger[@bitlogger.RuntimeSink]` value that `parse_async_logger_build_config_text(...)` plus `build_async_logger(...)` would produce directly. - The resulting facade keeps library-facing async operations such as `run()` and `shutdown()` while exposing a smaller public surface. +- The broader async helper surface is still preserved rather than rebuilt, but it is intentionally not directly exposed on the returned facade. Queue counters, lifecycle state, idle-wait helpers, and file-backed runtime helpers stay behind `to_async_logger()` instead of disappearing. - The narrower facade does not change the underlying runtime-sink queue counters, failure state, sink shape, or runtime-dependent post-close behavior; it only hides the broader helper surface until `to_async_logger()` is used. - The narrower facade also preserves the underlying target rules on its exposed write methods: `log(..., target=...)` can override the target for one call, while `info(...)`, `warn(...)`, and `error(...)` continue using the stored logger target unless the facade first derived another logger with `with_target(...)` or `child(...)`. - In the current parsed-builder coverage, unwrapping this facade yields the same async state snapshot, runtime-sink variant, queue counters, lifecycle flags, and failure fields as `build_async_logger(parse_async_logger_build_config_text(input))`. @@ -78,6 +79,8 @@ ignore(full.pending_count()) In this example, the caller unwraps the library async facade before using async state helpers. +And unlike `ApplicationAsyncLogger`, the narrower parse/build result does not expose those broader async helpers directly on the facade surface. + #### When Need A Per-call Target Override Through The Library Facade When parsed library configuration should still allow a one-call target override without unwrapping first: diff --git a/docs/api/parse-and-build-library-logger.md b/docs/api/parse-and-build-library-logger.md index eb6f255..0037b64 100644 --- a/docs/api/parse-and-build-library-logger.md +++ b/docs/api/parse-and-build-library-logger.md @@ -39,6 +39,7 @@ Detailed rules explaining key parameters and behaviors - The parsed config still goes through the normal configured runtime logger build path, including runtime sink selection, optional queue wrapping, and timestamp application. - The returned facade wraps the same underlying `ConfiguredLogger` value that `parse_and_build_logger(...)` would produce directly. - The returned facade keeps a narrower surface than the underlying configured logger. +- The configured runtime helper surface is still preserved rather than rebuilt, but it is intentionally not directly exposed on the returned facade. Queue metrics, flush or drain helpers, and file controls stay behind `to_logger()` instead of disappearing. - The facade still preserves the underlying logger target rules on its exposed write methods: `log(..., target=...)` can override the target for one write, while `info(...)`, `warn(...)`, and `error(...)` continue using the stored logger target unless the facade first derived another logger with `with_target(...)` or `child(...)`. - 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. @@ -74,6 +75,8 @@ In this example, the caller unwraps the library facade before using runtime-spec And the unwrapped value still reflects the same `RuntimeSink` pipeline built from the parsed config text. +And unlike `ApplicationLogger`, the narrower parse/build result does not expose those runtime helpers directly on the facade surface. + #### When Need A Per-call Target Override Through The Library Facade When parsed library configuration should still allow a one-write target override without unwrapping first: