📝 Document logger config presets

docs/api/console.md

@@ -0,0 +1,73 @@
+---
+name: console
+group: api
+category: config
+update-time: 20260520
+description: Create a minimal logger config preset for the built-in console sink.
+key-word:
+    - preset
+    - console
+    - config
+    - public
+---
+
+## Console
+
+Create a `LoggerConfig` preset for the built-in plain console sink. This helper is the shortest way to assemble a config-driven logger that writes directly to the terminal without text formatter customization.
+
+### Interface
+
+```moonbit
+pub fn console(
+  min_level~ : Level = Level::Info,
+  target~ : String = "",
+  timestamp~ : Bool = false,
+) -> LoggerConfig {
+```
+
+#### input
+
+- `min_level : Level` - Minimum enabled level for the preset.
+- `target : String` - Default target stored in the returned config.
+- `timestamp : Bool` - Whether the built logger should emit timestamps.
+
+#### output
+
+- `LoggerConfig` - Config using `SinkKind::Console` with no queue wrapper by default.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This preset always returns `sink.kind=SinkKind::Console`.
+- `queue=None` by default, so output remains unqueued unless `with_queue(...)` is applied later.
+- This helper only selects the sink shape and top-level logger config fields; it does not build a runtime logger by itself.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Minimal Terminal Config
+
+When application startup wants a simple console config:
+```moonbit
+let config = console(min_level=Level::Debug, target="cli")
+let logger = build_logger(config)
+```
+
+In this example, the logger uses the built-in console sink.
+
+And no extra queue or file policy is configured.
+
+### Error Case
+
+e.g.:
+- If `target` is empty, the config is still valid.
+
+- If later runtime assembly targets an environment with sink-specific limitations, those runtime rules still apply outside this preset.
+
+### Notes
+
+1. Use this preset when you want the shortest path to console output.
+
+2. Apply `with_queue(...)` separately if bounded synchronous buffering is needed.

docs/api/file.md

@@ -0,0 +1,100 @@
+---
+name: file
+group: api
+category: config
+update-time: 20260520
+description: Create a logger config preset for the built-in file sink with optional rotation and formatter settings.
+key-word:
+    - preset
+    - file
+    - rotation
+    - public
+---
+
+## File
+
+Create a `LoggerConfig` preset for the built-in file sink. This helper packages file path, append policy, auto-flush behavior, optional rotation, and text formatter settings into a single config object for runtime logger assembly.
+
+### Interface
+
+```moonbit
+pub fn file(
+  path : String,
+  min_level~ : Level = Level::Info,
+  target~ : String = "",
+  timestamp~ : Bool = false,
+  append~ : Bool = true,
+  auto_flush~ : Bool = true,
+  rotation~ : FileRotation? = None,
+  text_formatter~ : TextFormatterConfig = default_text_formatter_config(),
+) -> LoggerConfig raise ConfigError {
+```
+
+#### input
+
+- `path : String` - Output file path for the file sink.
+- `min_level : Level` - Minimum enabled level for the preset.
+- `target : String` - Default target stored in the returned config.
+- `timestamp : Bool` - Whether the built logger should emit timestamps.
+- `append : Bool` - Whether file writes should append instead of truncate-on-open behavior.
+- `auto_flush : Bool` - Whether writes should be flushed automatically.
+- `rotation : FileRotation?` - Optional size-based file rotation policy.
+- `text_formatter : TextFormatterConfig` - Formatter config used for file text rendering.
+
+#### output
+
+- `LoggerConfig` - Config using `SinkKind::File` and the supplied file-specific settings.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This preset always returns `sink.kind=SinkKind::File`.
+- `path` must be non-empty.
+- `rotation=None` leaves file rotation disabled until a rotation policy is provided directly or through `with_file_rotation(...)`.
+- `queue=None` by default, so buffering is opt-in through `with_queue(...)`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Config-driven File Logger
+
+When application boot wants typed file logging config:
+```moonbit
+let config = file(
+  "service.log",
+  min_level=Level::Warn,
+  append=true,
+  auto_flush=true,
+)
+```
+
+In this example, the returned config targets the built-in file sink.
+
+And rotation remains disabled until configured.
+
+#### When Need File Config With Rotation Prepared Up Front
+
+When file retention should be included immediately:
+```moonbit
+let config = file(
+  "service.log",
+  rotation=Some(file_rotation(1024 * 1024, max_backups=3)),
+)
+```
+
+In this example, the file preset carries both path and rotation policy.
+
+### Error Case
+
+e.g.:
+- If `path` is empty, this preset raises `ConfigError::InvalidConfig("File sink requires non-empty path")`.
+
+- If you need console output instead of file output, use a console preset because file-only settings are meaningful only for `SinkKind::File`.
+
+### Notes
+
+1. This is the only preset in this set that accepts file path and file rotation settings directly.
+
+2. `with_file_rotation(...)` is designed to extend this preset or any other file-based `LoggerConfig`.

