📝 document root logger types

docs/api/async-logger-type.md

@@ -0,0 +1,92 @@
+---
+name: async-logger-type
+group: api
+category: async
+update-time: 20260613
+description: Public asynchronous logger root type used for queue-backed sink-preserving logging pipelines.
+key-word:
+    - async
+    - logger
+    - type
+    - public
+---
+
+## Async-logger-type
+
+`AsyncLogger[S]` is the public asynchronous root logger type. It stores a concrete sink type `S` together with queue policy, runtime state counters, and lifecycle flags, then serves as the base value for async composition, worker control, and async write APIs.
+
+### Interface
+
+```moonbit
+pub struct AsyncLogger[S] {
+  min_level : @bitlogger.Level
+  target : String
+  timestamp : Bool
+  overflow : AsyncOverflowPolicy
+  max_batch : Int
+  linger_ms : Int
+  flush_policy : AsyncFlushPolicy
+  sink : S
+  flush_sink : (S) -> Int raise
+  context_fields : Array[@bitlogger.Field]
+  filter : (@bitlogger.Record) -> Bool
+  patch : @bitlogger.RecordPatch
+  queue : @async.Queue[@bitlogger.Record]
+  pending_count : Ref[Int]
+  dropped_count : Ref[Int]
+  is_closed : Ref[Bool]
+  is_running : Ref[Bool]
+  has_failed : Ref[Bool]
+  last_error : Ref[String]
+}
+```
+
+#### output
+
+- `AsyncLogger[S]` - Public queue-backed asynchronous logger value parameterized by the concrete sink type `S`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a public root struct, not a type alias.
+- The current fields cover targeting, overflow policy, batching, linger timing, flush policy, the wrapped sink, context/filter/patch behavior, queue state, and worker lifecycle flags.
+- The sink type parameter is preserved across async composition, which is why helpers such as `with_target(...)`, `with_context_fields(...)`, `with_filter(...)`, and `with_patch(...)` keep returning `AsyncLogger[S]`.
+- `async_logger(...)` constructs this type as the main asynchronous entry point.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Root Async Logger Value
+
+When queue-backed logging should begin from a concrete sink-preserving root object:
+```moonbit
+let logger : AsyncLogger[ConsoleSink] = async_logger(console_sink(), target="app.async")
+```
+
+In this example, the root async logger keeps the concrete sink type visible for later typed composition.
+
+#### When Need Worker Control Plus Runtime State
+
+When code should both enqueue logs and inspect async runtime behavior:
+```moonbit
+let logger = async_logger(console_sink(), config=AsyncLoggerConfig::new(max_pending=32))
+ignore(logger.pending_count())
+ignore(logger.state())
+```
+
+In this example, the root type combines queue-backed logging with explicit runtime observability.
+
+### Error Case
+
+e.g.:
+- `AsyncLogger[S]` itself does not have a runtime failure mode.
+
+- Actual enqueue, worker, and flush behavior still depends on the wrapped sink `S`, async runtime support, and the configured queue policy.
+
+### Notes
+
+1. Use `async_logger(...)`, `build_async_logger(...)`, or `build_async_text_logger(...)` when you need a value of this type.
+
+2. Use `ApplicationAsyncLogger` or `LibraryAsyncLogger[S]` when a more intention-specific async wrapper or alias fits the calling boundary better.