Class ClockTimeTz

ClockTimeTz represents a time of day with timezone information.

Useful for representing TIME WITH TIME ZONE fields from a Postgres database. All output methods include timezone offset information.

Hierarchy

default
- ClockTimeTz

Index

Constructors

constructor

new ClockTimeTz(source?: DateTime | null): ClockTimeTz
Internal
Parameters
- Optionalsource: DateTime | null
Returns ClockTimeTz
Inherited from BaseClockTime.constructor
- Defined in src/utils/datetime/BaseClockTime.ts:18

Properties

`Protected` `Optional`_toSQL

_toSQL?: string

`Protected`dateTime

dateTime: DateTime

Accessors

hour

get hour(): number
Gets the hour (0-23).

Returns number
The hour number
Example
```
ClockTime/ClockTimeTz.fromObject({ hour: 14, minute: 30 }).hour  // 14
```
Inherited from BaseClockTime.hour
- Defined in src/utils/datetime/BaseClockTime.ts:224

microsecond

get microsecond(): number
Gets the microsecond (0-999).

Returns number
The microsecond number
Example
```
ClockTime/ClockTimeTz.fromISO('14:30:45.123456').microsecond  // 456
```
Inherited from BaseClockTime.microsecond
- Defined in src/utils/datetime/BaseClockTime.ts:272

millisecond

get millisecond(): number
Gets the millisecond (0-999).

Returns number
The millisecond number
Example
```
ClockTime/ClockTimeTz.fromObject({ hour: 14, minute: 30, millisecond: 123 }).millisecond  // 123
```
Inherited from BaseClockTime.millisecond
- Defined in src/utils/datetime/BaseClockTime.ts:260

minute

get minute(): number
Gets the minute (0-59).

Returns number
The minute number
Example
```
ClockTime/ClockTimeTz.fromObject({ hour: 14, minute: 30 }).minute  // 30
```
Inherited from BaseClockTime.minute
- Defined in src/utils/datetime/BaseClockTime.ts:236

offset

get offset(): number
Gets the timezone offset in minutes.

Returns number
The offset in minutes
Example
```
ClockTimeTz.fromISO('14:30:45-05:00').offset  // -300
```
- Defined in src/utils/datetime/ClockTimeTz.ts:192

second

get second(): number
Gets the second (0-59).

Returns number
The second number
Example
```
ClockTime/ClockTimeTz.fromObject({ hour: 14, minute: 30, second: 45 }).second  // 45
```
Inherited from BaseClockTime.second
- Defined in src/utils/datetime/BaseClockTime.ts:248

zoneName

get zoneName(): string
Gets the timezone name.

Returns string
The timezone name
Example
```
ClockTimeTz.fromObject({ hour: 14 }, { zone: 'America/New_York' }).zoneName
```
- Defined in src/utils/datetime/ClockTimeTz.ts:180

Methods

diff

diff<
    T extends BaseClockTime,
    U extends
        ClockTimeDurationUnit | ClockTimeDurationUnit[] | undefined = undefined,
>(
    this: T,
    other: T,
    unit?: U,
): ClockTimeDiffResult<U>
Returns the difference between this ClockTime and another in the specified unit(s). Supports microsecond precision when 'microseconds' is included in the unit parameter.
Type Parameters
- T extends BaseClockTime
- U extends ClockTimeDurationUnit | ClockTimeDurationUnit[] | undefined = undefined
Parameters
- this: T
- other: T
  ClockTime to compare against
- Optionalunit: U
  Unit or units to return (hours, minutes, seconds, milliseconds, microseconds)
Returns ClockTimeDiffResult<U>
Object with only the specified units (or all units if not specified)
Example
```
const t1 = ClockTime.fromObject({ hour: 15, minute: 30 })
const t2 = ClockTime.fromObject({ hour: 14, minute: 0 })
t1.diff(t2, 'hours')  // { hours: 1 }
t1.diff(t2, ['hours', 'minutes'])  // { hours: 1, minutes: 30 }
t1.diff(t2)  // { hours: 1, minutes: 30, seconds: 0, milliseconds: 0, microseconds: 0 }
```
Inherited from BaseClockTime.diff
- Defined in src/utils/datetime/BaseClockTime.ts:386