docs/api/index.md

@@ -111,6 +111,15 @@ BitLogger API navigation.
 - [build-logger.md](./build-logger.md)
 - [parse-and-build-logger.md](./parse-and-build-logger.md)
 
+## Presets
+
+- [console.md](./console.md)
+- [json-console.md](./json-console.md)
+- [text-console.md](./text-console.md)
+- [file.md](./file.md)
+- [with-queue.md](./with-queue.md)
+- [with-file-rotation.md](./with-file-rotation.md)
+
 ## Async logger
 
 - [async-logger.md](./async-logger.md)

docs/api/json-console.md

@@ -0,0 +1,73 @@
+---
+name: json-console
+group: api
+category: config
+update-time: 20260520
+description: Create a logger config preset for the built-in JSON console sink.
+key-word:
+    - preset
+    - json
+    - console
+    - public
+---
+
+## Json-console
+
+Create a `LoggerConfig` preset for structured JSON output on the console. This preset is intended for config-driven logging pipelines that want machine-readable terminal output.
+
+### Interface
+
+```moonbit
+pub fn json_console(
+  min_level~ : Level = Level::Info,
+  target~ : String = "",
+  timestamp~ : Bool = false,
+) -> LoggerConfig {
+```
+
+#### input
+
+- `min_level : Level` - Minimum enabled level for the preset.
+- `target : String` - Default target stored in the returned config.
+- `timestamp : Bool` - Whether emitted records should include timestamps.
+
+#### output
+
+- `LoggerConfig` - Config using `SinkKind::JsonConsole` with no queue wrapper by default.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This preset always returns `sink.kind=SinkKind::JsonConsole`.
+- `queue=None` by default, so JSON records are not buffered unless `with_queue(...)` is added later.
+- The preset does not carry file-only fields such as `path` or `rotation` in a meaningful way because the sink kind is not file-based.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Structured Console Output
+
+When logs should be easy to collect or parse from stdout:
+```moonbit
+let config = json_console(min_level=Level::Info, target="api", timestamp=true)
+let logger = build_logger(config)
+```
+
+In this example, records are emitted through the JSON console sink.
+
+And timestamps are enabled at the top-level logger config.
+
+### Error Case
+
+e.g.:
+- If `target` is empty, the preset still returns a valid config.
+
+- If you need file rotation or file paths, this preset is the wrong sink shape and should be replaced with `file(...)`.
+
+### Notes
+
+1. Use this preset when downstream tooling expects structured console logs.
+
+2. `with_file_rotation(...)` does not change this preset because it only applies to file configs.

docs/api/text-console.md

@@ -0,0 +1,75 @@
+---
+name: text-console
+group: api
+category: config
+update-time: 20260520
+description: Create a logger config preset for the built-in text console sink with formatter settings.
+key-word:
+    - preset
+    - text
+    - console
+    - public
+---
+
+## Text-console
+
+Create a `LoggerConfig` preset for text-formatted console output. This helper bundles `SinkKind::TextConsole` together with a `TextFormatterConfig` so config-driven logger assembly can control text rendering without manual `SinkConfig::new(...)` calls.
+
+### Interface
+
+```moonbit
+pub fn text_console(
+  min_level~ : Level = Level::Info,
+  target~ : String = "",
+  timestamp~ : Bool = false,
+  text_formatter~ : TextFormatterConfig = default_text_formatter_config(),
+) -> LoggerConfig {
+```
+
+#### input
+
+- `min_level : Level` - Minimum enabled level for the preset.
+- `target : String` - Default target stored in the returned config.
+- `timestamp : Bool` - Whether the built logger should emit timestamps.
+- `text_formatter : TextFormatterConfig` - Formatter config used by the text console sink.
+
+#### output
+
+- `LoggerConfig` - Config using `SinkKind::TextConsole` with the supplied formatter and no queue wrapper by default.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This preset always returns `sink.kind=SinkKind::TextConsole`.
+- `text_formatter` is copied into `config.sink.text_formatter`.
+- `queue=None` by default, so buffering remains opt-in through `with_queue(...)`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Customized Human-readable Console Output
+
+When console logs should use a specific separator or timestamp display:
+```moonbit
+let formatter = TextFormatterConfig::new(show_timestamp=false, separator=" | ")
+let config = text_console(target="worker", text_formatter=formatter)
+```
+
+In this example, the text console sink uses the supplied formatter config.
+
+And the preset stays fully compatible with later `build_logger(...)` assembly.
+
+### Error Case
+
+e.g.:
+- If `target` is empty, the preset still returns a valid config.
+
+- If you later apply `with_file_rotation(...)`, the config stays unchanged because this is not a file sink preset.
+
+### Notes
+
+1. Use this preset instead of `console(...)` when text formatting must be configured explicitly.
+
+2. File-only settings such as `path` and `rotation` are not part of this preset.

docs/api/with-file-rotation.md

