Class Tempo

constructor

• new Tempo(options?: Options): Tempo

  Instantiates a new Tempo object with configuration only.

  Parameters

  • Optionaloptions: Options

    Configuration options for this specific instance.

  Returns Tempo

• new Tempo(tempo: DateTime, options?: Options): Tempo

  Instantiates a new Tempo object with a value.

  Parameters

  • tempo: DateTime

    The date-time value to parse.

  • Optionaloptions: Options

    Configuration options for this specific instance.

  Returns Tempo

StaticInterval

cal

• get cal(): string

  Temporal Calendar ID (e.g., 'iso8601' | 'gregory')

  Returns string

config

• get config(): Readonly<t.Internal.Config>

  current Tempo configuration

  Returns Readonly<t.Internal.Config>

day

• get day(): dd

  Day of the month (1-31).

  Returns dd

  Deprecated

  Use dd (Tempo canonical) or zdt.day instead. To be removed in v5.0.0.

dd

• get dd(): dd

  Day of the month (1-31)

  Returns dd

dow

• get dow(): 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7

  iso weekday number: Mon=1, Sun=7

  Returns 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7

doy

• get doy(): number

  Day of year: 1-366

  Returns number

eon

• get eon(): number | undefined

  Year within the era (positive integer)

  Returns number | undefined

epoch

• get epoch(): Readonly<{ ms: number; ns: bigint; ss: number; us: number }>

  units since epoch for this date-time instance

  Returns Readonly<{ ms: number; ns: bigint; ss: number; us: number }>

era

• get era(): string | undefined

  Era string for the calendar (e.g., 'ce', 'bce')

  Returns string | undefined

eraYear

• get eraYear(): number | undefined

  Year within the era (positive integer).

  Returns number | undefined

  Deprecated

  Use eon (Tempo canonical) or zdt.eraYear instead. To be removed in v5.0.0.

ff

• get ff(): number

  Fractional seconds (e.g., 0.123456789)

  Returns number

fmt

• get fmt(): Record<string, string | undefined>

  Formatted results for all pre-defined format codes

  Returns Record<string, string | undefined>

geo

• get geo(): Readonly<GeoConfig> | undefined

  Resolved geographic coordinates object ({ latitude, longitude, ... })

  Returns Readonly<GeoConfig> | undefined

hh

• get hh(): hh

  Hour of the day (0-23)

  Returns hh

intl

• get intl(): ResolvedLocaleInfo

  Resolved cultural and regional locale information (firstDay, weekend, direction, etc.) via Intl.LocaleInfo

  Returns ResolvedLocaleInfo

iso

• get iso(): string

  Standard ISO 8601 string in UTC

  Returns string

isValid

• get isValid(): boolean | ZonedDateTime

  true if the underlying date-time is valid.

  Returns boolean | ZonedDateTime

locale

• get locale(): string

  Resolved BCP 47 locale (e.g., 'en-US')

  Returns string

mi

• get mi(): mi

  Minutes of the hour (0-59)

  Returns mi

mm

• get mm(): mm

  Month number: Jan=1, Dec=12

  Returns mm

mmm

• get mmm(): | "All"
  | "Jan"
  | "Feb"
  | "Mar"
  | "Apr"
  | "May"
  | "Jun"
  | "Jul"
  | "Aug"
  | "Sep"
  | "Oct"
  | "Nov"
  | "Dec"

  Short month name (e.g., 'Jan')

  Returns
      | "All"
      | "Jan"
      | "Feb"
      | "Mar"
      | "Apr"
      | "May"
      | "Jun"
      | "Jul"
      | "Aug"
      | "Sep"
      | "Oct"
      | "Nov"
      | "Dec"

mon

• get mon(): | "May"
  | "Every"
  | "January"
  | "February"
  | "March"
  | "April"
  | "June"
  | "July"
  | "August"
  | "September"
  | "October"
  | "November"
  | "December"

  Full month name (e.g., 'January')

  Returns
      | "May"
      | "Every"
      | "January"
      | "February"
      | "March"
      | "April"
      | "June"
      | "July"
      | "August"
      | "September"
      | "October"
      | "November"
      | "December"

ms

• get ms(): ms

  Milliseconds of the second (0-999)

  Returns ms

nano

• get nano(): bigint

  Nanoseconds since Unix epoch (BigInt)

  Returns bigint

ns

• get ns(): ns

  Nanoseconds of the microsecond (0-999)

  Returns ns

parse

• get parse(): Parse

  Instance-specific parse rules (merged with global)

  Returns Parse

ranges

• get ranges(): Readonly<Record<string, string>>

  current range key for every registered term

  Returns Readonly<Record<string, string>>

sphere

• get sphere(): string | undefined

  Resolved hemisphere ('north' | 'south' | undefined)

  Returns string | undefined

ss

• get ss(): ss

  Seconds of the minute (0-59)

  Returns ss

term

• get term(): TempoTermRegistry

  Keyed results for all resolved terms

  Returns TempoTermRegistry

terms

• get terms(): Readonly<Record<string, readonly string[]>>

  list of registered terms and their available range keys

  Returns Readonly<Record<string, readonly string[]>>

ts

• get ts(): number | bigint

  Unix timestamp (defaults to milliseconds)

  Returns number | bigint

tz

• get tz(): string

  IANA Time Zone ID (e.g., 'Australia/Sydney')

  Returns string

us

• get us(): us

  Microseconds of the millisecond (0-999)

  Returns us

wkd

