📝 document formatted sink constructors

docs/api/formatted-callback-sink.md

@@ -0,0 +1,81 @@
+---
+name: formatted-callback-sink
+group: api
+category: sink
+update-time: 20260613
+description: Create a callback sink from a low-level RecordFormatter function and string callback.
+key-word:
+    - sink
+    - callback
+    - formatter
+    - public
+---
+
+## Formatted-callback-sink
+
+Create a callback sink from a `RecordFormatter` and a string callback. This is the low-level text-delivery constructor for integrations that already have custom record-to-string formatting logic and want the final rendered text in a callback.
+
+### Interface
+
+```moonbit
+pub fn formatted_callback_sink(
+  formatter : RecordFormatter,
+  callback : (String) -> Unit,
+) -> FormattedCallbackSink {
+```
+
+#### input
+
+- `formatter : RecordFormatter` - Function used to render each record into a final string.
+- `callback : (String) -> Unit` - Function receiving the rendered string.
+
+#### output
+
+- `FormattedCallbackSink` - Callback sink that forwards formatter output as text.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper stores both the provided formatter and callback directly inside the sink.
+- The callback receives exactly the string returned by the formatter.
+- It is lower-level than `text_callback_sink(...)` because it works with arbitrary `RecordFormatter` functions instead of `TextFormatter` values.
+- Use it when formatting logic is already expressed as code rather than formatter configuration data.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need Custom Rendered Text In A Callback Integration
+
+When an adapter should receive a hand-formatted line instead of a structured record:
+```moonbit
+let formatter : RecordFormatter = fn(rec) { "[" + rec.level.label() + "] " + rec.message }
+let sink = formatted_callback_sink(formatter, fn(line) { println(line) })
+```
+
+In this example, the callback receives exactly the custom rendered text.
+
+#### When Already Working With Shared RecordFormatter Values
+
+When formatter creation already happened elsewhere and should be reused directly:
+```moonbit
+fn make_sink(formatter : RecordFormatter) -> FormattedCallbackSink {
+  formatted_callback_sink(formatter, fn(line) { println(line) })
+}
+```
+
+In this example, the low-level sink constructor keeps the integration in terms of formatter functions and final text callbacks.
+
+### Error Case
+
+e.g.:
+- If structured field access is required inside the callback, `callback_sink(...)` is the better API because it forwards full `Record` values.
+
+- If a configurable text formatting policy is preferred over a code-defined function, `text_callback_sink(...)` is usually the better API.
+
+### Notes
+
+1. Use this helper when the formatter is already a `RecordFormatter` and the destination expects final text.
+
+2. Use `text_callback_sink(...)` when the source formatting policy is a `TextFormatter` value.

docs/api/formatted-console-sink.md

@@ -0,0 +1,77 @@
+---
+name: formatted-console-sink
+group: api
+category: sink
+update-time: 20260613
+description: Create a console sink from a low-level RecordFormatter function.
+key-word:
+    - sink
+    - console
+    - formatter
+    - public
+---
+
+## Formatted-console-sink
+
+Create a console sink from a `RecordFormatter`. This is the low-level console output constructor for cases where code already has a record-to-string formatter function and does not want to go through `TextFormatter` first.
+
+### Interface
+
+```moonbit
+pub fn formatted_console_sink(formatter : RecordFormatter) -> FormattedConsoleSink {
+```
+
+#### input
+
+- `formatter : RecordFormatter` - Function used to render each record into a final string.
+
+#### output
+
+- `FormattedConsoleSink` - Console sink that prints the formatter output for each record.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper stores the provided formatter directly inside the sink.
+- The sink prints exactly the string returned by the formatter.
+- It is lower-level than `text_console_sink(...)` because it works with arbitrary `RecordFormatter` functions instead of `TextFormatter` values.
+- Use it when formatting logic is already expressed as code rather than formatter configuration data.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Custom Record-to-string Console Renderer
+
+When console output should come from a hand-written formatting function:
+```moonbit
+let formatter : RecordFormatter = fn(rec) { rec.level.label() + ": " + rec.message }
+let logger = Logger::new(formatted_console_sink(formatter), target="fmt")
+```
+
+In this example, the sink prints exactly the custom formatter output.
+
+#### When Already Working With RecordFormatter Values
+
+When formatter creation already happened elsewhere and should be reused directly:
+```moonbit
+fn make_sink(formatter : RecordFormatter) -> FormattedConsoleSink {
+  formatted_console_sink(formatter)
+}
+```
+
+In this example, the low-level sink constructor avoids converting through `TextFormatter` first.
+
+### Error Case
+
+e.g.:
+- If the formatter omits useful fields or target information, console output may become harder to interpret.
+
+- If a configurable text formatting policy is preferred over a code-defined function, `text_console_sink(...)` is usually the better API.
+
+### Notes
+
+1. Use this helper when the formatter is already a `RecordFormatter`.
+
+2. Use `text_console_sink(...)` when the source formatting policy is a `TextFormatter` value.

docs/api/index.md

@@ -101,8 +101,10 @@ BitLogger API navigation.
 
 - [console-sink.md](./console-sink.md)
 - [json-console-sink.md](./json-console-sink.md)
+- [formatted-console-sink.md](./formatted-console-sink.md)
 - [text-console-sink.md](./text-console-sink.md)
 - [callback-sink.md](./callback-sink.md)
+- [formatted-callback-sink.md](./formatted-callback-sink.md)
 - [text-callback-sink.md](./text-callback-sink.md)
 - [fanout-sink.md](./fanout-sink.md)
 - [split-sink.md](./split-sink.md)