diff --git a/docs/api/async-logger-build-config-to-json.md b/docs/api/async-logger-build-config-to-json.md new file mode 100644 index 0000000..0bb1214 --- /dev/null +++ b/docs/api/async-logger-build-config-to-json.md @@ -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. diff --git a/docs/api/async-logger-config-to-json.md b/docs/api/async-logger-config-to-json.md new file mode 100644 index 0000000..0aa077b --- /dev/null +++ b/docs/api/async-logger-config-to-json.md @@ -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. diff --git a/docs/api/async-logger-state-to-json.md b/docs/api/async-logger-state-to-json.md new file mode 100644 index 0000000..b87022c --- /dev/null +++ b/docs/api/async-logger-state-to-json.md @@ -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. diff --git a/docs/api/async-runtime-state-to-json.md b/docs/api/async-runtime-state-to-json.md new file mode 100644 index 0000000..10d7745 --- /dev/null +++ b/docs/api/async-runtime-state-to-json.md @@ -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. diff --git a/docs/api/stringify-async-logger-build-config.md b/docs/api/stringify-async-logger-build-config.md new file mode 100644 index 0000000..04823e2 --- /dev/null +++ b/docs/api/stringify-async-logger-build-config.md @@ -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. diff --git a/docs/api/stringify-async-logger-config.md b/docs/api/stringify-async-logger-config.md new file mode 100644 index 0000000..0e9aa69 --- /dev/null +++ b/docs/api/stringify-async-logger-config.md @@ -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. diff --git a/docs/api/stringify-async-logger-state.md b/docs/api/stringify-async-logger-state.md new file mode 100644 index 0000000..61e8d6c --- /dev/null +++ b/docs/api/stringify-async-logger-state.md @@ -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. diff --git a/docs/api/stringify-async-runtime-state.md b/docs/api/stringify-async-runtime-state.md new file mode 100644 index 0000000..001f377 --- /dev/null +++ b/docs/api/stringify-async-runtime-state.md @@ -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.