Intervals And Lists

List helpers are useful when you need predictable data structures for calendars, schedulers, availability grids, or reporting periods.

Create an inclusive day list

createDayList() returns every date from the start boundary through the end boundary.

import { function createDayList(start: Timestamp, end: Timestamp, now: Timestamp, weekdays?: number[], disabledBefore?: string | undefined, disabledAfter?: string | undefined, disabledWeekdays?: number[], disabledDays?: DisabledDays, max?: number, min?: number): Timestamp[]
Creates an inclusive list of Timestamp days between start and end. The returned days are formatted, marked with relative flags against `now`, and can include disabled metadata when disabled options are supplied.
@paramstart First day in the list.@paramend Last day boundary for the list.@paramnow Timestamp used to calculate relative flags.@paramweekdays Weekday numbers to include, from `0` Sunday to `6` Saturday.@paramdisabledBefore Disable days before this `YYYY-MM-DD` date.@paramdisabledAfter Disable days after this `YYYY-MM-DD` date.@paramdisabledWeekdays Weekday numbers to mark disabled.@paramdisabledDays Specific dates or date ranges to mark disabled.@parammax Maximum number of days to return.@parammin Minimum number of days to return.@returnsTimestamp days.
createDayList
, function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate
, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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`.
@paraminput Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.
parseTimestamp
} from '@timestamp-js/core'
const const start: Timestampstart = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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`.
@paraminput Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.
parseTimestamp
('2026-06-01')!
const const end: Timestampend = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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`.
@paraminput Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.
parseTimestamp
('2026-06-05')!
const const days: string[]days = function createDayList(start: Timestamp, end: Timestamp, now: Timestamp, weekdays?: number[], disabledBefore?: string | undefined, disabledAfter?: string | undefined, disabledWeekdays?: number[], disabledDays?: DisabledDays, max?: number, min?: number): Timestamp[]
Creates an inclusive list of Timestamp days between start and end. The returned days are formatted, marked with relative flags against `now`, and can include disabled metadata when disabled options are supplied.
@paramstart First day in the list.@paramend Last day boundary for the list.@paramnow Timestamp used to calculate relative flags.@paramweekdays Weekday numbers to include, from `0` Sunday to `6` Saturday.@paramdisabledBefore Disable days before this `YYYY-MM-DD` date.@paramdisabledAfter Disable days after this `YYYY-MM-DD` date.@paramdisabledWeekdays Weekday numbers to mark disabled.@paramdisabledDays Specific dates or date ranges to mark disabled.@parammax Maximum number of days to return.@parammin Minimum number of days to return.@returnsTimestamp days.
createDayList
(const start: Timestampstart, const end: Timestampend, const start: Timestampstart).Array<Timestamp>.map<string>(callbackfn: (value: Timestamp, index: number, array: Timestamp[]) => string, thisArg?: any): string[]
Calls a defined callback function on each element of an array, and returns an array that contains the results.
@paramcallbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.@paramthisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
map
(function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate
)
const days: string[]days // [ // "2026-06-01", // "2026-06-02", // "2026-06-03", // "2026-06-04", // "2026-06-05", // ]

Mark disabled days while building lists

createDayList() can apply disabled metadata as the list is generated. This is handy for date pickers, availability grids, and scheduler UIs.

import { function createDayList(start: Timestamp, end: Timestamp, now: Timestamp, weekdays?: number[], disabledBefore?: string | undefined, disabledAfter?: string | undefined, disabledWeekdays?: number[], disabledDays?: DisabledDays, max?: number, min?: number): Timestamp[]
Creates an inclusive list of Timestamp days between start and end. The returned days are formatted, marked with relative flags against `now`, and can include disabled metadata when disabled options are supplied.
@paramstart First day in the list.@paramend Last day boundary for the list.@paramnow Timestamp used to calculate relative flags.@paramweekdays Weekday numbers to include, from `0` Sunday to `6` Saturday.@paramdisabledBefore Disable days before this `YYYY-MM-DD` date.@paramdisabledAfter Disable days after this `YYYY-MM-DD` date.@paramdisabledWeekdays Weekday numbers to mark disabled.@paramdisabledDays Specific dates or date ranges to mark disabled.@parammax Maximum number of days to return.@parammin Minimum number of days to return.@returnsTimestamp days.
createDayList
, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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`.
@paraminput Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.
parseTimestamp
} from '@timestamp-js/core'
import type { type DisabledDays = DisabledDay[]
Collection of disabled-day declarations.
DisabledDays
} from '@timestamp-js/core'
const const start: Timestampstart = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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`.
@paraminput Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.
parseTimestamp
('2036-06-01')!
const const end: Timestampend = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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`.
@paraminput Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.
parseTimestamp
('2036-06-07')!
const const today: Timestamptoday = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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`.
@paraminput Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.
parseTimestamp
('2036-06-03')!
const const disabledDays: DisabledDaysdisabledDays: type DisabledDays = DisabledDay[]
Collection of disabled-day declarations.
DisabledDays
= [
'2036-06-04', { DisabledDayConfig.from?: string | undefined
Inclusive range start date in `YYYY-MM-DD` form.
from
: '2036-06-06', DisabledDayConfig.to?: string | undefined
Inclusive range end date in `YYYY-MM-DD` form.
to
: '2036-06-07', DisabledDayConfig.label?: string | undefined
Optional human-readable label for matching disabled dates.
label
: 'Maintenance' },
] const const days: Timestamp[]days = function createDayList(start: Timestamp, end: Timestamp, now: Timestamp, weekdays?: number[], disabledBefore?: string | undefined, disabledAfter?: string | undefined, disabledWeekdays?: number[], disabledDays?: DisabledDays, max?: number, min?: number): Timestamp[]
Creates an inclusive list of Timestamp days between start and end. The returned days are formatted, marked with relative flags against `now`, and can include disabled metadata when disabled options are supplied.
@paramstart First day in the list.@paramend Last day boundary for the list.@paramnow Timestamp used to calculate relative flags.@paramweekdays Weekday numbers to include, from `0` Sunday to `6` Saturday.@paramdisabledBefore Disable days before this `YYYY-MM-DD` date.@paramdisabledAfter Disable days after this `YYYY-MM-DD` date.@paramdisabledWeekdays Weekday numbers to mark disabled.@paramdisabledDays Specific dates or date ranges to mark disabled.@parammax Maximum number of days to return.@parammin Minimum number of days to return.@returnsTimestamp days.
createDayList
(
const start: Timestampstart, const end: Timestampend, const today: Timestamptoday, [0, 1, 2, 3, 4, 5, 6], var undefinedundefined, var undefinedundefined, [], const disabledDays: DisabledDaysdisabledDays, ) const days: Timestamp[]days.Array<Timestamp>.find(predicate: (value: Timestamp, index: number, obj: Timestamp[]) => unknown, thisArg?: any): Timestamp | undefined (+1 overload)
Returns the value of the first element in the array where predicate is true, and undefined otherwise.
@parampredicate find calls predicate once for each element of the array, in ascending order, until it finds one where predicate returns true. If such an element is found, find immediately returns that element value. Otherwise, find returns undefined.@paramthisArg If provided, it will be used as the this value for each invocation of predicate. If it is not provided, undefined is used instead.
find
((day: Timestampday) => day: Timestampday.Timestamp.date: string
Date string in `YYYY-MM-DD` form when the timestamp has a day.
date
=== '2036-06-04')?.Timestamp.disabled?: boolean | undefined
True when this timestamp represents a disabled date.
disabled
// true
const days: Timestamp[]days.Array<Timestamp>.find(predicate: (value: Timestamp, index: number, obj: Timestamp[]) => unknown, thisArg?: any): Timestamp | undefined (+1 overload)
Returns the value of the first element in the array where predicate is true, and undefined otherwise.
@parampredicate find calls predicate once for each element of the array, in ascending order, until it finds one where predicate returns true. If such an element is found, find immediately returns that element value. Otherwise, find returns undefined.@paramthisArg If provided, it will be used as the this value for each invocation of predicate. If it is not provided, undefined is used instead.
find
((day: Timestampday) => day: Timestampday.Timestamp.date: string
Date string in `YYYY-MM-DD` form when the timestamp has a day.
date
=== '2036-06-06')?.Timestamp.disabledLabel?: string | undefined
Optional human-readable label for a disabled date.
disabledLabel
// "Maintenance"

Mark one timestamp as disabled

Use updateDisabled() when you already have a timestamp and want to apply the same disabled-day rules without building a whole list.

import { function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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`.
@paraminput Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.
parseTimestamp
, function updateDisabled(timestamp: Timestamp, disabledBefore?: string, disabledAfter?: string, disabledWeekdays?: number[], disabledDays?: DisabledDays): Timestamp
Updates the passed Timestamp with disabled, if needed
@paramtimestamp The Timestamp to transform@paramdisabledBefore In `YYYY-MM-DD` format@paramdisabledAfter In `YYYY-MM-DD` format@paramdisabledWeekdays An array of numbers representing weekdays [0 = Sun, ..., 6 = Sat]@paramdisabledDays An array of days in 'YYYY-MM-DD' format. If an array with a pair of dates is in first array, then this is treated as a range. Object entries can include date/from/to plus color metadata.@returnsA new Timestamp
updateDisabled
} from '@timestamp-js/core'
import type { type DisabledDays = DisabledDay[]
Collection of disabled-day declarations.
DisabledDays
} from '@timestamp-js/core'
const const holiday: Timestampholiday = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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`.
@paraminput Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.
parseTimestamp
('2036-06-04')!
const const disabledDays: DisabledDaysdisabledDays: type DisabledDays = DisabledDay[]
Collection of disabled-day declarations.
DisabledDays
= [{ DisabledDayConfig.date?: string | undefined
Single disabled date in `YYYY-MM-DD` form.
date
: '2036-06-04', DisabledDayConfig.label?: string | undefined
Optional human-readable label for matching disabled dates.
label
: 'Holiday' }]
const const disabled: Timestampdisabled = function updateDisabled(timestamp: Timestamp, disabledBefore?: string, disabledAfter?: string, disabledWeekdays?: number[], disabledDays?: DisabledDays): Timestamp
Updates the passed Timestamp with disabled, if needed
@paramtimestamp The Timestamp to transform@paramdisabledBefore In `YYYY-MM-DD` format@paramdisabledAfter In `YYYY-MM-DD` format@paramdisabledWeekdays An array of numbers representing weekdays [0 = Sun, ..., 6 = Sat]@paramdisabledDays An array of days in 'YYYY-MM-DD' format. If an array with a pair of dates is in first array, then this is treated as a range. Object entries can include date/from/to plus color metadata.@returnsA new Timestamp
updateDisabled
(const holiday: Timestampholiday, var undefinedundefined, var undefinedundefined, [], const disabledDays: DisabledDaysdisabledDays)
const disabled: Timestampdisabled.Timestamp.disabled?: boolean | undefined
True when this timestamp represents a disabled date.
disabled
// true
const disabled: Timestampdisabled.Timestamp.disabledLabel?: string | undefined
Optional human-readable label for a disabled date.
disabledLabel
// "Holiday"

Create day intervals

createIntervalList() creates time slots for a single day. Pass the starting interval index, minutes per interval, total interval count, and the Timestamp to use for relative flags.

import { function createIntervalList(timestamp: Timestamp, first: number, minutes: number, count: number, now: Timestamp): Timestamp[]
Creates an array of interval Timestamp objects for one day.
@paramtimestamp Base date for the intervals.@paramfirst Starting interval index.@paramminutes Minutes between intervals, such as 60, 30, or 15.@paramcount Number of intervals to create.@paramnow Timestamp used to calculate relative flags.@returnsInterval Timestamp objects.
createIntervalList
, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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`.
@paraminput Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.
parseTimestamp
} from '@timestamp-js/core'
const const day: Timestampday = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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`.
@paraminput Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.
parseTimestamp
('2026-06-08')!
const const hourly: Timestamp[]hourly = function createIntervalList(timestamp: Timestamp, first: number, minutes: number, count: number, now: Timestamp): Timestamp[]
Creates an array of interval Timestamp objects for one day.
@paramtimestamp Base date for the intervals.@paramfirst Starting interval index.@paramminutes Minutes between intervals, such as 60, 30, or 15.@paramcount Number of intervals to create.@paramnow Timestamp used to calculate relative flags.@returnsInterval Timestamp objects.
createIntervalList
(const day: Timestampday, 0, 60, 24, const day: Timestampday)
const hourly: Timestamp[]hourly[0]?.Timestamp.time?: string | undefined
Formatted 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"
const hourly: Timestamp[]hourly[9]?.Timestamp.time?: string | undefined
Formatted time string. Minute precision is formatted as `HH:mm`; second precision as `HH:mm:ss`; millisecond precision as `HH:mm:ss.SSS`.
time
// "09:00"
const hourly: Timestamp[]hourly[23]?.Timestamp.time?: string | undefined
Formatted time string. Minute precision is formatted as `HH:mm`; second precision as `HH:mm:ss`; millisecond precision as `HH:mm:ss.SSS`.
time
// "23:00"

Build smaller picker lists

You can also create compact option lists for forms or filters.

import { function createIntervalList(timestamp: Timestamp, first: number, minutes: number, count: number, now: Timestamp): Timestamp[]
Creates an array of interval Timestamp objects for one day.
@paramtimestamp Base date for the intervals.@paramfirst Starting interval index.@paramminutes Minutes between intervals, such as 60, 30, or 15.@paramcount Number of intervals to create.@paramnow Timestamp used to calculate relative flags.@returnsInterval Timestamp objects.
createIntervalList
, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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`.
@paraminput Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.
parseTimestamp
} from '@timestamp-js/core'
const const day: Timestampday = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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`.
@paraminput Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.
parseTimestamp
('2026-06-08')!
const const businessHours: (string | undefined)[]businessHours = function createIntervalList(timestamp: Timestamp, first: number, minutes: number, count: number, now: Timestamp): Timestamp[]
Creates an array of interval Timestamp objects for one day.
@paramtimestamp Base date for the intervals.@paramfirst Starting interval index.@paramminutes Minutes between intervals, such as 60, 30, or 15.@paramcount Number of intervals to create.@paramnow Timestamp used to calculate relative flags.@returnsInterval Timestamp objects.
createIntervalList
(const day: Timestampday, 9, 60, 8, const day: Timestampday).Array<Timestamp>.map<string | undefined>(callbackfn: (value: Timestamp, index: number, array: Timestamp[]) => string | undefined, thisArg?: any): (string | undefined)[]
Calls a defined callback function on each element of an array, and returns an array that contains the results.
@paramcallbackfn A function that accepts up to three arguments. The map method calls the callbackfn function one time for each element in the array.@paramthisArg An object to which the this keyword can refer in the callbackfn function. If thisArg is omitted, undefined is used as the this value.
map
((timestamp: Timestamptimestamp) => timestamp: Timestamptimestamp.Timestamp.time?: string | undefined
Formatted time string. Minute precision is formatted as `HH:mm`; second precision as `HH:mm:ss`; millisecond precision as `HH:mm:ss.SSS`.
time
)
const businessHours: (string | undefined)[]businessHours // ["09:00", "10:00", "11:00", "12:00", "13:00", "14:00", "15:00", "16:00"]

Generate localized labels

Month and weekday labels use Intl.DateTimeFormat, so pass an explicit locale when server and client output must match.

import { function getMonthNames(type: string, locale: string): string[]
Retrieves localized month names.
@paramtype Format type: `narrow`, `short`, or `long`.@paramlocale Locale to use for formatting, such as `en-US`.@returnsLocalized month names in January-first order.
getMonthNames
, function getWeekdayNames(type: string, locale: string): string[]
Retrieves localized weekday names.
@paramtype Format type: `narrow`, `short`, or `long`.@paramlocale Locale to use for formatting, such as `en-US`.@returnsLocalized weekday names in Sunday-first order.
getWeekdayNames
} from '@timestamp-js/core'
function getWeekdayNames(type: string, locale: string): string[]
Retrieves localized weekday names.
@paramtype Format type: `narrow`, `short`, or `long`.@paramlocale Locale to use for formatting, such as `en-US`.@returnsLocalized weekday names in Sunday-first order.
getWeekdayNames
('long', 'en-US').Array<string>.slice(start?: number, end?: number): string[]
Returns a copy of a section of an array. For both start and end, a negative index can be used to indicate an offset from the end of the array. For example, -2 refers to the second to last element of the array.
@paramstart The beginning index of the specified portion of the array. If start is undefined, then the slice begins at index 0.@paramend The end index of the specified portion of the array. This is exclusive of the element at the index 'end'. If end is undefined, then the slice extends to the end of the array.
slice
(0, 3) // ["Sunday", "Monday", "Tuesday"]
function getMonthNames(type: string, locale: string): string[]
Retrieves localized month names.
@paramtype Format type: `narrow`, `short`, or `long`.@paramlocale Locale to use for formatting, such as `en-US`.@returnsLocalized month names in January-first order.
getMonthNames
('long', 'en-US').Array<string>.slice(start?: number, end?: number): string[]
Returns a copy of a section of an array. For both start and end, a negative index can be used to indicate an offset from the end of the array. For example, -2 refers to the second to last element of the array.
@paramstart The beginning index of the specified portion of the array. If start is undefined, then the slice begins at index 0.@paramend The end index of the specified portion of the array. This is exclusive of the element at the index 'end'. If end is undefined, then the slice extends to the end of the array.
slice
(0, 3) // ["January", "February", "March"]

Reuse formatter factories

Use formatter factories when your app needs labels one at a time instead of full arrays.

import { function getMonthFormatter(): MonthFormatter
Creates and returns a function for formatting month names based on locale and format type.
@returnsA function that formats month names. The returned function accepts the following parameters:@parammonth - The month to format (0-11, where 0 is January).@paramtype - The format type: 'narrow', 'short', or 'long'.@paramlocale - The locale to use for formatting. If not provided, the default locale is used.@returnsThe formatted month name.@throws{Error} If Intl or Intl.DateTimeFormat is not supported in the environment.
getMonthFormatter
, function getWeekdayFormatter(): WeekdayFormatter
Returns a function that uses Intl.DateTimeFormat to format weekdays.
@functiongetWeekdayFormatter@returnsA function that formats weekdays.@exampleconst formatWeekday = getWeekdayFormatter(); console.log(formatWeekday('Mon', 'long', 'en-US')); // "Monday" console.log(formatWeekday('Mon', 'short', 'fr-FR')); // "lun."@paramweekday - The abbreviation of the weekday (e.g., 'Mon', 'Tue', 'Wed', etc.).@paramtype - The type of formatting to use ('narrow', 'short', or 'long').@paramlocale - The locale to use for formatting.@returnsThe formatted weekday.
getWeekdayFormatter
} from '@timestamp-js/core'
const const formatWeekday: WeekdayFormatterformatWeekday = function getWeekdayFormatter(): WeekdayFormatter
Returns a function that uses Intl.DateTimeFormat to format weekdays.
@functiongetWeekdayFormatter@returnsA function that formats weekdays.@exampleconst formatWeekday = getWeekdayFormatter(); console.log(formatWeekday('Mon', 'long', 'en-US')); // "Monday" console.log(formatWeekday('Mon', 'short', 'fr-FR')); // "lun."@paramweekday - The abbreviation of the weekday (e.g., 'Mon', 'Tue', 'Wed', etc.).@paramtype - The type of formatting to use ('narrow', 'short', or 'long').@paramlocale - The locale to use for formatting.@returnsThe formatted weekday.
getWeekdayFormatter
()
const const formatMonth: MonthFormatterformatMonth = function getMonthFormatter(): MonthFormatter
Creates and returns a function for formatting month names based on locale and format type.
@returnsA function that formats month names. The returned function accepts the following parameters:@parammonth - The month to format (0-11, where 0 is January).@paramtype - The format type: 'narrow', 'short', or 'long'.@paramlocale - The locale to use for formatting. If not provided, the default locale is used.@returnsThe formatted month name.@throws{Error} If Intl or Intl.DateTimeFormat is not supported in the environment.
getMonthFormatter
()
const formatWeekday: (_weekday: "Sun" | "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat", _type: string, _locale?: string) => stringformatWeekday('Mon', 'short', 'en-US') // "Mon" const formatMonth: (_month: number, _type?: string, _locale?: string) => stringformatMonth(5, 'long', 'en-US') // "June"

Create custom native locale formatters

createNativeLocaleFormatter() lets you share one host-local formatting strategy and switch options per call. Use createNativeLocaleFormatterUTC() when the timestamp should be converted to a native Date from UTC fields before formatting.

import {
  function createNativeLocaleFormatter(locale: string, cb: LocaleFormatter): (_timestamp: Timestamp, _short: boolean) => string
Returns a host-local locale formatter backed by `Intl.DateTimeFormat`. The helper is SSR-safe: if `Intl.DateTimeFormat` is unavailable in a target runtime, it returns a formatter that produces an empty string instead of throwing during module load. Use `createNativeLocaleFormatterUTC()` when Timestamp values should be read as UTC fields before formatting.
@paramlocale The locale to use (ie: en-US)@paramcb The function to call for options. This function should return an Intl formatted object. The function is passed (timestamp, short).@returnsThe function has params (timestamp, short). The short is to use the short options.
createNativeLocaleFormatter
,
function createNativeLocaleFormatterUTC(locale: string, cb: LocaleFormatter): (_timestamp: Timestamp, _short: boolean) => string
Returns a UTC locale formatter backed by `Intl.DateTimeFormat`. This helper constructs the native `Date` with UTC fields before formatting. Pair it with `timeZone: "UTC"` when calendar labels must remain pinned to the Timestamp's UTC date instead of the viewer's local timezone.
@paramlocale The locale to use (ie: en-US)@paramcb The function to call for options. This function should return an Intl formatted object. The function is passed (timestamp, short).@returnsThe function has params (timestamp, short). The short is to use the short options.
createNativeLocaleFormatterUTC
,
function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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`.
@paraminput Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.
parseTimestamp
,
} from '@timestamp-js/core' const const formatDate: (_timestamp: Timestamp, _short: boolean) => stringformatDate = function createNativeLocaleFormatter(locale: string, cb: LocaleFormatter): (_timestamp: Timestamp, _short: boolean) => string
Returns a host-local locale formatter backed by `Intl.DateTimeFormat`. The helper is SSR-safe: if `Intl.DateTimeFormat` is unavailable in a target runtime, it returns a formatter that produces an empty string instead of throwing during module load. Use `createNativeLocaleFormatterUTC()` when Timestamp values should be read as UTC fields before formatting.
@paramlocale The locale to use (ie: en-US)@paramcb The function to call for options. This function should return an Intl formatted object. The function is passed (timestamp, short).@returnsThe function has params (timestamp, short). The short is to use the short options.
createNativeLocaleFormatter
('en-US', (_timestamp: Timestamp_timestamp, short: booleanshort) => ({
Intl.DateTimeFormatOptions.dateStyle?: "medium" | "full" | "long" | "short" | undefineddateStyle: short: booleanshort ? 'medium' : 'full', })) const const formatDateUTC: (_timestamp: Timestamp, _short: boolean) => stringformatDateUTC = function createNativeLocaleFormatterUTC(locale: string, cb: LocaleFormatter): (_timestamp: Timestamp, _short: boolean) => string
Returns a UTC locale formatter backed by `Intl.DateTimeFormat`. This helper constructs the native `Date` with UTC fields before formatting. Pair it with `timeZone: "UTC"` when calendar labels must remain pinned to the Timestamp's UTC date instead of the viewer's local timezone.
@paramlocale The locale to use (ie: en-US)@paramcb The function to call for options. This function should return an Intl formatted object. The function is passed (timestamp, short).@returnsThe function has params (timestamp, short). The short is to use the short options.
createNativeLocaleFormatterUTC
('en-US', (_timestamp: Timestamp_timestamp, short: booleanshort) => ({
Intl.DateTimeFormatOptions.dateStyle?: "medium" | "full" | "long" | "short" | undefineddateStyle: short: booleanshort ? 'medium' : 'full', Intl.DateTimeFormatOptions.timeZone?: string | undefinedtimeZone: 'UTC', })) const const timestamp: Timestamptimestamp = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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`.
@paraminput Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.
parseTimestamp
('2036-06-08')!
const formatDate: (_timestamp: Timestamp, _short: boolean) => stringformatDate(const timestamp: Timestamptimestamp, true) // "Jun 8, 2036" const formatDate: (_timestamp: Timestamp, _short: boolean) => stringformatDate(const timestamp: Timestamptimestamp, false) // "Sunday, June 8, 2036" const formatDateUTC: (_timestamp: Timestamp, _short: boolean) => stringformatDateUTC(const timestamp: Timestamptimestamp, true) // "Jun 8, 2036"