diff --git a/docs/api/index.md b/docs/api/index.md index 0634e9f..61c23e7 100644 --- a/docs/api/index.md +++ b/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) diff --git a/docs/api/record-formatter.md b/docs/api/record-formatter.md new file mode 100644 index 0000000..c7e1d5e --- /dev/null +++ b/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. diff --git a/docs/api/record-patch.md b/docs/api/record-patch.md new file mode 100644 index 0000000..80e842d --- /dev/null +++ b/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. diff --git a/docs/api/record-predicate.md b/docs/api/record-predicate.md new file mode 100644 index 0000000..fa29aa2 --- /dev/null +++ b/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.