Dates, time, and durations

Sugar represents a moment or calendar day with a Date value. The Date namespace creates those values, and the Duration namespace creates amounts of elapsed time.

Get the current date and time

text {
  let now: Date = Date::now();
  "The current year is {now.year}."
}

Read it from left to right:

Inside that text program:

1. let now creates a temporary variable named now.
2. : Date says that the variable must contain a Date value.
3. Date::now() returns the current date and time.

The type is optional for a temporary variable, but writing it makes the intent clear and prevents another type of value from being assigned later.

Read Date properties

A Date contains calendar information. Read each property with a dot:

now.year
now.month
now.day
now.weekday
now.hour
now.minute
now.timestamp

For Monday, September 7, 2026 at 9:30 AM, those values include:

timestamp is the Unix timestamp in milliseconds. Most creations are easier to read when they use the calendar properties instead.

Create a specific date

Pass a year, month, and day to Date::from():

var release: Date = Date::from(2026, 9, 7);

Sugar rejects impossible dates such as February 30. Writing release directly as output displays 2026-09-07.

Compare dates

Dates use the comparison operators you already learned:

Date::now() >= release

This becomes true when the current moment has reached the release date.

All six comparisons work with two Date values: ==, !=, <, <=, >, and >=.

let release: Date = Date::from(2026, 9, 7);

text if Date::now() >= release {
  "The event is open."
} else {
  "The event has not started."
}

Move through time with Durations

A Duration is a fixed amount of elapsed time:

Duration::minutes(30)
Duration::hours(24)
Duration::days(7)
Duration::weeks(2)

Add a Duration to a Date to move forward, or subtract one to move backward:

let now: Date = Date::now();
let tomorrow: Date = now + Duration::days(1);
let nextWeek: Date = now + Duration::weeks(1);
let threeHoursAgo: Date = now - Duration::hours(3);

Sugar intentionally does not provide month or year Durations. Months and years do not have fixed lengths.

Declare a Date variable

Top-level variable declarations also accept the Date type. The declaration and the text that reads it belong together in Code:

var releaseDate: Date = Date::from(2026, 9, 7);

text if Date::now() >= releaseDate {
  "The release is available."
} else {
  "The release is scheduled for {releaseDate}."
}

Date variables cannot use input: true; people cannot enter them through the creation’s inputs.

After the course introduces Memory variables, you can also declare a mem var with the Date type and remember when something last happened.

Which timezone Sugar uses

Date::now() and Date::from() use the active timezone. An Automation may specify one in its configuration. Without one, JOI uses the detected user timezone when available and falls back to Pacific Time.

Older Sugar code may use dayOfWeek(). It remains available for compatibility, but new code should use Date::now().weekday.

The next lesson returns to JOI-specific values by explaining participants and their helper functions.