@@ -0,0 +1,86 @@
+---
+name: with-file-rotation
+group: api
+category: config
+update-time: 20260520
+description: Add or replace size-based file rotation on an existing file logger config preset.
+key-word:
+    - preset
+    - file
+    - rotation
+    - public
+---
+
+## With-file-rotation
+
+Add or replace a size-based file rotation policy on an existing `LoggerConfig`. This helper is intentionally narrow: it only mutates configs whose sink kind is `File` and leaves every non-file config unchanged.
+
+### Interface
+
+```moonbit
+pub fn with_file_rotation(
+  config : LoggerConfig,
+  max_bytes : Int,
+  max_backups~ : Int = 1,
+) -> LoggerConfig {
+```
+
+#### input
+
+- `config : LoggerConfig` - Base logger config to inspect and possibly update.
+- `max_bytes : Int` - Maximum active file size before rotation.
+- `max_backups : Int` - Number of rotated backup files to retain.
+
+#### output
+
+- `LoggerConfig` - Updated file config with rotation, or the original config unchanged when the sink is not file-based.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- `with_file_rotation(...)` only applies to file presets or other configs whose `sink.kind=SinkKind::File`.
+- If the input config is not file-based, the helper returns the config unchanged.
+- When the input config is file-based, the helper preserves `min_level`, `target`, `timestamp`, file path, append mode, auto-flush, formatter, and queue settings while replacing `sink.rotation`.
+- Rotation policy creation follows `file_rotation(...)` normalization rules for `max_bytes` and `max_backups`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need To Extend A File Preset
+
+When file rotation should be added after the base preset is assembled:
+```moonbit
+let config = with_file_rotation(file("service.log"), 1024 * 1024, max_backups=3)
+```
+
+In this example, the file preset gains a size-based rotation policy.
+
+And all other file sink settings remain unchanged.
+
+#### When Compose Queue And Rotation Together
+
+When the file logger also needs bounded queueing:
+```moonbit
+let config = with_file_rotation(
+  with_queue(file("service.log"), max_pending=32),
+  4096,
+  max_backups=2,
+)
+```
+
+In this example, queue settings are preserved while file rotation is added.
+
+### Error Case
+
+e.g.:
+- If the input config is not file-based, no error is raised and the config is returned unchanged.
+
+- If `max_bytes` or `max_backups` are non-positive, normalization behavior follows `file_rotation(...)`.
+
+### Notes
+
+1. This helper is a no-op for `console(...)`, `json_console(...)`, and `text_console(...)` presets.
+
+2. Use `file(...)` when you need to provide the initial file path, because `with_file_rotation(...)` does not create a file sink from a non-file config.

docs/api/with-queue.md

@@ -0,0 +1,76 @@
+---
+name: with-queue
+group: api
+category: config
+update-time: 20260520
+description: Add a queue wrapper to an existing logger config preset.
+key-word:
+    - preset
+    - queue
+    - config
+    - public
+---
+
+## With-queue
+
+Add a synchronous queue wrapper to an existing `LoggerConfig`. This preset helper is the config-side counterpart to `Logger::with_queue(...)`, allowing queue behavior to be expressed before the runtime logger is built.
+
+### Interface
+
+```moonbit
+pub fn with_queue(
+  config : LoggerConfig,
+  max_pending~ : Int = 0,
+  overflow~ : QueueOverflowPolicy = QueueOverflowPolicy::DropNewest,
+) -> LoggerConfig {
+```
+
+#### input
+
+- `config : LoggerConfig` - Base logger config to wrap.
+- `max_pending : Int` - Maximum number of pending records allowed in the queue.
+- `overflow : QueueOverflowPolicy` - Overflow behavior such as `DropNewest` or `DropOldest`.
+
+#### output
+
+- `LoggerConfig` - A copy of the input config with `queue=Some(QueueConfig::new(...))`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper preserves the original config's `min_level`, `target`, `timestamp`, and `sink` fields.
+- Only the top-level `queue` field is added or replaced.
+- The helper can be composed with any preset, including `console(...)`, `json_console(...)`, `text_console(...)`, and `file(...)`.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Config-side Queueing
+
+When queue behavior should be configured before calling `build_logger(...)`:
+```moonbit
+let config = with_queue(
+  text_console(target="svc"),
+  max_pending=32,
+  overflow=QueueOverflowPolicy::DropOldest,
+)
+```
+
+In this example, the text console preset is wrapped with a bounded queue config.
+
+And sink-specific settings remain unchanged.
+
+### Error Case
+
+e.g.:
+- If `max_pending` is too small, burst traffic may trigger overflow handling sooner.
+
+- If the wrapped runtime logger is never flushed or drained, queued records may remain pending depending on how the built sink is used.
+
+### Notes
+
+1. This helper is config composition only; it does not build or run the logger.
+
+2. Queue wrapping can be combined with `with_file_rotation(...)` when the base config is file-based.