Timestamp Recipes || QScroller

QScroller

v3.0.0-rc.1

Timestamp Recipes

Developing

QScroller keeps the UI small and focused. @timestamp-js/core is the companion layer for date math, UTC persistence, interval snapping, and range validation when the selected values need to become application data.

Use the scroller for collection, then normalize the emitted value into a Timestamp before saving, comparing, or sending the value to an API.

Calendar Adapters

QDateScroller, QDateRangeScroller, and QDateTimeScroller model dates in the active Timestamp calendar system. For native calendar systems such as Islamic Civil (Hijri), Indian National (Saka), Hebrew, or Persian, pass calendar-system; string, array, and object model values use that calendar’s native YYYY-MM-DD fields, while JavaScript Date values remain Gregorian interop values.

Install the adapter package you need beside @timestamp-js/core:

pnpm add @timestamp-js/core @timestamp-js/calendar-hebrew @timestamp-js/calendar-islamic @timestamp-js/calendar-saka @timestamp-js/calendar-persian

Store Instants Explicitly

QDateTimeScroller emits the same shape it received where possible. If your app stores instants in a database, normalize the emitted value, snap it if needed, and store Unix milliseconds.

import {
  function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.@categoryconversiongetDateTime,
  function roundToInterval(timestamp: Timestamp, minutes: number): TimestampRounds a Timestamp to the nearest interval.
@paramtimestamp Timestamp object to round.@paramminutes Interval size in minutes.@returnsRounded Timestamp.@categoryarithmeticroundToInterval,
  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.
@paramtimestamp Timestamp object to convert.@returnsUnix milliseconds.@categoryconversiontoUnixMilliseconds,
  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`.
@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.@categoryparsingparseTimestamp,
} from '@timestamp-js/core'

const const input: Timestamp | nullinput = 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`.
@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.@categoryparsingparseTimestamp('2036-06-08 09:37')
const const snapped: Timestamp | nullsnapped = const input: Timestamp | nullinput === null ? null : function roundToInterval(timestamp: Timestamp, minutes: number): TimestampRounds a Timestamp to the nearest interval.
@paramtimestamp Timestamp object to round.@paramminutes Interval size in minutes.@returnsRounded Timestamp.@categoryarithmeticroundToInterval(const input: Timestampinput, 15)

const snapped: Timestamp | nullsnapped === null ? null : function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.@categoryconversiongetDateTime(const snapped: Timestampsnapped) // "2036-06-08 09:30"
const snapped: Timestamp | nullsnapped === null ? null : 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.
@paramtimestamp Timestamp object to convert.@returnsUnix milliseconds.@categoryconversiontoUnixMilliseconds(const snapped: Timestampsnapped)

Validate Ranges Outside The Picker

QDateRangeScroller validates that the end date does not come before the start date. Domain validation, such as checking blackout windows, booking windows, or availability gaps, belongs in your app logic.

import {
  function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRangeCreates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.@categoryrangescreateTimestampRange,
  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.
@paramsource Source range.@paramoccupied Ranges that are not available.@paramuseTime Include time-of-day in the comparison.@returnsGap ranges.@categoryrangesfindRangeGaps,
  function isRangeOverlapping(first: TimestampRange, second: TimestampRange, useTime?: boolean): booleanChecks whether two inclusive TimestampRange values overlap.
@paramfirst First range.@paramsecond Second range.@paramuseTime Include time-of-day in the comparison.@returnsTrue when the ranges overlap.@categorycomparisonisRangeOverlapping,
  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`.
@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.@categoryparsingparseTimestamp,
} from '@timestamp-js/core'

const const request: TimestampRangerequest = function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRangeCreates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.@categoryrangescreateTimestampRange(
  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`.
@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.@categoryparsingparseTimestamp('2036-06-08 00:00')!,
  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`.
@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.@categoryparsingparseTimestamp('2036-06-12 00:00')!,
)
const const blackout: TimestampRangeblackout = function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRangeCreates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.@categoryrangescreateTimestampRange(
  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`.
@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.@categoryparsingparseTimestamp('2036-06-14 00:00')!,
  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`.
@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.@categoryparsingparseTimestamp('2036-06-17 00:00')!,
)

function isRangeOverlapping(first: TimestampRange, second: TimestampRange, useTime?: boolean): booleanChecks whether two inclusive TimestampRange values overlap.
@paramfirst First range.@paramsecond Second range.@paramuseTime Include time-of-day in the comparison.@returnsTrue when the ranges overlap.@categorycomparisonisRangeOverlapping(const request: TimestampRangerequest, const blackout: TimestampRangeblackout) // false
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.
@paramsource Source range.@paramoccupied Ranges that are not available.@paramuseTime Include time-of-day in the comparison.@returnsGap ranges.@categoryrangesfindRangeGaps(const request: TimestampRangerequest, [const blackout: TimestampRangeblackout]) // request is still open

Preserve UI Precision

QScroller date-time views are minute-focused today. Timestamp can still parse, store, and format seconds and milliseconds for API payloads, audit values, or background scheduling state.

import { function makeDateTimeUTC(timestamp: Timestamp): DateConverts a Timestamp date and time into a UTC JavaScript Date.
@paramtimestamp Timestamp object to convert.@returnsJavaScript Date object built with `Date.UTC()`.@categoryconversionmakeDateTimeUTC, 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`.
@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.@categoryparsingparseTimestamp } from '@timestamp-js/core'

const const timestamp: Timestamp | nulltimestamp = 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`.
@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.@categoryparsingparseTimestamp('2036-06-08T09:30:15.250Z')

const timestamp: Timestamp | nulltimestamp?.Timestamp.second?: number | undefinedOptional second of the minute.second // 15
const timestamp: Timestamp | nulltimestamp?.Timestamp.millisecond?: number | undefinedOptional millisecond of the second.millisecond // 250
const timestamp: Timestamp | nulltimestamp === null ? null : function makeDateTimeUTC(timestamp: Timestamp): DateConverts a Timestamp date and time into a UTC JavaScript Date.
@paramtimestamp Timestamp object to convert.@returnsJavaScript Date object built with `Date.UTC()`.@categoryconversionmakeDateTimeUTC(const timestamp: Timestamptimestamp).Date.toISOString(): stringReturns a date as a string value in ISO format.toISOString()

Ready for more?

Caught a mistake?Edit this page in browser

1. Introduction

2. Date-Time Storage

3. Range Validation

4. Calendar Adapters

5. Calendar Adapter Scrollers

6. Store Instants Explicitly

7. Validate Ranges Outside The Picker

8. Preserve UI Precision