📝 document sync config model aliases

docs/api/index.md

@@ -80,6 +80,7 @@ BitLogger API navigation.
 - [style-markup-mode-label.md](./style-markup-mode-label.md)
 - [color-mode-label.md](./color-mode-label.md)
 - [fields.md](./fields.md)
+- [text-formatter-config-type.md](./text-formatter-config-type.md)
 
 ## Record and level
 
@@ -149,11 +150,14 @@ BitLogger API navigation.
 
 - [config-error.md](./config-error.md)
 - [sink-kind.md](./sink-kind.md)
+- [queue-config-type.md](./queue-config-type.md)
 - [queue-config.md](./queue-config.md)
 - [queue-config-to-json.md](./queue-config-to-json.md)
 - [stringify-queue-config.md](./stringify-queue-config.md)
+- [sink-config-type.md](./sink-config-type.md)
 - [default-sink-config.md](./default-sink-config.md)
 - [logger-config.md](./logger-config.md)
+- [logger-config-type.md](./logger-config-type.md)
 - [default-logger-config.md](./default-logger-config.md)
 - [logger-config-to-json.md](./logger-config-to-json.md)
 - [stringify-logger-config.md](./stringify-logger-config.md)

docs/api/logger-config-type.md

@@ -0,0 +1,71 @@
+---
+name: logger-config-type
+group: api
+category: config
+update-time: 20260613
+description: Public logger config alias used for serializable top-level sync logger settings.
+key-word:
+    - logger
+    - config
+    - alias
+    - public
+---
+
+## Logger-config-type
+
+`LoggerConfig` is the public top-level serializable config type used to describe sync logger behavior. It is a direct alias to the logger config model used by config parsers, sync logger builders, and async build config embedding.
+
+### Interface
+
+```moonbit
+pub type LoggerConfig = @utils.LoggerConfig
+```
+
+#### output
+
+- `LoggerConfig` - Public logger config object containing `min_level`, `target`, `timestamp`, `sink`, and optional `queue`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a built logger instance.
+- The current fields are `min_level : Level`, `target : String`, `timestamp : Bool`, `sink : SinkConfig`, and `queue : QueueConfig?`.
+- `LoggerConfig::new(...)` constructs this type as the main sync config entry point.
+- `parse_logger_config_text(...)`, `logger_config_to_json(...)`, `stringify_logger_config(...)`, and `build_logger(...)` all consume or produce the same public config shape.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Top-level Logger Policy
+
+When sync logger settings should remain structured config data before runtime construction:
+```moonbit
+let config : LoggerConfig = LoggerConfig::new(target="svc")
+```
+
+In this example, the logger setup stays as a typed config object instead of becoming a runtime logger immediately.
+
+#### When Need To Inspect Or Export Full Sync Logger Settings
+
+When configuration should be reviewed or serialized before build time:
+```moonbit
+let config = LoggerConfig::new(queue=Some(QueueConfig::new(16)))
+println(stringify_logger_config(config, pretty=true))
+```
+
+In this example, the same public config type supports both inspection and later runtime assembly.
+
+### Error Case
+
+e.g.:
+- `LoggerConfig` itself does not have a runtime failure mode.
+
+- A valid config object can still describe a sink shape whose eventual runtime behavior depends on backend support, such as file output on limited targets.
+
+### Notes
+
+1. Use `LoggerConfig::new(...)` when you need a value of this type in code.
+
+2. Use `ConfiguredLogger` or `Logger` only after a build step when runtime logging behavior is actually needed.

docs/api/queue-config-type.md

@@ -0,0 +1,71 @@
+---
+name: queue-config-type
+group: api
+category: config
+update-time: 20260613
+description: Public queue config alias used for serializable synchronous queue wrapping settings.
+key-word:
+    - queue
+    - config
+    - alias
+    - public
+---
+
+## Queue-config-type
+
+`QueueConfig` is the public serializable config type used to describe synchronous queue wrapping. It is a direct alias to the queue config model used by sync logger configuration, parsers, and queue config serializers.
+
+### Interface
+
+```moonbit
+pub type QueueConfig = @utils.QueueConfig
+```
+
+#### output
+
+- `QueueConfig` - Public queue config object containing `max_pending` and `overflow`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a runtime queue instance.
+- The current fields are `max_pending : Int` and `overflow : QueueOverflowPolicy`.
+- `QueueConfig::new(...)` constructs this type as the normal handwritten entry point.
+- `queue_config_to_json(...)` and `stringify_queue_config(...)` serialize the same public config shape for tooling or persistence.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Queue Policy Value
+
+When synchronous queue behavior should be carried as config instead of attached immediately to a logger:
+```moonbit
+let queue : QueueConfig = QueueConfig::new(32, overflow=QueueOverflowPolicy::DropOldest)
+```
+
+In this example, the queue policy stays as one typed value that can be embedded into larger config objects later.
+
+#### When Need To Inspect Or Export Queue Settings
+
+When queue wrapping policy should be serialized or logged before build time:
+```moonbit
+let queue = QueueConfig::new(8)
+println(stringify_queue_config(queue, pretty=true))
+```
+
+In this example, the same public config type supports both inspection and later runtime assembly.
+
+### Error Case
+
+e.g.:
+- `QueueConfig` itself does not have a runtime failure mode.
+
+- If queue config is never attached to a `LoggerConfig`, it remains valid data but has no effect on built runtime loggers.
+
+### Notes
+
+1. Use `QueueConfig::new(...)` when you need a value of this type in code.
+
+2. Use `QueuedSink` or `Logger::with_queue(...)` when you need direct runtime queue composition instead of config data.