• get wkd(): | "Everyday"
  | "Monday"
  | "Tuesday"
  | "Wednesday"
  | "Thursday"
  | "Friday"
  | "Saturday"
  | "Sunday"

  Full weekday name (e.g., 'Monday')

  Returns
      | "Everyday"
      | "Monday"
      | "Tuesday"
      | "Wednesday"
      | "Thursday"
      | "Friday"
      | "Saturday"
      | "Sunday"

ww

• get ww(): wy

  ISO week number of the year.

  Returns wy

  Deprecated

  Use wy (Tempo canonical) or zdt.weekOfYear instead. To be removed in v5.0.0.

www

• get www(): "All" | "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat" | "Sun"

  Short weekday name (e.g., 'Mon')

  Returns "All" | "Mon" | "Tue" | "Wed" | "Thu" | "Fri" | "Sat" | "Sun"

wy

• get wy(): wy

  iso week number of the year

  Returns wy

yw

• get yw(): number

  4-digit iso week-numbering year

  Returns number

yy

• get yy(): number

  4-digit year (e.g., 2024)

  Returns number

zdt

• get zdt(): ZonedDateTime

  returns the underlying Temporal.ZonedDateTime

  Returns ZonedDateTime

Staticcache

• get cache(): SecureObject<
      {
          clear(count?: number): void;
          delete(key: string): boolean;
          deletePrefix(prefix: string): number;
          entries(): MapIterator<[string, string]>;
          fromEntries(
              entries: Iterable<readonly [string, string]>,
          ): { readonly get: (key: string) => string | undefined; readonly has: (key: string) => boolean; readonly set: (key: string, value: string) => ...; readonly setStatic: (key: string, value: string) => ...; ... 5 more ...; readonly toJSON: () => Record<...>; };
          get(key: string): string | undefined;
          has(key: string): boolean;
          set(
              key: string,
              value: string,
          ): { readonly get: (key: string) => string | undefined; readonly has: (key: string) => boolean; readonly set: (key: string, value: string) => ...; readonly setStatic: (key: string, value: string) => ...; ... 5 more ...; readonly toJSON: () => Record<...>; };
          setStatic(
              key: string,
              value: string,
          ): { readonly get: (key: string) => string | undefined; readonly has: (key: string) => boolean; readonly set: (key: string, value: string) => ...; readonly setStatic: (key: string, value: string) => ...; ... 5 more ...; readonly toJSON: () => Record<...>; };
          toJSON(): Record<string, string>;
      },
  >

  high-performance in-memory cache facade for glossary and dynamic parse results

  Returns SecureObject<
      {
          clear(count?: number): void;
          delete(key: string): boolean;
          deletePrefix(prefix: string): number;
          entries(): MapIterator<[string, string]>;
          fromEntries(
              entries: Iterable<readonly [string, string]>,
          ): { readonly get: (key: string) => string | undefined; readonly has: (key: string) => boolean; readonly set: (key: string, value: string) => ...; readonly setStatic: (key: string, value: string) => ...; ... 5 more ...; readonly toJSON: () => Record<...>; };
          get(key: string): string | undefined;
          has(key: string): boolean;
          set(
              key: string,
              value: string,
          ): { readonly get: (key: string) => string | undefined; readonly has: (key: string) => boolean; readonly set: (key: string, value: string) => ...; readonly setStatic: (key: string, value: string) => ...; ... 5 more ...; readonly toJSON: () => Record<...>; };
          setStatic(
              key: string,
              value: string,
          ): { readonly get: (key: string) => string | undefined; readonly has: (key: string) => boolean; readonly set: (key: string, value: string) => ...; readonly setStatic: (key: string, value: string) => ...; ... 5 more ...; readonly toJSON: () => Record<...>; };
          toJSON(): Record<string, string>;
      },
  >

StaticCACHE

• get CACHE(): EnumifyType<{ Off: false; On: true; Refresh: "refresh" }>

  cache operation modes

  Returns EnumifyType<{ Off: false; On: true; Refresh: "refresh" }>

Staticconfig

• get config(): Config

  global Tempo configuration

  Returns Config

Staticdefault

• get default(): Readonly<t.Config>

  Tempo initial default settings

  Returns Readonly<t.Config>

Staticdiscovery

• get discovery(): Readonly<any>

  global discovery configuration

  Returns Readonly<any>

Staticepoch

• get epoch(): Readonly<{ ms: number; ns: bigint; ss: number; us: number }>

  static units since Unix epoch

  Returns Readonly<{ ms: number; ns: bigint; ss: number; us: number }>

StaticFORMAT

• get FORMAT(): Extend<
      EnumifyType<
          {
              date: "{yyyy}-{mm}-{dd}";
              dayDate: "{dd}-{mmm}-{yyyy}";
              dayMonth: "{dd}-{mmm}";
              dayTime: "{dd}-{mmm}-{yyyy} {hh}:{mi}:{ss}";
              display: "{www}, {dd} {mmm} {yyyy}";
              logStamp: "{ymd}T{hms}.{ff}";
              sortTime: "{yyyy}-{mm}-{dd} {hh}:{mi}:{ss}";
              time: "{hh}:{mi}:{ss}";
              weekDate: "{www}, {yyyy}-{mmm}-{dd}";
              weekStamp: "{www}, {yyyy}-{mmm}-{dd} {hh}:{mi}:{ss}.{ff}";
              weekTime: "{www}, {yyyy}-{mmm}-{dd} {hh}:{mi}:{ss}";
              yearMonth: "{yyyy}{mm}";
              yearMonthDay: "{ymd}";
              yearWeek: "{yw}{wy}";
          },
      >,
      string,
      string,
  >

  Pre-configured format {name -> string} pairs

  Returns Extend<
      EnumifyType<
          {
              date: "{yyyy}-{mm}-{dd}";
              dayDate: "{dd}-{mmm}-{yyyy}";
              dayMonth: "{dd}-{mmm}";
              dayTime: "{dd}-{mmm}-{yyyy} {hh}:{mi}:{ss}";
              display: "{www}, {dd} {mmm} {yyyy}";
              logStamp: "{ymd}T{hms}.{ff}";
              sortTime: "{yyyy}-{mm}-{dd} {hh}:{mi}:{ss}";
              time: "{hh}:{mi}:{ss}";
              weekDate: "{www}, {yyyy}-{mmm}-{dd}";
              weekStamp: "{www}, {yyyy}-{mmm}-{dd} {hh}:{mi}:{ss}.{ff}";
              weekTime: "{www}, {yyyy}-{mmm}-{dd} {hh}:{mi}:{ss}";
              yearMonth: "{yyyy}{mm}";
              yearMonthDay: "{ymd}";
              yearWeek: "{yw}{wy}";
          },
      >,
      string,
      string,
  >

