📝 Add sync config export API docs

docs/api/logger-config-to-json.md

@@ -0,0 +1,97 @@
+---
+name: logger-config-to-json
+group: api
+category: config
+update-time: 20260512
+description: Convert LoggerConfig into a JSON value for export, persistence, or generated config output.
+key-word:
+    - logger
+    - config
+    - json
+    - public
+---
+
+## Logger-config-to-json
+
+Convert a typed `LoggerConfig` into a `JsonValue`. This helper is the structured export path when config should be persisted, inspected, or embedded into larger JSON payloads.
+
+### Interface
+
+```moonbit
+pub fn logger_config_to_json(config : LoggerConfig) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `config : LoggerConfig` - Typed logger configuration.
+
+#### output
+
+- `JsonValue` - JSON representation of the logger config.
+
+---
+
+e.g.:
+```moonbit
+pub fn logger_config_to_json(config : LoggerConfig) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `config : LoggerConfig` - Config to export.
+
+#### output
+
+- `JsonValue` - Structured JSON value.
+
+---
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The output includes `min_level`, `target`, `timestamp`, `sink`, and optional `queue`.
+- Sink export is delegated to `sink_config_to_json(...)`.
+- The result is suitable for downstream JSON composition as well as stringification.
+- Exported JSON follows the stable supported config schema rather than raw internal runtime state.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Generated Config Output
+
+When code constructs config and later exports it:
+```moonbit
+let json = logger_config_to_json(LoggerConfig::new(target="svc"))
+```
+
+In this example, the typed config becomes a structured JSON value.
+
+#### When Need To Embed Logger Config In A Larger Payload
+
+When logger config should be one part of a bigger object:
+```moonbit
+let payload = logger_config_to_json(config)
+```
+
+In this example, the helper avoids re-implementing config serialization by hand.
+
+### Error Case
+
+e.g.:
+- If `queue` is `None`, the exported JSON simply omits the queue field.
+
+- If some sink options are unused by the chosen sink kind, they still follow the supported config export shape rather than a runtime-only interpretation.
+
+### Notes
+
+Notes are here.
+
+1. Use this API when you need a JSON value instead of text output.
+
+2. Use `stringify_logger_config(...)` for immediate string output.
+
+3. This helper complements `parse_logger_config_text(...)` for roundtrip workflows.
+
+4. The output is configuration-oriented, not runtime-state-oriented.

docs/api/queue-config-to-json.md

@@ -0,0 +1,99 @@
+---
+name: queue-config-to-json
+group: api
+category: config
+update-time: 20260512
+description: Convert QueueConfig into a JSON value for export, persistence, or generated config tooling.
+key-word:
+    - queue
+    - config
+    - json
+    - public
+---
+
+## Queue-config-to-json
+
+Convert a typed `QueueConfig` into a `JsonValue`. This helper is the structured export path for synchronous queue wrapper configuration when callers want machine-readable config output.
+
+### Interface
+
+```moonbit
+pub fn queue_config_to_json(queue : QueueConfig) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `queue : QueueConfig` - Queue wrapper configuration created in code or parsed from config text.
+
+#### output
+
+- `JsonValue` - Structured JSON representation of the queue config.
+
+---
+
+e.g.:
+```moonbit
+pub fn queue_config_to_json(queue : QueueConfig) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `queue : QueueConfig` - Queue settings to export.
+
+#### output
+
+- `JsonValue` - JSON-exportable queue object.
+
+---
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The output includes `max_pending` and `overflow`.
+- Overflow is serialized using the supported config labels such as `DropNewest` and `DropOldest`.
+- This helper is intended for config export rather than runtime queue inspection.
+- The JSON shape matches the queue section accepted by `parse_logger_config_text(...)`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Structured Queue Config Export
+
+When queue settings should be embedded into a larger JSON payload:
+```moonbit
+let queue_json = queue_config_to_json(
+  QueueConfig::new(64, overflow=QueueOverflowPolicy::DropOldest),
+)
+```
+
+In this example, callers receive a reusable JSON value instead of a final string.
+
+#### When Need Roundtrip-friendly Config Data
+
+When code generates queue policy and later persists it:
+```moonbit
+let value = queue_config_to_json(QueueConfig::new(16))
+```
+
+In this example, the exported shape stays aligned with the supported parser schema.
+
+### Error Case
+
+e.g.:
+- If `max_pending` is very small, the config still serializes successfully even though runtime drops may happen more often.
+
+- If callers need direct text output instead of a JSON value, they should use `stringify_queue_config(...)` instead.
+
+### Notes
+
+Notes are here.
+
+1. This helper exports config data, not queue runtime metrics.
+
+2. Use this API when downstream code expects `JsonValue`.
+
+3. Pair it with `QueueConfig::new(...)` for code-generated config.
+
+4. The output is suitable for persistence, testing, and generated configuration flows.

