> ## Documentation Index > Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt > Use this file to discover all available pages before exploring further. # Date and time helpers > Every registered date and time helper, with signatures and examples for deadlines, schedules, service windows, and reporting periods. ## When to use these helpers Use ISO-like date values where possible and test the expression in the same field, form, or template context where it will run. Formatting is presentation; comparisons and calculations should use the underlying date value. ## Calling style Call a helper as `dateFormat($.submitted_at, "YYYY-MM-DD")`. Not every helper is available everywhere: validation, form, and document-template helpers have distinct context contracts. Editor suggestions are not proof that a helper is supported at runtime. ## Complete function reference ### `addDays` Adds a specified number of days to a date **Signature:** `addDays(date, days)` **Example:** ```txt theme={null} addDays("2023-01-01T00:00:00Z", 5) // "2023-01-06T00:00:00Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | addDays(...)`. ### `addHours` Adds a specified number of hours to a date **Signature:** `addHours(date, hours)` **Example:** ```txt theme={null} addHours("2023-01-01T00:00:00Z", 5) // "2023-01-01T05:00:00Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | addHours(...)`. ### `addMinutes` Adds a specified number of minutes to a date **Signature:** `addMinutes(date, minutes)` **Example:** ```txt theme={null} addMinutes("2023-01-01T00:00:00Z", 30) // "2023-01-01T00:30:00Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | addMinutes(...)`. ### `addMonths` Adds a specified number of months to a date **Signature:** `addMonths(date, months)` **Example:** ```txt theme={null} addMonths("2023-01-01T00:00:00Z", 3) // "2023-04-01T00:00:00Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | addMonths(...)`. ### `addYears` Adds a specified number of years to a date **Signature:** `addYears(date, years)` **Example:** ```txt theme={null} addYears("2023-01-01T00:00:00Z", 2) // "2025-01-01T00:00:00Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | addYears(...)`. ### `date` Constructs a date from components (UTC-normalized wall time) **Signature:** `date(year, month, day, hour?, minute?, second?, millisecond?)` **Example:** ```txt theme={null} date(2025,10,15) // "2025-10-15T00:00:00.000Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | date(...)`. ### `dateAdd` Adds an amount to a date by unit **Signature:** `dateAdd(date, amount, unit)` **Example:** ```txt theme={null} dateAdd("2025-01-15T10:30:00Z", 2, "day") // Date representing 2025-01-17T10:30:00.000Z ``` **Note:** It can also be written as a transform when the first value is the input: `value | dateAdd(...)`. ### `dateDiff` Returns the integer difference between two dates in the specified unit **Signature:** `dateDiff(date, other, unit)` **Example:** ```txt theme={null} dateDiff("2025-01-17T10:30:00Z", "2025-01-15T10:30:00Z", "day") // 2 ``` **Note:** It can also be written as a transform when the first value is the input: `value | dateDiff(...)`. ### `dateFormat` Formats a date using tokens YYYY, MM, DD, HH, mm, ss, SSS (UTC) **Signature:** `dateFormat(date, format)` **Example:** ```txt theme={null} dateFormat("2025-01-15T10:30:45.123Z", "YYYY-MM-DD") // "2025-01-15" ``` **Note:** It can also be written as a transform when the first value is the input: `value | dateFormat(...)`. ### `dateFromString` Creates a date from a string **Signature:** `dateFromString(str)` **Example:** ```txt theme={null} dateFromString("2025-01-15") // Date representing 2025-01-15 ``` **Note:** It can also be written as a transform when the first value is the input: `value | dateFromString(...)`. ### `dateFromTime` Creates a date from a time string (hh:mm or hh:mm:ss) **Signature:** `dateFromTime(time)` **Example:** ```txt theme={null} dateFromTime("14:30") // Today at 14:30:00 ``` **Note:** It can also be written as a transform when the first value is the input: `value | dateFromTime(...)`. ### `dateFromTimestamp` Creates a date from a numeric timestamp (ms) **Signature:** `dateFromTimestamp(timestamp)` **Example:** ```txt theme={null} dateFromTimestamp(1736937045123) // Date representing 2025-01-15T10:30:45.123Z ``` **Note:** It can also be written as a transform when the first value is the input: `value | dateFromTimestamp(...)`. ### `dateParse` Parses a date from a tokenized format string **Signature:** `dateParse(str, format)` **Example:** ```txt theme={null} dateParse("2025-01-15", "YYYY-MM-DD") // Date representing 2025-01-15T00:00:00.000Z ``` **Note:** It can also be written as a transform when the first value is the input: `value | dateParse(...)`. ### `dateSubtract` Subtracts an amount from a date by unit **Signature:** `dateSubtract(date, amount, unit)` **Example:** ```txt theme={null} dateSubtract("2025-01-15T10:30:00Z", 2, "day") // Date representing 2025-01-13T10:30:00.000Z ``` **Note:** It can also be written as a transform when the first value is the input: `value | dateSubtract(...)`. ### `day` Returns UTC day of month **Signature:** `day(date)` **Example:** ```txt theme={null} day("2025-01-15T10:30:45.123Z") // 15 ``` **Note:** It can also be written as a transform when the first value is the input: `value | day(...)`. ### `dayOfYear` Returns the day of the year for a given date **Signature:** `dayOfYear(date)` **Example:** ```txt theme={null} dayOfYear("2023-01-01T00:00:00Z") // 1 ``` **Note:** It can also be written as a transform when the first value is the input: `value | dayOfYear(...)`. ### `daysInMonth` Returns the number of days in a given month of a year **Signature:** `daysInMonth(year, month)` **Example:** ```txt theme={null} daysInMonth(2023, 1) // 31 ``` **Note:** It can also be written as a transform when the first value is the input: `value | daysInMonth(...)`. ### `diffDays` Calculates the difference in days between two dates **Signature:** `diffDays(date1, date2)` **Example:** ```txt theme={null} diffDays("2023-01-01T00:00:00Z", "2023-01-10T00:00:00Z") // 9 ``` **Note:** It can also be written as a transform when the first value is the input: `value | diffDays(...)`. ### `diffHours` Calculates the difference in hours between two dates **Signature:** `diffHours(date1, date2)` **Example:** ```txt theme={null} diffHours("2023-01-01T00:00:00Z", "2023-01-02T00:00:00Z") // 24 ``` **Note:** It can also be written as a transform when the first value is the input: `value | diffHours(...)`. ### `diffMinutes` Calculates the difference in minutes between two dates **Signature:** `diffMinutes(date1, date2)` **Example:** ```txt theme={null} diffMinutes("2023-01-01T00:00:00Z", "2023-01-01T01:00:00Z") // 60 ``` **Note:** It can also be written as a transform when the first value is the input: `value | diffMinutes(...)`. ### `endOfDay` Returns the end of the day for a given date **Signature:** `endOfDay(date)` **Example:** ```txt theme={null} endOfDay("2023-01-01T12:34:56Z") // "2023-01-01T23:59:59Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | endOfDay(...)`. ### `endOfMonth` Returns the end of the month for a given date **Signature:** `endOfMonth(date)` **Example:** ```txt theme={null} endOfMonth("2023-01-15T12:34:56Z") // "2023-01-31T23:59:59Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | endOfMonth(...)`. ### `endOfWeek` Returns the end of the week for a given date **Signature:** `endOfWeek(date)` **Example:** ```txt theme={null} endOfWeek("2023-01-15T12:34:56Z") // "2023-01-15T23:59:59Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | endOfWeek(...)`. ### `endOfYear` Returns the end of the year for a given date **Signature:** `endOfYear(date)` **Example:** ```txt theme={null} endOfYear("2023-05-15T12:34:56Z") // "2023-12-31T23:59:59Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | endOfYear(...)`. ### `formatDateTime` Formats a date and time together **Signature:** `formatDateTime(date, dateStyle?, timeStyle?, locale?)` **Example:** ```txt theme={null} formatDateTime("2023-01-01T00:00:00Z") // "Jan 1, 2023, 12:00:00 AM" ``` **Note:** It can also be written as a transform when the first value is the input: `value | formatDateTime(...)`. ### `formatFull` Formats a date as a full date string **Signature:** `formatFull(date, locale?)` **Example:** ```txt theme={null} formatFull("2023-01-01T00:00:00Z") // "Sunday, January 1, 2023" ``` **Note:** It can also be written as a transform when the first value is the input: `value | formatFull(...)`. ### `formatLong` Formats a date as a long date string **Signature:** `formatLong(date, locale?)` **Example:** ```txt theme={null} formatLong("2023-01-01T00:00:00Z") // "January 1, 2023" ``` **Note:** It can also be written as a transform when the first value is the input: `value | formatLong(...)`. ### `formatMedium` Formats a date as a medium date string **Signature:** `formatMedium(date, locale?)` **Example:** ```txt theme={null} formatMedium("2023-01-01T00:00:00Z") // "Jan 1, 2023" ``` **Note:** It can also be written as a transform when the first value is the input: `value | formatMedium(...)`. ### `formatShort` Formats a date as a short date string **Signature:** `formatShort(date, locale?)` **Example:** ```txt theme={null} formatShort("2023-01-01T00:00:00Z") // "1/1/2023" ``` **Note:** It can also be written as a transform when the first value is the input: `value | formatShort(...)`. ### `formatTimeLong` Formats a date as a long time string **Signature:** `formatTimeLong(date, locale?)` **Example:** ```txt theme={null} formatTimeLong("2023-01-01T00:00:00Z") // "12:00:00 AM GMT" ``` **Note:** It can also be written as a transform when the first value is the input: `value | formatTimeLong(...)`. ### `formatTimeMedium` Formats a date as a medium time string **Signature:** `formatTimeMedium(date, locale?)` **Example:** ```txt theme={null} formatTimeMedium("2023-01-01T00:00:00Z") // "12:00:00 AM" ``` **Note:** It can also be written as a transform when the first value is the input: `value | formatTimeMedium(...)`. ### `formatTimeShort` Formats a date as a short time string **Signature:** `formatTimeShort(date, locale?)` **Example:** ```txt theme={null} formatTimeShort("2023-01-01T00:00:00Z") // "12:00 AM" ``` **Note:** It can also be written as a transform when the first value is the input: `value | formatTimeShort(...)`. ### `getAge` Calculates the age in years from a given date **Signature:** `getAge(birthDate)` **Example:** ```txt theme={null} getAge("2000-01-01T00:00:00Z") // 23 ``` **Note:** It can also be written as a transform when the first value is the input: `value | getAge(...)`. ### `hour` Returns UTC hour **Signature:** `hour(date)` **Example:** ```txt theme={null} hour("2025-01-15T10:30:45.123Z") // 10 ``` **Note:** It can also be written as a transform when the first value is the input: `value | hour(...)`. ### `isAfter` Checks if a date is after another by unit **Signature:** `isAfter(date, other, unit)` **Example:** ```txt theme={null} isAfter("2025-01-16T10:30:00Z", "2025-01-15T08:00:00Z", "day") // true ``` **Note:** It can also be written as a transform when the first value is the input: `value | isAfter(...)`. ### `isBefore` Checks if a date is before another by unit **Signature:** `isBefore(date, other, unit)` **Example:** ```txt theme={null} isBefore("2025-01-15T10:30:00Z", "2025-01-16T08:00:00Z", "day") // true ``` **Note:** It can also be written as a transform when the first value is the input: `value | isBefore(...)`. ### `isLeapYear` Checks if a given year is a leap year **Signature:** `isLeapYear(year)` **Example:** ```txt theme={null} isLeapYear(2020) // true ``` **Note:** It can also be written as a transform when the first value is the input: `value | isLeapYear(...)`. ### `isSame` Checks if two dates are the same by unit **Signature:** `isSame(date, other, unit)` **Example:** ```txt theme={null} isSame("2025-01-15T10:30:00Z", "2025-01-15T08:00:00Z", "day") // true ``` **Note:** It can also be written as a transform when the first value is the input: `value | isSame(...)`. ### `isSameDay` Checks if two dates fall on the same calendar day **Signature:** `isSameDay(date1, date2)` **Example:** ```txt theme={null} isSameDay("2023-01-01T00:00:00Z", "2023-01-01T23:59:59Z") // true ``` **Note:** It can also be written as a transform when the first value is the input: `value | isSameDay(...)`. ### `isSameOrAfter` Checks if a date is the same or after another by unit **Signature:** `isSameOrAfter(date, other, unit)` **Example:** ```txt theme={null} isSameOrAfter("2025-01-15T10:30:00Z", "2025-01-15T08:00:00Z", "day") // true ``` **Note:** It can also be written as a transform when the first value is the input: `value | isSameOrAfter(...)`. ### `isSameOrBefore` Checks if a date is the same or before another by unit **Signature:** `isSameOrBefore(date, other, unit)` **Example:** ```txt theme={null} isSameOrBefore("2025-01-15T10:30:00Z", "2025-01-15T08:00:00Z", "day") // true ``` **Note:** It can also be written as a transform when the first value is the input: `value | isSameOrBefore(...)`. ### `isToday` Checks if a given date is today **Signature:** `isToday(date)` **Example:** ```txt theme={null} isToday("2023-01-01T00:00:00Z") // false ``` **Note:** It can also be written as a transform when the first value is the input: `value | isToday(...)`. ### `isTomorrow` Checks if a given date is tomorrow **Signature:** `isTomorrow(date)` **Example:** ```txt theme={null} isTomorrow("2023-01-01T00:00:00Z") // false ``` **Note:** It can also be written as a transform when the first value is the input: `value | isTomorrow(...)`. ### `isValidDatePattern` Validates if a date string matches supported patterns **Signature:** `isValidDatePattern(dateString)` **Example:** ```txt theme={null} isValidDatePattern("2025-10-15") // true ``` **Note:** It can also be written as a transform when the first value is the input: `value | isValidDatePattern(...)`. ### `isYesterday` Checks if a given date is yesterday **Signature:** `isYesterday(date)` **Example:** ```txt theme={null} isYesterday("2023-01-01T00:00:00Z") // false ``` **Note:** It can also be written as a transform when the first value is the input: `value | isYesterday(...)`. ### `millisecond` Returns UTC millisecond **Signature:** `millisecond(date)` **Example:** ```txt theme={null} millisecond("2025-01-15T10:30:45.123Z") // 123 ``` **Note:** It can also be written as a transform when the first value is the input: `value | millisecond(...)`. ### `minute` Returns UTC minute **Signature:** `minute(date)` **Example:** ```txt theme={null} minute("2025-01-15T10:30:45.123Z") // 30 ``` **Note:** It can also be written as a transform when the first value is the input: `value | minute(...)`. ### `month` Returns UTC month (1-12) **Signature:** `month(date)` **Example:** ```txt theme={null} month("2025-01-15T10:30:45.123Z") // 1 ``` **Note:** It can also be written as a transform when the first value is the input: `value | month(...)`. ### `normalizeDateInput` Runs the registered date helper named normalizeDateInput. **Signature:** `normalizeDateInput(value)` **Example:** ```txt theme={null} normalizeDateInput(value) ``` **Note:** It can also be written as a transform when the first value is the input: `value | normalizeDateInput(...)`. ### `now` Returns the current Date at evaluation time. In a document template, now() is supplied by the render helper; use the stable \$now context value when every section needs one captured timestamp. **Signature:** `now()` **Example:** ```txt theme={null} dateFormat(now(), "YYYY-MM-DD") ``` **Availability:** General helper. It is time-dependent; do not use it for a deterministic serial namespace or a persisted result without a refresh policy. **Note:** It can also be written as a transform when the first value is the input: `value | now(...)`. ### `parseDateString` Validates and parses a date string to a Date or null **Signature:** `parseDateString(dateString)` **Example:** ```txt theme={null} parseDateString("2025-10-15") // "2025-10-15T00:00:00.000Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | parseDateString(...)`. ### `parseIsoDate` Parses an ISO date string into a date object **Signature:** `parseIsoDate(isoDate)` **Example:** ```txt theme={null} parseIsoDate("2023-01-01T00:00:00Z") // "2023-01-01T00:00:00Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | parseIsoDate(...)`. ### `second` Returns UTC second **Signature:** `second(date)` **Example:** ```txt theme={null} second("2025-01-15T10:30:45.123Z") // 45 ``` **Note:** It can also be written as a transform when the first value is the input: `value | second(...)`. ### `startOfDay` Returns the start of the day for a given date **Signature:** `startOfDay(date)` **Example:** ```txt theme={null} startOfDay("2023-01-01T12:34:56Z") // "2023-01-01T00:00:00Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | startOfDay(...)`. ### `startOfMonth` Returns the start of the month for a given date **Signature:** `startOfMonth(date)` **Example:** ```txt theme={null} startOfMonth("2023-01-15T12:34:56Z") // "2023-01-01T00:00:00Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | startOfMonth(...)`. ### `startOfWeek` Returns the start of the week for a given date **Signature:** `startOfWeek(date)` **Example:** ```txt theme={null} startOfWeek("2023-01-15T12:34:56Z") // "2023-01-09T00:00:00Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | startOfWeek(...)`. ### `startOfYear` Returns the start of the year for a given date **Signature:** `startOfYear(date)` **Example:** ```txt theme={null} startOfYear("2023-05-15T12:34:56Z") // "2023-01-01T00:00:00Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | startOfYear(...)`. ### `subtractDays` Subtracts a specified number of days from a date **Signature:** `subtractDays(date, days)` **Example:** ```txt theme={null} subtractDays("2023-01-01T00:00:00Z", 5) // "2022-12-27T00:00:00Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | subtractDays(...)`. ### `subtractMonths` Subtracts a specified number of months from a date **Signature:** `subtractMonths(date, months)` **Example:** ```txt theme={null} subtractMonths("2023-01-01T00:00:00Z", 3) // "2022-10-01T00:00:00Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | subtractMonths(...)`. ### `subtractYears` Subtracts a specified number of years from a date **Signature:** `subtractYears(date, years)` **Example:** ```txt theme={null} subtractYears("2023-01-01T00:00:00Z", 2) // "2021-01-01T00:00:00Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | subtractYears(...)`. ### `timestamp` Returns milliseconds since epoch **Signature:** `timestamp(date)` **Example:** ```txt theme={null} timestamp("2025-01-15T10:30:45.123Z") // 1736937045123 ``` **Note:** It can also be written as a transform when the first value is the input: `value | timestamp(...)`. ### `toIsoDate` Converts a date object to an ISO date string **Signature:** `toIsoDate(date)` **Example:** ```txt theme={null} toIsoDate("2023-01-01T00:00:00Z") // "2023-01-01T00:00:00Z" ``` **Note:** It can also be written as a transform when the first value is the input: `value | toIsoDate(...)`. ### `weekOfYear` Returns the week number of the year for a given date **Signature:** `weekOfYear(date)` **Example:** ```txt theme={null} weekOfYear("2023-01-01T00:00:00Z") // 52 ``` **Note:** It can also be written as a transform when the first value is the input: `value | weekOfYear(...)`. ### `year` Returns UTC full year **Signature:** `year(date)` **Example:** ```txt theme={null} year("2025-01-15T10:30:45.123Z") // 2025 ``` **Note:** It can also be written as a transform when the first value is the input: `value | year(...)`. ## Before you publish * Start with a known value and confirm the expected result. * Handle null, empty text, and empty lists deliberately. * Do not place secrets, access tokens, or sensitive personal data in an expression. * Read [expression contexts and availability](/reference/expressions/contexts) before copying an expression between features. ![Date and time helpers in KayanOS](https://kayanos.app/docs-images/en/reference/expressions-helpers-date.png)