📝 document routing sink types

docs/api/fanout-sink-type.md

@@ -0,0 +1,76 @@
+---
+name: fanout-sink-type
+group: api
+category: sink
+update-time: 20260613
+description: Public fanout sink type used for duplicating records to two underlying sinks.
+key-word:
+    - sink
+    - fanout
+    - type
+    - public
+---
+
+## Fanout-sink-type
+
+`FanoutSink[A, B]` is the public routing sink type used for duplicating each record to two underlying sinks. It is the concrete sink type returned by `fanout_sink(...)` and preserves both wrapped sink types in its type parameters.
+
+### Interface
+
+```moonbit
+pub struct FanoutSink[A, B] {
+  left : A
+  right : B
+}
+```
+
+#### output
+
+- `FanoutSink[A, B]` - Public synchronous sink type that forwards each record to both wrapped sinks.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a public root struct, not a type alias.
+- The current fields are `left : A` and `right : B`.
+- `fanout_sink(...)` constructs this type directly from two sink values.
+- The sink preserves both wrapped sink types in the public type, which is useful when typed composition still matters after duplication is introduced.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Dual-output Sink Value
+
+When code should keep the concrete duplication sink type visible:
+```moonbit
+let sink : FanoutSink[ConsoleSink, JsonConsoleSink] = fanout_sink(console_sink(), json_console_sink())
+```
+
+In this example, the sink value stays explicit and preserves both destination sink types.
+
+#### When Need A Typed Logger With Duplicated Delivery
+
+When logging should preserve the fanout sink type in the logger:
+```moonbit
+let logger : Logger[FanoutSink[ConsoleSink, JsonConsoleSink]] = Logger::new(
+  fanout_sink(console_sink(), json_console_sink()),
+  target="dual",
+)
+```
+
+In this example, the concrete duplication sink remains part of the logger type.
+
+### Error Case
+
+e.g.:
+- `FanoutSink[A, B]` itself does not have a runtime failure mode.
+
+- Runtime behavior still depends on both wrapped sinks, so any sink-specific limitations remain unchanged behind the fanout wrapper.
+
+### Notes
+
+1. Use `fanout_sink(...)` when you need a value of this type.
+
+2. Use `SplitSink[A, B]` when records should go to one side conditionally instead of always going to both sides.

docs/api/index.md

@@ -112,7 +112,9 @@ BitLogger API navigation.
 - [formatted-callback-sink-type.md](./formatted-callback-sink-type.md)
 - [text-callback-sink.md](./text-callback-sink.md)
 - [fanout-sink.md](./fanout-sink.md)
+- [fanout-sink-type.md](./fanout-sink-type.md)
 - [split-sink.md](./split-sink.md)
+- [split-sink-type.md](./split-sink-type.md)
 - [split-by-level.md](./split-by-level.md)
 - [buffered-sink.md](./buffered-sink.md)
 - [queued-sink.md](./queued-sink.md)

docs/api/split-sink-type.md

@@ -0,0 +1,81 @@
+---
+name: split-sink-type
+group: api
+category: sink
+update-time: 20260613
+description: Public split sink type used for routing records to one of two underlying sinks with a predicate.
+key-word:
+    - sink
+    - split
+    - type
+    - public
+---
+
+## Split-sink-type
+
+`SplitSink[A, B]` is the public routing sink type used for sending each record to one of two underlying sinks based on a predicate. It is the concrete sink type returned by both `split_sink(...)` and `split_by_level(...)`, and it preserves both wrapped sink types in its type parameters.
+
+### Interface
+
+```moonbit
+pub struct SplitSink[A, B] {
+  left : A
+  right : B
+  predicate : (Record) -> Bool
+}
+```
+
+#### output
+
+- `SplitSink[A, B]` - Public synchronous sink type that routes each record to one of two wrapped sinks.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a public root struct, not a type alias.
+- The current fields are `left : A`, `right : B`, and `predicate : (Record) -> Bool`.
+- `split_sink(...)` constructs this type directly from two sink values and a predicate.
+- `split_by_level(...)` also returns this same type after building a level-based predicate wrapper.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Typed Predicate-routing Sink Value
+
+When code should keep the concrete routing sink type visible:
+```moonbit
+let sink : SplitSink[ConsoleSink, JsonConsoleSink] = split_sink(
+  console_sink(),
+  json_console_sink(),
+  fn(rec) { rec.target == "audit" },
+)
+```
+
+In this example, the sink value stays explicit and preserves both destination sink types plus the routing behavior.
+
+#### When Need A Typed Logger With Conditional Delivery
+
+When logging should preserve the split sink type in the logger:
+```moonbit
+let logger : Logger[SplitSink[ConsoleSink, JsonConsoleSink]] = Logger::new(
+  split_by_level(console_sink(), json_console_sink(), min_level=Level::Warn),
+  target="route",
+)
+```
+
+In this example, the concrete conditional routing sink remains part of the logger type.
+
+### Error Case
+
+e.g.:
+- `SplitSink[A, B]` itself does not have a runtime failure mode.
+
+- Routing behavior still depends on the stored predicate and both wrapped sinks, so misrouting or sink-specific limitations remain outside the split type itself.
+
+### Notes
+
+1. Use `split_sink(...)` or `split_by_level(...)` when you need a value of this type.
+
+2. Use `FanoutSink[A, B]` when each record should always be delivered to both sides instead of one side conditionally.