📝 document public function type aliases

docs/api/index.md

@@ -60,6 +60,7 @@ BitLogger API navigation.
 ## Formatter and fields
 
 - [field.md](./field.md)
+- [record-formatter.md](./record-formatter.md)
 - [text-style.md](./text-style.md)
 - [style-tag-registry.md](./style-tag-registry.md)
 - [default-style-tag-registry.md](./default-style-tag-registry.md)
@@ -108,6 +109,8 @@ BitLogger API navigation.
 
 ## Predicates and helpers
 
+- [record-predicate.md](./record-predicate.md)
+- [record-patch.md](./record-patch.md)
 - [level-at-least.md](./level-at-least.md)
 - [target-is.md](./target-is.md)
 - [target-has-prefix.md](./target-has-prefix.md)

docs/api/record-formatter.md

@@ -0,0 +1,73 @@
+---
+name: record-formatter
+group: api
+category: helper
+update-time: 20260613
+description: Public formatter function type used to render records into strings.
+key-word:
+    - formatter
+    - record
+    - text
+    - public
+---
+
+## Record-formatter
+
+`RecordFormatter` is the public function type used for rendering a `Record` into a `String`. It is the shared shape behind helpers such as `format_text(...)`, custom formatter closures, and sinks that accept formatter functions.
+
+### Interface
+
+```moonbit
+pub type RecordFormatter = @utils.RecordFormatter
+```
+
+#### output
+
+- `RecordFormatter` - A function type equivalent to `(Record) -> String`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a new runtime wrapper.
+- Any function matching `(Record) -> String` can be used wherever a `RecordFormatter` is expected.
+- Formatter values are used by `formatted_console_sink(...)`, `formatted_callback_sink(...)`, and text-formatting helpers.
+- The alias exists to make rendering-oriented APIs clearer and easier to read in public signatures.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Custom Formatting Function
+
+When a sink should render records with custom output rules:
+```moonbit
+let formatter : RecordFormatter = fn(rec) { rec.level.label() + ": " + rec.message }
+let sink = formatted_console_sink(formatter)
+```
+
+In this example, the alias makes the custom renderer shape explicit.
+
+#### When Pass A Formatter Through Higher-level APIs
+
+When application code should accept any formatter function:
+```moonbit
+fn make_sink(formatter : RecordFormatter) -> FormattedConsoleSink {
+  formatted_console_sink(formatter)
+}
+```
+
+In this example, the alias communicates that the parameter is a record-to-string renderer.
+
+### Error Case
+
+e.g.:
+- A formatter that omits important fields or level information can make output harder to interpret.
+
+- A formatter that performs heavy work on every record can add noticeable runtime cost.
+
+### Notes
+
+1. Use the alias when function signatures should communicate rendering intent clearly.
+
+2. `text_formatter(...)` plus `format_text(...)` is usually the better default for configurable human-readable output.

docs/api/record-patch.md

@@ -0,0 +1,74 @@
+---
+name: record-patch
+group: api
+category: helper
+update-time: 20260613
+description: Public patch function type used for record transformation before sink write.
+key-word:
+    - patch
+    - record
+    - transform
+    - public
+---
+
+## Record-patch
+
+`RecordPatch` is the public function type used for record transformation. It represents any function that receives a `Record` and returns a new `Record`, and it is the shared shape behind helpers such as `set_target(...)`, `prefix_message(...)`, and `append_fields(...)`.
+
+### Interface
+
+```moonbit
+pub type RecordPatch = @utils.RecordPatch
+```
+
+#### output
+
+- `RecordPatch` - A function type equivalent to `(Record) -> Record`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a new runtime wrapper.
+- Any function matching `(Record) -> Record` can be used wherever a `RecordPatch` is expected.
+- Patches are used by `Logger::with_patch(...)`, `patch_sink(...)`, and helper constructors in `patchers.mbt`.
+- The alias exists to make record-rewrite APIs clearer and easier to read in public signatures.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Custom Record Rewrite Step
+
+When a logger should rewrite each record before sink write:
+```moonbit
+let patch : RecordPatch = fn(rec) { rec.with_message("[custom] " + rec.message) }
+let logger = Logger::new(console_sink()).with_patch(patch)
+```
+
+In this example, the alias makes the custom transformation shape explicit.
+
+#### When Compose Existing Patch Helpers
+
+When several reusable transformations should be combined:
+```moonbit
+let patch : RecordPatch = compose_patches([
+  set_target("service.worker"),
+  prefix_message("[worker] "),
+])
+```
+
+In this example, the alias describes the common type returned by the patch helper constructors.
+
+### Error Case
+
+e.g.:
+- A patch that drops important fields or overwrites the target can change downstream observability unexpectedly.
+
+- A patch that allocates heavily or copies too much data can add cost to every write path.
+
+### Notes
+
+1. Use the alias when function signatures should communicate transformation intent clearly.
+
+2. Helper constructors in `patchers.mbt` are usually preferable to handwritten patches for common cases.

docs/api/record-predicate.md

@@ -0,0 +1,74 @@
+---
+name: record-predicate
+group: api
+category: helper
+update-time: 20260613
+description: Public predicate function type used for logger filtering and record selection.
+key-word:
+    - predicate
+    - filter
+    - record
+    - public
+---
+
+## Record-predicate
+
+`RecordPredicate` is the public function type used for record filtering. It represents any function that receives a `Record` and returns `Bool`, and it is the shared shape behind helpers such as `level_at_least(...)`, `target_is(...)`, and `filter_sink(...)`.
+
+### Interface
+
+```moonbit
+pub type RecordPredicate = @utils.RecordPredicate
+```
+
+#### output
+
+- `RecordPredicate` - A function type equivalent to `(Record) -> Bool`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This is a type alias, not a new runtime wrapper.
+- Any function matching `(Record) -> Bool` can be used wherever a `RecordPredicate` is expected.
+- Predicates are used by `Logger::with_filter(...)`, `filter_sink(...)`, and helper constructors in `filters.mbt`.
+- The alias exists to make filtering APIs clearer and easier to read in public signatures.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need A Custom Logger Filter
+
+When a logger should only accept records that match local rules:
+```moonbit
+let predicate : RecordPredicate = fn(rec) { rec.level.priority() >= Level::Warn.priority() }
+let logger = Logger::new(console_sink()).with_filter(predicate)
+```
+
+In this example, the alias makes the custom filter shape explicit.
+
+#### When Compose Existing Predicate Helpers
+
+When several reusable filters should be combined:
+```moonbit
+let predicate : RecordPredicate = all_of([
+  target_has_prefix("service"),
+  not_(message_contains("ignore")),
+])
+```
+
+In this example, the alias describes the common type returned by the helper constructors.
+
+### Error Case
+
+e.g.:
+- A predicate that always returns `false` is valid but will suppress all matching writes.
+
+- A predicate that is expensive to evaluate can add avoidable cost to every filtered record.
+
+### Notes
+
+1. Use the alias when function signatures should communicate filtering intent clearly.
+
+2. Helper constructors in `filters.mbt` are usually preferable to handwritten predicates for common cases.