📝 Document config-driven logger usage and 0.3 changes

README.md

@@ -138,6 +138,21 @@ logger.info("hello", fields=[field("mode", "pretty")])
 
 </details>
 
+<details><summary>JSON 配置加载示例</summary>
+
+```moonbit
+let config = parse_logger_config_text(
+  "{\"min_level\":\"debug\",\"target\":\"config.demo\",\"timestamp\":true,\"sink\":{\"kind\":\"text_console\",\"text_formatter\":{\"separator\":\" | \",\"show_timestamp\":false}},\"queue\":{\"max_pending\":2,\"overflow\":\"DropOldest\"}}",
+)
+
+let logger = build_logger(config)
+
+logger.info("configured from json")
+ignore(logger.flush())
+```
+
+</details>
+
 <details><summary>native 文件 sink 示例</summary>
 
 ```moonbit
@@ -159,3 +174,10 @@ if native_files_supported() {
 
 - [Mooncake 文档页](https://mooncakes.io/docs/Nanaloveyuki/BitLogger)
 - [English README](./docs/README-en.md)
+
+## 📝 配置说明
+
+- 当前提供 JSON 配置层：`parse_logger_config_text(...)`、`stringify_logger_config(...)`、`build_logger(...)`
+- 已支持字段：`min_level`、`target`、`timestamp`、`sink.kind`、`sink.path`、`sink.append`、`sink.auto_flush`、`sink.text_formatter`、`queue`
+- 当前可由配置直接组装的 sink 类型：`console`、`json_console`、`text_console`、`file`
+- `queue` 会作为显式包装层附着在最终 sink 外侧；这仍然是同步 drain 模型，不是 async runtime

bitlogger/README.mbt.md

@@ -38,6 +38,10 @@ BitLogger 是一个基于 MoonBit 的结构化日志库。
 - 支持 `queued_sink(...)`、`with_queue(...)`、有界积压与溢出策略
 - configurable text formatting via `text_formatter(...)`, `format_text(...)`, and `text_console_sink(...)`
 - 支持 `text_formatter(...)`、`format_text(...)`、`text_console_sink(...)` 等文本格式化能力
+- JSON config parsing via `parse_logger_config_text(...)` and `stringify_logger_config(...)`
+- 支持 `parse_logger_config_text(...)`、`stringify_logger_config(...)` 进行最小 JSON 配置读写
+- config-driven logger assembly via `build_logger(...)`
+- 支持 `build_logger(...)` 将配置组装为可直接使用的 logger
 - native-only file output via `file_sink(...)`
 - 支持 `file_sink(...)`，但当前仅保证 `native/llvm` backend 可用
 
@@ -146,6 +150,17 @@ test {
 }
 ```
 
+```mbt check
+test {
+  let config = parse_logger_config_text(
+    "{\"min_level\":\"debug\",\"target\":\"config.demo\",\"timestamp\":true,\"sink\":{\"kind\":\"text_console\",\"text_formatter\":{\"separator\":\" | \",\"show_timestamp\":false}},\"queue\":{\"max_pending\":2,\"overflow\":\"DropOldest\"}}",
+  )
+  let logger = build_logger(config)
+  logger.info("configured from json")
+  ignore(logger.flush())
+}
+```
+
 ```mbt check
 test {
   if native_files_supported() {

docs/README-en.md

@@ -130,6 +130,19 @@ let logger = Logger::new(text_console_sink(formatter), target="pretty")
 logger.info("hello", fields=[field("mode", "pretty")])
 ```
 
+JSON config loading:
+
+```moonbit
+let config = parse_logger_config_text(
+  "{\"min_level\":\"debug\",\"target\":\"config.demo\",\"timestamp\":true,\"sink\":{\"kind\":\"text_console\",\"text_formatter\":{\"separator\":\" | \",\"show_timestamp\":false}},\"queue\":{\"max_pending\":2,\"overflow\":\"DropOldest\"}}",
+)
+
+let logger = build_logger(config)
+
+logger.info("configured from json")
+ignore(logger.flush())
+```
+
 Native file sink:
 
 ```moonbit
@@ -150,3 +163,10 @@ if native_files_supported() {
 
 - [Mooncake package page](https://mooncakes.io/docs/Nanaloveyuki/BitLogger)
 - [Chinese README](../README.md)
+
+## Config Notes
+
+- BitLogger now includes a JSON config layer via `parse_logger_config_text(...)`, `stringify_logger_config(...)`, and `build_logger(...)`.
+- Supported keys include `min_level`, `target`, `timestamp`, `sink.kind`, `sink.path`, `sink.append`, `sink.auto_flush`, `sink.text_formatter`, and `queue`.
+- Config-driven sink assembly currently supports `console`, `json_console`, `text_console`, and `file`.
+- `queue` remains a synchronous bounded wrapper around the final sink, not an async runtime.

docs/changes/0.3.0.md

@@ -0,0 +1,39 @@
+## BitLogger Update Changes
+
+version 0.3.0
+
+### Feature
+
+- feat: add `config.mbt` as a minimal JSON-backed logger configuration layer
+- feat: add `TextFormatterConfig`, `QueueConfig`, and `LoggerConfig` public config types
+- feat: add `TextFormatterConfig::new(...)`, `QueueConfig::new(...)`, and `LoggerConfig::new(...)` constructors for explicit config assembly
+- feat: add `SinkKind` and `SinkConfig` for sink-specific configuration
+- feat: add `TextFormatterConfig::to_formatter()` for bridging parsed config into runtime formatter setup
+- feat: add `parse_logger_config_text(...)` for JSON config parsing
+- feat: add `logger_config_to_json(...)` and `stringify_logger_config(...)` for config serialization
+- feat: add `RuntimeSink`, `ConfiguredLogger`, `build_logger(...)`, and `parse_and_build_logger(...)` for config-driven logger assembly
+- feat: add `ConfiguredLogger::drain(...)`, `ConfiguredLogger::pending_count()`, and `ConfiguredLogger::dropped_count()` queue observability helpers
+- feat: support config keys `min_level`, `target`, `timestamp`, `sink.kind`, `sink.path`, `sink.append`, `sink.auto_flush`, `sink.text_formatter`, and `queue`
+- feat: support config-driven sink assembly for `console`, `json_console`, `text_console`, and `file`
+- feat: use `maria/json_parser` as the first external dependency for practical config loading
+
+### Test
+
+- test: cover parsing of core logger config fields
+- test: cover nested formatter and queue config parsing
+- test: cover config stringify and parse roundtrip behavior
+- test: cover config-built queued text logger flushing and pending count behavior
+- test: cover partial drain behavior for config-built queued logger
+- test: cover dropped-count reporting for bounded config-built queue
+
+### Example
+
+- docs: update `examples/basic` with JSON config loading example
+- docs: update `examples/basic` to use `parse_and_build_logger(...)` with explicit error handling in `main`
+- docs: update root README, English README, and Mooncake README with config usage notes
+- chore: ignore local `.mooncakes/` cache directory in git
+
+### Notes
+
+- current config scope is still intentionally constrained to stable built-in sink shapes
+- queue wrapping remains synchronous drain-based delivery, not async runtime scheduling