From 1a30562a28be4667f408d50121f64eb8e2980f27 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 21:42:30 +0800 Subject: [PATCH] :memo: document callback sink types --- docs/api/callback-sink-type.md | 72 +++++++++++++++++++++++ docs/api/formatted-callback-sink-type.md | 75 ++++++++++++++++++++++++ docs/api/index.md | 2 + 3 files changed, 149 insertions(+) create mode 100644 docs/api/callback-sink-type.md create mode 100644 docs/api/formatted-callback-sink-type.md diff --git a/docs/api/callback-sink-type.md b/docs/api/callback-sink-type.md new file mode 100644 index 0000000..f36227b --- /dev/null +++ b/docs/api/callback-sink-type.md @@ -0,0 +1,72 @@ +--- +name: callback-sink-type +group: api +category: sink +update-time: 20260613 +description: Public callback sink type used for forwarding structured records to user code. +key-word: + - sink + - callback + - type + - public +--- + +## Callback-sink-type + +`CallbackSink` is the public callback sink type used for forwarding structured `Record` values to user code. It is the concrete sink type returned by `callback_sink(...)` and is intended for tests, adapters, and custom integrations that want raw record access. + +### Interface + +```moonbit +pub struct CallbackSink { + callback : (Record) -> Unit +} +``` + +#### output + +- `CallbackSink` - Public synchronous sink type that forwards full `Record` values to a stored callback. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a public root struct, not a type alias. +- The current field is `callback : (Record) -> Unit`. +- `callback_sink(...)` constructs this type directly from a record callback. +- Unlike `FormattedCallbackSink`, this sink preserves full structured record access instead of converting records into text first. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed Structured Callback Sink Value + +When code should keep the concrete record-callback sink type visible: +```moonbit +let sink : CallbackSink = callback_sink(fn(rec) { println(rec.message) }) +``` + +In this example, the sink value stays explicit and preserves direct access to structured record data. + +#### When Need A Typed Callback-backed Logger + +When logging should preserve the raw-record callback sink type in the logger: +```moonbit +let logger : Logger[CallbackSink] = Logger::new(callback_sink(fn(rec) { println(rec.target) })) +``` + +In this example, the concrete callback sink remains part of the logger type. + +### Error Case + +e.g.: +- `CallbackSink` itself does not have a runtime failure mode. + +- Behavior inside the stored callback is fully user-defined, so failures there are outside the sink type's own API contract. + +### Notes + +1. Use `callback_sink(...)` when you need a value of this type. + +2. Use `FormattedCallbackSink` when the destination expects final rendered text rather than full `Record` values. diff --git a/docs/api/formatted-callback-sink-type.md b/docs/api/formatted-callback-sink-type.md new file mode 100644 index 0000000..a0238f8 --- /dev/null +++ b/docs/api/formatted-callback-sink-type.md @@ -0,0 +1,75 @@ +--- +name: formatted-callback-sink-type +group: api +category: sink +update-time: 20260613 +description: Public formatted callback sink type used for RecordFormatter-driven text delivery to user callbacks. +key-word: + - sink + - callback + - formatter + - public +--- + +## Formatted-callback-sink-type + +`FormattedCallbackSink` is the public callback sink type used for formatter-driven text delivery. It is the concrete sink type returned by both `formatted_callback_sink(...)` and `text_callback_sink(...)`, and it stores the rendering function and the string callback used for each record. + +### Interface + +```moonbit +pub struct FormattedCallbackSink { + formatter : RecordFormatter + callback : (String) -> Unit +} +``` + +#### output + +- `FormattedCallbackSink` - Public synchronous sink type that renders each record through a stored formatter and forwards the text to a stored callback. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This is a public root struct, not a type alias. +- The current fields are `formatter : RecordFormatter` and `callback : (String) -> Unit`. +- `formatted_callback_sink(...)` constructs this type directly from a formatter function and string callback. +- `text_callback_sink(...)` also returns this same type after adapting a `TextFormatter` into a `RecordFormatter`. + +### How to Use + +Here are some specific examples provided. + +#### When Need A Typed Formatter-driven Callback Sink Value + +When code should keep the concrete rendered-text callback sink type visible: +```moonbit +let sink : FormattedCallbackSink = formatted_callback_sink(fn(rec) { rec.message }, fn(line) { println(line) }) +``` + +In this example, the sink value stays explicit and preserves the formatter-driven text delivery path. + +#### When Need A Typed Text-callback Logger + +When logging should preserve the rendered-text callback sink type in the logger: +```moonbit +let logger : Logger[FormattedCallbackSink] = Logger::new( + text_callback_sink(text_formatter(show_timestamp=false), fn(line) { println(line) }), +) +``` + +In this example, the concrete formatted callback sink remains part of the logger type. + +### Error Case + +e.g.: +- `FormattedCallbackSink` itself does not have a runtime failure mode. + +- Output readability, callback behavior, and runtime cost still depend on the stored formatter and callback functions. + +### Notes + +1. Use `formatted_callback_sink(...)` or `text_callback_sink(...)` when you need a value of this type. + +2. Use `CallbackSink` when the destination should receive full `Record` values instead of rendered text. diff --git a/docs/api/index.md b/docs/api/index.md index 356cfac..44078bd 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -107,7 +107,9 @@ BitLogger API navigation. - [formatted-console-sink-type.md](./formatted-console-sink-type.md) - [text-console-sink.md](./text-console-sink.md) - [callback-sink.md](./callback-sink.md) +- [callback-sink-type.md](./callback-sink-type.md) - [formatted-callback-sink.md](./formatted-callback-sink.md) +- [formatted-callback-sink-type.md](./formatted-callback-sink-type.md) - [text-callback-sink.md](./text-callback-sink.md) - [fanout-sink.md](./fanout-sink.md) - [split-sink.md](./split-sink.md)