From 00e06c302f22b6b3f58d6edd12d22d7b14b63bd9 Mon Sep 17 00:00:00 2001
From: Nanaloveyuki <miaomiao_159@outlook.com>
Date: Sat, 13 Jun 2026 20:45:41 +0800
Subject: [PATCH] :memo: document async library facade write apis

---
 docs/api/index.md                           |  7 ++
 docs/api/library-async-logger-error.md      | 83 +++++++++++++++++++
 docs/api/library-async-logger-info.md       | 83 +++++++++++++++++++
 docs/api/library-async-logger-is-enabled.md | 82 +++++++++++++++++++
 docs/api/library-async-logger-log.md        | 89 +++++++++++++++++++++
 docs/api/library-async-logger-run.md        | 79 ++++++++++++++++++
 docs/api/library-async-logger-shutdown.md   | 78 ++++++++++++++++++
 docs/api/library-async-logger-warn.md       | 83 +++++++++++++++++++
 8 files changed, 584 insertions(+)
 create mode 100644 docs/api/library-async-logger-error.md
 create mode 100644 docs/api/library-async-logger-info.md
 create mode 100644 docs/api/library-async-logger-is-enabled.md
 create mode 100644 docs/api/library-async-logger-log.md
 create mode 100644 docs/api/library-async-logger-run.md
 create mode 100644 docs/api/library-async-logger-shutdown.md
 create mode 100644 docs/api/library-async-logger-warn.md

diff --git a/docs/api/index.md b/docs/api/index.md
index 38e37dc..f3bcc14 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -229,6 +229,13 @@ BitLogger API navigation.
 - [library-async-logger-child.md](./library-async-logger-child.md)
 - [library-async-logger-with-context-fields.md](./library-async-logger-with-context-fields.md)
 - [library-async-logger-bind.md](./library-async-logger-bind.md)
+- [library-async-logger-is-enabled.md](./library-async-logger-is-enabled.md)
+- [library-async-logger-log.md](./library-async-logger-log.md)
+- [library-async-logger-info.md](./library-async-logger-info.md)
+- [library-async-logger-warn.md](./library-async-logger-warn.md)
+- [library-async-logger-error.md](./library-async-logger-error.md)
+- [library-async-logger-run.md](./library-async-logger-run.md)
+- [library-async-logger-shutdown.md](./library-async-logger-shutdown.md)
 - [build-application-async-logger.md](./build-application-async-logger.md)
 - [build-application-text-async-logger.md](./build-application-text-async-logger.md)
 - [parse-and-build-application-async-logger.md](./parse-and-build-application-async-logger.md)
