📝 document record transformation apis

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)

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.

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.

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`.