endOf

endOf<T extends BaseClockTime>(this: T, period: ClockTimeUnit): T
Returns a new ClockTime at the end of the given period.
Type Parameters
- T extends BaseClockTime
Parameters
- this: T
- period: ClockTimeUnit
  Unit to extend to end of ('hour', 'minute', or 'second')
Returns T
A ClockTime at the end of the period
Example
```
ClockTime.fromObject({ hour: 14, minute: 30 }).endOf('hour')
// hour: 14, minute: 59, second: 59, millisecond: 999
```
Inherited from BaseClockTime.endOf
- Defined in src/utils/datetime/BaseClockTime.ts:95

equals

equals<T extends BaseClockTime>(this: T, otherClockTime: T): boolean
Returns true if this ClockTime equals another ClockTime.
Type Parameters
- T extends BaseClockTime
Parameters
- this: T
- otherClockTime: T
  ClockTime to compare
Returns boolean
true if times are equal
Example
```
const t1 = ClockTime.fromObject({ hour: 14, minute: 30 })
const t2 = ClockTime.fromObject({ hour: 14, minute: 30 })
t1.equals(t2)  // true
```
Inherited from BaseClockTime.equals
- Defined in src/utils/datetime/BaseClockTime.ts:50

hasSame

hasSame<T extends BaseClockTime>(
    this: T,
    otherClockTime: T,
    period: ClockTimeUnit,
): boolean
Returns true if this and other are in the same unit of time.
Type Parameters
- T extends BaseClockTime
Parameters
- this: T
- otherClockTime: T
  ClockTime to compare against
- period: ClockTimeUnit
  Unit to check ('hour', 'minute', or 'second')
Returns boolean
true if same period
Example
```
const t1 = ClockTime.fromObject({ hour: 14, minute: 30 })
const t2 = ClockTime.fromObject({ hour: 14, minute: 45 })
t1.hasSame(t2, 'hour')    // true
t1.hasSame(t2, 'minute')  // false
```
Inherited from BaseClockTime.hasSame
- Defined in src/utils/datetime/BaseClockTime.ts:351

minus

minus<T extends BaseClockTime>(
this: T,
duration: ClockTimeDurationLikeObject,
): T
Returns a new ClockTime/ClockTimeTz with the given duration subtracted.
Type Parameters
- T extends BaseClockTime
Parameters
- this: T
- duration: ClockTimeDurationLikeObject
  Duration to subtract (object with hours, minutes, seconds, etc.)
Returns T
A new ClockTime/ClockTimeTz
Example
```
ClockTime/ClockTimeTz.fromObject({ hour: 14, minute: 30 }).minus({ hours: 2, minutes: 15 })
// hour: 12, minute: 15
```
Inherited from BaseClockTime.minus
- Defined in src/utils/datetime/BaseClockTime.ts:334

plus

plus<T extends BaseClockTime>(this: T, duration: ClockTimeDurationLikeObject): T
Returns a new ClockTime/ClockTimeTz with the given duration added.
Type Parameters
- T extends BaseClockTime
Parameters
- this: T
- duration: ClockTimeDurationLikeObject
  Duration to add (object with hours, minutes, seconds, etc.)
Returns T
A new ClockTime/ClockTimeTz
Example
```
ClockTime/ClockTimeTz.fromObject({ hour: 14, minute: 30 }).plus({ hours: 2, minutes: 15 })
// hour: 16, minute: 45
```
Inherited from BaseClockTime.plus
- Defined in src/utils/datetime/BaseClockTime.ts:320

set

set<T extends BaseClockTime>(this: T, values: Partial<ClockTimeObject>): T
Returns a new ClockTime with the given time units set.
Type Parameters
- T extends BaseClockTime
Parameters
- this: T
- values: Partial<ClockTimeObject>
  Object with time units to set (hour, minute, second, millisecond, microsecond)