docs/api/sink-config-to-json.md

@@ -0,0 +1,97 @@
+---
+name: sink-config-to-json
+group: api
+category: config
+update-time: 20260512
+description: Convert SinkConfig into a JSON value for export and nested logger config serialization.
+key-word:
+    - sink
+    - config
+    - json
+    - public
+---
+
+## Sink-config-to-json
+
+Convert `SinkConfig` into a `JsonValue`. This helper is used directly for sink export and indirectly when exporting `LoggerConfig`.
+
+### Interface
+
+```moonbit
+pub fn sink_config_to_json(config : SinkConfig) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `config : SinkConfig` - Sink config to export.
+
+#### output
+
+- `JsonValue` - JSON representation of the sink configuration.
+
+---
+
+e.g.:
+```moonbit
+pub fn sink_config_to_json(config : SinkConfig) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `config : SinkConfig` - Sink definition.
+
+#### output
+
+- `JsonValue` - Structured JSON sink value.
+
+---
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The output includes `kind`, `path`, `append`, `auto_flush`, and `text_formatter`.
+- `rotation` is only included when present.
+- The exported shape is schema-oriented and shared by larger config export helpers.
+- This helper is especially useful when building larger config payloads manually.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Sink-only Export
+
+When only the sink portion should be emitted:
+```moonbit
+let json = sink_config_to_json(SinkConfig::new(kind=SinkKind::TextConsole))
+```
+
+In this example, sink config can be exported independently of the full logger config.
+
+#### When Compose A Larger JSON Payload
+
+When sink config should be embedded elsewhere:
+```moonbit
+let sink_json = sink_config_to_json(config.sink)
+```
+
+In this example, sink config becomes a structured JSON component.
+
+### Error Case
+
+e.g.:
+- If `rotation` is absent, it is simply omitted from the exported sink config.
+
+- If file-related fields are unused by the sink kind, they are still exported according to the stable config shape.
+
+### Notes
+
+Notes are here.
+
+1. This API is sink-config export only, not runtime sink inspection.
+
+2. Use `stringify_sink_config(...)` for direct string output.
+
+3. This helper is reused by `logger_config_to_json(...)`.
+
+4. It is useful for tooling that needs nested config JSON values.

docs/api/stringify-logger-config.md

@@ -0,0 +1,99 @@
+---
+name: stringify-logger-config
+group: api
+category: config
+update-time: 20260512
+description: Serialize LoggerConfig into compact or pretty JSON text for persistence and diagnostics.
+key-word:
+    - logger
+    - config
+    - stringify
+    - public
+---
+
+## Stringify-logger-config
+
+Serialize `LoggerConfig` into JSON text. This is the easiest way to emit typed logger configuration as a string for persistence, examples, diagnostics, or generated config files.
+
+### Interface
+
+```moonbit
+pub fn stringify_logger_config(config : LoggerConfig, pretty~ : Bool = false) -> String {}
+```
+
+#### input
+
+- `config : LoggerConfig` - Config to serialize.
+- `pretty : Bool` - Whether JSON output should be pretty-printed.
+
+#### output
+
+- `String` - Serialized logger config JSON.
+
+---
+
+e.g.:
+```moonbit
+pub fn stringify_logger_config(config : LoggerConfig, pretty~ : Bool = false) -> String {}
+```
+
+#### input
+
+- `config : LoggerConfig` - Logger config value.
+- `pretty : Bool` - Pretty-print flag.
+
+#### output
+
+- `String` - JSON string.
+
+---
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `pretty=false` produces compact JSON.
+- `pretty=true` produces indented human-readable JSON.
+- This helper builds on top of `logger_config_to_json(...)`.
+- Output is stable and suited for roundtrip config workflows.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Human-readable Generated Config
+
+When config should be printed or checked by humans:
+```moonbit
+println(stringify_logger_config(config, pretty=true))
+```
+
+In this example, the output is readable enough for documentation or operator inspection.
+
+#### When Need Compact Export
+
+When config should be emitted as a compact payload:
+```moonbit
+println(stringify_logger_config(config))
+```
+
+In this example, the config stays small and machine-oriented.
+
+### Error Case
+
+e.g.:
+- If callers need a JSON value rather than text, use `logger_config_to_json(...)` instead.
+
+- If config contains optional `queue=None`, the output omits that section rather than failing.
+
+### Notes
+
+Notes are here.
+
+1. This API is ideal for generated examples and stored config payloads.
+
+2. Use `pretty=true` when readability matters.
+
+3. Pair with `parse_logger_config_text(...)` for roundtrip validation workflows.
+
+4. The output describes config, not runtime sink state.

docs/api/stringify-queue-config.md

