From 4e32a7350a24b768eac72b3d37e828daed11e921 Mon Sep 17 00:00:00 2001
From: Nanaloveyuki <miaomiao_159@outlook.com>
Date: Sat, 13 Jun 2026 20:36:45 +0800
Subject: [PATCH] :memo: document sync library facade composition apis

---
 docs/api/index.md                             |  5 ++
 docs/api/library-logger-bind.md               | 82 +++++++++++++++++++
 docs/api/library-logger-child.md              | 79 ++++++++++++++++++
 docs/api/library-logger-new.md                | 81 ++++++++++++++++++
 .../api/library-logger-with-context-fields.md | 82 +++++++++++++++++++
 docs/api/library-logger-with-target.md        | 78 ++++++++++++++++++
 6 files changed, 407 insertions(+)
 create mode 100644 docs/api/library-logger-bind.md
 create mode 100644 docs/api/library-logger-child.md
 create mode 100644 docs/api/library-logger-new.md
 create mode 100644 docs/api/library-logger-with-context-fields.md
 create mode 100644 docs/api/library-logger-with-target.md

diff --git a/docs/api/index.md b/docs/api/index.md
index fdae07b..3fb54c0 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -205,8 +205,13 @@ BitLogger API navigation.
 
 ## Application and library facades
 
+- [library-logger-new.md](./library-logger-new.md)
 - [logger-to-library-logger.md](./logger-to-library-logger.md)
 - [library-logger-to-logger.md](./library-logger-to-logger.md)
