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

---
 docs/api/index.md                     |  5 ++
 docs/api/library-logger-error.md      | 80 +++++++++++++++++++++++
 docs/api/library-logger-info.md       | 80 +++++++++++++++++++++++
 docs/api/library-logger-is-enabled.md | 79 +++++++++++++++++++++++
 docs/api/library-logger-log.md        | 91 +++++++++++++++++++++++++++
 docs/api/library-logger-warn.md       | 80 +++++++++++++++++++++++
 6 files changed, 415 insertions(+)
 create mode 100644 docs/api/library-logger-error.md
 create mode 100644 docs/api/library-logger-info.md
 create mode 100644 docs/api/library-logger-is-enabled.md
 create mode 100644 docs/api/library-logger-log.md
 create mode 100644 docs/api/library-logger-warn.md

diff --git a/docs/api/index.md b/docs/api/index.md
index 8cc808c..38e37dc 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -212,6 +212,11 @@ BitLogger API navigation.
 - [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)
+- [library-logger-is-enabled.md](./library-logger-is-enabled.md)
+- [library-logger-log.md](./library-logger-log.md)
+- [library-logger-info.md](./library-logger-info.md)
+- [library-logger-warn.md](./library-logger-warn.md)
+- [library-logger-error.md](./library-logger-error.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-error.md b/docs/api/library-logger-error.md
new file mode 100644
index 0000000..5a05c12
--- /dev/null
+++ b/docs/api/library-logger-error.md
@@ -0,0 +1,80 @@
+---
+name: library-logger-error
+group: api
+category: facade
+update-time: 20260613
+description: Emit an error-level record through a LibraryLogger facade using the highest built-in severity shortcut.
+key-word:
+    - library
+    - facade
+    - error
+    - public
+---
+
+## Library-logger-error
+
+Emit an error-level record through the library-facing sync logger. This is the convenience wrapper for `log(Level::Error, ...)` on `LibraryLogger[S]`.
+
+### Interface
+
+```moonbit
+pub fn[S : Sink] LibraryLogger::error(
+  self : LibraryLogger[S],
+  message : String,
+  fields~ : Array[Field] = [],
+) -> Unit {
+```
+
+#### input
+
+- `self : LibraryLogger[S]` - Library-facing logger that should emit the error record.
+- `message : String` - Error message text.
+- `fields : Array[Field]` - Optional structured fields attached to the record.
+
+#### output
+
+- `Unit` - No return value. The record is handled according to the current threshold and wrapped sink pipeline.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper delegates to `log(Level::Error, ...)` on the wrapped logger.
+- `Error` is the highest built-in severity in this sync facade API.
+- Per-call target override is not exposed here; use `log(...)` when explicit target control is required.
+- Sink composition, filtering, patching, and queue wrappers still apply normally.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Report A Failing Library Operation
+
+When an operation should emit a high-severity failure event:
+```moonbit
+logger.error("worker execution failed")
+```
+
+In this example, the call site clearly communicates failure severity.
+
+#### When Attach Structured Error Context
+
+When an error event should include diagnostic fields:
+```moonbit
+logger.error("dispatch failed", fields=[field("job_id", "42")])
+```
+
+In this example, the record carries machine-readable context without dropping to the generic `log(...)` form.
+
+### Error Case
+
+e.g.:
+- If the logger minimum level is above `Error`, the call still returns without writing, though this configuration is unusual.
+
+- If a target override is required, use `log(...)` instead of this severity shortcut.
+
+### Notes
+
+1. Use this helper for high-severity library failures.
+
+2. Emitting an error record is separate from throwing or handling program exceptions.
diff --git a/docs/api/library-logger-info.md b/docs/api/library-logger-info.md
new file mode 100644
index 0000000..692f203
--- /dev/null
+++ b/docs/api/library-logger-info.md
@@ -0,0 +1,80 @@
+---
+name: library-logger-info
+group: api
+category: facade
+update-time: 20260613
+description: Emit an info-level record through a LibraryLogger facade using the informational severity shortcut.
+key-word:
+    - library
+    - facade
+    - info
+    - public
+---
+
+## Library-logger-info
+
+Emit an info-level record through the library-facing sync logger. This is the convenience wrapper for `log(Level::Info, ...)` on `LibraryLogger[S]`.
+
+### Interface
+
+```moonbit
+pub fn[S : Sink] LibraryLogger::info(
+  self : LibraryLogger[S],
+  message : String,
+  fields~ : Array[Field] = [],
+) -> Unit {
+```
+
+#### input
+
+- `self : LibraryLogger[S]` - Library-facing logger that should emit the info record.
+- `message : String` - Informational message text.
+- `fields : Array[Field]` - Optional structured fields attached to the record.
+
+#### output
+
+- `Unit` - No return value. The record is handled according to the current threshold and wrapped sink pipeline.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper delegates to `log(Level::Info, ...)` on the wrapped logger.
+- `Info` is the default minimum logger threshold unless changed explicitly.
+- Per-call target override is not exposed here; use `log(...)` if needed.
+- The library facade keeps the same write semantics while exposing a smaller public surface.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Emit Normal Library Lifecycle Events
+
+When a package should report standard lifecycle milestones:
+```moonbit
+logger.info("service started")
+```
+
+In this example, the event uses normal informational severity through the narrower facade.
+
+#### When Attach Structured Informational Context
+
+When an info event should include machine-readable metadata:
+```moonbit
+logger.info("request completed", fields=[field("status", "200")])
+```
+
+In this example, the event remains concise while still carrying useful fields.
+
+### Error Case
+
+e.g.:
+- If the logger minimum level is above `Info`, the call returns without writing a record.
+
+- If the event needs an explicit alternate target, use `log(...)` instead of this shortcut.
+
+### Notes
+
+1. This is the common convenience method for normal library-facing events.
+
+2. Because `Info` is often the default threshold, this helper is a natural baseline for facade examples.
diff --git a/docs/api/library-logger-is-enabled.md b/docs/api/library-logger-is-enabled.md
new file mode 100644
index 0000000..0f6a540
--- /dev/null
+++ b/docs/api/library-logger-is-enabled.md
@@ -0,0 +1,79 @@
+---
+name: library-logger-is-enabled
+group: api
+category: facade
+update-time: 20260613
+description: Check whether a LibraryLogger facade would accept a record at a given level.
+key-word:
+    - library
+    - facade
+    - enabled
+    - public
+---
+
+## Library-logger-is-enabled
+
+Check whether a `LibraryLogger[S]` would accept a record at the given level based on its current `min_level`. This is the library-facing counterpart to `Logger::is_enabled(...)` and is useful for gating expensive message preparation.
+
+### Interface
+
+```moonbit
+pub fn[S] LibraryLogger::is_enabled(self : LibraryLogger[S], level : Level) -> Bool {
+```
+
+#### input
+
+- `self : LibraryLogger[S]` - Library-facing logger whose current minimum level should be checked.
+- `level : 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 logger's `is_enabled(...)` behavior.
+- It only checks logger-level severity gating; it does not evaluate sink filters or patch logic.
+- 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 Library Debug Preparation
+
+When debug data should only be built if needed:
+```moonbit
+if logger.is_enabled(Level::Debug) {
+  logger.info(build_summary())
+}
+```
+
+In this example, expensive preparation is skipped unless the current threshold allows that severity.
+
+#### When Inspect Effective Facade Threshold
+
+When package code should branch based on current logger behavior:
+```moonbit
+if logger.is_enabled(Level::Info) {
+  logger.info("library path active")
+}
+```
+
+In this example, the check mirrors the same severity gate used by later 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 sink output if later filter logic 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 log payload is meaningfully expensive.
diff --git a/docs/api/library-logger-log.md b/docs/api/library-logger-log.md
new file mode 100644
index 0000000..f69bae4
--- /dev/null
+++ b/docs/api/library-logger-log.md
@@ -0,0 +1,91 @@
+---
+name: library-logger-log
+group: api
+category: facade
+update-time: 20260613
+description: Emit a record through a LibraryLogger facade with explicit level, message, fields, and optional target override.
+key-word:
+    - library
+    - facade
+    - log
+    - public
+---
+
+## Library-logger-log
+
+Emit a record through the library-facing sync logger with an explicit level and message. This is the core write API behind the level-specific `LibraryLogger` convenience methods.
+
+### Interface
+
+```moonbit
+pub fn[S : Sink] LibraryLogger::log(
+  self : LibraryLogger[S],
+  level : Level,
+  message : String,
+  fields~ : Array[Field] = [],
+  target? : String = "",
+) -> Unit {
+```
+
+#### input
+
+- `self : LibraryLogger[S]` - Library-facing logger that should emit the record.
+- `level : Level` - Severity level for the record.
+- `message : String` - Log message text.
+- `fields : Array[Field]` - Optional structured fields attached to the record.
+- `target : String` - Optional per-call target override.
+
+#### output
+
+- `Unit` - No return value. The record is either skipped by level gating or written to the wrapped sink pipeline.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This method delegates directly to the wrapped logger's `log(...)` behavior.
+- The logger checks `is_enabled(level)` before building and writing the record.
+- If `target` is empty, the facade's stored default target is used.
+- The narrower library facade does not change record construction 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 Library Facade
+
+When library code should choose level, fields, and target explicitly:
+```moonbit
+logger.log(
+  Level::Info,
+  "worker started",
+  fields=[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 Library Wrappers
+
+When package code defines its own logging helpers:
+```moonbit
+fn log_retry(logger : LibraryLogger[ConsoleSink], attempt : Int) -> Unit {
+  logger.log(Level::Warn, "retry scheduled", fields=[field("attempt", attempt.to_string())])
+}
+```
+
+In this example, `log(...)` acts as the shared primitive under custom library-facing wrappers.
+
+### Error Case
+
+e.g.:
+- If `level` is below the current minimum threshold, the method returns without writing a record.
+
+- If `target` is empty and the logger default target is also empty, the emitted record simply has no target label.
+
+### Notes
+
+1. Use this API when the call site needs full control instead of a fixed-severity helper.
+
+2. The facade remains synchronous; any buffering behavior only comes from the wrapped sink type.
diff --git a/docs/api/library-logger-warn.md b/docs/api/library-logger-warn.md
new file mode 100644
index 0000000..3739e96
--- /dev/null
+++ b/docs/api/library-logger-warn.md
@@ -0,0 +1,80 @@
+---
+name: library-logger-warn
+group: api
+category: facade
+update-time: 20260613
+description: Emit a warn-level record through a LibraryLogger facade using the warning severity shortcut.
+key-word:
+    - library
+    - facade
+    - warn
+    - public
+---
+
+## Library-logger-warn
+
+Emit a warn-level record through the library-facing sync logger. This is the convenience wrapper for `log(Level::Warn, ...)` on `LibraryLogger[S]`.
+
+### Interface
+
+```moonbit
+pub fn[S : Sink] LibraryLogger::warn(
+  self : LibraryLogger[S],
+  message : String,
+  fields~ : Array[Field] = [],
+) -> Unit {
+```
+
+#### input
+
+- `self : LibraryLogger[S]` - Library-facing logger that should emit the warning record.
+- `message : String` - Warning message text.
+- `fields : Array[Field]` - Optional structured fields attached to the record.
+
+#### output
+
+- `Unit` - No return value. The record is handled according to the current threshold and wrapped sink pipeline.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper delegates to `log(Level::Warn, ...)` on the wrapped logger.
+- Warning records are useful for abnormal but non-fatal conditions.
+- Per-call target override is not exposed here; use `log(...)` when that is required.
+- All logger wrappers still participate normally in the write path.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Signal A Recoverable Library Problem
+
+When an operation degraded but still continued:
+```moonbit
+logger.warn("cache miss ratio increased")
+```
+
+In this example, the event is elevated above normal information without being treated as a hard failure.
+
+#### When Attach Structured Warning Context
+
+When a warning should include machine-readable detail:
+```moonbit
+logger.warn("retry scheduled", fields=[field("attempt", "3")])
+```
+
+In this example, the warning remains easy to filter and inspect later.
+
+### Error Case
+
+e.g.:
+- If the logger minimum level is above `Warn`, the call returns without writing a record.
+
+- If a target override is needed at this call site, use `log(...)` instead of this shortcut.
+
+### Notes
+
+1. Use this helper for degraded or suspicious states that do not stop execution.
+
+2. Warning logs are often a practical signal threshold for alerting or separate routing.