Use these helpers when app code needs to accept external input, guard form values, or build calendar-style boundaries before doing date math.
Validate before parsing
validateTimestamp() is a lightweight grammar check. Use parseTimestamp() when you need a full immutable object.
import { function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts a supported date or date-time string into a formatted Timestamp object.
If `now` is supplied, the returned timestamp also includes relative flags
such as `past`, `current`, `future`, and `currentWeekday`.parseTimestamp, function validateTimestamp(input: string): booleanValidates whether an input string matches the supported timestamp grammar.validateTimestamp } from '@timestamp-js/core'
function validateTimestamp(input: string): booleanValidates whether an input string matches the supported timestamp grammar.validateTimestamp('2036-06-08T09:30:15.250Z') // true
function validateTimestamp(input: string): booleanValidates whether an input string matches the supported timestamp grammar.validateTimestamp('not a date') // false
const const timestamp: Timestamp | nulltimestamp = function validateTimestamp(input: string): booleanValidates whether an input string matches the supported timestamp grammar.validateTimestamp('2036-06-08') ? function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts a supported date or date-time string into a formatted Timestamp object.
If `now` is supplied, the returned timestamp also includes relative flags
such as `past`, `current`, `future`, and `currentWeekday`.parseTimestamp('2036-06-08') : null
const timestamp: Timestamp | nulltimestamp?.Timestamp.date: string | undefinedDate string in `YYYY-MM-DD` form when the timestamp has a day.date // "2036-06-08"Use the low-level parser when you only need fields
parsed() is intentionally smaller than parseTimestamp(). It reads fields and preserves timezone suffixes, but does not fill derived values such as weekday, day of year, or workweek.
import { function parsed(input: string): Timestamp | nullFast low-level parser for date and date-time strings.
This parser fills numeric fields, but does not update formatted date,
weekday, day-of-year, workweek, or relative flags. Use parseTimestamp()
when those derived fields are needed.parsed, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts a supported date or date-time string into a formatted Timestamp object.
If `now` is supplied, the returned timestamp also includes relative flags
such as `past`, `current`, `future`, and `currentWeekday`.parseTimestamp } from '@timestamp-js/core'
const const minimal: Timestampminimal = function parsed(input: string): Timestamp | nullFast low-level parser for date and date-time strings.
This parser fills numeric fields, but does not update formatted date,
weekday, day-of-year, workweek, or relative flags. Use parseTimestamp()
when those derived fields are needed.parsed('2036-06-08T09:30:15-07:00')!
const const formatted: Timestampformatted = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts a supported date or date-time string into a formatted Timestamp object.
If `now` is supplied, the returned timestamp also includes relative flags
such as `past`, `current`, `future`, and `currentWeekday`.parseTimestamp('2036-06-08T09:30:15-07:00')!
const minimal: Timestampminimal.Timestamp.timezone?: string | undefinedOptional parsed ISO timezone suffix such as `Z`, `+06:00`, or `-0700`.
The suffix is preserved for callers, but parsing does not convert the
wall-clock values into another timezone.timezone // "-07:00"
const minimal: Timestampminimal.Timestamp.doy?: number | undefinedDay of the year.doy // 0
const formatted: Timestampformatted.Timestamp.doy?: number | undefinedDay of the year.doy // 160Validate numeric input
validateNumber() is useful before converting text input into offsets, intervals, or form-driven date math.
import { function validateNumber(input: string | number): booleanValidates if the input is a finite number.validateNumber } from '@timestamp-js/core'
function validateNumber(input: string | number): booleanValidates if the input is a finite number.validateNumber('15') // true
function validateNumber(input: string | number): booleanValidates if the input is a finite number.validateNumber(30) // true
function validateNumber(input: string | number): booleanValidates if the input is a finite number.validateNumber('fifteen') // falseInspect Gregorian month facts
Use isLeapYear() and daysInMonth() when you need to explain or constrain calendar choices.
import { function daysInMonth(year: number, month: number, calendar?: CalendarSystem): numberReturns the days of the specified month in a yeardaysInMonth, function isLeapYear(year: number, calendar?: CalendarSystem): booleanReturns if the passed year is a leap yearisLeapYear } from '@timestamp-js/core'
function isLeapYear(year: number, calendar?: CalendarSystem): booleanReturns if the passed year is a leap yearisLeapYear(2036) // true
function daysInMonth(year: number, month: number, calendar?: CalendarSystem): numberReturns the days of the specified month in a yeardaysInMonth(2036, 2) // 29
function daysInMonth(year: number, month: number, calendar?: CalendarSystem): numberReturns the days of the specified month in a yeardaysInMonth(2037, 2) // 28Format small numeric pieces
padNumber() is intentionally simple, but it keeps custom output consistent with Timestamp’s own formatting.
import { function padNumber(x: number, length: number): stringPads a number to a requested string length.
Useful for formatting values such as `5` as `05`.padNumber } from '@timestamp-js/core'
function padNumber(x: number, length: number): stringPads a number to a requested string length.
Useful for formatting values such as `5` as `05`.padNumber(7, 2) // "07"
function padNumber(x: number, length: number): stringPads a number to a requested string length.
Useful for formatting values such as `5` as `05`.padNumber(42, 4) // "0042"Read period boundaries
Start/end helpers are useful for month grids, week views, and reporting ranges.
import {
function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.getDate,
function getEndOfDay(timestamp: Timestamp): TimestampReturns a Timestamp at the end of the same calendar day.getEndOfDay,
function getEndOfMonth(timestamp: Timestamp, calendar?: CalendarSystem): TimestampFinds the end of the month based on the passed in TimestampgetEndOfMonth,
function getEndOfWeek(timestamp: Timestamp, weekdays: number[], today: Timestamp, calendar?: CalendarSystem): TimestampReturns the end of the week for a Timestamp and weekday set.
If a current Timestamp is provided, the returned Timestamp includes updated relative information.getEndOfWeek,
function getEndOfYear(timestamp: Timestamp, calendar?: CalendarSystem): TimestampReturns a Timestamp at the end of the same calendar year.getEndOfYear,
function getStartOfDay(timestamp: Timestamp): TimestampReturns a Timestamp at the start of the same calendar day.getStartOfDay,
function getStartOfMonth(timestamp: Timestamp, calendar?: CalendarSystem): TimestampFinds the start of the month based on the passed in TimestampgetStartOfMonth,
function getStartOfWeek(timestamp: Timestamp, weekdays: number[], today: Timestamp, calendar?: CalendarSystem): TimestampReturns the start of the week for a Timestamp and weekday set.
If a current Timestamp is provided, the returned Timestamp includes updated relative information.getStartOfWeek,
function getStartOfYear(timestamp: Timestamp, calendar?: CalendarSystem): TimestampReturns a Timestamp at the start of the same calendar year.getStartOfYear,
function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts a supported date or date-time string into a formatted Timestamp object.
If `now` is supplied, the returned timestamp also includes relative flags
such as `past`, `current`, `future`, and `currentWeekday`.parseTimestamp,
} from '@timestamp-js/core'
const const now: Timestampnow = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts a supported date or date-time string into a formatted Timestamp object.
If `now` is supplied, the returned timestamp also includes relative flags
such as `past`, `current`, `future`, and `currentWeekday`.parseTimestamp('2036-06-08')!
const const weekdays: number[]weekdays = [0, 1, 2, 3, 4, 5, 6]
function getStartOfDay(timestamp: Timestamp): TimestampReturns a Timestamp at the start of the same calendar day.getStartOfDay(const now: Timestampnow).Timestamp.time?: string | undefinedFormatted time string.
Minute precision is formatted as `HH:mm`; second precision as `HH:mm:ss`;
millisecond precision as `HH:mm:ss.SSS`.time // "00:00"
function getEndOfDay(timestamp: Timestamp): TimestampReturns a Timestamp at the end of the same calendar day.getEndOfDay(const now: Timestampnow).Timestamp.time?: string | undefinedFormatted time string.
Minute precision is formatted as `HH:mm`; second precision as `HH:mm:ss`;
millisecond precision as `HH:mm:ss.SSS`.time // "23:59:59.999"
function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.getDate(function getStartOfWeek(timestamp: Timestamp, weekdays: number[], today: Timestamp, calendar?: CalendarSystem): TimestampReturns the start of the week for a Timestamp and weekday set.
If a current Timestamp is provided, the returned Timestamp includes updated relative information.getStartOfWeek(const now: Timestampnow, const weekdays: number[]weekdays, const now: Timestampnow)) // "2036-06-08"
function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.getDate(function getEndOfWeek(timestamp: Timestamp, weekdays: number[], today: Timestamp, calendar?: CalendarSystem): TimestampReturns the end of the week for a Timestamp and weekday set.
If a current Timestamp is provided, the returned Timestamp includes updated relative information.getEndOfWeek(const now: Timestampnow, const weekdays: number[]weekdays, const now: Timestampnow)) // "2036-06-14"
function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.getDate(function getStartOfMonth(timestamp: Timestamp, calendar?: CalendarSystem): TimestampFinds the start of the month based on the passed in TimestampgetStartOfMonth(const now: Timestampnow)) // "2036-06-01"
function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.getDate(function getEndOfMonth(timestamp: Timestamp, calendar?: CalendarSystem): TimestampFinds the end of the month based on the passed in TimestampgetEndOfMonth(const now: Timestampnow)) // "2036-06-30"
function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.getDate(function getStartOfYear(timestamp: Timestamp, calendar?: CalendarSystem): TimestampReturns a Timestamp at the start of the same calendar year.getStartOfYear(const now: Timestampnow)) // "2036-01-01"
function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.getDate(function getEndOfYear(timestamp: Timestamp, calendar?: CalendarSystem): TimestampReturns a Timestamp at the end of the same calendar year.getEndOfYear(const now: Timestampnow)) // "2036-12-31"Convert Unix epoch values
Unix helpers read and write Timestamp fields as UTC. Use them when storage or APIs use epoch seconds or milliseconds.
import {
function fromUnixMilliseconds(milliseconds: number): Timestamp | nullConverts Unix milliseconds into an immutable Timestamp using UTC fields.fromUnixMilliseconds,
function fromUnixSeconds(seconds: number): Timestamp | nullConverts Unix seconds into an immutable Timestamp using UTC fields.fromUnixSeconds,
function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.getDateTime,
function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts a supported date or date-time string into a formatted Timestamp object.
If `now` is supplied, the returned timestamp also includes relative flags
such as `past`, `current`, `future`, and `currentWeekday`.parseTimestamp,
function toUnixMilliseconds(timestamp: Timestamp): numberConverts a Timestamp into Unix milliseconds by reading its fields as UTC.
This is deterministic across server and client runtimes. It does not read or
convert the optional `timezone` suffix stored on the Timestamp.toUnixMilliseconds,
function toUnixSeconds(timestamp: Timestamp): numberConverts a Timestamp into Unix seconds by reading its fields as UTC.
Milliseconds are floored because Unix seconds are integer-oriented.toUnixSeconds,
} from '@timestamp-js/core'
const const timestamp: Timestamptimestamp = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts a supported date or date-time string into a formatted Timestamp object.
If `now` is supplied, the returned timestamp also includes relative flags
such as `past`, `current`, `future`, and `currentWeekday`.parseTimestamp('2036-06-08T09:30:15.250')!
const const milliseconds: numbermilliseconds = function toUnixMilliseconds(timestamp: Timestamp): numberConverts a Timestamp into Unix milliseconds by reading its fields as UTC.
This is deterministic across server and client runtimes. It does not read or
convert the optional `timezone` suffix stored on the Timestamp.toUnixMilliseconds(const timestamp: Timestamptimestamp)
const const seconds: numberseconds = function toUnixSeconds(timestamp: Timestamp): numberConverts a Timestamp into Unix seconds by reading its fields as UTC.
Milliseconds are floored because Unix seconds are integer-oriented.toUnixSeconds(const timestamp: Timestamptimestamp)
function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.getDateTime(function fromUnixMilliseconds(milliseconds: number): Timestamp | nullConverts Unix milliseconds into an immutable Timestamp using UTC fields.fromUnixMilliseconds(const milliseconds: numbermilliseconds)!) // "2036-06-08 09:30:15.250"
function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.getDateTime(function fromUnixSeconds(seconds: number): Timestamp | nullConverts Unix seconds into an immutable Timestamp using UTC fields.fromUnixSeconds(const seconds: numberseconds)!) // "2036-06-08 09:30:15"Read and refresh derived fields
Parser helpers fill these values for normal use. The explicit helpers are useful when code creates or transforms timestamp-like objects and then needs fresh derived metadata.
import {
function getDayOfYear(timestamp: Timestamp, calendar?: CalendarSystem): number | voidReturns day of the year (doy) for the passed in TimestampgetDayOfYear,
function getWeekday(timestamp: Timestamp, calendar?: CalendarSystem): numberReturns weekday for the passed in TimestampgetWeekday,
function getWorkWeek(timestamp: Timestamp, calendar?: CalendarSystem): numberReturns workweek for the passed in TimestampgetWorkWeek,
function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts a supported date or date-time string into a formatted Timestamp object.
If `now` is supplied, the returned timestamp also includes relative flags
such as `past`, `current`, `future`, and `currentWeekday`.parseTimestamp,
function updateDayOfYear(timestamp: Timestamp, calendar?: CalendarSystem): TimestampUpdates the Timestamp with the day of the year (doy)updateDayOfYear,
function updateWeekday(timestamp: Timestamp, calendar?: CalendarSystem): TimestampUpdates the Timestamp with the weekdayupdateWeekday,
function updateWorkWeek(timestamp: Timestamp, calendar?: CalendarSystem): TimestampUpdates the Timestamp with the workweekupdateWorkWeek,
} from '@timestamp-js/core'
const const timestamp: Timestamptimestamp = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts a supported date or date-time string into a formatted Timestamp object.
If `now` is supplied, the returned timestamp also includes relative flags
such as `past`, `current`, `future`, and `currentWeekday`.parseTimestamp('2036-06-08')!
function getWeekday(timestamp: Timestamp, calendar?: CalendarSystem): numberReturns weekday for the passed in TimestampgetWeekday(const timestamp: Timestamptimestamp) // 0
function getDayOfYear(timestamp: Timestamp, calendar?: CalendarSystem): number | voidReturns day of the year (doy) for the passed in TimestampgetDayOfYear(const timestamp: Timestamptimestamp) // 160
function getWorkWeek(timestamp: Timestamp, calendar?: CalendarSystem): numberReturns workweek for the passed in TimestampgetWorkWeek(const timestamp: Timestamptimestamp) // 23
function updateWeekday(timestamp: Timestamp, calendar?: CalendarSystem): TimestampUpdates the Timestamp with the weekdayupdateWeekday(const timestamp: Timestamptimestamp).Timestamp.weekday?: number | undefinedWeekday number where Sunday is `0` and Saturday is `6`.weekday // 0
function updateDayOfYear(timestamp: Timestamp, calendar?: CalendarSystem): TimestampUpdates the Timestamp with the day of the year (doy)updateDayOfYear(const timestamp: Timestamptimestamp).Timestamp.doy?: number | undefinedDay of the year.doy // 160
function updateWorkWeek(timestamp: Timestamp, calendar?: CalendarSystem): TimestampUpdates the Timestamp with the workweekupdateWorkWeek(const timestamp: Timestamptimestamp).Timestamp.workweek?: number | undefinedISO-style workweek number.workweek // 23Reuse shared constants sparingly
Constants are best when your app needs to avoid duplicate magic numbers.
import {
const DAYS_IN_WEEK: numberNumber of days in a week.DAYS_IN_WEEK,
const HOURS_IN_DAY: numberNumber of hours in a day.HOURS_IN_DAY,
const MILLISECONDS_IN_DAY: numberNumber of milliseconds in one day.MILLISECONDS_IN_DAY,
const MILLISECONDS_IN_HOUR: numberNumber of milliseconds in one hour.MILLISECONDS_IN_HOUR,
const MILLISECONDS_IN_MINUTE: numberNumber of milliseconds in one minute.MILLISECONDS_IN_MINUTE,
const MILLISECONDS_IN_SECOND: numberNumber of milliseconds in one second.MILLISECONDS_IN_SECOND,
const MINUTES_IN_HOUR: numberNumber of minutes in an hour.MINUTES_IN_HOUR,
const SECONDS_IN_DAY: numberNumber of seconds in one day.SECONDS_IN_DAY,
const SECONDS_IN_HOUR: numberNumber of seconds in one hour.SECONDS_IN_HOUR,
const SECONDS_IN_MINUTE: numberNumber of seconds in one minute.SECONDS_IN_MINUTE,
const TIME_CONSTANTS: {
MILLISECONDS_IN: {
SECOND: number;
MINUTE: number;
HOUR: number;
DAY: number;
WEEK: number;
};
SECONDS_IN: {
MINUTE: number;
HOUR: number;
DAY: number;
WEEK: number;
};
MINUTES_IN: {
MINUTE: number;
HOUR: number;
DAY: number;
WEEK: number;
};
HOURS_IN: {
DAY: number;
WEEK: number;
};
DAYS_IN: {
WEEK: number;
};
}
const DAYS_IN_WEEK: numberNumber of days in a week.DAYS_IN_WEEK // 7
const HOURS_IN_DAY: numberNumber of hours in a day.HOURS_IN_DAY // 24
const MINUTES_IN_HOUR: numberNumber of minutes in an hour.MINUTES_IN_HOUR // 60
const SECONDS_IN_MINUTE: numberNumber of seconds in one minute.SECONDS_IN_MINUTE // 60
const SECONDS_IN_HOUR: numberNumber of seconds in one hour.SECONDS_IN_HOUR // 3600
const SECONDS_IN_DAY: numberNumber of seconds in one day.SECONDS_IN_DAY // 86400
const MILLISECONDS_IN_SECOND: numberNumber of milliseconds in one second.MILLISECONDS_IN_SECOND // 1000
const MILLISECONDS_IN_MINUTE: numberNumber of milliseconds in one minute.MILLISECONDS_IN_MINUTE // 60000
const MILLISECONDS_IN_HOUR: numberNumber of milliseconds in one hour.MILLISECONDS_IN_HOUR // 3600000
const MILLISECONDS_IN_DAY: numberNumber of milliseconds in one day.MILLISECONDS_IN_DAY // 86400000
const TIME_CONSTANTS: {
MILLISECONDS_IN: {
SECOND: number;
MINUTE: number;
HOUR: number;
DAY: number;
WEEK: number;
};
SECONDS_IN: {
MINUTE: number;
HOUR: number;
DAY: number;
WEEK: number;
};
MINUTES_IN: {
MINUTE: number;
HOUR: number;
DAY: number;
WEEK: number;
};
HOURS_IN: {
DAY: number;
WEEK: number;
};
DAYS_IN: {
WEEK: number;
};
}
type SECONDS_IN: {
MINUTE: number;
HOUR: number;
DAY: number;
WEEK: number;
}
type HOUR: numberHOUR // 3600