API reference

Every export of clockworktz and clockworktz/tzdb, grouped by purpose. Types are TypeScript; everything is available from both ESM and CommonJS.

type DateInput = string | Date | number // ISO string with offset, Date, or epoch ms
type Disambiguation = 'compatible' | 'earliest' | 'latest' | 'reject'
type EngineKind = 'system-intl' | 'embedded-tzdb'
type LabelStyle = 'original' | 'offset' | 'abbrev' | 'altName'

Conversion#

fromUTC#

function fromUTC(input: DateInput, zone: string, opts?: FormatOptions): ClockworkTime

An instant as seen in zone. Throws TimezoneError for an invalid zone or an input that isn't an instant (including strings without an offset). Guide

fromUTC('2024-07-15T14:00:00Z', 'Asia/Kolkata').local // '2024-07-15 19:30:00.000'

interpretLocal#

function interpretLocal(wallTime: string | WallTime, zone: string, opts?: ConvertOptions): ClockworkTime

type WallTime = {
  year: number
  month: number // 1–12
  day: number
  hour?: number
  minute?: number
  second?: number
  millisecond?: number
}

The instant a wall time names in zone. Skipped and repeated times resolve with opts.disambiguation (default compatible). Throws TimezoneError for invalid input, InvalidTimeError or AmbiguousTimeError with reject. Guide

interpretLocal('2024-03-10T02:30:00', 'America/New_York').local // '2024-03-10 03:30:00.000'

convert#

function convert(input: DateInput, fromZone: string, toZone: string, opts?: ConvertOptions): ClockworkTime

A string without an offset is wall time in fromZone; anything else is an instant. Returns the result in toZone.

convert('2024-07-15T16:30:00', 'Asia/Kathmandu', 'America/St_Johns').local // '2024-07-15 08:15:00.000'

ClockworkTime#

Options#

interface FormatOptions {
  format?: string // pattern for `local`
  locale?: string // month/weekday/day-period names, default 'en'
}

interface ConvertOptions extends FormatOptions {
  disambiguation?: Disambiguation // default 'compatible'
}

Zone information#

getZoneInfo('2024-07-01T00:00:00Z', 'Asia/Kathmandu')
// { offsetSeconds: 20700, isDST: false, abbreviation: '+0545' }

getZoneInfo, getOffset, canonicalizeTimeZone and getZoneCountries throw TimezoneError for an invalid zone.

interface ListOptions {
  labelStyle?: LabelStyle // default 'original'
  at?: DateInput // default now
  locale?: string // for 'altName', default 'en'
  country?: string // ISO 3166 code
}

interface TimeZoneItem {
  value: string
  label: string
  offsetMinutes: number
  countryCodes: string[]
}

Guide

Formatting#

Guide and token table

Parsing#

interface ParseOptions {
  strict?: boolean // default true
  defaultTimezone?: string // default 'UTC'
}

interface ParseResult {
  date: Date
  hasTimezone: boolean
  original: string
  isValid: boolean
}

interface DateComponents {
  year: number
  month: number
  day: number
  hour: number
  minute: number
  second: number
  millisecond: number
}

Guide

Transitions and clocks#

getNextTransition and getPreviousTransition search two years by default and also accept engine and searchDays arguments.

interface TransitionInfo {
  date: Date
  fromOffset: number // minutes
  toOffset: number // minutes
  isDSTStart: boolean
  isDSTEnd: boolean
  fromAbbreviation: string
  toAbbreviation: string
}

Guide

Lifecycle#

interface ClockworkOptions {
  engine?: EngineKind // default 'system-intl'
  data?: unknown // tzdb data for 'embedded-tzdb'
  manifestURL?: string // signed manifest to load and keep fresh
  publicKey?: string // base64 raw Ed25519 key, default DEFAULT_PUBLIC_KEY
  autoUpdateIntervalMs?: number // default 24h, 0 disables
}

Guide

Data updates#

interface TzdbManifest {
  version: string // e.g. '2026f'
  releaseDate: string
  dataUrl: string // absolute, or relative to the manifest URL
  sha256: string // hex SHA-256 of the data file
  signature: string // base64 Ed25519 over `${version}\n${sha256}`
  keyId: string
}

Security & signing

Engines#

interface TzEngine {
  readonly kind: EngineKind
  getVersion(): string | undefined
  isValidTimeZone(zone: string): boolean
  canonicalize(zone: string): string
  listZoneIds(): string[]
  getZoneInfo(epochMs: number, zone: string): ZoneInfo
  getTransitions?(zone: string, fromMs: number, toMs: number): Transition[]
  getCountryCodes?(zone: string): string[]
}

interface LoadableEngine extends TzEngine {
  loadTzdbData(data: unknown): void
  isDataLoaded(): boolean
}

interface ZoneInfo {
  offsetSeconds: number
  isDST: boolean
  abbreviation: string
}

interface Transition {
  at: number // epoch ms
  before: ZoneInfo
  after: ZoneInfo
}

Errors#

Guide

clockworktz/tzdb#

import { tzdb, TZDB_VERSION } from 'clockworktz/tzdb'
import type { TzdbData, CompactZone } from 'clockworktz/tzdb'

TZDB_VERSION // '2026f'