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({ 
  extends: [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

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/[email protected]/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

• 🗣️ Natural Language & Smart Parsing: Parse natural language phrases (e.g. "next Friday 3pm", "two days ago") with zero-cost lazy evaluation and functional aliases.
• 🌍 Zero-Bundle Localization: Multi-language date parsing and formatting powered natively by ECMAScript Intl—no heavy static locale dictionaries required.
• 🧩 Extensible & AI-Ready: Modular plugin ecosystem for astronomical cycles (astro), financial quarters (finance), schedulers (ticker), and LLM-powered parsing (ai).
• 🏗️ Future-Proof & Ultra-Lightweight: Built natively on the TC39 Stage 4 Temporal foundation with zero legacy runtime baggage and full tree-shaking support.

📚 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-plugin-ai | LLM-powered natural language parsing, recurrence expansion & smart scheduling | | | @magmacomputing/tempo-plugin-* | Premium & community plugins — Ticker, Astro, Finance, Sync, Snap and more | | | @magmacomputing/tempo-fns | Pure functional utilities built on native Temporal & Tempo — tree-shakeable helpers | |

💬 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 [email protected].

🗳️ Feedback & Reactions

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

⚖️ License

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