From b47f95c91845ba98405ef71cc5d756bf05502cda Mon Sep 17 00:00:00 2001 From: Nanaloveyuki Date: Sat, 13 Jun 2026 21:10:58 +0800 Subject: [PATCH] :memo: document remaining record helpers --- docs/api/field-with-value.md | 76 ++++++++++++++++++++++++++++++++++++ docs/api/index.md | 2 + docs/api/record-copy.md | 76 ++++++++++++++++++++++++++++++++++++ 3 files changed, 154 insertions(+) create mode 100644 docs/api/field-with-value.md create mode 100644 docs/api/record-copy.md diff --git a/docs/api/field-with-value.md b/docs/api/field-with-value.md new file mode 100644 index 0000000..3bb5704 --- /dev/null +++ b/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. diff --git a/docs/api/index.md b/docs/api/index.md index 684df5d..bea3454 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) +- [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) diff --git a/docs/api/record-copy.md b/docs/api/record-copy.md new file mode 100644 index 0000000..d20cfb3 --- /dev/null +++ b/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.