diff --git a/docs/api/library-async-logger-error.md b/docs/api/library-async-logger-error.md
new file mode 100644
index 0000000..1c513f0
--- /dev/null
+++ b/docs/api/library-async-logger-error.md
@@ -0,0 +1,83 @@
+---
+name: library-async-logger-error
+group: api
+category: facade
+update-time: 20260613
+description: Enqueue an error-level record through a LibraryAsyncLogger facade using the highest built-in severity shortcut.
+key-word:
+    - async
+    - library
+    - error
+    - public
+---
+
+## Library-async-logger-error
+
+Enqueue an error-level record through the library-facing async logger. This is the convenience wrapper for `log(Level::Error, ...)` on `LibraryAsyncLogger[S]`.
+
+### Interface
+
+```moonbit
+pub async fn[S] LibraryAsyncLogger::error(
+  self : LibraryAsyncLogger[S],
+  message : String,
+  fields~ : Array[@bitlogger.Field] = [],
+) -> Unit {
+```
+
+#### input
+
+- `self : LibraryAsyncLogger[S]` - Library-facing async logger that should receive the error record.
+- `message : String` - Error message text.
+- `fields : Array[@bitlogger.Field]` - Optional structured fields added to the record.
+
+#### output
+
+- `Unit` - No return value. The record is handled according to logger state and policy.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper delegates to `log(Level::Error, ...)` on the wrapped async logger.
+- The record is still subject to patching, filtering, and overflow policy.
+- Error records represent the highest built-in severity in this async facade API.
+- Use this helper when a named error call is clearer than a raw `log(...)` call.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Async Failure Reporting In A Library Boundary
+
+When an operation should emit a high-severity failure event:
+```moonbit
+await logger.error("worker execution failed")
+```
+
+In this example, failure intent is explicit at the call site.
+
+#### When Attach Structured Error Context
+
+When an error event should include diagnostic fields:
+```moonbit
+await logger.error(
+  "dispatch failed",
+  fields=[@bitlogger.field("job_id", "42")],
+)
+```
+
+In this example, the error record carries structured context without falling back to the generic `log(...)` form.
+
+### Error Case
+
+e.g.:
+- If the logger is closed or overflow policy prevents acceptance, even an error-level record may not become a normal queued record.
+
+- If callers need to inspect worker failure rather than emit an error record, `has_failed()` and `last_error()` are the relevant APIs on the full async logger.
+
+### Notes
+
+1. Use this helper for high-severity async application failures.
+
+2. Emitting an error record is separate from the logger worker itself entering failure state.
diff --git a/docs/api/library-async-logger-info.md b/docs/api/library-async-logger-info.md
new file mode 100644
index 0000000..fb4ad7b
--- /dev/null
+++ b/docs/api/library-async-logger-info.md
@@ -0,0 +1,83 @@
+---
+name: library-async-logger-info
+group: api
+category: facade
+update-time: 20260613
+description: Enqueue an info-level record through a LibraryAsyncLogger facade using the informational severity shortcut.
+key-word:
+    - async
+    - library
+    - info
+    - public
+---
+
+## Library-async-logger-info
+
+Enqueue an info-level record through the library-facing async logger. This is the convenience wrapper for `log(Level::Info, ...)` on `LibraryAsyncLogger[S]`.
+
+### Interface
+
+```moonbit
+pub async fn[S] LibraryAsyncLogger::info(
+  self : LibraryAsyncLogger[S],
+  message : String,
+  fields~ : Array[@bitlogger.Field] = [],
+) -> Unit {
+```
+
+#### input
+
+- `self : LibraryAsyncLogger[S]` - Library-facing async logger that should receive the info record.
+- `message : String` - Info message text.
+- `fields : Array[@bitlogger.Field]` - Optional structured fields added to the record.
+
+#### output
+
+- `Unit` - No return value. The record is handled according to logger state and policy.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper delegates to `log(Level::Info, ...)` on the wrapped async logger.
+- The record is still subject to min-level gating, patching, filtering, and overflow policy.
+- `Info` is often the default operational logging level for async application events.
+- Use this helper when explicit info intent is clearer than a raw `log(...)` call.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Normal Operational Async Library Events
+
+When async package code should report routine progress or lifecycle events:
+```moonbit
+await logger.info("worker started")
+```
+
+In this example, the event is expressed at the common operational logging level through the narrower facade.
+
+#### When Add Structured Operational Metadata
+
+When an info event should include stable structured detail:
+```moonbit
+await logger.info(
+  "job queued",
+  fields=[@bitlogger.field("queue", "sync")],
+)
+```
+
+In this example, the record remains concise while still carrying useful metadata.
+
+### Error Case
+
+e.g.:
+- If the logger minimum level is above `Info`, the record is skipped before enqueue.
+
+- If the logger is closed or overflow policy prevents acceptance, the write may not become a normal queued record.
+
+### Notes
+
+1. This is often the most common convenience method for normal async library events.
+
+2. Use `log(...)` when the call site needs a dynamic level or target override.
diff --git a/docs/api/library-async-logger-is-enabled.md b/docs/api/library-async-logger-is-enabled.md
new file mode 100644
index 0000000..16c36f9
--- /dev/null
+++ b/docs/api/library-async-logger-is-enabled.md
@@ -0,0 +1,82 @@
+---
+name: library-async-logger-is-enabled
+group: api
+category: facade
+update-time: 20260613
+description: Check whether a LibraryAsyncLogger facade would accept a record at a given level.
+key-word:
+    - async
+    - library
+    - enabled
+    - public
+---
+
+## Library-async-logger-is-enabled
+
+Check whether a `LibraryAsyncLogger[S]` would accept a record at the given level based on its current `min_level`. This is the library-facing counterpart to `AsyncLogger::is_enabled(...)` and is useful for gating expensive async message preparation.
+
+### Interface
+
+```moonbit
+pub fn[S] LibraryAsyncLogger::is_enabled(
+  self : LibraryAsyncLogger[S],
+  level : @bitlogger.Level,
+) -> Bool {
+```
+
+#### input
+
+- `self : LibraryAsyncLogger[S]` - Library-facing async logger whose current minimum level should be checked.
+- `level : @bitlogger.Level` - Candidate severity to test.
+
+#### output
+
+- `Bool` - `true` when the level is enabled by the facade's current threshold.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This method delegates directly to the wrapped async logger's `is_enabled(...)` behavior.
+- It only checks logger-level severity gating; it does not evaluate later filter or overflow behavior.
+- The result reflects the current facade value, so derived facades with different thresholds can return different answers.
+- Use it when message construction or field gathering is expensive enough to justify a pre-check.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Avoid Expensive Async Debug Preparation
+
+When debug data should only be built if needed:
+```moonbit
+if logger.is_enabled(@bitlogger.Level::Info) {
+  await logger.info(build_summary())
+}
+```
+
+In this example, expensive preparation is skipped unless the current threshold allows that severity.
+
+#### When Inspect Effective Async Facade Threshold
+
+When package code should branch based on current logger behavior:
+```moonbit
+if logger.is_enabled(@bitlogger.Level::Warn) {
+  await logger.warn("slow path active")
+}
+```
+
+In this example, the check mirrors the same severity gate used by later async write calls.
+
+### Error Case
+
+e.g.:
+- If `level` is below the current minimum threshold, the method returns `false`.
+
+- A `true` result does not guarantee final delivery if later queue or filter behavior rejects the record.
+
+### Notes
+
+1. This is a cheap severity check, not a full end-to-end delivery guarantee.
+
+2. Prefer using it only when precomputing the async log payload is meaningfully expensive.
diff --git a/docs/api/library-async-logger-log.md b/docs/api/library-async-logger-log.md
new file mode 100644
index 0000000..163ba8e
--- /dev/null
+++ b/docs/api/library-async-logger-log.md
@@ -0,0 +1,89 @@
+---
+name: library-async-logger-log
+group: api
+category: facade
+update-time: 20260613
+description: Enqueue a record through a LibraryAsyncLogger facade with explicit level, message, fields, and optional target override.
+key-word:
+    - async
+    - library
+    - log
+    - public
+---
+
+## Library-async-logger-log
+
+Enqueue a record through the library-facing async logger with an explicit level and message. This is the core write API behind the level-specific `LibraryAsyncLogger` convenience methods.
+
+### Interface
+
+```moonbit
+pub async fn[S] LibraryAsyncLogger::log(
+  self : LibraryAsyncLogger[S],
+  level : @bitlogger.Level,
+  message : String,
+  fields~ : Array[@bitlogger.Field] = [],
+  target? : String = "",
+) -> Unit {
+```
+
+#### input
+
+- `self : LibraryAsyncLogger[S]` - Library-facing async logger that should receive the record.
+- `level : @bitlogger.Level` - Severity level for the record.
+- `message : String` - Log message text.
+- `fields : Array[@bitlogger.Field]` - Optional structured fields added to the record.
+- `target : String` - Optional per-call target override.
+
+#### output
+
+- `Unit` - No return value. The record is either skipped, enqueued, or dropped according to logger state and policy.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This method delegates directly to the wrapped async logger's `log(...)` behavior.
+- The logger checks `is_enabled(level)` before building a record.
+- Context fields, patch logic, and filter logic are applied before enqueue.
+- The narrower library facade does not change enqueue semantics; it only limits the visible API surface.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Full Per-call Control Through The Async Facade
+
+When library code should choose level, fields, and target per event:
+```moonbit
+await logger.log(
+  @bitlogger.Level::Info,
+  "worker started",
+  fields=[@bitlogger.field("job", "sync")],
+  target="service.worker",
+)
+```
+
+In this example, the call site controls every major record property while keeping the narrower facade type.
+
+#### When Build Higher-level Async Library Wrappers
+
+When package code defines its own logging helpers:
+```moonbit
+await logger.log(@bitlogger.Level::Warn, "slow request")
+```
+
+In this example, `log(...)` acts as the shared primitive under custom library-facing wrappers.
+
+### Error Case
+
+e.g.:
+- If the level is below the current minimum threshold, the record is skipped before queue insertion.
+
+- If the logger is closed or overflow policy rejects the record, enqueue may not proceed as a normal accepted write.
+
+### Notes
+
+1. Use this API when the call site needs full control instead of a fixed severity helper.
+
+2. Prefer `info()`, `warn()`, `error()`, and the other shortcuts when only the level differs.
diff --git a/docs/api/library-async-logger-run.md b/docs/api/library-async-logger-run.md
new file mode 100644
index 0000000..6ea00a2
--- /dev/null
+++ b/docs/api/library-async-logger-run.md
@@ -0,0 +1,79 @@
+---
+name: library-async-logger-run
+group: api
+category: facade
+update-time: 20260613
+description: Start the LibraryAsyncLogger worker loop so queued records are drained to the underlying sink.
+key-word:
+    - async
+    - library
+    - worker
+    - public
+---
+
+## Library-async-logger-run
+
+Start the library-facing async logger worker loop. This is the core runtime API that drains queued records to the underlying sink while preserving the narrower facade boundary.
+
+### Interface
+
+```moonbit
+pub async fn[S : @bitlogger.Sink] LibraryAsyncLogger::run(self : LibraryAsyncLogger[S]) -> Unit {
+```
+
+#### input
+
+- `self : LibraryAsyncLogger[S]` - Library-facing async logger whose queue should be drained by the worker loop.
+
+#### output
+
+- `Unit` - No return value. The method runs until the queue is closed or a worker failure occurs.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This method delegates directly to the wrapped async logger's `run()` behavior.
+- It starts the worker loop that makes accepted queued records reach the underlying sink.
+- Failure and lifecycle state are still tracked by the wrapped async logger.
+- The narrower library facade does not hide the need to explicitly activate queue draining.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Background Queue Drain Through The Facade
+
+When library async logging should be processed by a worker task:
+```moonbit
+let logger = LibraryAsyncLogger::new(@bitlogger.console_sink())
+@async.with_task_group(group => {
+  group.spawn_bg(() => logger.run())
+  logger.info("started")
+  logger.shutdown()
+})
+```
+
+In this example, `run()` is the worker loop that makes the async facade actually deliver queued records.
+
+#### When Need Explicit Worker Lifetime Control
+
+When worker execution should be started under caller control:
+```moonbit
+group.spawn_bg(() => logger.run())
+```
+
+In this example, the caller decides when the worker begins instead of hiding that lifecycle step.
+
+### Error Case
+
+e.g.:
+- If the worker loop fails, the wrapped async logger records failure state.
+
+- If `run()` is never started, accepted records may remain queued and not reach the sink.
+
+### Notes
+
+1. `LibraryAsyncLogger::new(...)` only constructs the facade; `run()` is what activates queue draining.
+
+2. Pair this API with `shutdown()` for a complete worker lifecycle.
diff --git a/docs/api/library-async-logger-shutdown.md b/docs/api/library-async-logger-shutdown.md
new file mode 100644
index 0000000..e07bdf1
--- /dev/null
+++ b/docs/api/library-async-logger-shutdown.md
@@ -0,0 +1,78 @@
+---
+name: library-async-logger-shutdown
+group: api
+category: facade
+update-time: 20260613
+description: Gracefully stop a LibraryAsyncLogger by draining or clearing queued work, then waiting for the worker to finish.
+key-word:
+    - async
+    - library
+    - lifecycle
+    - public
+---
+
+## Library-async-logger-shutdown
+
+Gracefully stop a library-facing async logger. This is the high-level shutdown API for `LibraryAsyncLogger[S]` because it coordinates drain behavior, closure, and worker completion while preserving the narrower facade surface.
+
+### Interface
+
+```moonbit
+pub async fn[S] LibraryAsyncLogger::shutdown(
+  self : LibraryAsyncLogger[S],
+  clear? : Bool = false,
+) -> Unit {
+```
+
+#### input
+
+- `self : LibraryAsyncLogger[S]` - Library-facing async logger that should be shut down.
+- `clear : Bool` - Whether pending records should be abandoned immediately instead of waiting for idle first.
+
+#### output
+
+- `Unit` - No return value. The method completes after shutdown coordination finishes.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This method delegates directly to the wrapped async logger's `shutdown(...)` behavior.
+- `clear=false` first waits for idle, then closes the logger.
+- `clear=true` immediately closes and abandons pending records.
+- The method waits until the worker is no longer running before returning.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Graceful Async Library Shutdown
+
+When a service should stop logging only after queued records are drained:
+```moonbit
+await logger.shutdown()
+```
+
+In this example, the facade waits for normal drain behavior before final closure.
+
+#### When Need Fast Shutdown Under Pressure
+
+When teardown should prefer speed over preserving backlog:
+```moonbit
+await logger.shutdown(clear=true)
+```
+
+In this example, pending work is abandoned intentionally so shutdown can complete sooner.
+
+### Error Case
+
+e.g.:
+- If `clear=true`, pending records are intentionally dropped rather than drained.
+
+- If callers skip `shutdown()` and only inspect flags manually, it is easier to leave the worker lifecycle in an unclear state.
+
+### Notes
+
+1. Prefer this API over low-level closure control in normal library shutdown paths.
+
+2. Choose `clear=true` only when loss of queued records is acceptable.
diff --git a/docs/api/library-async-logger-warn.md b/docs/api/library-async-logger-warn.md
new file mode 100644
index 0000000..dcb6182
--- /dev/null
+++ b/docs/api/library-async-logger-warn.md
@@ -0,0 +1,83 @@
+---
+name: library-async-logger-warn
+group: api
+category: facade
+update-time: 20260613
+description: Enqueue a warning-level record through a LibraryAsyncLogger facade using the built-in severity shortcut.
+key-word:
+    - async
+    - library
+    - warn
+    - public
+---
+
+## Library-async-logger-warn
+
+Enqueue a warning-level record through the library-facing async logger. This is the convenience wrapper for `log(Level::Warn, ...)` on `LibraryAsyncLogger[S]`.
+
+### Interface
+
+```moonbit
+pub async fn[S] LibraryAsyncLogger::warn(
+  self : LibraryAsyncLogger[S],
+  message : String,
+  fields~ : Array[@bitlogger.Field] = [],
+) -> Unit {
+```
+
+#### input
+
+- `self : LibraryAsyncLogger[S]` - Library-facing async logger that should receive the warning record.
+- `message : String` - Warning message text.
+- `fields : Array[@bitlogger.Field]` - Optional structured fields added to the record.
+
+#### output
+
+- `Unit` - No return value. The record is handled according to logger state and policy.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper delegates to `log(Level::Warn, ...)` on the wrapped async logger.
+- The record is still subject to min-level gating, patching, filtering, and overflow policy.
+- Warning records are useful for degraded but non-fatal runtime conditions.
+- Use this helper when a named warning call is clearer than a raw `log(...)` call.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Async Degradation Signals In Library Code
+
+When the system should report a non-fatal problem:
+```moonbit
+await logger.warn("retry budget running low")
+```
+
+In this example, the event is surfaced at warning severity without using the generic `log(...)` form.
+
+#### When Attach Structured Warning Detail
+
+When a warning event should include context:
+```moonbit
+await logger.warn(
+  "queue near capacity",
+  fields=[@bitlogger.field("pending", "64")],
+)
+```
+
+In this example, the warning carries structured operational detail.
+
+### Error Case
+
+e.g.:
+- If the logger minimum level is above `Warn`, the record is skipped before enqueue.
+
+- If the logger is closed or overflow policy prevents acceptance, the write may not become a normal queued record.
+
+### Notes
+
+1. Use this helper for notable but non-fatal async runtime conditions.
+
+2. Pair warnings with structured fields when operators need quick context.