Returns T
A new ClockTime
Throws
When the underlying DateTime operation fails
Example
```
ClockTime.fromObject({ hour: 10, minute: 30 }).set({ hour: 14, microsecond: 500 })
// hour: 14, minute: 30, microsecond: 500
```
Inherited from BaseClockTime.set
- Defined in src/utils/datetime/BaseClockTime.ts:65

setZone

setZone(zone: string | Zone): ClockTimeTz
Returns a new ClockTimeTz with the timezone changed. The time value changes to reflect the same instant in the new timezone.
Parameters
- zone: string | Zone
  The timezone to convert to
Returns ClockTimeTz
A new ClockTimeTz in the specified timezone
Example
```
const utc = ClockTimeTz.fromObject({ hour: 14, minute: 30 }, { zone: 'UTC' })
const ny = utc.setZone('America/New_York')
// Time is converted to New York timezone (e.g., 09:30 EST)
```
- Defined in src/utils/datetime/ClockTimeTz.ts:220

startOf

startOf<T extends BaseClockTime>(this: T, period: ClockTimeUnit): T
Returns a new ClockTime at the start of the given period.
Type Parameters
- T extends BaseClockTime
Parameters
- this: T
- period: ClockTimeUnit
  Unit to truncate to ('hour', 'minute', or 'second')
Returns T
A ClockTime at the start of the period
Example
```
ClockTime.fromObject({ hour: 14, minute: 30, second: 45 }).startOf('hour')
// hour: 14, minute: 0, second: 0
```
Inherited from BaseClockTime.startOf
- Defined in src/utils/datetime/BaseClockTime.ts:81

toDateTime

toDateTime(): DateTime
Returns the underlying DateTime instance.

Returns DateTime
A DateTime representing this time with zone
Example
```
const dt = ClockTime/ClockTimeTz.now().toDateTime()
```
Inherited from BaseClockTime.toDateTime
- Defined in src/utils/datetime/BaseClockTime.ts:212

toISO

toISO(
    opts?: {
        format?: "basic" | "extended";
        suppressMilliseconds?: boolean;
        suppressSeconds?: boolean;
    },
): string
Returns the time as an ISO 8601 time string with timezone offset. Alias for toISOTime().
Parameters
- Optionalopts: {
      format?: "basic" | "extended";
      suppressMilliseconds?: boolean;
      suppressSeconds?: boolean;
  }
  Optional format options
  - Optionalformat?: "basic" | "extended"
    Format variant: 'basic' (compact) or 'extended' (default, with colons)
  - OptionalsuppressMilliseconds?: boolean
    If true, omits milliseconds/microseconds when they are zero
  - OptionalsuppressSeconds?: boolean
    If true, omits seconds when they are zero
Returns string
ISO time string with timezone offset (e.g., '14:30:45.123456-05:00')
Example
```
ClockTimeTz.fromObject({ hour: 14, minute: 30, second: 45 }).toISO()  // '14:30:45.000000+00:00'
ClockTimeTz.fromISO('14:30:45-05:00').toISO()  // '14:30:45.000000-05:00'
```
Overrides BaseClockTime.toISO
- Defined in src/utils/datetime/ClockTimeTz.ts:148

toISOTime

toISOTime(
    opts?: {
        format?: "basic" | "extended";
        suppressMilliseconds?: boolean;
        suppressSeconds?: boolean;
    },
): string
Returns the time as an ISO 8601 time string with timezone offset. Alias for toISO().
Parameters
- Optionalopts: {
      format?: "basic" | "extended";
      suppressMilliseconds?: boolean;
      suppressSeconds?: boolean;
  }
  Optional format options
  - Optionalformat?: "basic" | "extended"
    Format variant: 'basic' (compact) or 'extended' (default, with colons)
  - OptionalsuppressMilliseconds?: boolean
    If true, omits milliseconds/microseconds when they are zero
  - OptionalsuppressSeconds?: boolean
    If true, omits seconds when they are zero
