📝 document callback sink types

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.

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.

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)