📝 clarify sync projection runtime helper state

This commit is contained in:
Nanaloveyuki
2026-06-14 09:15:04 +08:00
parent d94b415cb0
commit f6fc9c4201
3 changed files with 8 additions and 0 deletions
+4
View File
@@ -37,6 +37,8 @@ Detailed rules explaining key parameters and behaviors
- Target, min level, timestamp behavior, and sink wiring are preserved because the same underlying logger value is wrapped.
- The returned facade keeps library-oriented write APIs such as `info(...)`, `warn(...)`, and `error(...)`.
- Broader sync composition helpers remain on the underlying `Logger[S]` and are intentionally hidden until `to_logger()` is used again.
- When `S` is `RuntimeSink`, projection also preserves queued runtime state and file-backed runtime helper behavior behind the facade instead of replacing them with a library-specific copy.
- Unwrapping later with `to_logger()` therefore exposes the same pending counts, drain or flush results, file state, and runtime file controls that the original logger already carried.
### How to Use
@@ -71,6 +73,8 @@ e.g.:
- If callers later need composition helpers such as `with_timestamp(...)`, `with_filter(...)`, or `with_patch(...)`, they must unwrap again with `to_logger()`.
- Projection does not normalize configured runtime state; if the original logger already carried queued runtime data or file-backed helper state, a later unwrap still exposes that same live state.
### Notes
1. Use this when library boundaries should avoid exposing the full sync logger surface.