QCalendar emits and receives date-like strings, date-time strings, and Timestamp objects in slots and events. Use @timestamp-js/core when application logic needs deterministic range math, interval snapping, durations, or UTC storage boundaries.
The calendar stays focused on rendering and interaction. Timestamp owns the reusable date/time primitives.
Range Windows And Disabled Days
Use Timestamp range helpers to normalize unavailable periods before passing them to disabled-days, selected-start-end-dates, or a day-class function.
The important pieces are:
import {
function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRangeCreates an inclusive Timestamp range and normalizes start/end order.createTimestampRange,
function findRangeGaps(source: TimestampRange, occupied: TimestampRange[], useTime?: boolean): TimestampRange[]Finds open gaps inside a source range after occupied ranges are removed.
This is an alias for subtractRanges() with naming that reads naturally in
booking, resource, and availability workflows.findRangeGaps,
function isTimestampInRange(timestamp: Timestamp, range: TimestampRange, useTime?: boolean): booleanChecks whether a Timestamp falls inside an inclusive TimestampRange.isTimestampInRange,
function mergeRanges(ranges: TimestampRange[], useTime?: boolean): TimestampRange[]Merges overlapping or touching TimestampRange values.
Date-only ranges touch when the next range starts on the next calendar day.
Time-aware ranges touch when the next range starts one millisecond after the
previous range ends.mergeRanges,
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 windowStart: TimestampwindowStart = 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 windowEnd: TimestampwindowEnd = 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-30')!
const const bookingWindow: TimestampRangebookingWindow = function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRangeCreates an inclusive Timestamp range and normalizes start/end order.createTimestampRange(const windowStart: TimestampwindowStart, const windowEnd: TimestampwindowEnd)
const const blocked: TimestampRange[]blocked = function mergeRanges(ranges: TimestampRange[], useTime?: boolean): TimestampRange[]Merges overlapping or touching TimestampRange values.
Date-only ranges touch when the next range starts on the next calendar day.
Time-aware ranges touch when the next range starts one millisecond after the
previous range ends.mergeRanges([
function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRangeCreates an inclusive Timestamp range and normalizes start/end order.createTimestampRange(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')!, 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-05')!),
function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRangeCreates an inclusive Timestamp range and normalizes start/end order.createTimestampRange(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-14')!, 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-18')!),
])
const const available: TimestampRange[]available = function findRangeGaps(source: TimestampRange, occupied: TimestampRange[], useTime?: boolean): TimestampRange[]Finds open gaps inside a source range after occupied ranges are removed.
This is an alias for subtractRanges() with naming that reads naturally in
booking, resource, and availability workflows.findRangeGaps(const bookingWindow: TimestampRangebookingWindow, const blocked: TimestampRange[]blocked)
const const isAvailable: booleanisAvailable = function isTimestampInRange(timestamp: Timestamp, range: TimestampRange, useTime?: boolean): booleanChecks whether a Timestamp falls inside an inclusive TimestampRange.isTimestampInRange(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-10')!, const available: TimestampRange[]available[0]!)Snap Scheduler Intervals
Use time-clicks-clamped when you want QCalendar to return the interval the pointer is inside. Use Timestamp rounding helpers when the application needs a different snapping rule than the visible interval grid.
The same pattern works for drag and drop, scheduler resources, and appointment builders:
import {
function addDuration(timestamp: Timestamp, duration: TimestampDuration | number): TimestampAdds an elapsed duration to a Timestamp.
This helper treats the Timestamp fields as UTC and returns a Timestamp built
from UTC fields. Use addToDate() for calendar-unit arithmetic such as
"one month from now".addDuration,
function createDuration(milliseconds: number): TimestampDurationCreates a TimestampDuration from signed milliseconds.createDuration,
function durationBetween(start: Timestamp, end: Timestamp): TimestampDurationMeasures the elapsed duration between two Timestamp values.
Timestamp fields are read as UTC so the result is deterministic across
server and client runtimes.durationBetween,
function formatDuration(duration: TimestampDuration | number, options?: FormatDurationOptions): stringFormats a duration as `HH:mm:ss` or `HH:mm:ss.SSS`.
Hours include full days, so a two-day duration formats as `48:00:00`.formatDuration,
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 roundToInterval(timestamp: Timestamp, minutes: number): TimestampRounds a Timestamp to the nearest interval.roundToInterval,
} from '@timestamp-js/core'
const const clicked: Timestampclicked = 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 09:37')!
const const start: Timestampstart = function roundToInterval(timestamp: Timestamp, minutes: number): TimestampRounds a Timestamp to the nearest interval.roundToInterval(const clicked: Timestampclicked, 30)
const const end: Timestampend = function addDuration(timestamp: Timestamp, duration: TimestampDuration | number): TimestampAdds an elapsed duration to a Timestamp.
This helper treats the Timestamp fields as UTC and returns a Timestamp built
from UTC fields. Use addToDate() for calendar-unit arithmetic such as
"one month from now".addDuration(const start: Timestampstart, function createDuration(milliseconds: number): TimestampDurationCreates a TimestampDuration from signed milliseconds.createDuration(90 * 60 * 1000))
const const label: stringlabel = function formatDuration(duration: TimestampDuration | number, options?: FormatDurationOptions): stringFormats a duration as `HH:mm:ss` or `HH:mm:ss.SSS`.
Hours include full days, so a two-day duration formats as `48:00:00`.formatDuration(function durationBetween(start: Timestamp, end: Timestamp): TimestampDurationMeasures the elapsed duration between two Timestamp values.
Timestamp fields are read as UTC so the result is deterministic across
server and client runtimes.durationBetween(const start: Timestampstart, const end: Timestampend))Store UTC, Render Local
For event systems and server APIs, store instants in UTC and convert at the application boundary. QCalendar can keep rendering local wall-clock values after the app parses and formats the values explicitly.
import {
function makeDateTime(timestamp: Timestamp): DateConverts a Timestamp date and time into a host-local JavaScript Date.makeDateTime,
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 fromUnixMilliseconds(milliseconds: number): Timestamp | nullConverts Unix milliseconds into an immutable Timestamp using UTC fields.fromUnixMilliseconds,
} from '@timestamp-js/core'
const const meeting: Timestampmeeting = 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-08T16:30:00.000Z')!
const const persisted: numberpersisted = 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 meeting: Timestampmeeting)
const const restored: Timestamprestored = function fromUnixMilliseconds(milliseconds: number): Timestamp | nullConverts Unix milliseconds into an immutable Timestamp using UTC fields.fromUnixMilliseconds(const persisted: numberpersisted)!
const const localDate: DatelocalDate = function makeDateTime(timestamp: Timestamp): DateConverts a Timestamp date and time into a host-local JavaScript Date.makeDateTime(const restored: Timestamprestored)Use UTC helpers from Timestamp when server and client output must agree exactly. Use local helpers when the calendar should preserve the user’s wall-clock date and time.