@@ -0,0 +1,101 @@
+---
+name: stringify-queue-config
+group: api
+category: config
+update-time: 20260512
+description: Serialize QueueConfig into compact or pretty JSON text for config output and diagnostics.
+key-word:
+    - queue
+    - config
+    - stringify
+    - public
+---
+
+## Stringify-queue-config
+
+Serialize `QueueConfig` into JSON text. This helper is the most direct export path for synchronous queue wrapper configuration when callers want immediate string output.
+
+### Interface
+
+```moonbit
+pub fn stringify_queue_config(queue : QueueConfig, pretty~ : Bool = false) -> String {}
+```
+
+#### input
+
+- `queue : QueueConfig` - Queue wrapper configuration to serialize.
+- `pretty : Bool` - Whether JSON should be pretty-printed.
+
+#### output
+
+- `String` - Serialized JSON text for the queue config.
+
+---
+
+e.g.:
+```moonbit
+pub fn stringify_queue_config(queue : QueueConfig, pretty~ : Bool = false) -> String {}
+```
+
+#### input
+
+- `queue : QueueConfig` - 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 logs and snapshots.
+- `pretty=true` returns indented JSON for human inspection.
+- This helper is built on top of `queue_config_to_json(...)`.
+- The resulting text follows the same queue schema accepted by config parsing flows.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Config Text For Humans
+
+When queue settings should be printed or pasted into docs:
+```moonbit
+println(stringify_queue_config(QueueConfig::new(32), pretty=true))
+```
+
+In this example, the output is formatted for readability.
+
+#### When Need Compact Generated Output
+
+When queue config should stay small:
+```moonbit
+let text = stringify_queue_config(
+  QueueConfig::new(8, overflow=QueueOverflowPolicy::DropNewest),
+)
+```
+
+In this example, compact JSON is returned without extra formatting.
+
+### Error Case
+
+e.g.:
+- If callers need a `JsonValue` for further composition, this API is the wrong layer and `queue_config_to_json(...)` should be used instead.
+
+- If queue policy is too aggressive for workload burst size, serialization still succeeds because this helper only exports config.
+
+### Notes
+
+Notes are here.
+
+1. This API is convenient for generated config text and tests.
+
+2. Use `pretty=true` when the output is intended for humans.
+
+3. The compact default is better for snapshots and transport.
+
+4. This helper belongs to synchronous configured queue wrapping, not `bitlogger_async`.

docs/api/stringify-sink-config.md

@@ -0,0 +1,99 @@
+---
+name: stringify-sink-config
+group: api
+category: config
+update-time: 20260512
+description: Serialize SinkConfig into compact or pretty JSON text.
+key-word:
+    - sink
+    - config
+    - stringify
+    - public
+---
+
+## Stringify-sink-config
+
+Serialize `SinkConfig` into JSON text. This helper is the direct text output path for sink configuration when examples, tooling, or diagnostics want the sink section by itself.
+
+### Interface
+
+```moonbit
+pub fn stringify_sink_config(config : SinkConfig, pretty~ : Bool = false) -> String {}
+```
+
+#### input
+
+- `config : SinkConfig` - Sink config to serialize.
+- `pretty : Bool` - Whether output should be pretty-printed.
+
+#### output
+
+- `String` - Serialized sink config JSON.
+
+---
+
+e.g.:
+```moonbit
+pub fn stringify_sink_config(config : SinkConfig, pretty~ : Bool = false) -> String {}
+```
+
+#### input
+
+- `config : SinkConfig` - Sink config value.
+- `pretty : Bool` - Pretty-print option.
+
+#### output
+
+- `String` - JSON string.
+
+---
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `pretty=false` gives compact JSON.
+- `pretty=true` gives indented output.
+- This helper builds on top of `sink_config_to_json(...)`.
+- It is useful when examples or generated docs want to show only sink-specific config.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Human-readable Sink Config
+
+When sink config should be printed for review:
+```moonbit
+println(stringify_sink_config(SinkConfig::new(kind=SinkKind::File, path="app.log"), pretty=true))
+```
+
+In this example, the sink section is easy to inspect visually.
+
+#### When Need Compact Embedded Output
+
+When sink config should be emitted in a compact form:
+```moonbit
+println(stringify_sink_config(config.sink))
+```
+
+In this example, the helper provides a ready-made machine-oriented representation.
+
+### Error Case
+
+e.g.:
+- If callers need a JSON value instead of text, use `sink_config_to_json(...)` instead.
+
+- If optional `rotation` is absent, the serialized sink config simply omits that field.
+
+### Notes
+
+Notes are here.
+
+1. This helper is convenient for documentation, examples, and generated config output.
+
+2. Use `pretty=true` when humans are the primary audience.
+
+3. The output describes the config schema, not live runtime sink state.
+
+4. This API pairs naturally with `SinkConfig::new(...)` and `sink_config_to_json(...)`.

docs/api/stringify-text-formatter-config.md

