Tempo Documentation

Tempo is a lightweight, tree-shakable utility library for working with native JavaScript Date objects. Unlike libraries that introduce custom date primitives, Tempo provides a collection of utilities to format, parse, and manipulate standard Date objects. It leverages the built-in Intl.DateTimeFormat API to handle complex operations like timezone offsets and locale-aware formatting.

Because it is tree-shakable, you only include the code you use. For example, timezone support requires only a few bytes, while full international date formatting is approximately 2Kb (minified and brotlied).

To generate a production build of the documentation, run the following command from the repository root:

pnpm docs-build

# or

npm run docs-build

After installing dependencies from the repository root, you can preview the documentation app by running the preview command from the docs/ directory using the --prefix flag:

npm --prefix ./docs run preview

To contribute to or develop Tempo locally, install dependencies from the repository root using pnpm and build the library.

corepack enable
pnpm install

pnpm build

To start the documentation server for local development, run the dev command from the repository root. The app will be available at http://localhost:3000.

pnpm dev

# or

npm run dev

The Tempo documentation app is part of a monorepo workspace. To install dependencies correctly, you must run the installation commands from the repository root, not from within the docs/ directory. This ensures the local @formkit/tempo dependency is correctly resolved via the pnpm workspace.

Requirements

• Node ^20.19.0 || >=22.12.0
• Corepack-enabled pnpm

corepack enable
pnpm install

When formatting dates, the Format type allows you to specify how the date and time should appear. You can use a single style, a style object, or a custom token string.

Format Styles

Available styles include:

• full
• long
• medium
• short

Format Style Object

You can specify different styles for the date and time components using a FormatStyleObj:

• { date: FormatStyle; time: FormatStyle }
• { date: FormatStyle }
• { time: FormatStyle }

Custom Token Strings

You can also provide a string composed of specific tokens (e.g., "YYYY-MM-DD").

Tempo accepts several types for date inputs. When providing a date to formatting or parsing functions, you can use DateInput or MaybeDateInput:

• DateInput: A Date object or an ISO8601 string.
• MaybeDateInput: A DateInput or null (often used to represent the current time).

Tempo uses Duration and DurationObj interfaces to represent spans of time.

Duration includes:

• years, months, weeks, days, hours, minutes, seconds, milliseconds

DurationObj extends Duration to include high-precision units:

• microseconds, nanoseconds

To build the documentation website locally, use the docs-build command.

pnpm docs-build

Use diffMinutes to calculate the number of minutes between two dates.

Parameters:

• dateA: The first date input. If dateB is provided, dateA is treated as the right-hand date (the date to compare against). If dateB is omitted, dateA is compared against the current time.
• dateB (optional): The second date input. If provided, it is treated as the left-hand date.
• roundingMethod (optional): The method used to round the resulting number. The default is trunc.

Note on argument order:

• If you provide two dates, dateA is the right date and dateB is the left date.
• If you provide only one date, it is compared against the current time.

The diffMilliseconds() function returns the difference between two dates in milliseconds.

It accepts DateInput or MaybeDateInput (which allows for null or undefined).

• If dateB is provided, it calculates the difference between dateA and dateB (dateA - dateB).
• If dateB is omitted and dateA is provided, it calculates the difference between dateA and the current time.
• If dateA is null or undefined and dateB is provided, it calculates the difference between the current time and dateB.