Temporal

The Temporal submodule is a comprehensive date and time utility API for Apex. It provides helper methods for calculating date boundaries (week, month, year start/end), working with business days, querying date attributes, and formatting human-readable relative dates.

Documentation

💾 Source Code

• Temporal

Implementation

• The Temporal utility class is composed of static constants and methods for Date, Time, and Datetime calculations
• Calendar & Time Constants have been defined to expose standard boundaries such as MILLIS_PER_DAY, FIRST_MONTH_OF_YEAR, LAST_HOUR_OF_DAY, and more
• Methods are grouped according to functionality pertaining to Date, Time, and Datetime

Demos

Basic

Date today = Date.today();

// Boundaries
Datetime dayStart = Temporal.localStartOfDay(today); // Today at 12:00:00 AM
Date monthEnd = Temporal.endOfMonth(today);          // Last day of current month

// Calculations
Date nextWeek = today.addDays(7);
Boolean sameMonth = Temporal.isSameMonth(today, nextWeek);

// Relative Date String
String descPast = Temporal.relativeDate(today.addDays(-2)); // Output: "2 days ago"
String descFuture = Temporal.relativeDate(today.addDays(5)); // Output: "In 5 days"

Business Days

Date startingDate = Date.newInstance(2026, 6, 12); // A Friday

// Add 3 business days (skips Saturday/Sunday)
// Friday -> Monday (1) -> Tuesday (2) -> Wednesday (3)
Date targetDate = Temporal.addBusinessDays(startingDate, 3);
System.debug(targetDate); // Output: 2026-06-17 (Wednesday)

// Difference in business days
Integer diff = Temporal.businessDaysBetween(startingDate, targetDate); 
System.debug(diff); // Output: 3

ISO Day of Week

Date inputDate = Date.newInstance(2026, 6, 14); // A Sunday

Integer isoDay = Temporal.getIsoDayOfWeek(inputDate);
System.debug(isoDay); // Output: 7 (Sunday)

Boolean weekend = Temporal.isWeekend(inputDate);
System.debug(weekend); // Output: true

Benefits

• Creating local start/end-of-day datetimes using localStartOfDay and localEndOfDay ensures boundary checks are correct relative to the running user's timezone
• Built-in support for skipping weekends when adding days or calculating differences, preventing complex calendar arithmetic loops in application code
• Simplifies weekday checks by mapping to international ISO day standards where Monday is explicitly 1 and Sunday is 7
• Out-of-the-box support for generating relative descriptions like "Tomorrow" or "3 days ago", making it simple to present timeline interfaces to users