Add named factory constructors to Duration for single-unit creation

[GuillaumeMCK]

Motivation

Creating a Duration from a single time unit is a common operation. The current constructor handles it, but requires the reader to identify the one meaningful argument among six possible named parameters:

const timeout = Duration(seconds: 30);
const delay   = Duration(milliseconds: 500);

Named factory constructors would make the intent explicit at the call site:

const Duration timeout = .seconds(30);
const Duration delay   = .milliseconds(500);

This also improves IDE accessibility. Typing Duration. surfaces all available time units via autocomplete, which lowers the discovery barrier for developers unfamiliar with the full constructor signature.

---

The const problem with extensions

The popular 30.seconds pattern (via extension on int) is widely used in third-party packages but cannot be const. This makes it unsuitable for compile-time constants, annotation arguments, or any context where const is required.

Named factories on Duration itself have none of these limitations:

// extension on int — not const
final timeout = 30.seconds;

// named factory — fully const
const timeout = Duration.seconds(30);

---

Dot shorthand synergy

With Dart's dot shorthand syntax, named factories become especially concise when the type is inferred from context:

Future.delayed(.milliseconds(500), callback);
stream.timeout(.seconds(30));
Timer(.minutes(1), callback);

This pattern is readable, const-compatible, and fits naturally with the direction the language is already moving.

---

Proposed API

const factory Duration.days(int amount);
const factory Duration.hours(int amount);
const factory Duration.minutes(int amount);
const factory Duration.seconds(int amount);
const factory Duration.milliseconds(int amount);
const factory Duration.microseconds(int amount);

Each factory is a direct delegate to the existing primary constructor. No new behavior is introduced.

---

Usage examples

// compile-time constants
class Config {
  static const Duration sessionTimeout = .minutes(30);
  static const Duration retryDelay     = .seconds(5);
  static const Duration cacheTTL       = .hours(24);
}

// inline with dot shorthand
Future.delayed(.milliseconds(500), callback);
socket.timeout(.seconds(30));

---

Notes

This change is purely additive. No existing API is modified or removed. There is no runtime cost relative to the existing constructor. Implementation would only touch sdk/lib/core/duration.dart and its associated tests.

[lrhn]

Not really shorter, but possibly more discoverable.

It has one critical problem: You can't have both a constructor named Duration.milliseconds on a class with an instance getter named milliseconds.
(That's also the reason those constructors don't already exist.)

I hope the restriction against static and instance members with the same name can be removed with static extensions (dart-lang/language#723).
If not, then the constructors can still be added as static extension constructors.
(But it would feel annoyingly half-baked if you can add a static method or constructor on the side, but can't write it properly inside the class where it belongs.)

Could use different names, but then the symmetry is lost.

I'm not against this, but I'd delay it until it's actually possible using the suggested names.

[FMorschel]

@lrhn

It has one critical problem: You can't have both a constructor named Duration.milliseconds on a class with an instance getter named milliseconds.

I guess there is something I'm not understanding correctly. We have the following issue exactly because previously to the recent changes, dartdoc accepted () at the end of constructors to differentiate between constructors and instance members.

• Identifiers in dartdocs with parens /// [functionName()] do not generate navigation regions #47553 (comment)

See, these have no diagnostics:

class C {
  C.foo() : foo = true;
  bool foo;
}

class D {
  D.foo();
  int get foo => 42;
}

Edit: You can't have static members because their names would actually be the same. But constructor names are TypeName.constructorName, so they can be declared together.

[GuillaumeMCK]

Not really shorter, but possibly more discoverable.

It has one critical problem: You can't have both a constructor named Duration.milliseconds on a class with an instance getter named milliseconds. (That's also the reason those constructors don't already exist.)

I hope the restriction against static and instance members with the same name can be removed with static extensions (dart-lang/language#723). If not, then the constructors can still be added as static extension constructors. (But it would feel annoyingly half-baked if you can add a static method or constructor on the side, but can't write it properly inside the class where it belongs.)

Could use different names, but then the symmetry is lost.

I'm not against this, but I'd delay it until it's actually possible using the suggested names.

@lrhn

The naming conflict does not apply here. The existing getters are all prefixed with in — inMilliseconds, inSeconds, inHours. duration.dart

[lrhn]

ACK, my bad. Construtors are not in the static namespace, so they don't conflict with instance members.
(Inconsistent, but occasionally useful.)
Also, the names are different, I was probably thinking of DateTime.

So there is no problem. Maybe I should just do it 😁