📝 Document 0.2 examples and usage patterns

README.md

@@ -16,9 +16,15 @@ BitLogger 是一个基于 MoonBit 编写的结构化日志库。
 
 ## ❇️ 特点
 
-- 🧩 核心能力清晰：先把 logging core 做稳，再继续扩展 `FileSink`、buffered/async 等能力。
+- 🧩 核心能力清晰：先把 logging core 做稳，再继续扩展 rotation/async 等能力。
 - 🏗️ 结构明确：按 `level / record / formatter / sinks / logger / global` 拆文件，便于继续维护。
 - 🔌 可扩展：支持 `fanout_sink(...)` 和 `callback_sink(...)`，方便后续桥接文件、指标或外部系统。
+- 🧱 可组合：支持 `buffered_sink(...)` 和 `filter_sink(...)`，可以在不引入复杂 runtime 的前提下组合输出策略。
+- 🔎 可复用过滤：提供 `target_has_prefix(...)`、`message_contains(...)`、`level_at_least(...)`、`field_equals(...)` 等过滤辅助函数。
+- 🩹 可变换 Record：支持 `with_patch(...)`、`patch_sink(...)` 与脱敏/补字段/message 变换 helper。
+- 📮 显式队列：支持 `queued_sink(...)` / `with_queue(...)`、有界积压与溢出策略，作为后续 async sink 的 runtime-safe 基础。
+- 🧾 可配置文本格式：支持 `text_formatter(...)`、`format_text(...)`、`text_console_sink(...)` 和 `formatted_callback_sink(...)`。
+- 💾 Native 文件输出：支持 `file_sink(...)`，但当前仅保证 `native/llvm` backend 可用。
 - 📦 面向 MoonBit：API 和工程结构围绕 MoonBit 的 package / visibility / toolchain 现实约束设计。
 
 ## 🚀 快速开始
