From e01eed5c44caa17ea55c1d52e0f72f17d4877b60 Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 21:08:25 +0800 Subject: [PATCH] :memo: document record transformation apis --- docs/api/index.md | 3 ++ docs/api/record-with-fields.md | 77 +++++++++++++++++++++++++++++++++ docs/api/record-with-message.md | 76 ++++++++++++++++++++++++++++++++ docs/api/record-with-target.md | 76 ++++++++++++++++++++++++++++++++ 4 files changed, 232 insertions(+) create mode 100644 docs/api/record-with-fields.md create mode 100644 docs/api/record-with-message.md create mode 100644 docs/api/record-with-target.md diff --git a/docs/api/index.md b/docs/api/index.md index 407f8bd..684df5d 100644 --- a/docs/api/index.md +++ b/docs/api/index.md @@ -81,6 +81,9 @@ BitLogger API navigation. - [record.md](./record.md) - [record-new.md](./record-new.md) +- [record-with-target.md](./record-with-target.md) +- [record-with-message.md](./record-with-message.md) +- [record-with-fields.md](./record-with-fields.md) - [level.md](./level.md) - [level-priority.md](./level-priority.md) - [level-label.md](./level-label.md) diff --git a/docs/api/record-with-fields.md b/docs/api/record-with-fields.md new file mode 100644 index 0000000..8c4c680 --- /dev/null +++ b/docs/api/record-with-fields.md @@ -0,0 +1,77 @@ +--- +name: record-with-fields +group: api +category: record +update-time: 20260613 +description: Return a copy of a record with a replaced field array. +key-word: + - record + - fields + - transform + - public +--- + +## Record-with-fields + +Return a copy of a `Record` with a different field array. This helper is the narrowest way to replace structured metadata while preserving the record's level, message, timestamp, and target. + +### Interface + +```moonbit +pub fn Record::with_fields(self : Record, fields : Array[Field]) -> Record {} +``` + +#### input + +- `self : Record` - Base record whose field array should be replaced. +- `fields : Array[Field]` - New structured field list for the returned record. + +#### output + +- `Record` - New record value carrying the updated fields. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This helper returns a new record value instead of mutating the original one. +- Only the `fields` array is replaced. +- `level`, `message`, `timestamp_ms`, and `target` are preserved. +- This is useful when one record should swap its metadata wholesale rather than append more fields. + +### How to Use + +Here are some specific examples provided. + +#### When Need To Replace Metadata Entirely + +When one record should keep its message and severity but use a new field set: +```moonbit +let rec = Record::new(Level::Info, "accepted", fields=[field("user", "alice")]) +let sanitized = rec.with_fields([field("user", "***")]) +``` + +In this example, the original field array is replaced rather than extended. + +#### When Need To Clear Per-record Fields + +When structured metadata should be removed from one value: +```moonbit +let rec = Record::new(Level::Warn, "retry", fields=[field("job", "42")]) +let plain = rec.with_fields([]) +``` + +In this example, the returned record keeps the same event identity but carries no fields. + +### Error Case + +e.g.: +- If `fields` is empty, the returned record is still valid and simply carries no structured metadata. + +- If code should append or merge fields instead of replacing them, `append_fields(...)` or a custom patch is the better fit. + +### Notes + +1. Use this helper when one record should swap its entire field array. + +2. Use `append_fields(...)` when enrichment should preserve the original field list and add more entries afterward. diff --git a/docs/api/record-with-message.md b/docs/api/record-with-message.md new file mode 100644 index 0000000..733c77c --- /dev/null +++ b/docs/api/record-with-message.md @@ -0,0 +1,76 @@ +--- +name: record-with-message +group: api +category: record +update-time: 20260613 +description: Return a copy of a record with a replaced message field. +key-word: + - record + - message + - transform + - public +--- + +## Record-with-message + +Return a copy of a `Record` with a different `message`. This helper is the narrowest way to rewrite the visible event text while preserving the rest of the structured event data. + +### Interface + +```moonbit +pub fn Record::with_message(self : Record, message : String) -> Record {} +``` + +#### input + +- `self : Record` - Base record whose message should be replaced. +- `message : String` - New message text for the returned record. + +#### output + +- `Record` - New record value carrying the updated message. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This helper returns a new record value instead of mutating the original one. +- Only the `message` field is replaced. +- `level`, `timestamp_ms`, `target`, and `fields` are preserved. +- This is useful for adapters, tests, or explicit value-level rewriting before formatting or sink dispatch. + +### How to Use + +Here are some specific examples provided. + +#### When Need To Rewrite One Event Message + +When one record should keep its metadata but use different visible text: +```moonbit +let rec = Record::new(Level::Error, "raw failure", target="bridge") +let next = rec.with_message("dispatch failed") +``` + +In this example, the new message is applied without rebuilding the rest of the record manually. + +#### When Need To Normalize Message Text In Tests + +When one test record should be adapted to a different wording: +```moonbit +let rec = Record::new(Level::Info, "ok").with_message("started") +``` + +In this example, the helper keeps the change focused on one field. + +### Error Case + +e.g.: +- If `message` is empty, the returned record is still valid and simply carries an empty message string. + +- If the same rewrite should be reusable across many records, `prefix_message(...)` or a custom `RecordPatch` may be a better fit. + +### Notes + +1. Use this helper for one-off value-level message replacement. + +2. Use patch helpers when message rewriting should participate in a reusable logger pipeline. diff --git a/docs/api/record-with-target.md b/docs/api/record-with-target.md new file mode 100644 index 0000000..e74b959 --- /dev/null +++ b/docs/api/record-with-target.md @@ -0,0 +1,76 @@ +--- +name: record-with-target +group: api +category: record +update-time: 20260613 +description: Return a copy of a record with a replaced target field. +key-word: + - record + - target + - transform + - public +--- + +## Record-with-target + +Return a copy of a `Record` with a different `target`. This helper is the narrowest way to retarget one record value while preserving its level, message, timestamp, and fields. + +### Interface + +```moonbit +pub fn Record::with_target(self : Record, target : String) -> Record {} +``` + +#### input + +- `self : Record` - Base record whose target should be replaced. +- `target : String` - New target value for the returned record. + +#### output + +- `Record` - New record value carrying the updated target. + +### Explanation + +Detailed rules explaining key parameters and behaviors + +- This helper returns a new record value instead of mutating the original one. +- Only the `target` field is replaced. +- `level`, `message`, `timestamp_ms`, and `fields` are preserved. +- This is useful for adapters, patches, or tests that need one explicit retargeted record value. + +### How to Use + +Here are some specific examples provided. + +#### When Need To Retarget One Existing Record + +When one record should be reclassified under a different namespace: +```moonbit +let rec = Record::new(Level::Info, "started", target="worker") +let api_rec = rec.with_target("api") +``` + +In this example, only the returned record carries the new target. + +#### When Need Direct Value-level Rewriting In Tests + +When a formatter or filter test should exercise a different target without rebuilding the full record: +```moonbit +let rec = Record::new(Level::Warn, "retry").with_target("jobs.retry") +``` + +In this example, the retargeting stays local to one record value. + +### Error Case + +e.g.: +- If `target` is empty, the returned record is still valid and simply carries an empty target. + +- If code should rewrite many records consistently, a reusable patch such as `set_target(...)` may be a better fit than calling this helper repeatedly. + +### Notes + +1. Use this helper for value-level retargeting of one record. + +2. Use `set_target(...)` when the same transformation should be reused as a `RecordPatch`.