From f824cbfa6898aa8e4f87f20d13935f4dd876d1e7 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sun, 14 Jun 2026 01:50:30 +0800 Subject: [PATCH] :memo: clarify async state export docs --- docs/api/async-logger-state-to-json.md | 1 + docs/api/stringify-async-logger-state.md | 3 +++ docs/api/stringify-async-runtime-state.md | 3 +++ 3 files changed, 7 insertions(+) diff --git a/docs/api/async-logger-state-to-json.md b/docs/api/async-logger-state-to-json.md index 0387bbd..cac8a28 100644 --- a/docs/api/async-logger-state-to-json.md +++ b/docs/api/async-logger-state-to-json.md @@ -36,6 +36,7 @@ Detailed rules explaining key parameters and behaviors - The JSON includes runtime mode, worker support, queue counters, lifecycle flags, last error, and flush policy. - The top-level fields are `runtime`, `pending_count`, `dropped_count`, `is_closed`, `is_running`, `has_failed`, `last_error`, and `flush_policy`. - The nested `runtime` field reuses `async_runtime_state_to_json(...)`, and `flush_policy` is serialized with the canonical labels `Never`, `Batch`, or `Shutdown`. +- The public helper returns the same internal JSON snapshot shape used by `stringify_async_logger_state(...)`, so both export paths stay aligned without duplicate field assembly logic. - 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. diff --git a/docs/api/stringify-async-logger-state.md b/docs/api/stringify-async-logger-state.md index e5ec0e4..0aa9742 100644 --- a/docs/api/stringify-async-logger-state.md +++ b/docs/api/stringify-async-logger-state.md @@ -40,6 +40,7 @@ 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(...)`. +- Internally it stringifies the same JSON snapshot shape returned by the public export helper, using `@json_parser.stringify(...)` or `@json_parser.stringify_pretty(value, 2)`. - The compact form matches snapshots such as `{"runtime":{"mode":"native_worker","background_worker":true},"pending_count":0,...}`. - String output is convenient for logs, CLI output, and startup diagnostics. @@ -78,3 +79,5 @@ e.g.: 2. The compact output shape is already locked by the async runtime snapshot tests, so it is suitable for stable diagnostics and assertions. +3. Use `async_logger_state_to_json(...)` when the next consumer still needs a `JsonValue` for composition before final stringification. + diff --git a/docs/api/stringify-async-runtime-state.md b/docs/api/stringify-async-runtime-state.md index d4bf52a..b551b66 100644 --- a/docs/api/stringify-async-runtime-state.md +++ b/docs/api/stringify-async-runtime-state.md @@ -40,6 +40,7 @@ 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(...)`. +- Internally it serializes the `JsonValue` result with `@json_parser.stringify(...)` or `@json_parser.stringify_pretty(value, 2)`, so the text form stays aligned with the structured runtime-state export helper. - The compact form matches the tested snapshot shape such as `{"mode":"native_worker","background_worker":true}`. - It is well-suited for startup banners, support reports, and target capability logs. @@ -78,3 +79,5 @@ e.g.: 2. This helper is the direct text form of the same two-field runtime snapshot exported by `async_runtime_state_to_json(...)`. +3. Use `async_runtime_state_to_json(...)` when the next consumer still needs a `JsonValue` for composition before final stringification. +