+- [library-logger-with-target.md](./library-logger-with-target.md)
+- [library-logger-child.md](./library-logger-child.md)
+- [library-logger-with-context-fields.md](./library-logger-with-context-fields.md)
+- [library-logger-bind.md](./library-logger-bind.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)
diff --git a/docs/api/library-logger-bind.md b/docs/api/library-logger-bind.md
new file mode 100644
index 0000000..953f68d
--- /dev/null
+++ b/docs/api/library-logger-bind.md
@@ -0,0 +1,82 @@
+---
+name: library-logger-bind
+group: api
+category: facade
+update-time: 20260613
+description: Attach reusable structured fields to a LibraryLogger facade through the bind alias.
+key-word:
+    - library
+    - facade
+    - bind
+    - public
+---
+
+## Library-logger-bind
+
+Attach shared structured fields to a `LibraryLogger[S]` through the `bind(...)` alias. This is behaviorally identical to `with_context_fields(...)` and exists as a shorter name for common library-facing context binding.
+
+### Interface
+
+```moonbit
+pub fn[S] LibraryLogger::bind(
+  self : LibraryLogger[S],
+  fields : Array[Field],
+) -> LibraryLogger[ContextSink[S]] {
+```
+
+#### input
+
+- `self : LibraryLogger[S]` - Base facade that should gain shared fields.
+- `fields : Array[Field]` - Structured fields attached to every emitted record.
+
+#### output
+
+- `LibraryLogger[ContextSink[S]]` - New library-facing wrapper that prepends shared fields at write time.
+
+### Explanation
+
+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.
+- This alias is useful when you prefer shorter chaining syntax in library code.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Bind Shared Package Context
+
+When a library logger should carry stable metadata through a flow:
+```moonbit
+let request_logger = default_library_logger()
+  .with_target("sdk")
+  .bind([field("request_id", "req-42")])
+```
+
+In this example, subsequent writes automatically include `request_id`.
+
+#### When Prefer Shorter Chaining Syntax
+
+When a context-bound child facade should stay readable:
+```moonbit
+let worker = LibraryLogger::new(console_sink(), target="app")
+  .child("worker")
+  .bind([field("component", "worker")])
+```
+
+In this example, `bind(...)` communicates intent without changing underlying behavior.
+
+### Error Case
+
+e.g.:
+- If `fields` is empty, the returned facade remains valid and simply adds no extra metadata.
+
+- If duplicate field keys are bound, all copies are preserved for downstream formatting or inspection.
+
+### 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.
diff --git a/docs/api/library-logger-child.md b/docs/api/library-logger-child.md
new file mode 100644
index 0000000..5669ea7
--- /dev/null
+++ b/docs/api/library-logger-child.md
@@ -0,0 +1,79 @@
+---
+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.
+key-word:
+    - library
+    - facade
+    - child
+    - public
+---
+
+## Library-logger-child
+
+Create a child `LibraryLogger[S]` by composing the current target with another target segment. This is the library-facing hierarchical naming helper for targets such as `sdk.cache` or `plugin.worker.io`.
+
+### Interface
+
+```moonbit
+pub fn[S] LibraryLogger::child(self : LibraryLogger[S], target : String) -> LibraryLogger[S] {
+```
+
+#### input
+
+- `self : LibraryLogger[S]` - Parent facade whose target should be extended.
+- `target : String` - Child target segment or suffix.
+
+#### output
+
+- `LibraryLogger[S]` - New library-facing facade whose target is the composed child path.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This API delegates to the wrapped logger's `child(...)` behavior and then re-wraps the result.
+- 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 `.`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Hierarchical Target Naming In A Library API
+
+When a package wants stable namespace composition without exposing `Logger[S]`:
+```moonbit
+let worker = default_library_logger()
+  .with_target("plugin")
+  .child("worker")
+```
+
+In this example, the final target becomes `plugin.worker`.
+
+#### When Build Scoped Facades Step By Step
+
+When deeper target composition should stay readable:
+```moonbit
+let client = LibraryLogger::new(console_sink(), target="sdk")
+  .child("http")
+  .child("client")
+```
+
+In this example, the final facade emits under `sdk.http.client`.
+
+### Error Case
+
+e.g.:
+- If `target` is empty, the returned facade keeps the original parent target.
+
+- If callers need complete replacement instead of composition, `with_target(...)` should be used instead.
+
+### Notes
+
+1. This is the preferred library-facing API for hierarchical target naming.
+
+2. Composition uses `.` as the separator between parent and child segments.
diff --git a/docs/api/library-logger-new.md b/docs/api/library-logger-new.md
new file mode 100644
index 0000000..9b1e198
--- /dev/null
+++ b/docs/api/library-logger-new.md
@@ -0,0 +1,81 @@
+---
+name: library-logger-new
+group: api
+category: facade
+update-time: 20260613
+description: Create a narrower sync library logger facade from any sink implementation.
+key-word:
+    - library
+    - facade
+    - logger
+    - public
+---
+
+## Library-logger-new
+
+Create a `LibraryLogger[S]` from any sink implementation. This is the library-facing sync constructor when you want standard logging behavior but do not want to expose the full `Logger[S]` surface.
+
+### Interface
+
+```moonbit
+pub fn[S] LibraryLogger::new(
+  sink : S,
+  min_level~ : Level = Level::Info,
+  target~ : String = "",
+) -> LibraryLogger[S] {
+```
+
+#### input
+
+- `sink : S` - Any sink value implementing `Sink`, such as `console_sink()` or a composed sink.
+- `min_level : Level` - Minimum enabled level. Messages below this threshold are ignored.
+- `target : String` - Default target attached to emitted records unless later overridden.
+
+#### output
+
+- `LibraryLogger[S]` - Narrow library-facing wrapper over a newly created sync logger.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This API builds a regular `Logger::new(...)` internally and then wraps it as `LibraryLogger`.
+- The returned facade intentionally exposes a smaller method set than the full `Logger[S]` type.
+- The original sink type is still preserved in `LibraryLogger[S]`.
+- Call `to_logger()` if later code must recover the full sync logger surface.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Narrower Library-facing Constructor
+
+When a package should create a logger without exposing the full logger API:
+```moonbit
+let logger = LibraryLogger::new(console_sink(), min_level=Level::Info, target="plugin")
+logger.info("loaded")
+```
+
+In this example, the package creates a normal sync logger pipeline but publishes only the smaller facade type.
+
+#### When Accept A Generic Sink But Keep Library Boundaries Small
+
+When a library API wants typed sinks without exposing extra composition helpers:
+```moonbit
+let logger = LibraryLogger::new(text_console_sink(text_formatter()), target="worker")
+```
+
+In this example, sink typing remains explicit while the consumer only sees the library facade.
+
+### Error Case
+
+e.g.:
+- If `target` is empty, the returned logger remains valid and later records simply use an empty default target.
+
+- If later code needs methods outside the facade, it must unwrap with `to_logger()`.
+
+### Notes
+
+1. This is the direct constructor counterpart to `Logger::new(...)` for library-oriented APIs.
+
+2. Prefer this when public package boundaries should stay narrower than `Logger[S]`.
diff --git a/docs/api/library-logger-with-context-fields.md b/docs/api/library-logger-with-context-fields.md
new file mode 100644
index 0000000..a9dc703
--- /dev/null
+++ b/docs/api/library-logger-with-context-fields.md
@@ -0,0 +1,82 @@
+---
+name: library-logger-with-context-fields
+group: api
+category: facade
+update-time: 20260613
+description: Attach reusable structured fields to a LibraryLogger facade.
+key-word:
+    - library
+    - facade
+    - fields
+    - public
+---
+
+## Library-logger-with-context-fields
+
+Bind shared structured fields to a `LibraryLogger[S]`. This is the library-facing API for attaching stable metadata such as component name, plugin id, or request scope without repeating those fields on every log call.
+
+### Interface
+
+```moonbit
+pub fn[S] LibraryLogger::with_context_fields(
+  self : LibraryLogger[S],
+  fields : Array[Field],
+) -> LibraryLogger[ContextSink[S]] {
+```
+
+#### input
+
+- `self : LibraryLogger[S]` - Base facade that should gain shared fields.
+- `fields : Array[Field]` - Structured fields that will be prepended to each emitted record.
+
+#### output
+
+- `LibraryLogger[ContextSink[S]]` - New library-facing facade wrapping the original sink with context-field merging behavior.
+
+### Explanation
+
+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.
+- `bind(...)` is an ergonomic alias for this same behavior.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Stable Library Metadata On Every Record
+
+When a package should attach fixed metadata to all emitted records:
+```moonbit
+let logger = default_library_logger()
+  .with_target("plugin")
+  .with_context_fields([field("plugin", "alpha"), field("region", "cn")])
+```
+
+In this example, both fields are automatically included on every later write.
+
+#### When Combine Target Scoping And Shared Fields
+
+When a subsystem facade should carry both a target and stable context:
+```moonbit
+let worker = LibraryLogger::new(console_sink(), target="sdk")
+  .child("worker")
+  .with_context_fields([field("component", "worker")])
+```
+
+In this example, target composition and field binding stay separate but compose cleanly.
+
+### Error Case
+
+e.g.:
+- If `fields` is empty, the returned facade remains valid and simply adds no extra metadata.
+
+- If duplicate field keys are provided, all fields are still emitted for downstream formatting or inspection.
+
+### Notes
+
+1. Use this for stable shared metadata, not highly dynamic event-specific values.
+
+2. The narrower `LibraryLogger` surface is preserved after context binding.
diff --git a/docs/api/library-logger-with-target.md b/docs/api/library-logger-with-target.md
new file mode 100644
index 0000000..0e35211
--- /dev/null
+++ b/docs/api/library-logger-with-target.md
@@ -0,0 +1,78 @@
+---
+name: library-logger-with-target
+group: api
+category: facade
+update-time: 20260613
+description: Replace the default target carried by a LibraryLogger facade.
+key-word:
+    - library
+    - facade
+    - target
+    - public
+---
+
+## Library-logger-with-target
+
+Replace the default target on a `LibraryLogger[S]`. This is the library-facing counterpart to `Logger::with_target(...)` when a package wants to retarget a logger without exposing the full sync logger API.
+
+### Interface
+
+```moonbit
+pub fn[S] LibraryLogger::with_target(self : LibraryLogger[S], target : String) -> LibraryLogger[S] {
+```
+
+#### input
+
+- `self : LibraryLogger[S]` - Base facade whose default target should be replaced.
+- `target : String` - New default target namespace.
+
+#### output
+
+- `LibraryLogger[S]` - New library-facing logger facade carrying the updated target.
+
+### Explanation
+
+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.
+- This replaces the default target instead of composing it.
+- The original facade value is not mutated.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A New Fixed Namespace Inside Library Code
+
+When one facade should emit under a different target namespace:
+```moonbit
+let logger = default_library_logger().with_target("sdk.http")
+logger.info("request prepared")
+```
+
+In this example, later writes inherit `sdk.http` unless a call overrides the target directly.
+
+#### When Reuse The Same Sink Across Several Library Subsystems
+
+When multiple library-facing loggers should share one base pipeline:
+```moonbit
+let base = LibraryLogger::new(console_sink())
+let cache = base.with_target("cache")
+let io = base.with_target("io")
+```
+
+In this example, one base facade becomes several target-specific facades.
+
+### Error Case
+
+e.g.:
+- If `target` is empty, the returned logger remains valid and later records simply use an empty default target.
+
+- If callers need hierarchical target composition rather than replacement, `child(...)` is the better API.
+
+### Notes
+
+1. Use this API for replacement, not target-path composition.
+
+2. It keeps the narrower `LibraryLogger` boundary intact.