📝 document config constructors

docs/api/index.md

@@ -221,12 +221,15 @@ BitLogger API navigation.
 - [file-rotation-config-to-json.md](./file-rotation-config-to-json.md)
 - [queue-config-type.md](./queue-config-type.md)
 - [queue-config.md](./queue-config.md)
+- [queue-config-new.md](./queue-config-new.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)
+- [sink-config-new.md](./sink-config-new.md)
 - [logger-config.md](./logger-config.md)
 - [logger-config-type.md](./logger-config-type.md)
+- [logger-config-new.md](./logger-config-new.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-new.md

@@ -0,0 +1,90 @@
+---
+name: logger-config-new
+group: api
+category: config
+update-time: 20260613
+description: Construct the main LoggerConfig value for config-driven runtime logger assembly.
+key-word:
+    - logger
+    - config
+    - constructor
+    - public
+---
+
+## Logger-config-new
+
+Construct a `LoggerConfig` value for config-driven runtime logger assembly. This constructor stores level, target, timestamp behavior, sink shape, and optional queue wrapping as one typed config object.
+
+### Interface
+
+```moonbit
+pub fn LoggerConfig::new(
+  min_level~ : Level = Level::Info,
+  target~ : String = "",
+  timestamp~ : Bool = false,
+  sink~ : SinkConfig = default_sink_config(),
+  queue~ : QueueConfig? = None,
+) -> LoggerConfig {
+```
+
+#### input
+
+- `min_level : Level` - Global level gate.
+- `target : String` - Default target namespace.
+- `timestamp : Bool` - Whether the built logger should emit timestamps.
+- `sink : SinkConfig` - Configured sink shape.
+- `queue : QueueConfig?` - Optional synchronous queue wrapper.
+
+#### output
+
+- `LoggerConfig` - Main logger configuration object.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The constructor stores the supplied logging policy and sink config directly.
+- `min_level` defaults to `Level::Info`, `target` defaults to `""`, and `timestamp` defaults to `false`.
+- `sink` defaults to `default_sink_config()`.
+- `queue=None` means no configured synchronous queue layer.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Build Config In Code Instead Of JSON
+
+When application bootstrapping prefers typed config values:
+```moonbit
+let config = LoggerConfig::new(
+  min_level=Level::Warn,
+  target="svc",
+  timestamp=true,
+  sink=SinkConfig::new(kind=SinkKind::TextConsole),
+)
+```
+
+In this example, the logger configuration is explicit and strongly typed.
+
+#### When Prepare Config For A Later Builder
+
+When config is assembled in one place and built later:
+```moonbit
+let config = LoggerConfig::new(queue=Some(QueueConfig::new(16)))
+let logger = build_logger(config)
+```
+
+In this example, the config object becomes the handoff boundary between assembly and runtime construction.
+
+### Error Case
+
+e.g.:
+- If `sink` describes a capability-limited backend shape such as native file output on a non-native target, later runtime behavior still follows backend support rules.
+
+- If `target` is empty, the configuration is still valid.
+
+### Notes
+
+1. This is the core typed constructor for sync logger assembly.
+
+2. Prefer this API when config is generated in code rather than parsed from text.

docs/api/queue-config-new.md

@@ -0,0 +1,78 @@
+---
+name: queue-config-new
+group: api
+category: config
+update-time: 20260613
+description: Construct a QueueConfig value for config-driven synchronous queue wrapping.
+key-word:
+    - queue
+    - config
+    - constructor
+    - public
+---
+
+## Queue-config-new
+
+Construct a `QueueConfig` value for config-driven synchronous queue wrapping. This constructor stores queue capacity and overflow behavior as data for later logger assembly.
+
+### Interface
+
+```moonbit
+pub fn QueueConfig::new(
+  max_pending : Int,
+  overflow~ : QueueOverflowPolicy = QueueOverflowPolicy::DropNewest,
+) -> QueueConfig {
+```
+
+#### input
+
+- `max_pending : Int` - Queue capacity used by the configured queue wrapper.
+- `overflow : QueueOverflowPolicy` - Overflow strategy used when the queue is full.
+
+#### output
+
+- `QueueConfig` - Queue configuration value suitable for `LoggerConfig` or JSON serialization helpers.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The constructor stores `max_pending` and `overflow` directly without additional normalization.
+- This config is used by `build_logger(...)` and `parse_and_build_logger(...)` when `queue` is present in `LoggerConfig`.
+- It configures the synchronous `QueuedSink`, not the async adapter package.
+- `overflow` defaults to `QueueOverflowPolicy::DropNewest`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Config-driven Bounded Queueing
+
+When runtime queue wrapping should be described as config data:
+```moonbit
+let queue = QueueConfig::new(32, overflow=QueueOverflowPolicy::DropOldest)
+```
+
+In this example, queue capacity and overflow behavior are captured for later runtime assembly.
+
+#### When Embed Queue Config In Logger Config
+
+When queueing should be part of a larger logger configuration object:
+```moonbit
+let config = LoggerConfig::new(queue=Some(QueueConfig::new(16)))
+```
+
+In this example, queue config becomes one component of the top-level logger config.
+
+### Error Case
+
+e.g.:
+- If `max_pending` is too small, configured runtime drops may happen frequently under bursty load.
+
+- If queue config is omitted from `LoggerConfig`, no synchronous queue wrapper is added.
+
+### Notes
+
+1. This constructor is for config-driven queue wrapping, not `bitlogger_async`.
+
+2. Use `Logger::with_queue(...)` when queue composition should be done directly in code.

docs/api/sink-config-new.md

@@ -0,0 +1,93 @@
+---
+name: sink-config-new
+group: api
+category: config
+update-time: 20260613
+description: Construct a SinkConfig value for config-driven logger sink selection.
+key-word:
+    - sink
+    - config
+    - constructor
+    - public
+---
+
+## Sink-config-new
+
+Construct a `SinkConfig` value for config-driven logger assembly. This constructor stores sink shape and sink-specific settings as typed data for later runtime building.
+
+### Interface
+
+```moonbit
+pub fn SinkConfig::new(
+  kind~ : SinkKind = SinkKind::Console,
+  path~ : String = "",
+  append~ : Bool = true,
+  auto_flush~ : Bool = true,
+  rotation~ : FileRotation? = None,
+  text_formatter~ : TextFormatterConfig = default_text_formatter_config(),
+) -> SinkConfig {
+```
+
+#### input
+
+- `kind : SinkKind` - Sink variant such as `Console`, `JsonConsole`, `TextConsole`, or `File`.
+- `path : String` - File path used when `kind=File`.
+- `append : Bool` - File append policy.
+- `auto_flush : Bool` - File auto-flush policy.
+- `rotation : FileRotation?` - Optional file rotation policy.
+- `text_formatter : TextFormatterConfig` - Formatter config used by text console or file text rendering.
+
+#### output
+
+- `SinkConfig` - Typed sink configuration used by `LoggerConfig`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- The constructor stores the supplied sink-shape and file-specific fields directly.
+- `kind` defaults to `SinkKind::Console`.
+- `text_formatter` defaults to `default_text_formatter_config()` so text-oriented sink config always has a formatter config available.
+- File-only options are stored even though only `kind=File` actually consumes them at runtime.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Build A Text Console Config
+
+When runtime output should be text-formatted through config data:
+```moonbit
+let sink = SinkConfig::new(
+  kind=SinkKind::TextConsole,
+  text_formatter=TextFormatterConfig::new(show_timestamp=false),
+)
+```
+
+In this example, the formatter choice is embedded directly into sink config.
+
+#### When Build A File Sink Config
+
+When file behavior should be data-driven:
+```moonbit
+let sink = SinkConfig::new(
+  kind=SinkKind::File,
+  path="app.log",
+  rotation=Some(file_rotation(1024, max_backups=2)),
+)
+```
+
+In this example, file location and retention policy are part of the same sink definition.
+
+### Error Case
+
+e.g.:
+- If `kind=File` but `path` is empty, the config object is still constructible, but runtime usage should be evaluated carefully.
+
+- If `kind` is non-file, file-specific options may simply be unused by the runtime builder.
+
+### Notes
+
+1. This constructor builds sink-shape configuration, not the runtime sink itself.
+
+2. Use `sink_config_to_json(...)` and `stringify_sink_config(...)` for export.