Tempo The Professional Date-Time Library for the Temporal API

Tempo is a premium, high-performance wrapper for the ECMAScript Temporal API. Designed for professionals, it combines immutable state-management with a fluent, natural-language engine. It is the modern, type-safe successor to legacy libraries like Moment.js and Luxon.

---

⚡ Quick Start

import { Tempo } from '@magmacomputing/tempo';
import { AstroPlugin } from '@magmacomputing/tempo-plugin-astro';

// 🔌 Instantly Extensible (with deterministic defaults)
Tempo.init({ 
  plugins: [AstroPlugin],
  timeZone: 'America/New_York'
});

// 🎯 Natural Language Parsing (Deterministic anchor)
const event = new Tempo('next Friday 3pm', { anchor: '2026-10-15' });

// 🔄 Fluent Mutations (Immutable)
const reminder = event.add({ hours: 2 }).set({ minute: 0 });

// ⏳ Comparative Durations
const diff = event.until('2026-12-25');
console.log(diff.iso); // P2M2D

// 📝 Beautiful Formatting
console.log(event.format('{mon} {dd:ord}, {yyyy}')); // October 23rd, 2026

// 🌌 Domain Logic (via Plugin)
console.log(event.term.astronomy.season); // 'Autumn'

---

📦 Installation

npm install @magmacomputing/tempo       # npm
yarn add @magmacomputing/tempo          # yarn
pnpm add @magmacomputing/tempo          # pnpm
bun add @magmacomputing/tempo           # bun
deno add npm:@magmacomputing/tempo      # deno

🌐 Browser & Native Environments

For standard usage natively in the browser, use the pre-optimized Global ESM Bundle. It includes the entire core engine in a single file:

<script type="importmap">
{
  "imports": {
    "@js-temporal/polyfill": "https://cdn.jsdelivr.net/npm/@js-temporal/polyfill@0.5.1/dist/index.esm.js",
    "@magmacomputing/tempo": "https://cdn.jsdelivr.net/npm/@magmacomputing/tempo@3/dist/tempo.bundle.esm.js"
  }
}
</script>

<script type="module">
  import '@js-temporal/polyfill';
  import { Tempo } from '@magmacomputing/tempo';
  
  const t = new Tempo('next Friday');
</script>

Advanced Usage (Tempo Plugins & CDNs) If you need to use Tempo Premium Plugins natively in the browser, require granular module resolution, or want to use on-the-fly bundling CDNs (like esm.sh), please see our comprehensive Installation Guide for detailed import map configurations.

---

✨ Why Tempo?

While the native Temporal API gives you perfect primitives (ZonedDateTime, PlainDate), it doesn't give you business logic. Tempo bridges that gap.

Feature	Native Temporal API	The Tempo Ecosystem
Primitives	Perfect (Instant, ZonedDateTime)	Powered by Native Primitives ✨
Timezones	IANA String Support	Advanced fallback & auto-syncing
Domain Logic	❌ Build it yourself	✅ Plugins (astro, sync)
Natural Language	❌ Manual parsing	✅ "next Friday 3pm"

The Missing Domain Layer

• 🏗️ Future Standard: Built natively on the TC39 Temporal proposal. Inherit the reliability of the future standard.
• 🧩 Premium Ecosystem: Don't build temporal math from scratch. Drop in our plugins for Astronomical seasons (astro) and atomic state syncing (sync).
• 🌍 Zero-Bundle Localization: Best-in-class multi-language parsing and formatting powered natively by the Intl API—no massive static locale dictionaries required.
• 🗣️ Natural Language: Resolve complex terms like "two days ago" with zero configuration.
• 🧠 Functional Aliases: Extend the parser with custom logic using a powerful resolution context for relative date math.
• 🔄 Cycle Persistence: Shift by semantic terms (Quarters, Seasons) while preserving your relative day-of-period offset.
• ⚡ Zero-Cost Parsing: Lazy evaluation and smart matching ensure instantiation overhead is near-zero.
• 🛡️ Monorepo Resilient: Built for stability in complex environments with proxy-protected registries.
• 📦 Tree-Shakable: Keep your bundle light. Only load what you need—from Fiscal calendars to high-performance Tickers.
• 🪶 Ultra Lightweight: Tempo itself is incredibly lean. While the required Temporal polyfill adds weight today, it can be dropped entirely the moment JavaScript environments natively adopt the Stage 4 standard.

---

📚 Documentation

For a deeper dive into the API, architecture, and advanced features:

• Official Documentation Website — Tutorials, interactive demos, and "Getting Started" guides.
• Full API Reference Guide — Detailed technical documentation for every class and method.

---

🧰 The Tempo Ecosystem

Tempo is the core library, but the ecosystem extends further:

Package	Description	Resources
@magmacomputing/tempo	Core library — parsing, formatting, natural-language engine
@magmacomputing/tempo-fns	Pure functional utilities built on native Temporal & Tempo — tree-shakeable helpers
@magmacomputing/tempo-plugin-*	Premium & community plugins — Ticker, Astro, Finance, Sync, Snap and more

---

💬 Contact & Support

1. Bug Reports & Features: Please open an Issue.
2. Questions & Ideas: Start a thread in Discussions.
3. Direct Contact: You can reach us at hello@magmacomputing.com.au.

---

🗳️ Feedback & Reactions

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

---

⚖️ License

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