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.createDayList, function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.getDate, 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 start: Timestampstart = 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('2026-06-01')!
const const end: Timestampend = 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('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.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.map(function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.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.createDayList, 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'
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 | 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-01')!
const const end: Timestampend = 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-07')!
const const today: Timestamptoday = 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-03')!
const const disabledDays: DisabledDaysdisabledDays: type DisabledDays = DisabledDay[]Collection of disabled-day declarations.DisabledDays = [
'2036-06-04',
{ DisabledDayConfig.from?: string | undefinedInclusive range start date in `YYYY-MM-DD` form.from: '2036-06-06', DisabledDayConfig.to?: string | undefinedInclusive range end date in `YYYY-MM-DD` form.to: '2036-06-07', DisabledDayConfig.label?: string | undefinedOptional 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.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.find((day: Timestampday) => day: Timestampday.Timestamp.date: stringDate string in `YYYY-MM-DD` form when the timestamp has a day.date === '2036-06-04')?.Timestamp.disabled?: boolean | undefinedTrue 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.find((day: Timestampday) => day: Timestampday.Timestamp.date: stringDate string in `YYYY-MM-DD` form when the timestamp has a day.date === '2036-06-06')?.Timestamp.disabledLabel?: string | undefinedOptional 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 | 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 updateDisabled(timestamp: Timestamp, disabledBefore?: string, disabledAfter?: string, disabledWeekdays?: number[], disabledDays?: DisabledDays): TimestampUpdates the passed Timestamp with disabled, if neededupdateDisabled } 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 | 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-04')!
const const disabledDays: DisabledDaysdisabledDays: type DisabledDays = DisabledDay[]Collection of disabled-day declarations.DisabledDays = [{ DisabledDayConfig.date?: string | undefinedSingle disabled date in `YYYY-MM-DD` form.date: '2036-06-04', DisabledDayConfig.label?: string | undefinedOptional 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): TimestampUpdates the passed Timestamp with disabled, if neededupdateDisabled(const holiday: Timestampholiday, var undefinedundefined, var undefinedundefined, [], const disabledDays: DisabledDaysdisabledDays)
const disabled: Timestampdisabled.Timestamp.disabled?: boolean | undefinedTrue when this timestamp represents a disabled date.disabled // true
const disabled: Timestampdisabled.Timestamp.disabledLabel?: string | undefinedOptional 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.createIntervalList, 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 day: Timestampday = 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('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.createIntervalList(const day: Timestampday, 0, 60, 24, const day: Timestampday)
const hourly: Timestamp[]hourly[0]?.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"
const hourly: Timestamp[]hourly[9]?.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 // "09:00"
const hourly: Timestamp[]hourly[23]?.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: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.createIntervalList, 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 day: Timestampday = 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('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.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.map((timestamp: Timestamptimestamp) => timestamp: Timestamptimestamp.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)
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.getMonthNames, function getWeekdayNames(type: string, locale: string): string[]Retrieves localized weekday names.getWeekdayNames } from '@timestamp-js/core'
function getWeekdayNames(type: string, locale: string): string[]Retrieves localized weekday names.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.slice(0, 3) // ["Sunday", "Monday", "Tuesday"]
function getMonthNames(type: string, locale: string): string[]Retrieves localized month names.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.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(): MonthFormatterCreates and returns a function for formatting month names based on locale and format type.getMonthFormatter, function getWeekdayFormatter(): WeekdayFormatterReturns a function that uses Intl.DateTimeFormat to format weekdays.getWeekdayFormatter } from '@timestamp-js/core'
const const formatWeekday: WeekdayFormatterformatWeekday = function getWeekdayFormatter(): WeekdayFormatterReturns a function that uses Intl.DateTimeFormat to format weekdays.getWeekdayFormatter()
const const formatMonth: MonthFormatterformatMonth = function getMonthFormatter(): MonthFormatterCreates and returns a function for formatting month names based on locale and format type.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) => stringReturns 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.createNativeLocaleFormatter,
function createNativeLocaleFormatterUTC(locale: string, cb: LocaleFormatter): (_timestamp: Timestamp, _short: boolean) => stringReturns 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.createNativeLocaleFormatterUTC,
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 formatDate: (_timestamp: Timestamp, _short: boolean) => stringformatDate = function createNativeLocaleFormatter(locale: string, cb: LocaleFormatter): (_timestamp: Timestamp, _short: boolean) => stringReturns 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.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) => stringReturns 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.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 | 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 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"