Moment class final

A rich, human-friendly wrapper around date and time values.

Moment gives you everything Dart's DateTime does — and then some. It supports flexible formatting with token-based patterns, relative time strings ("3 hours ago"), arithmetic with Period objects, and convenient accessors for common display formats.

Creating a Moment

// From right now
final now = Moment.now();

// From individual components
final birthday = Moment(year: 1999, month: 12, date: 25, hour: 8);

// From an existing DateTime
final converted = Moment.fromDateTime(DateTime.utc(2025, 1, 1));

// By parsing a string (format: "yyyy/MM/dd-HH:mm:ss")
final parsed = Moment.parse(string: '2025/06/15-14:30:00');

Formatting

Build any date/time string you need using format tokens:

final m = Moment.now();
m.format(formatStyle: [dddd, comma, space, mmmm, space, D, comma, space, yyyy]);
// → "Wednesday, February 19, 2026"

See the token constants (D, Do, DD, M, MM, MMM, mmmm, yy, yyyy, h, hh, H, HH, m, mm, s, ss, A, a) for a full list of available format tokens.

Relative Time

final posted = Moment(year: 2026, month: 2, date: 19, hour: 10);
print(posted.timeAgo());       // "3 hours ago"
print(posted.timeAgo(short: true)); // "3h"

Arithmetic

Add or subtract Period values to move through time:

final nextWeek = Moment.now() + Period(days: 7);
final lastMonth = Moment.now() - Period(months: 1);

Comparison

Moment implements Comparable and supports all comparison operators:

if (deadline > Moment.now()) print('Still time!');

Implemented types

Comparable<Moment>

Constructors

Moment({int? second, int? minute, int? hour, int? date, int? month, int? year, List<String> formatStyle = defaultFormatStyle}): Creates a Moment from individual date/time components.
Moment.fromDateTime(DateTime dateTime): Creates a Moment from an existing DateTime instance.

Properties

asMap → Map<String, dynamic>: Serializes this Moment to a Map<String, dynamic>.
no setter
clock → String: The time as a 12-hour clock string with AM/PM: "2:05:09 PM".
no setter
clockPhase → String: "AM" or "PM" based on the hour value.
no setter
date ↔ int?: The day-of-month component (1-31), or null if not specified.
getter/setter pair
dateTime → DateTime: Converts this Moment to a standard Dart DateTime.
no setter
era → String?: The historical era — "AD" for years >= 1, "BC" for years <= -1, or null for year 0.
no setter
formatStyle ↔ List<String>: The token sequence used by format to produce a formatted string.
getter/setter pair
hashCode → int: The hash code for this object.
no setteroverride
hour ↔ int?: The hour component (0-23), or null if not specified.
getter/setter pair
millisecondsSinceEpoch → int: Milliseconds since the Unix epoch (1970-01-01 00:00:00 UTC).
no setter
minute ↔ int?: The minute component (0-59), or null if not specified.
getter/setter pair
month ↔ int?: The month component (1-12), or null if not specified.
getter/setter pair
period → Period: Converts the time portion of this Moment into a Period.
no setter
runtimeType → Type: A representation of the runtime type of the object.
no setteroverride
second ↔ int?: The second component (0-59), or null if not specified.
getter/setter pair
shortClock → String: The time as a short 12-hour string without seconds: "2:05 PM".
no setter
shortTime → String: The time as a short 24-hour string without seconds: "HH:mm".
no setter
time → String: The time as a 24-hour string: "HH:mm:ss" (e.g. "14:05:09").
no setter
totalSeconds → int: The total number of seconds from the Unix epoch (1970-01-01) to this Moment.
no setter
weekday → int?: The ISO day of the week (1 = Monday, 7 = Sunday), or null if the date components are incomplete.
no setter
year ↔ int?: The year component (e.g. 2026), or null if not specified.
getter/setter pair

Methods

addPeriod(Period period) → Moment: Alias for the + operator. Returns a new Moment shifted by period.
compareTo(Moment other) → int: Compares this object to another object.
override
difference(Moment other) → Period: Returns the absolute difference between this Moment and other as a Period.
format({List<String>? formatStyle = defaultFormatStyle}) → String: Builds a formatted date/time string by evaluating each token in formatStyle against this Moment's values.
formatToken(Moment moment, String token) → String?: Resolves a single format token into its string value for the given moment.
fromMap(Map<String, dynamic> map) → Moment: Constructs a Moment from a map with string keys.
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
override
timeAgo({Moment? from, bool short = false}) → String: Returns a human-readable string describing how long ago (or from now) this Moment is relative to from (defaults to Moment.now).
toList() → List: Returns the components as a list: [second, minute, hour, date, month, year].
toString() → String: A string representation of this object.
override

Operators

operator +(Period period) → Moment: Returns a new Moment advanced forward by period.
operator -(Period period) → Moment: Returns a new Moment moved backward by period.
operator <(Moment other) → bool: Returns true if this moment comes before other chronologically.
operator <=(Moment other) → bool: Returns true if this moment is at or before other.
operator ==(Object other) → bool: The equality operator.
override
operator >(Moment other) → bool: Returns true if this moment comes after other chronologically.
operator >=(Moment other) → bool: Returns true if this moment is at or after other.

Static Methods

now() → Moment: Creates a Moment representing the current date and time.
parse({required String string}) → Moment: Parses a Moment from a string in the format "yyyy/MM/dd-HH:mm:ss".
tomorrow() → Moment: Returns a Moment representing tomorrow at the current time.
tryParse(String? string, {dynamic onException}) → Moment?: Attempts to parse a Moment from string, returning null on failure.
yesterday() → Moment: Returns a Moment representing yesterday at the current time.