docs/api/sink-config-type.md

@@ -0,0 +1,71 @@
+---
+name: sink-config-type
+group: api
+category: config
+update-time: 20260613
+description: Public sink config alias used for serializable built-in sink selection and settings.
+key-word:
+    - sink
+    - config
+    - alias
+    - public
+---
+
+## Sink-config-type
+
+`SinkConfig` is the public serializable config type used to describe the built-in sink shape and its related settings. It is a direct alias to the sink config model used by config parsing, logger building, and sink config serializers.
+
+### Interface
+
+```moonbit
+pub type SinkConfig = @utils.SinkConfig
+```
+
+#### output
+
+- `SinkConfig` - Public sink config object containing `kind`, `path`, `append`, `auto_flush`, `rotation`, and `text_formatter`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a runtime sink instance.
+- The current fields are `kind : SinkKind`, `path : String`, `append : Bool`, `auto_flush : Bool`, `rotation : FileRotation?`, and `text_formatter : TextFormatterConfig`.
+- `SinkConfig::new(...)` constructs this type as the main code-side entry point.
+- `sink_config_to_json(...)`, `stringify_sink_config(...)`, and `build_logger(...)` all consume the same public config shape.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Built-in Sink Description
+
+When sink selection and file/text settings should remain config data before logger construction:
+```moonbit
+let sink : SinkConfig = SinkConfig::new(kind=SinkKind::TextConsole)
+```
+
+In this example, the sink choice stays as a typed config object instead of becoming a runtime sink immediately.
+
+#### When Need To Inspect Or Export Sink Settings
+
+When a sink definition should be serialized or reviewed before build time:
+```moonbit
+let sink = SinkConfig::new(kind=SinkKind::File, path="app.log")
+println(stringify_sink_config(sink, pretty=true))
+```
+
+In this example, the same public config type supports both inspection and later runtime assembly.
+
+### Error Case
+
+e.g.:
+- `SinkConfig` itself does not have a runtime failure mode.
+
+- File-oriented fields can still be present on a non-file sink config, but those values may remain unused by the runtime builder.
+
+### Notes
+
+1. Use `SinkConfig::new(...)` when you need a value of this type in code.
+
+2. Use concrete sink constructors when you need a runtime sink directly instead of serializable config data.

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

@@ -0,0 +1,71 @@
+---
+name: text-formatter-config-type
+group: api
+category: config
+update-time: 20260613
+description: Public text formatter config alias used for serializable formatter settings.
+key-word:
+    - formatter
+    - config
+    - alias
+    - public
+---
+
+## Text-formatter-config-type
+
+`TextFormatterConfig` is the public serializable config type used to describe text rendering behavior. It is a direct alias to the formatter config model used by config parsing, config serialization, and runtime formatter conversion.
+
+### Interface
+
+```moonbit
+pub type TextFormatterConfig = @utils.TextFormatterConfig
+```
+
+#### output
+
+- `TextFormatterConfig` - Public formatter config object containing timestamp, level, target, field, template, color, markup, and style-tag settings.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a runtime `TextFormatter` instance.
+- The current fields are `show_timestamp`, `show_level`, `show_target`, `show_fields`, `separator`, `field_separator`, `template`, `color_mode`, `color_support`, `style_markup`, `target_style_markup`, `fields_style_markup`, and `style_tags`.
+- `TextFormatterConfig::new(...)` constructs this type as the main code-side entry point.
+- `text_formatter_config_to_json(...)`, `stringify_text_formatter_config(...)`, and `TextFormatterConfig::to_formatter()` all consume the same public config shape.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Serializable Formatter Policy
+
+When formatter settings should remain structured config data before becoming a runtime formatter:
+```moonbit
+let config : TextFormatterConfig = TextFormatterConfig::new(show_timestamp=false)
+```
+
+In this example, the formatter policy stays as a typed config object instead of a runtime formatter value.
+
+#### When Need To Inspect Or Export Formatter Config Before Runtime Use
+
+When configuration should be reviewed or serialized before a logger is built:
+```moonbit
+let config = TextFormatterConfig::new(template="[{level}] {message}")
+println(stringify_text_formatter_config(config, pretty=true))
+```
+
+In this example, the same public config type supports both inspection and later conversion.
+
+### Error Case
+
+e.g.:
+- `TextFormatterConfig` itself does not have a runtime failure mode.
+
+- If `style_tags` is empty, later `to_formatter()` conversion simply creates no local tag registry.
+
+### Notes
+
+1. Use `TextFormatterConfig::new(...)` when you need a value of this type in code.
+
+2. Use `TextFormatter` when you need the runtime rendering object directly instead of serializable config data.