📝 Add async state and config export API docs

2026-05-30 15:42:25 +00:00 · 2026-05-12 13:08:27 +08:00
parent 3dbf848a53
commit 8dbadd5938
8 changed files with 807 additions and 0 deletions
@@ -0,0 +1,104 @@
+---
+name: async-logger-build-config-to-json
+group: api
+category: async
+update-time: 20260512
+description: Convert AsyncLoggerBuildConfig into a JSON value for exporting complete async logger build settings.
+key-word:
+    - async
+    - build
+    - config
+    - public
+---
+
+## Async-logger-build-config-to-json
+
+Convert `AsyncLoggerBuildConfig` into a `JsonValue`. This helper exports both the base synchronous logger config and the async runtime config as one structured payload.
+
+### Interface
+
+```moonbit
+pub fn async_logger_build_config_to_json(
+  config : AsyncLoggerBuildConfig,
+) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `config : AsyncLoggerBuildConfig` - Complete build config used by async logger builders.
+
+#### output
+
+- `JsonValue` - Structured JSON representation of the full async build config.
+
+---
+
+e.g.:
+```moonbit
+pub fn async_logger_build_config_to_json(config : AsyncLoggerBuildConfig) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `config : AsyncLoggerBuildConfig` - Combined logger and async config.
+
+#### output
+
+- `JsonValue` - JSON-exportable build payload.
+
+---
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The output always includes `logger` and `async_config`.
+- Logger export is delegated to `@bitlogger.logger_config_to_json(...)`.
+- Async export is delegated to `async_logger_config_to_json(...)`.
+- This helper is useful when generated setup should preserve both sink/logger behavior and async runtime behavior together.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Structured Export Of Full Async Setup
+
+When a tool or test needs one object describing the whole async logger build:
+```moonbit
+let payload = async_logger_build_config_to_json(
+  AsyncLoggerBuildConfig::new(
+    logger=@bitlogger.LoggerConfig::new(target="svc"),
+    async_config=AsyncLoggerConfig::new(max_pending=64),
+  ),
+)
+```
+
+In this example, both layers of configuration are exported together.
+
+#### When Need Roundtrip-friendly Build Config Data
+
+When generated build config should later be parsed again:
+```moonbit
+let value = async_logger_build_config_to_json(AsyncLoggerBuildConfig::new())
+```
+
+In this example, the resulting JSON matches the supported async build config shape.
+
+### Error Case
+
+e.g.:
+- If callers only need the async runtime section, this API is broader than necessary and `async_logger_config_to_json(...)` should be used instead.
+
+- If callers want direct text output, they should use `stringify_async_logger_build_config(...)` instead.
+
+### Notes
+
+Notes are here.
+
+1. This helper exports complete build settings, not runtime state.
+
+2. It is useful for generated configs, test fixtures, and setup introspection.
+
+3. The output combines `LoggerConfig` and `AsyncLoggerConfig` without flattening them.
+
+4. This API complements `parse_async_logger_build_config_text(...)` in roundtrip workflows.
@@ -0,0 +1,99 @@
+---
+name: async-logger-config-to-json
+group: api
+category: async
+update-time: 20260512
+description: Convert AsyncLoggerConfig into a JSON value for export, persistence, or generated async config output.
+key-word:
+    - async
+    - config
+    - json
+    - public
+---
+
+## Async-logger-config-to-json
+
+Convert a typed `AsyncLoggerConfig` into a `JsonValue`. This helper exports async queue capacity, overflow policy, batch sizing, linger timing, and flush behavior in a structured form.
+
+### Interface
+
+```moonbit
+pub fn async_logger_config_to_json(config : AsyncLoggerConfig) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `config : AsyncLoggerConfig` - Async logger runtime config to export.
+
+#### output
+
+- `JsonValue` - Structured JSON representation of the async config.
+
+---
+
+e.g.:
+```moonbit
+pub fn async_logger_config_to_json(config : AsyncLoggerConfig) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `config : AsyncLoggerConfig` - Typed async config.
+
+#### output
+
+- `JsonValue` - JSON-exportable async configuration.
+
+---
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The output includes `max_pending`, `max_batch`, `linger_ms`, `overflow`, and `flush`.
+- Policy fields are serialized using the stable labels accepted by the config parser.
+- This helper exports effective typed config after constructor normalization has already happened.
+- The JSON shape matches the `async_config` section used by async build config parsing.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Structured Async Config Export
+
+When async runtime policy should be embedded in a larger JSON payload:
+```moonbit
+let async_json = async_logger_config_to_json(
+  AsyncLoggerConfig::new(max_pending=128, max_batch=8),
+)
+```
+
+In this example, callers receive a machine-readable config value.
+
+#### When Need Roundtrip-friendly Async Settings
+
+When code generates async policy and later persists it:
+```moonbit
+let value = async_logger_config_to_json(AsyncLoggerConfig::new(flush=AsyncFlushPolicy::Batch))
+```
+
+In this example, the exported JSON stays aligned with parser expectations.
+
+### Error Case
+
+e.g.:
+- If `max_batch` or `linger_ms` were normalized during construction, the exported JSON reflects the normalized values rather than the original invalid inputs.
+
+- If callers want direct text output instead of a JSON value, they should use `stringify_async_logger_config(...)` instead.
+
+### Notes
+
+Notes are here.
+
+1. This helper exports config data, not runtime counters or failure state.
+
+2. Use it when downstream code expects `JsonValue`.
+
+3. Pair it with `AsyncLoggerConfig::new(...)` for code-generated config.
+
+4. The output is suitable for persistence, tests, and generated async setup flows.
@@ -0,0 +1,98 @@
+---
+name: async-logger-state-to-json
+group: api
+category: async
+update-time: 20260512
+description: Convert an AsyncLoggerState snapshot into a JSON value for diagnostics and transport.
+key-word:
+    - async
+    - state
+    - json
+    - public
+---
+
+## Async-logger-state-to-json
+
+Convert `AsyncLoggerState` into a `JsonValue`. This helper is the structured export path for async logger runtime snapshots when callers want machine-readable diagnostics instead of a plain string.
+
+### Interface
+
+```moonbit
+pub fn async_logger_state_to_json(state : AsyncLoggerState) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `state : AsyncLoggerState` - Snapshot produced by `AsyncLogger::state()`.
+
+#### output
+
+- `JsonValue` - Structured JSON representation of the async logger snapshot.
+
+---
+
+e.g.:
+```moonbit
+pub fn async_logger_state_to_json(state : AsyncLoggerState) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `state : AsyncLoggerState` - Async logger runtime snapshot.
+
+#### output
+
+- `JsonValue` - JSON-exportable state value.
+
+---
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The JSON includes runtime mode, worker support, queue counters, lifecycle flags, last error, and flush policy.
+- This helper is suitable for health endpoints, diagnostics payloads, and custom serialization flows.
+- It shares the same stable field names used by `stringify_async_logger_state(...)`.
+- The state must already have been captured before serialization.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Machine-readable Diagnostics
+
+When the snapshot should be embedded into a JSON payload:
+```moonbit
+let state_json = async_logger_state_to_json(logger.state())
+```
+
+In this example, callers receive a structured value that can be composed into larger JSON objects.
+
+#### When Need A Snapshot Before Custom Stringify
+
+When another serializer or pipeline expects a JSON value:
+```moonbit
+let payload = async_logger_state_to_json(logger.state())
+println(@json_parser.stringify(payload))
+```
+
+In this example, the helper stays useful even outside the built-in stringify wrapper.
+
+### Error Case
+
+e.g.:
+- If the snapshot contains no error, `last_error` is serialized as an empty string.
+
+- If the queue is empty, `pending_count` and `dropped_count` are still serialized normally as numeric values.
+
+### Notes
+
+Notes are here.
+
+1. Use this API when downstream code wants a JSON value rather than a ready-made string.
+
+2. Pair it with `AsyncLogger::state()` to capture the snapshot first.
+
+3. Prefer `stringify_async_logger_state(...)` when direct string output is enough.
+
+4. This helper is transport-oriented, not control-oriented.
@@ -0,0 +1,97 @@
+---
+name: async-runtime-state-to-json
+group: api
+category: async
+update-time: 20260512
+description: Convert AsyncRuntimeState into a JSON value for runtime capability and mode diagnostics.
+key-word:
+    - async
+    - state
+    - json
+    - public
+---
+
+## Async-runtime-state-to-json
+
+Convert `AsyncRuntimeState` into a `JsonValue`. This helper exports the async runtime mode and background worker capability in a structured form.
+
+### Interface
+
+```moonbit
+pub fn async_runtime_state_to_json(state : AsyncRuntimeState) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `state : AsyncRuntimeState` - Runtime capability snapshot, usually produced by `async_runtime_state()`.
+
+#### output
+
+- `JsonValue` - Structured JSON representation of the runtime state.
+
+---
+
+e.g.:
+```moonbit
+pub fn async_runtime_state_to_json(state : AsyncRuntimeState) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `state : AsyncRuntimeState` - Runtime snapshot to export.
+
+#### output
+
+- `JsonValue` - JSON-exportable state object.
+
+---
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The output includes `mode` and `background_worker`.
+- `mode` is serialized through `async_runtime_mode_label(...)`.
+- This helper focuses on runtime capabilities rather than queue counters or logger lifecycle flags.
+- The exported JSON is suitable for diagnostics endpoints and startup environment checks.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Structured Runtime Capability Checks
+
+When startup diagnostics should include async runtime capability data:
+```moonbit
+let runtime_json = async_runtime_state_to_json(async_runtime_state())
+```
+
+In this example, the runtime snapshot becomes a reusable JSON value.
+
+#### When Need To Embed Runtime State In A Larger Payload
+
+When async support should be one field in a bigger diagnostics object:
+```moonbit
+let payload = async_runtime_state_to_json(state)
+```
+
+In this example, callers can reuse the exported object directly.
+
+### Error Case
+
+e.g.:
+- If callers expect logger queue counters or failure status, this API is too narrow and `async_logger_state_to_json(...)` should be used instead.
+
+- If the runtime is in compatibility mode, the helper still serializes normally using the matching mode label.
+
+### Notes
+
+Notes are here.
+
+1. This helper exports runtime capability state, not logger workload state.
+
+2. Use it with `async_runtime_state()` for a fresh snapshot.
+
+3. Prefer `stringify_async_runtime_state(...)` when immediate text output is enough.
+
+4. The output is useful for environment diagnostics across targets.
@@ -0,0 +1,104 @@
+---
+name: stringify-async-logger-build-config
+group: api
+category: async
+update-time: 20260512
+description: Serialize AsyncLoggerBuildConfig into compact or pretty JSON text for export and diagnostics.
+key-word:
+    - async
+    - build
+    - stringify
+    - public
+---
+
+## Stringify-async-logger-build-config
+
+Serialize `AsyncLoggerBuildConfig` into JSON text. This helper is the most direct export path when a full async logger setup should be printed, logged, or stored as JSON text.
+
+### Interface
+
+```moonbit
+pub fn stringify_async_logger_build_config(
+  config : AsyncLoggerBuildConfig,
+  pretty~ : Bool = false,
+) -> String {}
+```
+
+#### input
+
+- `config : AsyncLoggerBuildConfig` - Full async logger build config to serialize.
+- `pretty : Bool` - Whether JSON should be pretty-printed.
+
+#### output
+
+- `String` - Serialized JSON text for the full build config.
+
+---
+
+e.g.:
+```moonbit
+pub fn stringify_async_logger_build_config(config : AsyncLoggerBuildConfig, pretty~ : Bool = false) -> String {}
+```
+
+#### input
+
+- `config : AsyncLoggerBuildConfig` - Build config to stringify.
+- `pretty : Bool` - Pretty-print flag.
+
+#### output
+
+- `String` - JSON text.
+
+---
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `pretty=false` returns compact JSON.
+- `pretty=true` returns indented JSON for human inspection.
+- This helper is built on top of `async_logger_build_config_to_json(...)`.
+- The output keeps `logger` and `async_config` as separate sections, matching supported parser input.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Human-readable Full Async Setup
+
+When both logger and async policy should be inspected together:
+```moonbit
+println(stringify_async_logger_build_config(AsyncLoggerBuildConfig::new(), pretty=true))
+```
+
+In this example, the full build configuration is rendered as readable JSON.
+
+#### When Need Compact Generated Build Config
+
+When config text should stay small for snapshots or transport:
+```moonbit
+let text = stringify_async_logger_build_config(
+  AsyncLoggerBuildConfig::new(async_config=AsyncLoggerConfig::new(max_batch=4)),
+)
+```
+
+In this example, compact JSON is returned without extra formatting.
+
+### Error Case
+
+e.g.:
+- If callers need a `JsonValue` for further composition, they should use `async_logger_build_config_to_json(...)` instead.
+
+- If only one layer of config is required, this helper may be broader than necessary.
+
+### Notes
+
+Notes are here.
+
+1. This API exports build config data, not runtime logger diagnostics.
+
+2. Use `pretty=true` for docs, debugging, and support output.
+
+3. Compact mode is better for machine-oriented storage.
+
+4. This helper is useful when generated async setup should be inspected as one payload.
@@ -0,0 +1,101 @@
+---
+name: stringify-async-logger-config
+group: api
+category: async
+update-time: 20260512
+description: Serialize AsyncLoggerConfig into compact or pretty JSON text for export and diagnostics.
+key-word:
+    - async
+    - config
+    - stringify
+    - public
+---
+
+## Stringify-async-logger-config
+
+Serialize `AsyncLoggerConfig` into JSON text. This helper is the most direct output path when async runtime policy should be logged, printed, or copied as config text.
+
+### Interface
+
+```moonbit
+pub fn stringify_async_logger_config(config : AsyncLoggerConfig, pretty~ : Bool = false) -> String {}
+```
+
+#### input
+
+- `config : AsyncLoggerConfig` - Async config to serialize.
+- `pretty : Bool` - Whether JSON should be pretty-printed.
+
+#### output
+
+- `String` - Serialized JSON text for the async config.
+
+---
+
+e.g.:
+```moonbit
+pub fn stringify_async_logger_config(config : AsyncLoggerConfig, pretty~ : Bool = false) -> String {}
+```
+
+#### input
+
+- `config : AsyncLoggerConfig` - Config to stringify.
+- `pretty : Bool` - Pretty-print flag.
+
+#### output
+
+- `String` - JSON text.
+
+---
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `pretty=false` returns compact JSON suitable for transport and snapshots.
+- `pretty=true` returns indented JSON for humans.
+- This helper is built on top of `async_logger_config_to_json(...)`.
+- The exported text follows the supported async config schema rather than internal queue implementation details.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Human-readable Async Config
+
+When async policy should be printed during startup or testing:
+```moonbit
+println(stringify_async_logger_config(AsyncLoggerConfig::new(max_pending=32), pretty=true))
+```
+
+In this example, the config is emitted in readable JSON.
+
+#### When Need Compact Generated Config Text
+
+When async settings should stay small:
+```moonbit
+let text = stringify_async_logger_config(
+  AsyncLoggerConfig::new(flush=AsyncFlushPolicy::Shutdown),
+)
+```
+
+In this example, compact JSON is returned without extra formatting.
+
+### Error Case
+
+e.g.:
+- If callers need a `JsonValue` for composition, they should use `async_logger_config_to_json(...)` instead.
+
+- If invalid constructor inputs were normalized earlier, the resulting text contains the normalized config values.
+
+### Notes
+
+Notes are here.
+
+1. This API is convenient for config snapshots, examples, and tests.
+
+2. Use `pretty=true` when readability matters.
+
+3. Compact mode is a better default for machine-oriented output.
+
+4. This helper exports async config data, not runtime logger state.
@@ -0,0 +1,102 @@
+---
+name: stringify-async-logger-state
+group: api
+category: async
+update-time: 20260512
+description: Serialize AsyncLoggerState into compact or pretty JSON text for logs and diagnostics.
+key-word:
+    - async
+    - stringify
+    - state
+    - public
+---
+
+## Stringify-async-logger-state
+
+Serialize `AsyncLoggerState` into JSON text. This is the highest-level diagnostic export helper for async logger snapshots when callers want immediate text output.
+
+### Interface
+
+```moonbit
+pub fn stringify_async_logger_state(
+  state : AsyncLoggerState,
+  pretty~ : Bool = false,
+) -> String {}
+```
+
+#### input
+
+- `state : AsyncLoggerState` - Snapshot produced by `AsyncLogger::state()`.
+- `pretty : Bool` - Whether JSON should be pretty-printed.
+
+#### output
+
+- `String` - JSON text for the async logger snapshot.
+
+---
+
+e.g.:
+```moonbit
+pub fn stringify_async_logger_state(state : AsyncLoggerState, pretty~ : Bool = false) -> String {}
+```
+
+#### input
+
+- `state : AsyncLoggerState` - Snapshot to serialize.
+- `pretty : Bool` - Pretty-print flag.
+
+#### output
+
+- `String` - Serialized JSON text.
+
+---
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `pretty=false` returns compact JSON.
+- `pretty=true` returns indented JSON suitable for human diagnostics.
+- This helper is built on top of `async_logger_state_to_json(...)`.
+- String output is convenient for logs, CLI output, and startup diagnostics.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Human-readable Diagnostics
+
+When logger state should be printed for humans:
+```moonbit
+println(stringify_async_logger_state(logger.state(), pretty=true))
+```
+
+In this example, the pretty output is suitable for startup or incident diagnostics.
+
+#### When Need Compact Structured Logs
+
+When snapshot text should stay small:
+```moonbit
+println(stringify_async_logger_state(logger.state()))
+```
+
+In this example, compact JSON is emitted without extra formatting logic.
+
+### Error Case
+
+e.g.:
+- If the snapshot contains an empty `last_error`, it is still included as an empty string in the serialized output.
+
+- If callers need a JSON value instead of text, they should use `async_logger_state_to_json(...)` instead.
+
+### Notes
+
+Notes are here.
+
+1. This API is the most convenient direct output path for async logger snapshots.
+
+2. Use `pretty=true` for humans and the default compact mode for machine-oriented logs.
+
+3. Pair with `AsyncLogger::state()` to capture a consistent point-in-time snapshot.
+
+4. This helper is ideal for startup, shutdown, and failure reporting.
@@ -0,0 +1,102 @@
+---
+name: stringify-async-runtime-state
+group: api
+category: async
+update-time: 20260512
+description: Serialize AsyncRuntimeState into compact or pretty JSON text for diagnostics and startup reporting.
+key-word:
+    - async
+    - state
+    - stringify
+    - public
+---
+
+## Stringify-async-runtime-state
+
+Serialize `AsyncRuntimeState` into JSON text. This helper is the most direct reporting path for async runtime mode and background worker capability.
+
+### Interface
+
+```moonbit
+pub fn stringify_async_runtime_state(
+  state : AsyncRuntimeState,
+  pretty~ : Bool = false,
+) -> String {}
+```
+
+#### input
+
+- `state : AsyncRuntimeState` - Runtime capability snapshot to serialize.
+- `pretty : Bool` - Whether JSON should be pretty-printed.
+
+#### output
+
+- `String` - Serialized JSON text for the runtime state.
+
+---
+
+e.g.:
+```moonbit
+pub fn stringify_async_runtime_state(state : AsyncRuntimeState, pretty~ : Bool = false) -> String {}
+```
+
+#### input
+
+- `state : AsyncRuntimeState` - State to stringify.
+- `pretty : Bool` - Pretty-print flag.
+
+#### output
+
+- `String` - JSON text.
+
+---
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `pretty=false` returns compact JSON.
+- `pretty=true` returns indented JSON for human diagnostics.
+- This helper is built on top of `async_runtime_state_to_json(...)`.
+- It is well-suited for startup banners, support reports, and target capability logs.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Human-readable Runtime Diagnostics
+
+When capability information should be printed during startup:
+```moonbit
+println(stringify_async_runtime_state(async_runtime_state(), pretty=true))
+```
+
+In this example, the runtime state is emitted in a readable form.
+
+#### When Need Compact Capability Logs
+
+When runtime info should stay small in structured logs:
+```moonbit
+let text = stringify_async_runtime_state(async_runtime_state())
+```
+
+In this example, compact JSON is returned without extra formatting.
+
+### Error Case
+
+e.g.:
+- If callers need a JSON value rather than text, they should use `async_runtime_state_to_json(...)` instead.
+
+- If more complete async logger diagnostics are required, this helper should be replaced with `stringify_async_logger_state(...)`.
+
+### Notes
+
+Notes are here.
+
+1. This API reports runtime capability state only.
+
+2. `pretty=true` is more suitable for humans and support output.
+
+3. The compact default is better for transport and structured logging.
+
+4. This helper is useful when comparing target-specific async runtime behavior.