📝 Add file state export API docs

2026-05-30 23:52:27 +00:00 · 2026-05-12 15:05:58 +08:00
parent bab9864f1f
commit 694414e068
6 changed files with 447 additions and 0 deletions
@@ -0,0 +1,74 @@
+---
+name: runtime-file-state-to-json
+group: api
+category: runtime
+update-time: 20260512
+description: Convert RuntimeFileState into a JSON value that combines file status with outer queue runtime metrics.
+key-word:
+    - runtime
+    - file
+    - state
+    - public
+---
+
+## Runtime-file-state-to-json
+
+Convert `RuntimeFileState` into a `JsonValue`. This helper exports both file sink status and outer queue metrics for queued file runtime diagnostics.
+
+### Interface
+
+```moonbit
+pub fn runtime_file_state_to_json(state : RuntimeFileState) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `state : RuntimeFileState` - Combined file and queue runtime snapshot.
+
+#### output
+
+- `JsonValue` - Structured JSON representation of the runtime file state.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The output includes `file`, `queued`, `pending_count`, and `dropped_count`.
+- `file` is itself exported as a nested file sink state object.
+- This helper is richer than `file_sink_state_to_json(...)` because it also carries queue wrapping context.
+- It is useful for `ConfiguredLogger::file_runtime_state()` and similar queued-file diagnostics flows.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Structured Queued-file Diagnostics
+
+When file and queue status should be exported together:
+```moonbit
+let value = runtime_file_state_to_json(snapshot)
+```
+
+In this example, callers receive a machine-readable combined runtime snapshot.
+
+#### When Need Support Payload Composition
+
+When queued file runtime data should be embedded into a larger JSON object:
+```moonbit
+let payload = runtime_file_state_to_json(state)
+```
+
+In this example, the helper keeps file-plus-queue diagnostics in one reusable JSON value.
+
+### Error Case
+
+e.g.:
+- If `queued=false`, the state still serializes normally with queue counters present.
+
+- If callers need direct text output, `stringify_runtime_file_state(...)` is the better API.
+
+### Notes
+
+1. Use this helper when file and queue runtime context should stay together.
+
+2. It is especially useful for configured queued file loggers.