Staticignores

• get ignores(): Secure<Ignore>

  static Tempo.ignores (registry)

  Returns Secure<Ignore>

Staticinstant

• get instant(): Instant

  get the current system Instant

  Returns Instant

Staticintl

• get intl(): ResolvedLocaleInfo

  Resolved cultural and regional locale information for the global locale via Intl.LocaleInfo

  Returns ResolvedLocaleInfo

StaticLIMIT

• get LIMIT(): Readonly<{ get maxTempo(): bigint; get minTempo(): bigint }>

  some useful Dates

  Returns Readonly<{ get maxTempo(): bigint; get minTempo(): bigint }>

StaticMODE

• get MODE(): EnumifyType<{ Auto: "auto"; Defer: "defer"; Strict: "strict" }>

  initialization strategies

  Returns EnumifyType<{ Auto: "auto"; Defer: "defer"; Strict: "strict" }>

StaticMONTH_DAY

• get MONTH_DAY(): Readonly<
      {
          layouts: readonly [
              readonly ["dayMonthYearShort", "monthDayYearShort"],
              readonly ["dayMonthYear", "monthDayYear"],
          ];
          locales: readonly ["en-US", "en-AS"];
          timezones: {
              "en-AS": readonly ["Pacific/Pago_Pago"];
              "en-US": readonly [
                  "America/Adak",
                  "America/Anchorage",
                  "America/Boise",
                  "America/Chicago",
                  "America/Denver",
                  "America/Detroit",
                  "America/Indiana/Indianapolis",
                  "America/Indiana/Knox",
                  "America/Indiana/Marengo",
                  "America/Indiana/Petersburg",
                  "America/Indiana/Tell_City",
                  "America/Indiana/Vevay",
                  "America/Indiana/Vincennes",
                  "America/Indiana/Winamac",
                  "America/Indianapolis",
                  "America/Juneau",
                  "America/Kentucky/Louisville",
                  "America/Kentucky/Monticello",
                  "America/Los_Angeles",
                  "America/Louisville",
                  "America/Menominee",
                  "America/Metlakatla",
                  "America/New_York",
                  "America/Nome",
                  "America/North_Dakota/Beulah",
                  "America/North_Dakota/Center",
                  "America/North_Dakota/New_Salem",
                  "America/Phoenix",
                  "America/Sitka",
                  "America/Yakutat",
                  "Pacific/Honolulu",
                  "US/Aleutian",
                  "US/Alaska",
                  "US/Arizona",
                  "US/Central",
                  "US/Eastern",
                  "US/Mountain",
                  "US/Pacific",
              ];
          };
      },
  >

  regional date-parsing configuration

  Returns Readonly<
      {
          layouts: readonly [
              readonly ["dayMonthYearShort", "monthDayYearShort"],
              readonly ["dayMonthYear", "monthDayYear"],
          ];
          locales: readonly ["en-US", "en-AS"];
          timezones: {
              "en-AS": readonly ["Pacific/Pago_Pago"];
              "en-US": readonly [
                  "America/Adak",
                  "America/Anchorage",
                  "America/Boise",
                  "America/Chicago",
                  "America/Denver",
                  "America/Detroit",
                  "America/Indiana/Indianapolis",
                  "America/Indiana/Knox",
                  "America/Indiana/Marengo",
                  "America/Indiana/Petersburg",
                  "America/Indiana/Tell_City",
                  "America/Indiana/Vevay",
                  "America/Indiana/Vincennes",
                  "America/Indiana/Winamac",
                  "America/Indianapolis",
                  "America/Juneau",
                  "America/Kentucky/Louisville",
                  "America/Kentucky/Monticello",
                  "America/Los_Angeles",
                  "America/Louisville",
                  "America/Menominee",
                  "America/Metlakatla",
                  "America/New_York",
                  "America/Nome",
                  "America/North_Dakota/Beulah",
                  "America/North_Dakota/Center",
                  "America/North_Dakota/New_Salem",
                  "America/Phoenix",
                  "America/Sitka",
                  "America/Yakutat",
                  "Pacific/Honolulu",
                  "US/Aleutian",
                  "US/Alaska",
                  "US/Arizona",
                  "US/Central",
                  "US/Eastern",
                  "US/Mountain",
                  "US/Pacific",
              ];
          };
      },
  >

StaticNUMBER

