📝 document async library facade composition apis

docs/api/library-async-logger-with-context-fields.md

@@ -0,0 +1,85 @@
+---
+name: library-async-logger-with-context-fields
+group: api
+category: facade
+update-time: 20260613
+description: Attach reusable structured fields to a LibraryAsyncLogger facade.
+key-word:
+    - async
+    - library
+    - fields
+    - public
+---
+
+## Library-async-logger-with-context-fields
+
+Bind shared structured fields to a `LibraryAsyncLogger[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 async log call.
+
+### Interface
+
+```moonbit
+pub fn[S] LibraryAsyncLogger::with_context_fields(
+  self : LibraryAsyncLogger[S],
+  fields : Array[@bitlogger.Field],
+) -> LibraryAsyncLogger[S] {
+```
+
+#### input
+
+- `self : LibraryAsyncLogger[S]` - Base facade that should gain shared fields.
+- `fields : Array[@bitlogger.Field]` - Structured fields that will be prepended to each emitted record.
+
+#### output
+
+- `LibraryAsyncLogger[S]` - New library-facing async facade carrying the shared field set.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This API delegates to the wrapped async logger's `with_context_fields(...)` behavior and then narrows the result back to `LibraryAsyncLogger`.
+- Context fields are merged during `log(...)` before enqueue.
+- Unlike synchronous `LibraryLogger::with_context_fields(...)`, this async variant preserves the visible `LibraryAsyncLogger[S]` type instead of changing the visible sink type.
+- `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 Async Record
+
+When a package should attach fixed metadata to all queued records:
+```moonbit
+let logger = LibraryAsyncLogger::new(@bitlogger.console_sink())
+  .with_target("plugin")
+  .with_context_fields([
+    @bitlogger.field("plugin", "alpha"),
+    @bitlogger.field("region", "cn"),
+  ])
+```
+
+In this example, both fields are automatically attached before every record enters the queue.
+
+#### When Combine Async Target Scoping And Shared Fields
+
+When a subsystem facade should carry both a target and stable context:
+```moonbit
+let worker = LibraryAsyncLogger::new(@bitlogger.console_sink(), target="sdk")
+  .child("worker")
+  .with_context_fields([@bitlogger.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 `LibraryAsyncLogger` surface is preserved after field binding.