From 0b93af92617c7e2e0b00485573c56adcdf419152 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Tue, 12 May 2026 13:08:15 +0800 Subject: [PATCH] :memo: Add sync config export API docs --- docs/api/logger-config-to-json.md | 97 ++++++++++++++++++ docs/api/queue-config-to-json.md | 99 +++++++++++++++++++ docs/api/sink-config-to-json.md | 97 ++++++++++++++++++ docs/api/stringify-logger-config.md | 99 +++++++++++++++++++ docs/api/stringify-queue-config.md | 101 +++++++++++++++++++ docs/api/stringify-sink-config.md | 99 +++++++++++++++++++ docs/api/stringify-text-formatter-config.md | 104 ++++++++++++++++++++ docs/api/text-formatter-config-to-json.md | 99 +++++++++++++++++++ 8 files changed, 795 insertions(+) create mode 100644 docs/api/logger-config-to-json.md create mode 100644 docs/api/queue-config-to-json.md create mode 100644 docs/api/sink-config-to-json.md create mode 100644 docs/api/stringify-logger-config.md create mode 100644 docs/api/stringify-queue-config.md create mode 100644 docs/api/stringify-sink-config.md create mode 100644 docs/api/stringify-text-formatter-config.md create mode 100644 docs/api/text-formatter-config-to-json.md diff --git a/docs/api/logger-config-to-json.md b/docs/api/logger-config-to-json.md new file mode 100644 index 0000000..81cc431 --- /dev/null +++ b/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. diff --git a/docs/api/queue-config-to-json.md b/docs/api/queue-config-to-json.md new file mode 100644 index 0000000..6168e06 --- /dev/null +++ b/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. diff --git a/docs/api/sink-config-to-json.md b/docs/api/sink-config-to-json.md new file mode 100644 index 0000000..edae084 --- /dev/null +++ b/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. diff --git a/docs/api/stringify-logger-config.md b/docs/api/stringify-logger-config.md new file mode 100644 index 0000000..fc6f3a2 --- /dev/null +++ b/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. diff --git a/docs/api/stringify-queue-config.md b/docs/api/stringify-queue-config.md new file mode 100644 index 0000000..aaf3e84 --- /dev/null +++ b/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`. diff --git a/docs/api/stringify-sink-config.md b/docs/api/stringify-sink-config.md new file mode 100644 index 0000000..f865762 --- /dev/null +++ b/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(...)`. diff --git a/docs/api/stringify-text-formatter-config.md b/docs/api/stringify-text-formatter-config.md new file mode 100644 index 0000000..adde7c8 --- /dev/null +++ b/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. diff --git a/docs/api/text-formatter-config-to-json.md b/docs/api/text-formatter-config-to-json.md new file mode 100644 index 0000000..4b09c07 --- /dev/null +++ b/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.