• get NUMBER(): Extend<
      EnumifyType<
          {
              eight: 8;
              five: 5;
              four: 4;
              nine: 9;
              one: 1;
              seven: 7;
              six: 6;
              ten: 10;
              three: 3;
              two: 2;
              zero: 0;
          },
      >,
      string,
      number,
  >

  Number names (0-10)

  Returns Extend<
      EnumifyType<
          {
              eight: 8;
              five: 5;
              four: 4;
              nine: 9;
              one: 1;
              seven: 7;
              six: 6;
              ten: 10;
              three: 3;
              two: 2;
              zero: 0;
          },
      >,
      string,
      number,
  >

Staticoptions

• get options(): any

  Retrieves the merged options for this Tempo class, combining defaults, storage, discovery, and config.

  Returns any

  The complete options object for Tempo initialization

Staticparse

• get parse(): SecureObject<
      {
          anchor?: ZonedDateTime;
          event: {
              christmas: "25 Dec";
              "christmas ?eve": "24 Dec";
              fortnight: (this: AliasContext) => AliasContext;
              "new.?years? ?eve": "31 Dec";
              "new.?years?(?: ?day)?": "01 Jan";
              now: (this: AliasContext) => AliasContext;
              ny: "01 Jan";
              nye: "31 Dec";
              today: (this: AliasContext) => ZonedDateTime;
              tomorrow: (this: AliasContext) => AliasContext;
              xmas: "25 Dec";
              "xmas ?eve": "24 Dec";
              yesterday: (this: AliasContext) => AliasContext;
              readonly [key: string]: string | Function;
          };
          ignore: { readonly [key: string]: string };
          isAnchored?: boolean;
          layout: { readonly [key: symbol]: string };
          mode: "auto" | "strict" | "defer";
          monthDay: MonthDay;
          pattern: Registry;
          period: {
              "after[ -]?noon": "3:00pm";
              evening: "18:00";
              "half[ -]?hour": (this: AliasContext) => string;
              "mid[ -]?day": "12:00";
              "mid[ -]?morning": "10:00";
              "mid[ -]?night": "24:00";
              morning: "8:00";
              night: "20:00";
              noon: "12:00";
              readonly [key: string]: string | Function;
          };
          pivot: number;
          planner: { layoutOrder: (string | symbol)[]; preFilter: boolean };
          result: Match[];
          snippet: { readonly [key: symbol]: RegExp };
          token: Extend;
      },
  >

  configuration governing the static 'rules' used when parsing t.DateTime argument

  Returns SecureObject<
      {
          anchor?: ZonedDateTime;
          event: {
              christmas: "25 Dec";
              "christmas ?eve": "24 Dec";
              fortnight: (this: AliasContext) => AliasContext;
              "new.?years? ?eve": "31 Dec";
              "new.?years?(?: ?day)?": "01 Jan";
              now: (this: AliasContext) => AliasContext;
              ny: "01 Jan";
              nye: "31 Dec";
              today: (this: AliasContext) => ZonedDateTime;
              tomorrow: (this: AliasContext) => AliasContext;
              xmas: "25 Dec";
              "xmas ?eve": "24 Dec";
              yesterday: (this: AliasContext) => AliasContext;
              readonly [key: string]: string | Function;
          };
          ignore: { readonly [key: string]: string };
          isAnchored?: boolean;
          layout: { readonly [key: symbol]: string };
          mode: "auto" | "strict" | "defer";
          monthDay: MonthDay;
          pattern: Registry;
          period: {
              "after[ -]?noon": "3:00pm";
              evening: "18:00";
              "half[ -]?hour": (this: AliasContext) => string;
              "mid[ -]?day": "12:00";
              "mid[ -]?morning": "10:00";
              "mid[ -]?night": "24:00";
              morning: "8:00";
              night: "20:00";
              noon: "12:00";
              readonly [key: string]: string | Function;
          };
          pivot: number;
          planner: { layoutOrder: (string | symbol)[]; preFilter: boolean };
          result: Match[];
          snippet: { readonly [key: symbol]: RegExp };
          token: Extend;
      },
  >

Staticproperties

• get properties(): SecureArray<string>

  static Tempo properties getter

  Returns SecureArray<string>

Staticregistry

• get registry(): Readonly<
      {
          formats: EnumifyType;
          locales: Readonly<
              Record<string, Readonly<Record<string, string | Function>>>,
          >;
          modifiers?: Readonly<Record<string, string | readonly string[]>>;
          numbers?: Readonly<Record<string, number>>;
          tokens?: Readonly<Record<string, TokenEvaluator>>;
      },
  >

  static Tempo.registry

  Returns Readonly<
      {
          formats: EnumifyType;
          locales: Readonly<
              Record<string, Readonly<Record<string, string | Function>>>,
          >;
          modifiers?: Readonly<Record<string, string | readonly string[]>>;
          numbers?: Readonly<Record<string, number>>;
          tokens?: Readonly<Record<string, TokenEvaluator>>;
      },
  >

Staticterms

• get terms(): SecureArray<Omit<TermPlugin, "resolve" | "define">> & Readonly<
      Record<string, Omit<TermPlugin, "resolve" | "define">>,
  >

  static Tempo.terms (registry)

  Returns SecureArray<Omit<TermPlugin, "resolve" | "define">> & Readonly<
      Record<string, Omit<TermPlugin, "resolve" | "define">>,
  >

StaticTIMEZONE

