Feature request: Record Spread for Type-Safe `copyWith`-Style Updates

[Hu-Wentao]

Record Spread with Safe Defaults and Controlled Overrides

Summary

This proposal introduces a record spread operator ... inside record literals to support:

1. Concise, type-safe copyWith-style updates
2. Composability by embedding records into larger records

While enabling both use cases, the design enforces safe defaults:

• Spread operations never implicitly override fields
• Field replacement must be explicit
• The behavior is predictable and stable under API evolution

---

Design Goals

• Preserve immutability ergonomics (copyWith-style updates)
• Enable record composition (embedding smaller records into larger ones)
• Avoid implicit field overriding
• Maintain strong compile-time guarantees
• Keep syntax minimal and consistent

---

Core Semantics

1. Spread = structural expansion only

(...record)

Expands all fields of record into the new record.

---

2. Multiple spreads concatenate (no implicit override)

(...record1, ...record2)

• Positional fields: concatenated in order
• Named fields: must not conflict

// Compile-time error if both define `foo`
(...r1, ...r2)

➡️ No silent overriding.

---

3. Named field override (explicit by position in literal)

(...record, foo: newValue)

• Allowed only if foo already exists
• Replaces the previously introduced field

// Compile-time error
(...record, unknownField: 123)

---

4. Positional field override via integer index

(...record, 1: newValue)

• Replaces positional field at index 1
• Only allowed if that field was introduced by a spread

// Compile-time error
(1: newValue) // no prior spread

---

5. No $n positional syntax

Positional fields are referenced using integer indices, not $1, $2.

Rationale:

• Avoids conflict with valid named fields like $2
• Keeps syntax aligned with positional semantics

---

Examples

CopyWith-style update

final state = (isLoading: false, error: null, isSuccess: false);

final newState = (
  ...state,
  isLoading: true,
);

---

Positional update

final point = (10, 20);

final moved = (
  ...point,
  1: 50,
);

---

Record composition (embedding)

final point = (x: 10, y: 20);

final colored = (
  ...point,
  color: "red",
);

---

Combining records

final a = (1, 2);
final b = (3, 4);

final combined = (...a, ...b); // (1, 2, 3, 4)

---

Conflict detection

final a = (foo: 1);
final b = (foo: 2);

(...a, ...b); // Compile-time error

---

Rationale

1. Safe by default

• No implicit overriding
• No accidental field shadowing
• Fail-fast behavior

---

2. Supports both key use cases

Use case	Supported
copyWith-style updates	✅
record embedding	✅
record concatenation	✅
implicit merging	❌

---

3. Avoids API evolution hazards

Unlike argument-list spreading:

• No cross-boundary implicit binding
• No silent behavior changes when APIs evolve
• Field usage remains explicit

---

4. Minimal mental model

• ... always means expand
• Overriding is explicit and constrained
• No context-dependent semantics

---

Alternatives Considered

Implicit override (rejected)

(...record, foo: newValue)

where foo may or may not exist.

❌ Problem:

• Silent bugs
• Harder to reason about
• Weakens type guarantees

---

Explicit override syntax (:=, ...=)

(...record, foo:= newValue)
(...record, ...=otherRecord)

❌ Rejected because:

• Adds new syntax surface
• Increases complexity
• Not necessary if safe constraints exist

---

Acknowledgement

Parts of this proposal were inspired by community discussion, including suggestions around:

@lrhn

• Using integer indices for positional field updates
• Treating multiple spreads as concatenation rather than override
• Avoiding $n syntax for positional access

These contributions helped shape a design that balances composability and safety.

[Hu-Wentao]

abount contact, see #2128 (comment)

[nate-thegrate]

It's really nice how a Record typedef needs much less boilerplate than a class declaration. And the feature proposed in this issue would give them a convenient copyWith-style functionality.

But to compare them directly:

• This proposal would mean ...object behaves differently based on where it occurs: if used in a collection literal it unpacks the object, but inside a Record it sets the object up to have its fields overwritten.
• Record spreading #2128 would make it so ...object always unpacks the object, inlining each member at the spread-point.

I especially like how the proposal in #2128 would work for argument lists. It would have a compelling use case in Flutter projects:

void showAdaptiveDialog({required BuildContext context, Object? arg1, Object? arg2}) {
  final args = (arg1, arg2, context: context);

  final Widget dialog = switch (defaultTargetPlatform) {
    .iOS || .macOS => AppleDialog(...args),
    _ => MaterialDialog(...args),
  };

  // ...
}

For a signature with ten or more arguments, using the spread operator this way would have an enormous impact on readability.

Overall, both this issue and #2128 have the potential to make Dart code much more concise. With that in mind, I think using the ... for copyWith-style updates shouldn't be a feature, since it's less intuitive.

[Hu-Wentao]

@nate-thegrate

I don’t think “mismatched args will be caught by the compiler” addresses the core issue here.

The concern is not just present-time type safety, but API evolution.

With argument-list spreading, a field in the spread record that is not consumed today can become implicitly consumed in the future if the callee later introduces a parameter with the same name and a compatible type.

In that case:

• The call site does not change
• The code still compiles
• But the semantics of the call have silently changed

This is not a type error — it’s an evolution hazard.

In other words, argument-list spread introduces an implicit coupling between:

• the shape of the record, and
• the evolving signature of the callee

That coupling crosses an API boundary, which is exactly where implicit behavior tends to be the most dangerous.

---

By contrast, this proposal deliberately keeps ...record local and constrained:

• It is only allowed in a record literal of the same shape
• It cannot introduce new fields
• It cannot be used to forward arguments across API boundaries

So the feature is:

• fail-fast
• structurally constrained
• evolution-safe

The limitation is intentional. It avoids turning record shape into an implicit argument-binding mechanism.

---

So while argument-list spreading is more general, that generality comes with a real cost: it weakens the explicitness and stability of API boundaries.

This proposal focuses on a narrower use case (copyWith-style updates), but in doing so preserves stronger guarantees under API evolution.

[nate-thegrate]

With argument-list spreading, a field in the spread record that is not consumed today can become implicitly consumed in the future if the callee later introduces a parameter with the same name and a compatible type.

I don't believe this is true. The proposal in #2128 is for the ... operator to inline every member of the record, so if the record contains a field that doesn't fit into the current function signature, the result would be a syntax error.

[Hu-Wentao]

@nate-thegrate

Based on the section 'Named field override', this proposal can handle the use of named parameters very well. Of course, according to the section 'Positional field override via integer index', using positional arguments might be more complex, but I think this is worthwhile. Because if a function has so many parameters that it requires using the '...' syntax to pass a sequence of arguments, then this function should not use a positional argument list but rather a named parameter list.