Tempo API Reference

This document provides a comprehensive technical reference for the Tempo class, including static methods, properties, and instance API.

---

• TypeScript Types Reference
• Tempo Cookbook

---

🏗️ Constructor

You can instantiate Tempo in several ways:

• new Tempo(): Defaults to current time ("now").
• new Tempo(dateTime): Parses a date-time value.
• new Tempo(dateTime, options): Parses with specific configuration.
• new Tempo(options): Defaults to "now" with specific configuration.

Valid dateTime Types:

• string: ISO 8601, natural language ("tomorrow", "next Friday"), or custom patterns.
• number: Unix timestamps in milliseconds (default) or microseconds.
• BigInt: Unix timestamps in nanoseconds.
• Date: Standard JavaScript Date object.
• Tempo: Clones another Tempo instance.
• Temporal.*: Any native Temporal object (ZonedDateTime, PlainDate, etc.).

---

🏗️ Static Methods

Tempo.init(options?: Tempo.Options)

Initializes the global default configuration for all subsequent Tempo instances.

• Returns: Tempo.Config (The resolved global config).
• Note: Settings are inherited from library defaults, persistent storage, and provided options. Use silent: true to suppress console.error output for expected failures.

Tempo.extend(arg, options?)

Unified extender for library functionality.

• Plugin: Tempo.extend(TickerPlugin) — Adds functional extensions.

• Term: Tempo.extend(MyTerm) — Registers grammar/parsing terms.

• Discovery: Tempo.extend(config) — Bootstraps global configuration. Formats: Tempo.extend(MyFormat) — Registers custom format strings.

• Returns: typeof Tempo (for chaining).

• Note: Plugins are installed only once; existing core members are protected.

Tempo.from(tempo?: Tempo.DateTime | Tempo.Options, options?: Tempo.Options)

Creates a new Tempo instance. A static alternative to new Tempo().

• Returns: Tempo

Tempo.compare(tempo1, tempo2?)

Compares two Tempo instances or date-time values for sorting.

• Returns: -1 (smaller), 0 (equal), or 1 (larger).

Tempo.duration(input)

(Plugin required) Creates a full Tempo Duration object (EDO) from an ISO string or DurationLike object.

• Returns: Tempo.Duration
• Example: Tempo.duration('P1Y') or Tempo.duration({ months: 2 })

Tempo.now()

Returns the current Unix epoch in nanoseconds as a BigInt.

Tempo.getSymbol(key?: string | symbol)

Retrieves or registers a Symbol for internal token mapping.

Tempo.ticker(arg1?, arg2?)

(Plugin required) Creates a reactive stream of Tempo instances at regular intervals.

• Returns: An AsyncGenerator (if no callback) or a stop function (if callback provided).
• See: Tempo Ticker Guide for the full polymorphic signature and usage patterns.

Tempo.regexp(layout, snippet?)

Translates a Tempo layout string into a compiled RegExp.

Tempo[Symbol.dispose]()

Releases the global configuration and resets the library to its initial defaults. Equivalent to calling Tempo.init().

---

⚙️ Static Properties

Tempo.config

Returns the current global configuration settings.

Tempo.default

Returns the initial out-of-the-box library defaults.

Tempo.terms

Returns an array of all currently registered term plugins.

Tempo.parse

Returns the global parsing rules registry (snippets, layouts, events, etc.).

Tempo.properties

Returns a list of all public static accessor names on the Tempo class.

🔢 Static Enumerators

Access to the internal dictionaries used by Tempo:

• WEEKDAY | WEEKDAYS
• MONTH | MONTHS
• SEASON | COMPASS
• DURATION | DURATIONS
• ELEMENT (Units map)
• FORMAT (Registry of pre-defined formats)
• LIMIT (Useful boundary dates)

---

🚀 Instance Methods

tempo.add(payload: Tempo.DateTime | Tempo.Add, options?: Tempo.Options)

Returns a new Tempo instance with the specified duration or date-time payload added.