Returns string
ISO time string with timezone offset (e.g., '14:30:45.123456-05:00')
Example
```
ClockTime/ClockTimeTz.fromObject({ hour: 14, minute: 30, second: 45 }).toISOTime()  // '14:30:45.000000+00:00'
ClockTime/ClockTimeTz.fromISO('14:30:45-05:00').toISOTime()  // '14:30:45.000000-05:00'
```
Inherited from BaseClockTime.toISOTime
- Defined in src/utils/datetime/BaseClockTime.ts:142

toJSON

toJSON(): string
Returns the time as an ISO time string for JSON serialization.

Returns string
ISO time string
Example
```
JSON.stringify({ time: ClockTime.now() })
```
Inherited from BaseClockTime.toJSON
- Defined in src/utils/datetime/BaseClockTime.ts:158

toLocaleString

toLocaleString(formatOpts?: DateTimeFormatOptions, opts?: LocaleOptions): string
Returns a localized string representation of the time.
Parameters
- OptionalformatOpts: DateTimeFormatOptions
  Intl.DateTimeFormat options for formatting
- Optionalopts: LocaleOptions
  Optional locale configuration
  - locale
    Locale string (e.g., 'en-US', 'fr-FR')
  - numberingSystem
    Numbering system (e.g., 'arab', 'beng')
  - outputCalendar
    Calendar system (e.g., 'islamic', 'hebrew')
Returns string
Localized time string
Example
```
ClockTime/ClockTimeTz.now().toLocaleString()
ClockTime/ClockTimeTz.now().toLocaleString({ hour: 'numeric', minute: '2-digit' })
ClockTime/ClockTimeTz.now().toLocaleString({ hour: '2-digit' }, { locale: 'fr-FR' })
```
Inherited from BaseClockTime.toLocaleString
- Defined in src/utils/datetime/BaseClockTime.ts:188

toSQL

toSQL(): string
Returns the SQL time string with timezone offset. Result is memoized for performance.

Returns string
SQL time string with timezone offset (e.g., '14:30:45.123456 -05:00')
Example
```
ClockTimeTz.fromISO('14:30:45-05:00').toSQL()  // '14:30:45.000000 -05:00'
```
Overrides BaseClockTime.toSQL
- Defined in src/utils/datetime/ClockTimeTz.ts:166

toSQLTime

toSQLTime(): string
Alias of toSQL. Returns the SQL time string without timezone offset. Result is memoized for performance.

Returns string
SQL time string without timezone offset (e.g., '14:30:45.123456')
Inherited from BaseClockTime.toSQLTime
- Defined in src/utils/datetime/BaseClockTime.ts:169

toString

toString(): string
Returns the time as an ISO string (same as toISO).

Returns string
ISO datetime string
Example
```
ClockTime.now().toString()
```
Inherited from BaseClockTime.toString
- Defined in src/utils/datetime/BaseClockTime.ts:200

valueOf

valueOf(): string
Returns string
Inherited from BaseClockTime.valueOf
- Defined in src/utils/datetime/BaseClockTime.ts:108

`Protected`wrapLuxonError

wrapLuxonError<T>(fn: () => T): T
Type Parameters
- T
Parameters
- fn: () => T
Returns T
Overrides BaseClockTime.wrapLuxonError
- Defined in src/utils/datetime/ClockTimeTz.ts:233

`Static`fromDateTime

fromDateTime<T extends typeof default>(
this: T,
dateTime: DateTime,
): InstanceType<T>
Create a ClockTimeTz from a DateTime instance.
Type Parameters
- T extends typeof default
Parameters
- this: T
- dateTime: DateTime
  A DateTime instance
Returns InstanceType<T>
A ClockTimeTz for the time portion of the DateTime
Example
```
ClockTime/ClockTimeTz.fromDateTime(DateTime.now())
```
Inherited from BaseClockTime.fromDateTime
- Defined in src/utils/datetime/BaseClockTime.ts:35

`Static`fromFormat

fromFormat(text: string, format: string, opts?: DateTimeOptions): ClockTimeTz
Create a ClockTimeTz from a custom format string. Uses Luxon format tokens (e.g., 'HH:mm:ss', 'hh:mm a').
Parameters
- text: string
  The string to parse
