diff --git a/docs/api/fanout-sink-type.md b/docs/api/fanout-sink-type.md new file mode 100644 index 0000000..15faf26 --- /dev/null +++ b/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. diff --git a/docs/api/index.md b/docs/api/index.md index 44078bd..1f1ee22 100644 --- a/docs/api/index.md +++ b/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) diff --git a/docs/api/split-sink-type.md b/docs/api/split-sink-type.md new file mode 100644 index 0000000..6c31d96 --- /dev/null +++ b/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.