From 27886e1eba30cf63d93aa3e472d50d352273e794 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 21:47:40 +0800 Subject: [PATCH] :memo: document wrapper sink types --- docs/api/buffered-sink-type.md | 77 +++++++++++++++++++++++++++++++++ docs/api/filter-sink-type.md | 75 ++++++++++++++++++++++++++++++++ docs/api/index.md | 4 ++ docs/api/patch-sink-type.md | 75 ++++++++++++++++++++++++++++++++ docs/api/queued-sink-type.md | 79 ++++++++++++++++++++++++++++++++++ 5 files changed, 310 insertions(+) create mode 100644 docs/api/buffered-sink-type.md create mode 100644 docs/api/filter-sink-type.md create mode 100644 docs/api/patch-sink-type.md create mode 100644 docs/api/queued-sink-type.md diff --git a/docs/api/buffered-sink-type.md b/docs/api/buffered-sink-type.md new file mode 100644 index 0000000..546dd6f --- /dev/null +++ b/docs/api/buffered-sink-type.md @@ -0,0 +1,77 @@ +--- +name: buffered-sink-type +group: api +category: sink +update-time: 20260613 +description: Public buffered sink type used for threshold-based synchronous batching over another sink. +key-word: + - sink + - buffer + - type + - public +--- + +## Buffered-sink-type + +`BufferedSink[S]` is the public buffering sink type used for threshold-based synchronous batching over another sink. It is the concrete sink type returned by `buffered_sink(...)` and preserves the wrapped sink type in its type parameter. + +### Interface + +```moonbit +pub struct BufferedSink[S] { + sink : S + buffer : Ref[Array[Record]] + flush_limit : Int +} +``` + +#### output + +- `BufferedSink[S]` - Public synchronous sink type that buffers records before forwarding them to the wrapped sink. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a public root struct, not a type alias. +- The current fields are `sink : S`, `buffer : Ref[Array[Record]]`, and `flush_limit : Int`. +- `buffered_sink(...)` constructs this type directly from a wrapped sink and flush threshold. +- The sink preserves the wrapped sink type `S`, which is useful when typed composition still matters after buffering is introduced. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed Buffered Sink Value + +When code should keep the concrete buffering sink type visible: +```moonbit +let sink : BufferedSink[ConsoleSink] = buffered_sink(console_sink(), flush_limit=2) +``` + +In this example, the sink value stays explicit and preserves the wrapped console sink type. + +#### When Need A Typed Logger With Synchronous Batching + +When logging should preserve the buffering sink type in the logger: +```moonbit +let logger : Logger[BufferedSink[ConsoleSink]] = Logger::new( + buffered_sink(console_sink(), flush_limit=2), + target="buffered", +) +``` + +In this example, the concrete buffered sink remains part of the logger type. + +### Error Case + +e.g.: +- `BufferedSink[S]` itself does not have a runtime failure mode. + +- Runtime behavior still depends on the wrapped sink `S`, and buffered records can remain pending if flushing never happens. + +### Notes + +1. Use `buffered_sink(...)` when you need a value of this type. + +2. Use `QueuedSink[S]` when overflow-aware queueing behavior is needed instead of simple buffering. diff --git a/docs/api/filter-sink-type.md b/docs/api/filter-sink-type.md new file mode 100644 index 0000000..5b417e4 --- /dev/null +++ b/docs/api/filter-sink-type.md @@ -0,0 +1,75 @@ +--- +name: filter-sink-type +group: api +category: sink +update-time: 20260613 +description: Public filter sink type used for predicate-based record forwarding over another sink. +key-word: + - sink + - filter + - type + - public +--- + +## Filter-sink-type + +`FilterSink[S]` is the public predicate wrapper sink type used for forwarding only matching records to another sink. It is the concrete sink type returned by `filter_sink(...)` and preserves the wrapped sink type in its type parameter. + +### Interface + +```moonbit +pub struct FilterSink[S] { + sink : S + predicate : (Record) -> Bool +} +``` + +#### output + +- `FilterSink[S]` - Public synchronous sink type that forwards only predicate-matching records to the wrapped sink. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a public root struct, not a type alias. +- The current fields are `sink : S` and `predicate : (Record) -> Bool`. +- `filter_sink(...)` constructs this type directly from a wrapped sink and predicate. +- The sink preserves the wrapped sink type `S`, which is useful when typed composition still matters after filtering is introduced. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed Predicate-filtering Sink Value + +When code should keep the concrete filter wrapper sink type visible: +```moonbit +let sink : FilterSink[ConsoleSink] = filter_sink(console_sink(), fn(rec) { rec.target == "kept" }) +``` + +In this example, the sink value stays explicit and preserves the wrapped console sink type. + +#### When Need A Typed Logger With Sink-level Filtering + +When logging should preserve the filter wrapper sink type in the logger: +```moonbit +let logger : Logger[FilterSink[ConsoleSink]] = Logger::new( + filter_sink(console_sink(), fn(rec) { rec.level == Level::Warn }), +) +``` + +In this example, the concrete filter sink remains part of the logger type. + +### Error Case + +e.g.: +- `FilterSink[S]` itself does not have a runtime failure mode. + +- Runtime behavior still depends on the wrapped sink `S`, and record selection errors come from the supplied predicate rather than the type itself. + +### Notes + +1. Use `filter_sink(...)` when you need a value of this type. + +2. Use `PatchSink[S]` when records should be rewritten rather than accepted or rejected. diff --git a/docs/api/index.md b/docs/api/index.md index 1f1ee22..1329ace 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -117,10 +117,14 @@ BitLogger API navigation. - [split-sink-type.md](./split-sink-type.md) - [split-by-level.md](./split-by-level.md) - [buffered-sink.md](./buffered-sink.md) +- [buffered-sink-type.md](./buffered-sink-type.md) - [queued-sink.md](./queued-sink.md) +- [queued-sink-type.md](./queued-sink-type.md) - [queue-overflow-policy.md](./queue-overflow-policy.md) - [filter-sink.md](./filter-sink.md) +- [filter-sink-type.md](./filter-sink-type.md) - [patch-sink.md](./patch-sink.md) +- [patch-sink-type.md](./patch-sink-type.md) - [file-sink.md](./file-sink.md) - [native-files-supported.md](./native-files-supported.md) - [file-rotation.md](./file-rotation.md) diff --git a/docs/api/patch-sink-type.md b/docs/api/patch-sink-type.md new file mode 100644 index 0000000..8907614 --- /dev/null +++ b/docs/api/patch-sink-type.md @@ -0,0 +1,75 @@ +--- +name: patch-sink-type +group: api +category: sink +update-time: 20260613 +description: Public patch sink type used for record-rewriting forwarding over another sink. +key-word: + - sink + - patch + - type + - public +--- + +## Patch-sink-type + +`PatchSink[S]` is the public record-rewriting sink type used for forwarding patched records to another sink. It is the concrete sink type returned by `patch_sink(...)` and preserves the wrapped sink type in its type parameter. + +### Interface + +```moonbit +pub struct PatchSink[S] { + sink : S + patch : RecordPatch +} +``` + +#### output + +- `PatchSink[S]` - Public synchronous sink type that rewrites records before forwarding them to the wrapped sink. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a public root struct, not a type alias. +- The current fields are `sink : S` and `patch : RecordPatch`. +- `patch_sink(...)` constructs this type directly from a wrapped sink and patch function. +- The sink preserves the wrapped sink type `S`, which is useful when typed composition still matters after record rewriting is introduced. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed Record-rewriting Sink Value + +When code should keep the concrete patch wrapper sink type visible: +```moonbit +let sink : PatchSink[ConsoleSink] = patch_sink(console_sink(), prefix_message("[safe] ")) +``` + +In this example, the sink value stays explicit and preserves the wrapped console sink type. + +#### When Need A Typed Logger With Sink-level Patching + +When logging should preserve the patch wrapper sink type in the logger: +```moonbit +let logger : Logger[PatchSink[ConsoleSink]] = Logger::new( + patch_sink(console_sink(), set_target("audit")), +) +``` + +In this example, the concrete patch sink remains part of the logger type. + +### Error Case + +e.g.: +- `PatchSink[S]` itself does not have a runtime failure mode. + +- Runtime behavior still depends on the wrapped sink `S`, and semantic rewrite mistakes come from the supplied patch function rather than the type itself. + +### Notes + +1. Use `patch_sink(...)` when you need a value of this type. + +2. Use `FilterSink[S]` when records should be conditionally dropped rather than rewritten. diff --git a/docs/api/queued-sink-type.md b/docs/api/queued-sink-type.md new file mode 100644 index 0000000..a0ef515 --- /dev/null +++ b/docs/api/queued-sink-type.md @@ -0,0 +1,79 @@ +--- +name: queued-sink-type +group: api +category: sink +update-time: 20260613 +description: Public queued sink type used for explicit synchronous queueing over another sink. +key-word: + - sink + - queue + - type + - public +--- + +## Queued-sink-type + +`QueuedSink[S]` is the public queue wrapper sink type used for explicit synchronous queueing over another sink. It is the concrete sink type returned by `queued_sink(...)` and preserves the wrapped sink type in its type parameter. + +### Interface + +```moonbit +pub struct QueuedSink[S] { + sink : S + queue : @queue.Queue[Record] + max_pending : Int + overflow : QueueOverflowPolicy + dropped_count : Ref[Int] +} +``` + +#### output + +- `QueuedSink[S]` - Public synchronous sink type that queues records before they are drained to the wrapped sink. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a public root struct, not a type alias. +- The current fields are `sink : S`, `queue : @queue.Queue[Record]`, `max_pending : Int`, `overflow : QueueOverflowPolicy`, and `dropped_count : Ref[Int]`. +- `queued_sink(...)` constructs this type directly from a wrapped sink and queue policy. +- The sink preserves the wrapped sink type `S`, which is useful when typed composition still matters after queueing is introduced. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed Queued Sink Value + +When code should keep the concrete queue wrapper sink type visible: +```moonbit +let sink : QueuedSink[ConsoleSink] = queued_sink(console_sink(), max_pending=4) +``` + +In this example, the sink value stays explicit and preserves the wrapped console sink type. + +#### When Need A Typed Logger With Explicit Queueing + +When logging should preserve the queue wrapper sink type in the logger: +```moonbit +let logger : Logger[QueuedSink[ConsoleSink]] = Logger::new( + queued_sink(console_sink(), max_pending=2, overflow=QueueOverflowPolicy::DropOldest), + target="queue", +) +``` + +In this example, the concrete queued sink remains part of the logger type. + +### Error Case + +e.g.: +- `QueuedSink[S]` itself does not have a runtime failure mode. + +- Runtime behavior still depends on the wrapped sink `S`, and records may be dropped when the queue reaches the configured bound. + +### Notes + +1. Use `queued_sink(...)` when you need a value of this type. + +2. Use `BufferedSink[S]` when simple threshold buffering is enough and overflow policy is unnecessary.