📝 document remaining record helpers

docs/api/field-with-value.md

@@ -0,0 +1,76 @@
+---
+name: field-with-value
+group: api
+category: record
+update-time: 20260613
+description: Return a copy of a field with a replaced value while preserving the key.
+key-word:
+    - field
+    - value
+    - transform
+    - public
+---
+
+## Field-with-value
+
+Return a copy of a `Field` with a different `value`. This helper is the narrowest way to rewrite one field value while preserving the existing key.
+
+### Interface
+
+```moonbit
+pub fn Field::with_value(self : Field, value : String) -> Field {}
+```
+
+#### input
+
+- `self : Field` - Base field whose value should be replaced.
+- `value : String` - New value text for the returned field.
+
+#### output
+
+- `Field` - New field value carrying the updated value.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper returns a new field value instead of mutating the original one.
+- Only the `value` part is replaced.
+- The original `key` is preserved exactly.
+- This is useful for redaction, normalization, or tests that need one adjusted field value without rebuilding the key manually.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need To Redact One Existing Field Value
+
+When the field key should stay the same but the value should be hidden:
+```moonbit
+let user = field("user", "alice")
+let redacted = user.with_value("***")
+```
+
+In this example, the returned field keeps the same key while changing only the visible value.
+
+#### When Need To Rewrite A Field In Test Data
+
+When one field should be adapted without reconstructing the key by hand:
+```moonbit
+let region = field("region", "cn").with_value("eu")
+```
+
+In this example, the helper keeps the transformation local to one field value.
+
+### Error Case
+
+e.g.:
+- If `value` is empty, the returned field is still valid and simply carries an empty string value.
+
+- If the key should also change, constructing a new field with `field(...)` is clearer than chaining this helper.
+
+### Notes
+
+1. Use this helper when the key should stay stable and only the value should change.
+
+2. It is especially useful for redaction-style value updates in tests or adapters.

docs/api/index.md

@@ -60,6 +60,7 @@ BitLogger API navigation.
 ## Formatter and fields
 
 - [field.md](./field.md)
+- [field-with-value.md](./field-with-value.md)
 - [record-formatter.md](./record-formatter.md)
 - [color-mode.md](./color-mode.md)
 - [color-support.md](./color-support.md)
@@ -81,6 +82,7 @@ BitLogger API navigation.
 
 - [record.md](./record.md)
 - [record-new.md](./record-new.md)
+- [record-copy.md](./record-copy.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)

docs/api/record-copy.md

@@ -0,0 +1,76 @@
+---
+name: record-copy
+group: api
+category: record
+update-time: 20260613
+description: Return a shallow copy of a record without changing any of its fields.
+key-word:
+    - record
+    - copy
+    - helper
+    - public
+---
+
+## Record-copy
+
+Return a copy of a `Record` with the same field values. This helper is useful when code wants an explicit independent record value before passing it to sinks, patches, or other downstream steps.
+
+### Interface
+
+```moonbit
+pub fn Record::copy(self : Record) -> Record {}
+```
+
+#### input
+
+- `self : Record` - Base record that should be copied.
+
+#### output
+
+- `Record` - New record value containing the same `level`, `message`, `timestamp_ms`, `target`, and `fields`.
+
+### Explanation
+
+Detailed rules explaining key parameters and behaviors
+
+- This helper returns a new `Record` value instead of reusing the original one directly.
+- `level`, `message`, `timestamp_ms`, `target`, and `fields` are preserved unchanged.
+- It is the narrowest explicit duplication helper for a record value.
+- This is useful when a downstream path should receive its own record value even though the event data does not change.
+
+### How to Use
+
+Here are some specific examples provided.
+
+#### When Need An Explicit Duplicate For Fanout-style Handling
+
+When one path should keep the current record value while another path continues independently:
+```moonbit
+let rec = Record::new(Level::Info, "started", target="svc")
+let duplicate = rec.copy()
+```
+
+In this example, the caller gets a second `Record` value with the same event data.
+
+#### When Need A Stable Baseline Before Later Transformations
+
+When one value should be copied before applying further replacement helpers:
+```moonbit
+let base = Record::new(Level::Warn, "retry")
+let patched = base.copy().with_target("jobs.retry")
+```
+
+In this example, the copy step makes the later transformation intent explicit.
+
+### Error Case
+
+e.g.:
+- `Record::copy()` itself does not have a runtime failure mode.
+
+- If the code does not actually need a second record value, copying adds no new information and may be unnecessary.
+
+### Notes
+
+1. Use this helper when explicit value duplication improves clarity.
+
+2. It pairs naturally with later `Record` transformation helpers when one path should preserve a baseline value first.