• Example: t.add({ days: 2 }) or t.add('tomorrow')

tempo.set(payload: Tempo.DateTime | Tempo.Set, options?: Tempo.Options)

Returns a new Tempo instance with specific values or relative alignments.

• Example: t.set({ month: 5, hh: 12 }) or t.set({ start: 'month' }) landing on 01-May 00:00:00.
• Note (End): Using end with an anchor (e.g., set({ end: '#qtr' })) lands on the Inclusive End of the period (e.g., 30-Sep 23:59:59.999...). This follows industry UX expectations for "end-of-period" navigation.
• Note (Mid): Using mid with an anchor lands on the Arithmetic Mid-point (exact nanosecond center) of the period.

tempo.clone()

Returns a new, lean Tempo instance based on the current one. It preserves all local configuration but starts a fresh "parse history" (length 1). This is ideal for minimizing memory footprint in long chains or live tickers.

tempo.format(fmt: string)

Returns a formatted string or number based on the provided token or named format.

tempo.until(until, opts?)

Calculates the duration until another date-time.

• Returns: number (if a unit is provided) or a Tempo.Duration object.

tempo.since(since?: Tempo.DateTime | Tempo.Options, opts?: Tempo.Options)

Returns a human-readable relative time string (e.g., "3 days ago").

• Returns: string
• Options:
  • rtfStyle: 'long' | 'short' | 'narrow' (default: 'narrow'). See Intl.RelativeTimeFormatStyle.
  • rtfFormat: A pre-configured Intl.RelativeTimeFormat instance.
• Example:
  • t.since('yesterday') -> "1d ago"
  • t.since('yesterday', { rtfStyle: 'long' }) -> "1 day ago"
  • t.since(t2, { rtfFormat: new Intl.RelativeTimeFormat('fr') }) -> "il y a 2 heures"
• Performance: Tempo memoizes Intl object creation internally. For maximum performance in high-volume loops, you can pass a pre-allocated rtfFormat instance.

tempo.isValid

Returns true if the instance represents a valid date-time.

tempo.toString()

Returns the ISO 8601 string representation.

tempo.toDate()

Returns a standard JavaScript Date object.

tempo.toDateTime()

Returns the underlying Temporal.ZonedDateTime object.

tempo.toInstant()

Returns the underlying Temporal.Instant object.

tempo.toPlainDate()

Returns a Temporal.PlainDate representation.

tempo.toPlainTime()

Returns a Temporal.PlainTime representation.

tempo.toPlainDateTime()

Returns a Temporal.PlainDateTime representation.

---

🔍 Instance Properties

Date & Time Accessors

• yy: 4-digit year.
• yw: 4-digit ISO week-numbering year.
• mm: Month (1-12).
• dd: Day of month (1-31).
• ww: ISO week number (1-53).
• hh: Hour (0-23).
• mi: Minutes (0-59).
• ss: Seconds (0-59).
• ms: Milliseconds (0-999).
• us: Microseconds (0-999).
• ns: Nanoseconds (0-999).
• ff: Fractional seconds (decimal).

Localization & Context

• tz: IANA Time Zone ID.
• ts: Unix timestamp (based on config.timeStamp).
• mmm / mon: Short/Full Month name.
• www / wkd: Short/Full Weekday name.
• dow: Day of week number (Mon=1, Sun=7).

Lineage & Metadata

• nano: Epoch nanoseconds (BigInt).
• epoch: Object containing ss, ms, us, ns epoch values.
• term: Object containing results from all active term plugins. (Note: These are enumerable for easy discovery).
• fmt: Registry of pre-calculated strings for all standard formats. (Note: These are enumerable for easy discovery).
• config: The effective configuration for this specific instance (Note: scope, anchor, and value are excluded from the public object).
• parse: The parsing rules and lineage for this instance.

---

TIP

Looking for the full technical details?
For an exhaustive, auto-generated reference of every property, internal type, and class member, see our Full Technical API Reference.