• get TIMEZONE(): Extend<
      Readonly<
          {
              acdt: "Australia/Adelaide";
              acst: "Australia/Adelaide";
              aedt: "Australia/Sydney";
              aest: "Australia/Sydney";
              awst: "Australia/Perth";
              cdt: "America/Chicago";
              cest: "Europe/Paris";
              cet: "Europe/Paris";
              cst: "America/Chicago";
              edt: "America/New_York";
              eest: "Europe/Helsinki";
              eet: "Europe/Helsinki";
              est: "America/New_York";
              gmt: "UTC";
              ist: "Asia/Kolkata";
              jst: "Asia/Tokyo";
              mdt: "America/Denver";
              mst: "America/Denver";
              npt: "Asia/Kathmandu";
              nzdt: "Pacific/Auckland";
              nzst: "Pacific/Auckland";
              nzt: "Pacific/Auckland";
              pdt: "America/Los_Angeles";
              pst: "America/Los_Angeles";
              utc: "UTC";
          },
      >,
      string,
      string,
  >

  TimeZone aliases

  Returns Extend<
      Readonly<
          {
              acdt: "Australia/Adelaide";
              acst: "Australia/Adelaide";
              aedt: "Australia/Sydney";
              aest: "Australia/Sydney";
              awst: "Australia/Perth";
              cdt: "America/Chicago";
              cest: "Europe/Paris";
              cet: "Europe/Paris";
              cst: "America/Chicago";
              edt: "America/New_York";
              eest: "Europe/Helsinki";
              eet: "Europe/Helsinki";
              est: "America/New_York";
              gmt: "UTC";
              ist: "Asia/Kolkata";
              jst: "Asia/Tokyo";
              mdt: "America/Denver";
              mst: "America/Denver";
              npt: "Asia/Kathmandu";
              nzdt: "Pacific/Auckland";
              nzst: "Pacific/Auckland";
              nzt: "Pacific/Auckland";
              pdt: "America/Los_Angeles";
              pst: "America/Los_Angeles";
              utc: "UTC";
          },
      >,
      string,
      string,
  >

Staticversion

• get version(): string

  the version of this Tempo build (stamped at build-time from package.json)

  Returns string

Staticversions

• get versions(): Readonly<Record<string, string>>

  the active versions of Tempo and any registered plugins or modules

  Returns Readonly<Record<string, string>>

[iterator]

• "[iterator]"(): ArrayIterator<EntryOf<Record<string, string | undefined>>>

  iterate over instance formats

  Returns ArrayIterator<EntryOf<Record<string, string | undefined>>>

[toPrimitive]

• "[toPrimitive]"(
      hint?: "string" | "number" | "default",
  ): string | number | bigint

  allow for auto-convert of Tempo to BigInt, Number or String

  Parameters

  • Optionalhint: "string" | "number" | "default"

  Returns string | number | bigint

add

• add(tempo?: MutateAdd, options?: Options): Tempo

  returns a new Tempo with specific duration added.

  Parameters

  • Optionaltempo: MutateAdd
  • Optionaloptions: Options

  Returns Tempo

clone

• clone(): Tempo

  Returns a clone of the current Tempo instance.

  Returns Tempo

  Deprecated

  Tempo instances are immutable. Use Tempo.from(instance) instead.

format

• format(fmt?: any, options?: any): string

  apply a custom format.

  Parameters

  • Optionalfmt: any
  • Optionaloptions: any

  Returns string

• format(options: FormatOptions): string

  applies a format to the instance.

  Parameters

  • options: FormatOptions

  Returns string

• format<S extends string>(
      fmt: string extends S
          ? S
          : string extends ValidateFormat<S> ? S : ValidateFormat<S>,
      options?: any,
  ): string

  Applies a format to the instance. Format strings are validated at compile time — any unrecognised {token} will produce an IDE error showing the bad token name.

  Type Parameters

  • S extends string

  Parameters

  • fmt: string extends S ? S : string extends ValidateFormat<S> ? S : ValidateFormat<S>
  • Optionaloptions: any

  Returns string

  See

  TempoFormatTokens to extend the token set.

• format(): string

  applies a format to the instance (zero-argument — returns a pre-built format proxy).

  Returns string

nextOccurrence

• nextOccurrence(rrule: string | { rrule: string }): Tempo | null

  Computes the next occurrence of a recurrence rule (RRULE string) after this instant.

  Parameters

  • rrule: string | { rrule: string }

    The RFC 5545 RRULE string or object with an rrule property

  Returns Tempo | null

  A new Tempo instance at the next occurrence, or null if no further occurrences exist

set

• set(tempo?: MutateSet, options?: Options): Tempo

  returns a new Tempo with specific offsets.

  Parameters

  • Optionaltempo: MutateSet
  • Optionaloptions: Options

  Returns Tempo

setCatchMode

• setCatchMode(catchMode: boolean): this

  explicitly enable/disable "catch" mode for this instance

  Parameters

  • catchMode: boolean

  Returns this

since

• since(dateTimeOrOpts?: Options | DateTime, opts?: Options): Duration

  time elapsed since another date-time

  Parameters

  • OptionaldateTimeOrOpts: Options | DateTime
  • Optionalopts: Options

  Returns Duration

• since(unit: Unit, opts?: Options): number

  time elapsed since another date-time

  Parameters

  • unit: Unit
  • Optionalopts: Options

  Returns number

• since(dateTimeOrOpts: Options | DateTime, unit: Unit): number

  time elapsed since another date-time

  Parameters

  • dateTimeOrOpts: Options | DateTime
  • unit: Unit

  Returns number

• since(until: Until, opts?: Options): string

  time elapsed since (with unit)

  Parameters

  • until: Until
  • Optionalopts: Options

  Returns string

• since(dateTimeOrOpts: Options | DateTime, until: Until): string

  time elapsed since another date-time (with unit)

  Parameters

  • dateTimeOrOpts: Options | DateTime
  • until: Until

  Returns string

