Tempo

Tempo is a premium, high-performance wrapper around the JavaScript Temporal API, providing a fluent and intuitive interface for date-time manipulation and flexible parsing.

🚀 Overview

Working with dates in JavaScript has historically been painful. The new Temporal proposal (Stage 3) fixes this, but it can be verbose and strict when parsing strings.

Tempo bridges that gap by providing:

• Flexible Parsing: Interprets almost any date string, including relative ones like "next Friday".
• Fluent API: Chainable methods for adding, subtracting, and setting date-times.
• Formatting: Use custom tokens to format date-times in a way that is both intuitive and flexible.
• Built-in Plugins: Access complex date ranges (Quarters, Seasons, Fiscal Years) easily.
• Immutable: operations (like 'set', and 'add') return a new Tempo instance, ensuring thread safety and predictability.

📦 Installation

npm install @magmacomputing/tempo

💻 Node.js (Server-Side)

Tempo is a native ESM package. In Node.js (20+), simply import the class:

import { Tempo } from '@magmacomputing/tempo';

const t = new Tempo('next Friday');
console.log(t.format('{dd} {mon} {yyyy}'));

🌐 Browser (Import Maps)

Since Tempo is a native ESM package, you can use it directly in modern browsers using importmap:

<script type="importmap">
{
  "imports": {
    "@magmacomputing/tempo": "https://cdn.jsdelivr.net/npm/@magmacomputing/tempo/dist/index.js"
  }
}
</script>
<script type="module">
  import { Tempo } from '@magmacomputing/tempo';
  const t = new Tempo('next friday');
  console.log(t.format('{mon} {day}'));
</script>

📦 Browser (Script Tag)

For environments without importmap support or simple prototypes, use the bundled version:

<script src="https://cdn.jsdelivr.net/npm/@magmacomputing/tempo/dist/tempo.bundle.js"></script>
<script>
  const t = new Tempo('tomorrow');
  console.log(t.toString());
</script>

🛠️ Quick Start

import { Tempo } from '@magmacomputing/tempo';

// Instantiate 
const now = new Tempo(); 
const birthday = new Tempo('20-May-1990');
const nextWeek = new Tempo('next Monday');

// Manipulate
const later = now.add({ days: 3, hours: 2 });
const startOfMonth = now.set({ start: 'month' });

// Format
console.log(now.format('{dd} {mmm} {yyyy}')); // using custom format with tokens: "24 Jan 2026"
console.log(now.fmt.date);                    // using pre-built formats: "2026-01-24"

📚 Documentation

For detailed technical guides, please refer to:

• Vision & Value Proposition
• Tempo vs. Native Temporal
• Tempo vs. The Competition
• Tempo Class Documentation
• Data In ~ Parsing Engine
• Data Out ~ Formatting Tokens
• Plugin System (Terms)
• Configuration Guide
• Commercial Support & Consulting

💖 Support the Project

If you find Tempo useful and want to support its development, please consider sponsoring me on GitHub! Your support helps keep the project active and premium.

💬 Contact & Support

If you have a question, find a bug, or want to suggest a new feature:

1. Bug Reports & Features: Please open an Issue.
2. Questions & Ideas: Start a thread in Discussions.
3. Direct Contact: You can reach me at [email protected].

🛡️ Privacy & Transparency

We value your privacy. Tempo does not include any runtime telemetry or "phone-home" features. To understand adoption and prioritize features, we use Scarf to aggregate anonymous download statistics.

• No Runtime Tracking: Tempo will never make network requests from your application.
• Anonymous Data: We only see aggregated metadata (e.g., download volume, general geographic region) provided by the registry gateway.
• Opt-out: You can opt-out of Scarf's tracking by following their opt-out instructions.

🗳️ Feedback & Reactions

How are we doing? Let us know with a simple reaction!
(This will open a pre-filled GitHub Issue)

🚀 Premium!   |   ⭐ Loving it!   |   💡 Needs work   |   🐞 Found a bug

⚡ Quick Reactions

(Native reactions available in Discussions)

👍 Like   |   ❤️ Love   |   😄 Haha   |   😮 Wow   |   😢 Sad   |   😡 Angry   |   💩 Poop

⚖️ License

Distributed under the MIT License. See LICENSE for more information.