diff --git a/docs/api/library-logger-bind.md b/docs/api/library-logger-bind.md index 953f68d..bf14ead 100644 --- a/docs/api/library-logger-bind.md +++ b/docs/api/library-logger-bind.md @@ -3,7 +3,7 @@ name: library-logger-bind group: api category: facade update-time: 20260613 -description: Attach reusable structured fields to a LibraryLogger facade through the bind alias. +description: Attach reusable structured fields to a LibraryLogger facade through the bind alias while extending the visible sink type to ContextSink. key-word: - library - facade @@ -38,8 +38,11 @@ pub fn[S] LibraryLogger::bind( Detailed rules explaining key parameters and behaviors - `bind(...)` delegates directly to `with_context_fields(...)`. -- The original facade value is not mutated; a wrapped facade is returned. - Shared fields are applied to every later log call emitted through the returned facade. +- The returned facade changes visible type from `LibraryLogger[S]` to `LibraryLogger[ContextSink[S]]` because the sink pipeline is extended with context-field merging behavior. +- Minimum level, target, and timestamp behavior are preserved while the sink pipeline changes. +- Broader composition helpers remain hidden behind the narrower facade after rewrapping; use `to_logger()` if later code needs them. +- The original facade value is not mutated; a wrapped facade is returned. - This alias is useful when you prefer shorter chaining syntax in library code. ### How to Use @@ -68,15 +71,21 @@ let worker = LibraryLogger::new(console_sink(), target="app") In this example, `bind(...)` communicates intent without changing underlying behavior. +And because it is only an alias, the resulting facade behaves the same as calling `with_context_fields(...)` directly. + ### Error Case e.g.: -- If `fields` is empty, the returned facade remains valid and simply adds no extra metadata. +- If `fields` is empty, the returned facade remains valid and simply stores an empty shared field set in `ContextSink[S]`. - If duplicate field keys are bound, all copies are preserved for downstream formatting or inspection. +- If callers want event-specific fields without changing the shared bound set, they should pass those through `log(..., fields=...)` on the returned facade. + ### Notes 1. Use `bind(...)` and `with_context_fields(...)` interchangeably; choose the one that reads better in context. 2. This alias exists for ergonomics, not for different semantics. + +3. Use `with_context_fields(...)` when the longer name makes the shared-field sink-type change clearer at the call site. diff --git a/docs/api/library-logger-child.md b/docs/api/library-logger-child.md index 5669ea7..1a7d625 100644 --- a/docs/api/library-logger-child.md +++ b/docs/api/library-logger-child.md @@ -3,7 +3,7 @@ name: library-logger-child group: api category: facade update-time: 20260613 -description: Derive a child LibraryLogger facade by composing the current target with a child segment. +description: Derive a child LibraryLogger facade by composing the current target with a child segment while rewrapping the same underlying logger state. key-word: - library - facade @@ -38,6 +38,8 @@ Detailed rules explaining key parameters and behaviors - If the parent target is empty, the child target becomes the full target. - If the child target is empty, the parent target is preserved. - If both are non-empty, they are joined with `.`. +- Sink type, minimum level, timestamp behavior, and any existing sink wrappers remain the same because only the derived target changes. +- Broader composition helpers remain hidden behind the narrower facade after rewrapping; use `to_logger()` if later code needs them. ### How to Use @@ -65,6 +67,8 @@ let client = LibraryLogger::new(console_sink(), target="sdk") In this example, the final facade emits under `sdk.http.client`. +And the target derivation does not rebuild or reset the wrapped logger pipeline. + ### Error Case e.g.: @@ -77,3 +81,5 @@ e.g.: 1. This is the preferred library-facing API for hierarchical target naming. 2. Composition uses `.` as the separator between parent and child segments. + +3. Use `with_target(...)` instead when the new target should replace the current target rather than extend it. diff --git a/docs/api/library-logger-with-context-fields.md b/docs/api/library-logger-with-context-fields.md index a9dc703..c6c3acd 100644 --- a/docs/api/library-logger-with-context-fields.md +++ b/docs/api/library-logger-with-context-fields.md @@ -3,7 +3,7 @@ name: library-logger-with-context-fields group: api category: facade update-time: 20260613 -description: Attach reusable structured fields to a LibraryLogger facade. +description: Attach reusable structured fields to a LibraryLogger facade while extending the visible sink type to ContextSink. key-word: - library - facade @@ -27,7 +27,7 @@ pub fn[S] LibraryLogger::with_context_fields( #### input - `self : LibraryLogger[S]` - Base facade that should gain shared fields. -- `fields : Array[Field]` - Structured fields that will be prepended to each emitted record. +- `fields : Array[Field]` - Structured fields stored in the added `ContextSink` and prepended to each emitted record. #### output @@ -39,7 +39,9 @@ Detailed rules explaining key parameters and behaviors - This API delegates to the wrapped logger's `with_context_fields(...)` behavior and then narrows the result back to `LibraryLogger`. - Context fields are merged at write time rather than by mutating previously created records. -- The returned facade carries `ContextSink[S]` because the sink pipeline has been extended. +- The returned facade carries `ContextSink[S]` because the sink pipeline is extended around the previous sink instead of keeping the original visible sink type `S`. +- Minimum level, target, and timestamp behavior are preserved while the sink pipeline changes from `S` to `ContextSink[S]`. +- Broader composition helpers remain hidden behind the narrower facade after rewrapping; use `to_logger()` if later code needs them. - `bind(...)` is an ergonomic alias for this same behavior. ### How to Use @@ -68,15 +70,21 @@ let worker = LibraryLogger::new(console_sink(), target="sdk") In this example, target composition and field binding stay separate but compose cleanly. +And the returned facade keeps the same logger configuration while exposing the widened sink type `ContextSink[S]`. + ### Error Case e.g.: -- If `fields` is empty, the returned facade remains valid and simply adds no extra metadata. +- If `fields` is empty, the returned facade remains valid and simply stores an empty shared field set inside `ContextSink[S]`. - If duplicate field keys are provided, all fields are still emitted for downstream formatting or inspection. +- If callers want event-specific fields without changing the shared bound set, they should pass those through `log(..., fields=...)` on the returned facade. + ### Notes 1. Use this for stable shared metadata, not highly dynamic event-specific values. -2. The narrower `LibraryLogger` surface is preserved after context binding. +2. The narrower `LibraryLogger` surface is preserved after context binding, even though the visible sink type changes to `ContextSink[S]`. + +3. Use `bind(...)` when the shorter alias reads better in chained library code. diff --git a/docs/api/library-logger-with-target.md b/docs/api/library-logger-with-target.md index 0e35211..2c82c4f 100644 --- a/docs/api/library-logger-with-target.md +++ b/docs/api/library-logger-with-target.md @@ -3,7 +3,7 @@ name: library-logger-with-target group: api category: facade update-time: 20260613 -description: Replace the default target carried by a LibraryLogger facade. +description: Replace the default target carried by a LibraryLogger facade while rewrapping the same underlying logger state. key-word: - library - facade @@ -35,8 +35,9 @@ pub fn[S] LibraryLogger::with_target(self : LibraryLogger[S], target : String) - Detailed rules explaining key parameters and behaviors - This API delegates to the wrapped logger's `with_target(...)` behavior and then re-wraps the result. -- The returned value keeps the same sink type and minimum level settings. +- The returned value keeps the same sink type, minimum level, timestamp behavior, and any existing sink wrappers because only the default target field changes. - This replaces the default target instead of composing it. +- Broader composition helpers remain hidden behind the narrower facade after rewrapping; use `to_logger()` if later code needs them. - The original facade value is not mutated. ### How to Use @@ -64,6 +65,8 @@ let io = base.with_target("io") In this example, one base facade becomes several target-specific facades. +And each derived facade still wraps the same logger pipeline, differing only in the default target it carries. + ### Error Case e.g.: @@ -76,3 +79,5 @@ e.g.: 1. Use this API for replacement, not target-path composition. 2. It keeps the narrower `LibraryLogger` boundary intact. + +3. Use `child(...)` when the new target should be combined with the current one instead of replacing it.