@@ -31,14 +37,15 @@ let logger = Logger::new(console_sink(), min_level=Level::Info, target="demo")
 logger.info("starting", fields=[field("port", "8080")])
 ```
 
-层级 target 示例：
+<details><summary>层级 target 示例</summary>
 
 ```moonbit
 let worker = Logger::new(console_sink(), target="app").child("worker")
 worker.info("job ready")
 ```
+</details>
 
-自定义 callback sink 示例：
+<details><summary>自定义 callback sink 示例</summary>
 
 ```moonbit
 let hook = Logger::new(
@@ -50,6 +57,98 @@ let hook = Logger::new(
 
 hook.info("hello")
 ```
+</details>
+
+<details><summary>基础 buffered sink 示例</summary>
+
+```moonbit
+let sink = buffered_sink(console_sink(), flush_limit=2)
+let logger = Logger::new(sink, target="buffered")
+
+logger.info("one")
+logger.info("two")
+sink.flush()
+```
+</details>
+
+<details><summary>基础 filter sink 示例</summary>
+
+```moonbit
+let sink = filter_sink(console_sink(), fn(rec) {
+  rec.target == "kept"
+})
+
+let kept = Logger::new(sink, target="kept")
+let dropped = Logger::new(sink, target="dropped")
+
+kept.info("visible")
+dropped.info("hidden")
+```
+</details>
+
+<details><summary>Logger 链式 filter 示例</summary>
+
+```moonbit
+let logger = Logger::new(console_sink(), target="service")
+  .with_filter(all_of([
+    target_has_prefix("service"),
+    message_contains("visible"),
+  ]))
+
+logger.info("hidden")
+logger.child("api").info("visible")
+```
+</details>
+
+<details><summary>Record patch 示例</summary>
+
+```moonbit
+let logger = Logger::new(console_sink(), target="auth")
+  .with_patch(compose_patches([
+    prefix_message("[safe] "),
+    redact_fields(["token"]),
+    append_fields([field("service", "bitlogger")]),
+  ]))
+
+logger.info("login", fields=[field("user", "alice"), field("token", "secret")])
+```
+</details>
+
+<details><summary>显式 queue sink 示例</summary>
+
+```moonbit
+let logger = Logger::new(console_sink(), target="queue")
+  .with_queue(max_pending=2, overflow=QueueOverflowPolicy::DropOldest)
+
+logger.info("one")
+logger.info("two")
+logger.info("three")
+ignore(logger.sink.flush())
+```
+</details>
+
+<details><summary>自定义文本 formatter 示例</summary>
+
+```moonbit
+let formatter = text_formatter(show_timestamp=false, separator=" | ")
+let logger = Logger::new(text_console_sink(formatter), target="pretty")
+
+logger.info("hello", fields=[field("mode", "pretty")])
+```
+
+</details>
+
+<details><summary>native 文件 sink 示例</summary>
+
+```moonbit
+if native_files_supported() {
+  let logger = Logger::new(file_sink("bitlogger.log"), target="file")
+  logger.info("hello", fields=[field("kind", "file")])
+  ignore(logger.sink.flush())
+  ignore(logger.sink.close())
+}
+```
+</details>
 
 ## 📂 仓库结构
 
@@ -60,4 +159,3 @@ hook.info("hello")
 
 - [Mooncake 文档页](https://mooncakes.io/docs/Nanaloveyuki/BitLogger)
 - [English README](./docs/README-en.md)
-

bitlogger/README.mbt.md

@@ -26,6 +26,20 @@ BitLogger 是一个基于 MoonBit 的结构化日志库。
 - `fanout_sink(...)` 支持多 sink 组合
 - custom callback sink via `callback_sink(...)`
 - `callback_sink(...)` 支持自定义外部集成
+- buffered sink via `buffered_sink(...)`
+- `buffered_sink(...)` 支持内存缓冲与 flush
+- filter sink via `filter_sink(...)`
+- `filter_sink(...)` 支持按 `Record` 条件筛选输出
+- reusable filter helpers such as `target_has_prefix(...)`, `message_contains(...)`, and `field_equals(...)`
+- 提供 `target_has_prefix(...)`、`message_contains(...)`、`field_equals(...)` 等可复用过滤辅助函数
+- record patching via `with_patch(...)` and `patch_sink(...)`
+- 支持 `with_patch(...)`、`patch_sink(...)` 以及常见 record patch helper
+- explicit queued delivery via `queued_sink(...)` and `with_queue(...)`
+- 支持 `queued_sink(...)`、`with_queue(...)`、有界积压与溢出策略
+- configurable text formatting via `text_formatter(...)`, `format_text(...)`, and `text_console_sink(...)`
+- 支持 `text_formatter(...)`、`format_text(...)`、`text_console_sink(...)` 等文本格式化能力
+- native-only file output via `file_sink(...)`
+- 支持 `file_sink(...)`，但当前仅保证 `native/llvm` backend 可用
 
 ## Example / 示例
 
@@ -55,13 +69,6 @@ test {
 }
 ```
 
-```mbt check
-test {
-  let logger = Logger::new(console_sink(), target="app").child("worker")
-  logger.info("ready")
-}
-```
-
 ```mbt check
 test {
   let logger = Logger::new(
@@ -74,3 +81,78 @@ test {
 }
 ```
 
+```mbt check
+test {
+  let sink = buffered_sink(console_sink(), flush_limit=2)
+  let logger = Logger::new(sink, target="buffered")
+  logger.info("one")
+  logger.info("two")
+  sink.flush()
+}
+```
+
+```mbt check
+test {
+  let sink = filter_sink(console_sink(), fn(rec) {
+    rec.target == "kept"
+  })
+  let kept = Logger::new(sink, target="kept")
+  let dropped = Logger::new(sink, target="dropped")
+  kept.info("visible")
+  dropped.info("hidden")
+}
+```
+
+```mbt check
+test {
+  let logger = Logger::new(console_sink(), target="service")
+    .with_filter(all_of([
+      target_has_prefix("service"),
+      message_contains("visible"),
+    ]))
+  logger.info("hidden")
+  logger.child("api").info("visible")
+}
+```
+
+```mbt check
+test {
+  let logger = Logger::new(console_sink(), target="auth")
+    .with_patch(compose_patches([
+      prefix_message("[safe] "),
+      redact_fields(["token"]),
+      append_fields([field("service", "bitlogger")]),
+    ]))
+  logger.info("login", fields=[field("user", "alice"), field("token", "secret")])
+}
+```
+
+```mbt check
+test {
+  let logger = Logger::new(console_sink(), target="queue")
+    .with_queue(max_pending=2, overflow=QueueOverflowPolicy::DropOldest)
+  logger.info("one")
+  logger.info("two")
+  logger.info("three")
+  ignore(logger.sink.flush())
+}
+```
+
+```mbt check
+test {
+  let formatter = text_formatter(show_timestamp=false, separator=" | ")
+  let logger = Logger::new(text_console_sink(formatter), target="pretty")
+  logger.info("hello", fields=[field("mode", "pretty")])
+}
+```
+
+```mbt check
+test {
+  if native_files_supported() {
+    let logger = Logger::new(file_sink("bitlogger.log"), target="file")
+    logger.info("hello", fields=[field("kind", "file")])
+    ignore(logger.sink.flush())
+    ignore(logger.sink.close())
+  }
+}
+```

docs/README-en.md

@@ -15,6 +15,17 @@ BitLogger currently provides:
 - optional timestamps via `with_timestamp()`
 - sink fanout via `fanout_sink(...)`
 - custom integration via `callback_sink(...)`
+- in-memory buffering via `buffered_sink(...)`
+- record filtering via `filter_sink(...)`
+- reusable filter helpers such as `target_has_prefix(...)`, `message_contains(...)`, `level_at_least(...)`, and `field_equals(...)`
+- record patching via `with_patch(...)` and `patch_sink(...)`
+- patch helpers such as `prefix_message(...)`, `append_fields(...)`, and `redact_fields(...)`
+- explicit queued delivery via `queued_sink(...)` and `with_queue(...)`
+- bounded backlog with `QueueOverflowPolicy::DropNewest` and `QueueOverflowPolicy::DropOldest`
+- configurable text formatting via `text_formatter(...)`, `format_text(...)`, and `text_console_sink(...)`
+- formatter-based callback integration via `formatted_callback_sink(...)`
+- native-only file output via `file_sink(...)`
+- `native_files_supported()` for backend capability detection
 - default global logger helpers
 
 ## Quick Start
@@ -47,6 +58,89 @@ let hook = Logger::new(
 hook.info("hello")
 ```
 
+Basic buffered sink:
+
+```moonbit
+let sink = buffered_sink(console_sink(), flush_limit=2)
+let logger = Logger::new(sink, target="buffered")
+
+logger.info("one")
+logger.info("two")
+sink.flush()
+```
+
+Basic filter sink:
+
+```moonbit
+let sink = filter_sink(console_sink(), fn(rec) {
+  rec.target == "kept"
+})
+
+let kept = Logger::new(sink, target="kept")
+let dropped = Logger::new(sink, target="dropped")
+
+kept.info("visible")
+dropped.info("hidden")
+```
+
+Chained logger filter:
+
+```moonbit
+let logger = Logger::new(console_sink(), target="service")
+  .with_filter(all_of([
+    target_has_prefix("service"),
+    message_contains("visible"),
+  ]))
+
+logger.info("hidden")
+logger.child("api").info("visible")
+```
+
+Record patching:
+
+```moonbit
+let logger = Logger::new(console_sink(), target="auth")
+  .with_patch(compose_patches([
+    prefix_message("[safe] "),
+    redact_fields(["token"]),
+    append_fields([field("service", "bitlogger")]),
+  ]))
+
+logger.info("login", fields=[field("user", "alice"), field("token", "secret")])
+```
+
+Explicit queued sink:
+
+```moonbit
+let logger = Logger::new(console_sink(), target="queue")
+  .with_queue(max_pending=2, overflow=QueueOverflowPolicy::DropOldest)
+
+logger.info("one")
+logger.info("two")
+logger.info("three")
+ignore(logger.sink.flush())
+```
+
+Custom text formatter:
+
+```moonbit
+let formatter = text_formatter(show_timestamp=false, separator=" | ")
+let logger = Logger::new(text_console_sink(formatter), target="pretty")
+
+logger.info("hello", fields=[field("mode", "pretty")])
+```
+
+Native file sink:
+
+```moonbit
+if native_files_supported() {
+  let logger = Logger::new(file_sink("bitlogger.log"), target="file")
+  logger.info("hello", fields=[field("kind", "file")])
+  ignore(logger.sink.flush())
+  ignore(logger.sink.close())
+}
+```
+
 ## Repository Layout
 
 - `bitlogger/`: MoonBit library package, tests, and Mooncake package README

docs/changes/0.2.0.md

@@ -0,0 +1,47 @@
+## BitLogger Update Changes
+
+version 0.2.0
+
+### Feature
+
+- feat: add `BufferedSink[S]` with in-memory buffering support
+- feat: add `buffered_sink(...)` constructor with configurable `flush_limit`
+- feat: add `BufferedSink::flush()` for manual drain
+- feat: add `BufferedSink::pending_count()` for buffer inspection in tests and integration code
+- feat: add `FilterSink[S]` for predicate-based record filtering
+- feat: add `filter_sink(...)` constructor for composable sink routing
+- feat: add `Logger::with_filter(...)` as a higher-level chained filter entry point
+- feat: add reusable filter helpers such as `target_is(...)`, `target_has_prefix(...)`, `message_contains(...)`, `level_at_least(...)`, `has_field(...)`, and `field_equals(...)`
+- feat: add predicate combinators `all_of(...)`, `any_of(...)`, and `not_(...)`
+- feat: add `PatchSink[S]`, `patch_sink(...)`, and `Logger::with_patch(...)` for record transformation
+- feat: add record patch helpers such as `prefix_message(...)`, `set_target(...)`, `append_fields(...)`, `redact_field(...)`, `redact_fields(...)`, and `compose_patches(...)`
+- feat: add `QueuedSink[S]`, `queued_sink(...)`, and `Logger::with_queue(...)` for explicit queued delivery
+- feat: add `QueueOverflowPolicy` with `DropNewest` and `DropOldest` bounded-backlog strategies
+- feat: add configurable text formatter APIs `text_formatter(...)`, `format_text(...)`, and `format_json(...)`
+- feat: add formatter-based sinks `formatted_console_sink(...)`, `text_console_sink(...)`, `formatted_callback_sink(...)`, and `text_callback_sink(...)`
+- feat: add native-only `file_sink(...)` plus `native_files_supported()` backend capability detection
+- feat: add explicit file sink lifecycle helpers `FileSink::is_available()`, `flush()`, and `close()`
+
+### Test
+
+- test: cover manual flush behavior for buffered sink
+- test: cover auto flush when buffered records reach the configured limit
+- test: cover predicate-based forwarding for filter sink
+- test: cover chained `Logger::with_filter(...)` behavior with child target composition
+- test: cover helper-based filter composition for target, level, message, and field matching
+- test: cover record patch composition, target rewrite, message rewrite, field append, and field redaction
+- test: cover queue drain order, bounded backlog drop behavior, and chained `Logger::with_queue(...)` usage
+- test: cover formatter customization, formatter-only message mode, formatted callback output, and JSON formatter shape
+- test: cover backend-aware file sink availability and lifecycle behavior
+- test: keep callback-based composition validation with child target, context fields, and timestamp enabled
+
+### Example
+
+- docs: update `examples/basic` to demonstrate buffered sink usage
+- docs: update `examples/basic` to demonstrate filter sink usage
+- docs: update examples and README with helper-based chained logger filter usage
+- docs: update examples and README with record patch usage for redaction and enrichment
+- docs: update examples and README with explicit queued sink usage and overflow policy examples
+- docs: update examples and README with configurable text formatter usage
+- docs: update examples and README with native file sink usage and backend caveat
+- docs: keep README focused on public usage and move change tracking to `docs/changes/`

examples/basic/main.mbt

@@ -33,4 +33,71 @@ fn main {
     target="hook",
   )
   callback_logger.info("callback sink ready")
+
+  let pretty_logger = @lib.Logger::new(
+    @lib.text_console_sink(@lib.text_formatter(show_timestamp=false, separator=" | ")),
+    min_level=@lib.Level::Info,
+    target="pretty",
+  )
+  pretty_logger.info("custom text format", fields=[@lib.field("mode", "pretty")])
+
+  if @lib.native_files_supported() {
+    let file_logger = @lib.Logger::new(
+      @lib.file_sink("bitlogger-example.log"),
+      min_level=@lib.Level::Info,
+      target="file",
+    )
+    file_logger.info("native file sink ready", fields=[@lib.field("kind", "file")])
+    ignore(file_logger.sink.flush())
+    ignore(file_logger.sink.close())
+  }
+
+  let buffered = @lib.buffered_sink(@lib.console_sink(), flush_limit=2)
+  let buffered_logger = @lib.Logger::new(buffered, min_level=@lib.Level::Info, target="buffered")
+  buffered_logger.info("buffered one")
+  buffered_logger.info("buffered two")
+  buffered.flush()
+
+  let filtered = @lib.filter_sink(
+    @lib.console_sink(),
+    fn(rec) {
+      rec.target == "kept"
+    },
+  )
+  let kept_logger = @lib.Logger::new(filtered, min_level=@lib.Level::Info, target="kept")
+  let dropped_logger = @lib.Logger::new(filtered, min_level=@lib.Level::Info, target="dropped")
+  kept_logger.info("filter kept this")
+  dropped_logger.info("filter dropped this")
+
+  let filtered_logger = @lib.Logger::new(
+    @lib.console_sink(),
+    min_level=@lib.Level::Info,
+    target="service",
+  ).with_filter(@lib.all_of([
+    @lib.target_has_prefix("service"),
+    @lib.message_contains("kept"),
+  ]))
+  filtered_logger.info("logger filter dropped this")
+  filtered_logger.child("api").info("logger filter kept this")
+
+  let patched_logger = @lib.Logger::new(
+    @lib.console_sink(),
+    min_level=@lib.Level::Info,
+    target="auth",
+  ).with_patch(@lib.compose_patches([
+    @lib.prefix_message("[safe] "),
+    @lib.redact_fields(["token"]),
+    @lib.append_fields([@lib.field("service", "bitlogger")]),
+  ]))
+  patched_logger.info("login", fields=[@lib.field("user", "alice"), @lib.field("token", "secret")])
+
+  let queued_logger = @lib.Logger::new(
+    @lib.console_sink(),
+    min_level=@lib.Level::Info,
+    target="queue",
+  ).with_queue(max_pending=2, overflow=@lib.QueueOverflowPolicy::DropOldest)
+  queued_logger.info("queued one")
+  queued_logger.info("queued two")
+  queued_logger.info("queued three")
+  ignore(queued_logger.sink.flush())
 }