- format: string
  Format string using Luxon tokens
- Optionalopts: DateTimeOptions
  Optional configuration
  - zone
    Timezone to interpret the time in (IANA timezone name or Zone object)
  - locale
    Locale for parsing (e.g., 'en-US', 'fr-FR')
  - numberingSystem
    Numbering system (e.g., 'arab', 'beng')
  - outputCalendar
    Output calendar system (e.g., 'islamic', 'hebrew')
Returns ClockTimeTz
A ClockTimeTz for the parsed time
Throws
When the string doesn't match the format or is invalid
Example
```
ClockTimeTz.fromFormat('14:30:45', 'HH:mm:ss')
ClockTimeTz.fromFormat('2:30 PM', 'h:mm a')
ClockTimeTz.fromFormat('14:30:45 -05:00', 'HH:mm:ss ZZ')
```
- Defined in src/utils/datetime/ClockTimeTz.ts:89

`Static`fromISO

fromISO(str: string, opts?: { zone?: string | Zone }): ClockTimeTz
Create a ClockTimeTz from an ISO 8601 time string. If the string includes timezone information, it will be used. If no timezone is in the string, it will be interpreted as UTC.
Parameters
- str: string
  ISO time string (e.g., '14:30:45.123456-05:00')
- opts: { zone?: string | Zone } = {}
Returns ClockTimeTz
A ClockTimeTz for the given time
Throws
When the ISO string is invalid
Example
```
ClockTimeTz.fromISO('14:30:45.123456')        // Interpreted as UTC
ClockTimeTz.fromISO('14:30:45.123456-05:00')  // Uses timezone from string
```
- Defined in src/utils/datetime/ClockTimeTz.ts:45

`Static`fromJSDate

fromJSDate(javascriptDate: Date, opts?: { zone?: string | Zone }): ClockTimeTz
Create a ClockTimeTz from a JavaScript Date.
Parameters
- javascriptDate: Date
  A JavaScript Date instance
- opts: { zone?: string | Zone } = {}
Returns ClockTimeTz
A ClockTimeTz for the time portion
Example
```
ClockTimeTz.fromJSDate(new Date())
ClockTimeTz.fromJSDate(new Date(), { zone: 'America/New_York' })
```
- Defined in src/utils/datetime/ClockTimeTz.ts:25

`Static`fromObject

fromObject(obj: Partial<ClockTimeObject>, opts?: DateTimeJSOptions): ClockTimeTz
Create a ClockTimeTz from an object with time units.
Parameters
- obj: Partial<ClockTimeObject>
  Object with hour, minute, second, millisecond, microsecond properties
- Optionalopts: DateTimeJSOptions
  Optional configuration
  - zone
    Timezone for the time (IANA timezone name or Zone object, defaults to UTC)
  - locale
    Locale (e.g., 'en-US', 'fr-FR')
  - numberingSystem
    Numbering system (e.g., 'arab', 'beng')
  - outputCalendar
    Output calendar system (e.g., 'islamic', 'hebrew')
Returns ClockTimeTz
A ClockTimeTz for the given components
Throws
When time values are invalid
Example
```
ClockTimeTz.fromObject({ hour: 14, minute: 30, second: 45 })  // UTC by default

// Note for when sending a named, non-UTC time zone, soch as 'America/New_York':
// Sending a non-UTC time zone will interpret the time zone based on DateTime.now,
// meaning the resulting ClockTimeTz will have a different time and offset when
// generated during daylight savings time than not during daylight savings time
ClockTimeTz.fromObject({ hour: 14, minute: 30 }, { zone: 'America/New_York' })
```
- Defined in src/utils/datetime/ClockTimeTz.ts:115

`Static`fromSQL

fromSQL(str: string, opts?: { zone?: string | Zone }): ClockTimeTz
Create a ClockTimeTz from an SQL time string. If no zone option is provided, the time will be interpreted as UTC.
Parameters
- str: string
  SQL time string (e.g., '14:30:45.123456')