@@ -0,0 +1,104 @@
+---
+name: stringify-text-formatter-config
+group: api
+category: config
+update-time: 20260512
+description: Serialize TextFormatterConfig into compact or pretty JSON text for export and diagnostics.
+key-word:
+    - formatter
+    - config
+    - stringify
+    - public
+---
+
+## Stringify-text-formatter-config
+
+Serialize `TextFormatterConfig` into JSON text. This helper is the highest-level export path when formatter config should be printed, logged, or copied as config text.
+
+### Interface
+
+```moonbit
+pub fn stringify_text_formatter_config(
+  config : TextFormatterConfig,
+  pretty~ : Bool = false,
+) -> String {}
+```
+
+#### input
+
+- `config : TextFormatterConfig` - Formatter config to serialize.
+- `pretty : Bool` - Whether JSON should be pretty-printed.
+
+#### output
+
+- `String` - Serialized JSON text for the formatter config.
+
+---
+
+e.g.:
+```moonbit
+pub fn stringify_text_formatter_config(config : TextFormatterConfig, pretty~ : Bool = false) -> String {}
+```
+
+#### input
+
+- `config : TextFormatterConfig` - 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 humans.
+- This helper is built on top of `text_formatter_config_to_json(...)`.
+- The output preserves the supported formatter config schema instead of any runtime-only formatter instance details.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Human-readable Formatter Config
+
+When formatter settings should be inspected during setup:
+```moonbit
+println(stringify_text_formatter_config(default_text_formatter_config(), pretty=true))
+```
+
+In this example, the pretty output is suitable for diagnostics or docs.
+
+#### When Need Compact Export Text
+
+When generated config should stay small:
+```moonbit
+let text = stringify_text_formatter_config(
+  TextFormatterConfig::new(show_fields=false),
+)
+```
+
+In this example, compact JSON is returned for storage or transport.
+
+### Error Case
+
+e.g.:
+- If callers need a JSON value for composition, they should use `text_formatter_config_to_json(...)` instead.
+
+- If `style_tags` is empty, the serialized text omits that field rather than forcing an empty object.
+
+### Notes
+
+Notes are here.
+
+1. This helper is useful 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 API exports config data, not formatted records.

docs/api/text-formatter-config-to-json.md

@@ -0,0 +1,99 @@
+---
+name: text-formatter-config-to-json
+group: api
+category: config
+update-time: 20260512
+description: Convert TextFormatterConfig into a JSON value for formatter export, persistence, or generated config output.
+key-word:
+    - formatter
+    - config
+    - json
+    - public
+---
+
+## Text-formatter-config-to-json
+
+Convert a typed `TextFormatterConfig` into a `JsonValue`. This helper exports formatter toggles, separators, color settings, markup behavior, and optional style tags in a machine-readable form.
+
+### Interface
+
+```moonbit
+pub fn text_formatter_config_to_json(config : TextFormatterConfig) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `config : TextFormatterConfig` - Formatter configuration to export.
+
+#### output
+
+- `JsonValue` - Structured JSON representation of the formatter config.
+
+---
+
+e.g.:
+```moonbit
+pub fn text_formatter_config_to_json(config : TextFormatterConfig) -> @json_parser.JsonValue {}
+```
+
+#### input
+
+- `config : TextFormatterConfig` - Typed formatter config.
+
+#### output
+
+- `JsonValue` - JSON-exportable formatter object.
+
+---
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The output includes visibility flags, separators, template, color settings, and markup settings.
+- `style_tags` is exported only when the map is not empty.
+- Enum-like formatter options are serialized using their stable label strings.
+- The JSON shape matches the formatter section accepted by config parsing.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Structured Formatter Export
+
+When formatter config should be embedded inside a larger config object:
+```moonbit
+let value = text_formatter_config_to_json(TextFormatterConfig::new(show_target=false))
+```
+
+In this example, callers can compose the JSON value without re-implementing serialization.
+
+#### When Need To Persist Formatter Settings
+
+When generated formatter policy should be stored or inspected:
+```moonbit
+let formatter_json = text_formatter_config_to_json(
+  TextFormatterConfig::new(separator=" | ", template="[{level}] {message}"),
+)
+```
+
+In this example, the config becomes transport-friendly structured data.
+
+### Error Case
+
+e.g.:
+- If `style_tags` is empty, the field is omitted instead of being emitted as an empty object.
+
+- If callers need immediate text output rather than a JSON value, they should use `stringify_text_formatter_config(...)` instead.
+
+### Notes
+
+Notes are here.
+
+1. This helper exports formatter configuration, not rendered log output.
+
+2. Use it when downstream code expects `JsonValue`.
+
+3. Pair it with `TextFormatterConfig::new(...)` for code-generated formatter policies.
+
+4. The output is compatible with config roundtrip workflows.