• since(dateTimeOrOpts?: Options | DateTime, opts?: Options): string

  time elapsed since another date-time (w'out unit)

  Parameters

  • OptionaldateTimeOrOpts: Options | DateTime
  • Optionalopts: Options

  Returns string

• since(optsOrDate?: any, optsOrUntil?: any): string

  time elapsed since another date-time

  Parameters

  • OptionaloptsOrDate: any
  • OptionaloptsOrUntil: any

  Returns string

subtract

• subtract(tempo?: MutateAdd, options?: Options): Tempo

  returns a new Tempo with specific duration subtracted.

  Parameters

  • Optionaltempo: MutateAdd
  • Optionaloptions: Options

  Returns Tempo

toDate

• toDate(): Date

  the date-time as a standard Date object.

  Returns Date

toDateTime

• toDateTime(): ZonedDateTime

  returns the underlying Temporal.ZonedDateTime

  Returns ZonedDateTime

toInstant

• toInstant(): Instant

  returns the underlying Temporal.Instant

  Returns Instant

toJSON

• toJSON(): {
      calendar: CalendarLike;
      catch?: boolean;
      debug?: DebugLevel;
      discovery?: string
      | symbol
      | Discovery;
      geo?: Readonly<GeoConfig>;
      intl?: Readonly<IntlOptions>;
      locale: string | readonly string[];
      localeInfo?: boolean;
      mode?: "auto" | "strict" | "defer";
      planner?: Readonly<PlannerOptions>;
      pluginOptions?: Record<string, any>;
      plugins?: any;
      registry: Readonly<
          {
              formats: FormatRegistry;
              locales: Readonly<
                  Record<string, Readonly<Record<string, string | Function>>>,
              >;
              modifiers?: Readonly<Record<string, string | readonly string[]>>;
              numbers?: Readonly<Record<string, number>>;
              tokens?: Readonly<Record<string, TokenEvaluator>>;
          },
      >;
      scope: "global"
      | "local";
      silent?: boolean;
      sphere: string | undefined;
      store?: string;
      timeStamp?: TimeStamp;
      timeZone: TimeZoneLike;
      value: string;
  }

  Custom JSON serialization for JSON.stringify.

  Returns {
      calendar: CalendarLike;
      catch?: boolean;
      debug?: DebugLevel;
      discovery?: string | symbol | Discovery;
      geo?: Readonly<GeoConfig>;
      intl?: Readonly<IntlOptions>;
      locale: string | readonly string[];
      localeInfo?: boolean;
      mode?: "auto" | "strict" | "defer";
      planner?: Readonly<PlannerOptions>;
      pluginOptions?: Record<string, any>;
      plugins?: any;
      registry: Readonly<
          {
              formats: FormatRegistry;
              locales: Readonly<
                  Record<string, Readonly<Record<string, string | Function>>>,
              >;
              modifiers?: Readonly<Record<string, string | readonly string[]>>;
              numbers?: Readonly<Record<string, number>>;
              tokens?: Readonly<Record<string, TokenEvaluator>>;
          },
      >;
      scope: "global"
      | "local";
      silent?: boolean;
      sphere: string | undefined;
      store?: string;
      timeStamp?: TimeStamp;
      timeZone: TimeZoneLike;
      value: string;
  }

  • Readonlycalendar: CalendarLike

    Temporal calendar

  • Optionalcatch?: boolean

    catch or throw Errors

  • Optionaldebug?: DebugLevel

    additional console.log for tracking

  • Optionaldiscovery?: string | symbol | Discovery

    globalThis Discovery Symbol

  • Optional Readonlygeo?: Readonly<GeoConfig>

    Geolocation coordinates configuration

  • Optional Readonlyintl?: Readonly<IntlOptions>

    internationalization configuration (relativeTime, etc.)

  • Readonlylocale: string | readonly string[]

    locale (e.g. en-AU)

  • OptionallocaleInfo?: boolean

    enable regional calendar boundaries (week start/end/mid) via Intl.LocaleInfo

  • Optionalmode?: "auto" | "strict" | "defer"

    initialization strategy ('auto'|'strict'|'defer')

  • Optional Readonlyplanner?: Readonly<PlannerOptions>

    parse planner configuration (layoutOrder, etc.)

  • OptionalpluginOptions?: Record<string, any>

    Plugin configuration defaults and dictionaries keyed by plugin name

  • Optionalplugins?: any

    Plugins or terms to extend onto Tempo.

    Remarks

    To provide configuration options or defaults for plugins, use pluginOptions instead.

  • Readonlyregistry: Readonly<
        {
            formats: FormatRegistry;
            locales: Readonly<
                Record<string, Readonly<Record<string, string | Function>>>,
            >;
            modifiers?: Readonly<Record<string, string | readonly string[]>>;
            numbers?: Readonly<Record<string, number>>;
            tokens?: Readonly<Record<string, TokenEvaluator>>;
        },
    >

    custom data augmentation registries

  • Readonlyscope: "global" | "local"

    scope for configuration mutations

  • Optionalsilent?: boolean

    suppress console output during catch

  • Readonlysphere: string | undefined

    hemisphere for term.qtr or term.szn

  • Optionalstore?: string

    localStorage key

  • OptionaltimeStamp?: TimeStamp

    Precision to measure timestamps (ms | us)

  • ReadonlytimeZone: TimeZoneLike

    Temporal timeZone

  • value: string

toNow

• toNow(): ZonedDateTime

  the current system time localized to this instance.

  Returns ZonedDateTime

toPlainDate

• toPlainDate(): PlainDate

  returns a Temporal.PlainDate representation

  Returns PlainDate

toPlainDateTime

• toPlainDateTime(): PlainDateTime

  returns a Temporal.PlainDateTime representation

  Returns PlainDateTime

toPlainTime

• toPlainTime(): PlainTime

  returns a Temporal.PlainTime representation

  Returns PlainTime

toString

• toString(): string

  iso8601 string representation of the date-time.

  Returns string

until

• until(dateTimeOrOpts?: Options | DateTime, opts?: Options): Duration

  time duration until another date-time

  Parameters

  • OptionaldateTimeOrOpts: Options | DateTime
  • Optionalopts: Options

  Returns Duration

• until(unit: Unit, opts?: Options): number

  time duration until another date-time

  Parameters

  • unit: Unit
  • Optionalopts: Options

  Returns number

• until(dateTimeOrOpts: Options | DateTime, unit: Unit): number

  time duration until another date-time

  Parameters

  • dateTimeOrOpts: Options | DateTime
  • unit: Unit

  Returns number

• until(dateTimeOrOpts?: Options | DateTime, opts?: Options): Duration

  time duration until (returns Duration)

  Parameters

  • OptionaldateTimeOrOpts: Options | DateTime
  • Optionalopts: Options

  Returns Duration

• until(unit: Unit, opts?: Options): number

  time duration until (with unit, returns number)

  Parameters

  • unit: Unit
  • Optionalopts: Options

  Returns number

• until(dateTimeOrOpts: Options | DateTime, unit: Unit): number

  time duration until another date-time (with unit)

  Parameters

  • dateTimeOrOpts: Options | DateTime
  • unit: Unit

  Returns number

• until(
      optsOrDate?:
          | string
          | number
          | bigint
          | TempoBrand
          | ZonedDateTime
          | Instant
          | Options
          | PlainDate
          | PlainDateTime
          | PlainMonthDay
          | PlainYearMonth
          | Date
          | ZonedDateTimeLikeObject
          | ISOString
          | Tempo
          | PlainTime
          | Duration
          | DurationLikeObject
          | Options & { unit?: Unit }
          | null,
      optsOrUntil?: Options | Until,
  ): number | Duration

  fallback: union of possible returns

  Parameters

  • OptionaloptsOrDate:
        | string
        | number
        | bigint
        | TempoBrand
        | ZonedDateTime
        | Instant
        | Options
        | PlainDate
        | PlainDateTime
        | PlainMonthDay
        | PlainYearMonth
        | Date
        | ZonedDateTimeLikeObject
        | ISOString
        | Tempo
        | PlainTime
        | Duration
        | DurationLikeObject
        | Options & { unit?: Unit }
        | null
  • OptionaloptsOrUntil: Options | Until

  Returns number | Duration

Static[dispose]

• "[dispose]"(): void

  release global config and reset library to defaults

  Returns void

Static[hasInstance]

• "[hasInstance]"(instance: any): boolean

  Checks if an instance is a Tempo object using the brand symbol. Allows instanceof to work across module boundaries.

  Parameters

  • instance: any

    The instance to check

  Returns boolean

  True if the instance is a Tempo object

Static[iterator]

• "[iterator]"(): ArrayIterator<string>

  iterate over Tempo properties

  Returns ArrayIterator<string>

Staticbootstrap

• bootstrap(
      options?: { configFile?: string; cwd?: string },
  ): Promise<typeof Tempo>

  Automatically discovers and loads configuration from tempo.config.* before initializing the engine.

  Parameters

  • Optionaloptions: { configFile?: string; cwd?: string }

  Returns Promise<typeof Tempo>

Staticcompare

• compare(tempo1?: Options | DateTime, tempo2?: Options | DateTime): number

  Compares two Tempo instances or date-time values. Returns -1 (earlier), 0 (equal), or 1 (later).

  Parameters

  • Optionaltempo1: Options | DateTime
  • Optionaltempo2: Options | DateTime

  Returns number

Staticcreate

• create(options?: Options): typeof Tempo

  🏭 Sandbox Factory & Scoped Execution Mode

  1. Factory Mode: Creates a fresh, isolated Tempo subclass with its own configuration and registries. The returned class implements Disposable ([Symbol.dispose]()), allowing deterministic cleanup via using.

  2. Scoped Execution Mode: When provided a callback, creates an isolated sandbox, executes the callback, and automatically disposes the sandbox upon completion (supporting both synchronous and Promise returns).

  Parameters

  • Optionaloptions: Options

  Returns typeof Tempo

  Example

  // Factory mode with `using`
  {
    using sb = Tempo.create({ discovery: 'test' });
    sb.use(MyPlugin);
  }
  
  // Scoped callback mode
  const result = Tempo.create((sb) => {
    sb.use(MyPlugin);
    return sb('2026-05-10').format();
  });
  Copy

• create<R>(fn: (sandbox: typeof Tempo) => R): R

  🏭 Sandbox Factory & Scoped Execution Mode

  1. Factory Mode: Creates a fresh, isolated Tempo subclass with its own configuration and registries. The returned class implements Disposable ([Symbol.dispose]()), allowing deterministic cleanup via using.

  2. Scoped Execution Mode: When provided a callback, creates an isolated sandbox, executes the callback, and automatically disposes the sandbox upon completion (supporting both synchronous and Promise returns).

  Type Parameters

  • R

  Parameters

  • fn: (sandbox: typeof Tempo) => R

  Returns R

  Example

  // Factory mode with `using`
  {
    using sb = Tempo.create({ discovery: 'test' });
    sb.use(MyPlugin);
  }
  
  // Scoped callback mode
  const result = Tempo.create((sb) => {
    sb.use(MyPlugin);
    return sb('2026-05-10').format();
  });
  Copy

• create<R>(options: Options, fn: (sandbox: typeof Tempo) => R): R

  🏭 Sandbox Factory & Scoped Execution Mode

  1. Factory Mode: Creates a fresh, isolated Tempo subclass with its own configuration and registries. The returned class implements Disposable ([Symbol.dispose]()), allowing deterministic cleanup via using.

  2. Scoped Execution Mode: When provided a callback, creates an isolated sandbox, executes the callback, and automatically disposes the sandbox upon completion (supporting both synchronous and Promise returns).

  Type Parameters

  • R

  Parameters

  • options: Options
  • fn: (sandbox: typeof Tempo) => R

  Returns R

  Example

  // Factory mode with `using`
  {
    using sb = Tempo.create({ discovery: 'test' });
    sb.use(MyPlugin);
  }
  
  // Scoped callback mode
  const result = Tempo.create((sb) => {
    sb.use(MyPlugin);
    return sb('2026-05-10').format();
  });
  Copy

Staticextend

• extend(discovery: Discovery, symbol?: symbol): typeof Tempo

  Parameters

  • discovery: Discovery
  • Optionalsymbol: symbol

  Returns typeof Tempo

  Deprecated

  Use Tempo.use(...) instead.

• extend(plugin: TempoPlugin, options?: Options): typeof Tempo

  Parameters

  • plugin: TempoPlugin
  • Optionaloptions: Options

  Returns typeof Tempo

  Deprecated

  Use Tempo.use(...) instead.

• extend(plugins: any[], options?: Options): typeof Tempo

  Parameters

  • plugins: any[]
  • Optionaloptions: Options

  Returns typeof Tempo

  Deprecated

  Use Tempo.use(...) instead.

• extend(...args: any[]): typeof Tempo

  Parameters

  • ...args: any[]

  Returns typeof Tempo

  Deprecated

  Use Tempo.use(...) instead.

Staticfrom

• from(options?: Options): Tempo

  Creates a new Tempo instance.

  Parameters

  • Optionaloptions: Options

  Returns Tempo

• from(tempo: DateTime, options?: Options): Tempo

  Creates a new Tempo instance.

  Parameters

  • tempo: DateTime
  • Optionaloptions: Options

  Returns Tempo

Staticinit

• init(options?: Options): typeof Tempo

  Reset Tempo to its default, built-in registration state

  Parameters

  • options: Options = {}

  Returns typeof Tempo

StaticisTempo

• isTempo(instance?: any): instance is Tempo

  check if a supplied variable is a valid Tempo instance

  Parameters

  • Optionalinstance: any

  Returns instance is Tempo

Staticnow

• now(unit: "ss" | "ms" | "us"): number

  Gets the current timestamp in the specified unit.

  Parameters

  • unit: "ss" | "ms" | "us"

    The time unit ('ss', 'ms', 'us').

  Returns number

  The current timestamp as a number (for 'ss', 'ms', 'us')

• now(unit?: "ns"): bigint

  Gets the current timestamp in the specified unit.

  Parameters

  • Optionalunit: "ns"

    The time unit ('ss', 'ms', 'us', 'ns'). Defaults to 'ns' (nanoseconds).

  Returns bigint

  The current timestamp as a number (for 'ss', 'ms', 'us') or bigint (for 'ns')

Staticready

• ready(): Promise<string>

  Wait for engine readiness.

  Returns Promise<string>

  The final status ('none' in Community Tempo)

Staticregexp

• regexp(
      layout: string | RegExp,
      snippet?: Extend<{ readonly [key: symbol]: RegExp }, symbol, RegExp>,
  ): RegExp

  translates {layout} into an anchored, case-insensitive RegExp.

  Parameters

  • layout: string | RegExp
  • Optionalsnippet: Extend<{ readonly [key: symbol]: RegExp }, symbol, RegExp>

  Returns RegExp

StaticsetCatchMode

• setCatchMode(catchMode: boolean): typeof Tempo

  explicitly enable/disable "catch" mode for internal errors

  Parameters

  • catchMode: boolean

  Returns typeof Tempo

Staticuse

• use(discovery: Discovery, symbol?: symbol): typeof Tempo

  Register discovery configuration with an optional discovery symbol.

  Parameters

  • discovery: Discovery

    Discovery object defining options, formats, periods, or terms.

  • Optionalsymbol: symbol

    Optional symbol identifier under globalThis to attach discovery data.

  Returns typeof Tempo

• use<T extends TempoPlugin = TempoPlugin, Opts = any>(
      plugin: any,
      options?: Options,
  ): typeof Tempo

  Register an individual plugin or plugin factory.

  Type Parameters

  • T extends TempoPlugin = TempoPlugin
  • Opts = any

  Parameters

  • plugin: any

    The plugin function or definition to register.

  • Optionaloptions: Options

    Optional configuration for the plugin.

  Returns typeof Tempo

• use(plugins: any[], options?: Options): typeof Tempo

  Register an array of plugins, terms, factories, or tuples.

  Parameters

  • plugins: any[]

    An array of plugins, terms, factories, or tuples to register.

  • Optionaloptions: Options

    Optional configuration for the plugins.

  Returns typeof Tempo

• use(...args: any[]): typeof Tempo

  Register multiple plugins or term extensions.

  Parameters

  • ...args: any[]

    A plugin, term, or list of extensions to register.

  Returns typeof Tempo