- opts: { zone?: string | Zone } = {}
Returns ClockTimeTz
A ClockTimeTz for the given time
Throws
When the SQL string is invalid
Example
```
ClockTimeTz.fromSQL('14:30:45.123456')                    // Interpreted as UTC
ClockTimeTz.fromSQL('14:30:45.123456+05:30')              // Uses timezone from string
ClockTimeTz.fromSQL('14:30:45', { zone: 'America/Chicago' })  // Uses specified zone
```
- Defined in src/utils/datetime/ClockTimeTz.ts:65

`Static`max

max<T extends typeof default>(
this: T,
...clockTimes: InstanceType<T>[],
): InstanceType<T> | null
Returns the latest ClockTime/ClockTimeTz from the given arguments.
Type Parameters
- T extends typeof default
Parameters
- this: T
- ...clockTimes: InstanceType<T>[]
  ClockTime/ClockTimeTz instances to compare
Returns InstanceType<T> | null
The latest ClockTime/ClockTimeTz
Example
```
ClockTime/ClockTimeTz.max(time1, time2, time3)
```
Inherited from BaseClockTime.max
- Defined in src/utils/datetime/BaseClockTime.ts:302

`Static`min

min<T extends typeof default>(
this: T,
...clockTimes: InstanceType<T>[],
): InstanceType<T> | null
Returns the earliest ClockTime/ClockTimeTz from the given arguments.
Type Parameters
- T extends typeof default
Parameters
- this: T
- ...clockTimes: InstanceType<T>[]
  ClockTime/ClockTimeTz instances to compare
Returns InstanceType<T> | null
The earliest ClockTime/ClockTimeTz
Example
```
ClockTime/ClockTimeTz.min(time1, time2, time3)
```
Inherited from BaseClockTime.min
- Defined in src/utils/datetime/BaseClockTime.ts:285

`Static`now

now(opts?: { zone?: string | Zone }): ClockTimeTz
Returns a ClockTime for the current time.
Parameters
- Optionalopts: { zone?: string | Zone }
Returns ClockTimeTz
A ClockTime for now
Example
```
ClockTime.now()
```
- Defined in src/utils/datetime/ClockTimeTz.ts:204

`Protected` `Static`wrapLuxonError

wrapLuxonError<T>(fn: () => T): T
Type Parameters
- T
Parameters
- fn: () => T
Returns T
Overrides BaseClockTime.wrapLuxonError
- Defined in src/utils/datetime/ClockTimeTz.ts:224

Class ClockTimeTz

Hierarchy

Index

Constructors

Properties

Accessors

Methods

Constructors

constructor

Parameters

Returns ClockTimeTz

Properties

Protected Optional_toSQL

ProtecteddateTime

Accessors

hour

Returns number

Example

microsecond

Returns number

Example

millisecond

Returns number

Example

minute

Returns number

Example

offset

Returns number

Example

second

Returns number

Example

zoneName

Returns string

Example

Methods

diff

Type Parameters

Parameters

Returns ClockTimeDiffResult<U>

Example

endOf

Type Parameters

Parameters

Returns T

Example

equals

Type Parameters

Parameters

Returns boolean

Example

hasSame

Type Parameters

Parameters

Returns boolean

Example

minus

Type Parameters

Parameters

Returns T

Example

plus

Type Parameters

Parameters

Returns T

Example

set

Type Parameters

Parameters

Returns T

Throws

Example

setZone

Parameters

Returns ClockTimeTz

Example

startOf

Type Parameters

Parameters

`Protected` `Optional`_toSQL

`Protected`dateTime

`Optional`format?: "basic" | "extended"

`Optional`suppressMilliseconds?: boolean

`Optional`suppressSeconds?: boolean

`Optional`format?: "basic" | "extended"

`Optional`suppressMilliseconds?: boolean

`Optional`suppressSeconds?: boolean

`Protected`wrapLuxonError

`Static`fromDateTime

`Static`fromFormat

`Static`fromISO

`Static`fromJSDate

`Static`fromObject