Smart Parsing Guide

Tempo's strongest feature is its flexible, natural-language parsing engine. While native Temporal is strictly ISO-only, Tempo can interpret a vast range of human-friendly date and time expressions.

🚀 Standalone Parsing (Zero-Overhead)

If you only need Tempo's "Smart" parsing but want to keep your project lightweight, you can use the standalone parse function. This returns a native Temporal.ZonedDateTime without importing the full Tempo class.

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

// Returns a native Temporal.ZonedDateTime
const zdt = parse('next Tuesday at 3pm', { timeZone: 'Australia/Sydney' });

console.log(zdt.toString()); // 2026-04-28T15:00:00+10:00[Australia/Sydney]

Why use Standalone Parse?

• Tree-Shaking: Your bundler can skip the entire Tempo class and its associated methods, significantly reducing your bundle size.
• Temporal Native: Perfect for projects that already use native Temporal objects but need a friendlier input layer for users.
• Strict by Default: The standalone function defaults to mode: 'strict', ensuring that it won't "guess" if the input is ambiguous.

WARNING

Terms and Standalone Parsing: Standalone parse() supports all standard natural language patterns but does not resolve Global Terms or aliases unless they are part of the core pattern registry. For full term-dispatch and instance-aware resolution, use the Tempo class.

⚠️ Standalone vs. Class-Based

It is important to understand the trade-offs when using the lightweight parse() function:

Feature	Standalone parse()	new Tempo() Class
Return Type	Native Temporal.ZonedDateTime	Tempo Instance
Fluent API	❌ Native Temporal methods only	✅ .add(), .set(), .format(), etc.
Validation	❌ No .isValid property	✅ Track success via .isValid
State	❌ One-off (Stateless)	✅ Persistent instance configuration
Plugins	❌ Bypasses class-level plugins	✅ Full support for .ticker(), etc.
Global Config	❌ Configuration per call only	✅ Configure once via Tempo.init()

TIP

Use Standalone Parse for server-side processing or background tasks where bundle size is the priority. Use the Tempo Class for UI-heavy applications that need advanced formatting and mutation chains.

---

🏗️ Class-Based Parsing

When using the Tempo class, parsing is handled automatically by the constructor.

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

const t = new Tempo('2 days ago');

Supported Formats

The engine can interpret:

• ISO Strings: 2024-05-20T10:00:00Z
• Short Dates: 20-May, May 20 (locale-aware)
• Relative Strings: next Monday, last Friday, 2 days ago
• Numbers/BigInt: Unix timestamps in milliseconds or nanoseconds.
• Temporal Objects: ZonedDateTime, PlainDate, PlainDateTime.

---

🧩 Modularity: Core vs. Full

The parsing engine is modular. Depending on which version of Tempo you are using, you may need to explicitly enable it:

Version	Smart Parsing Status
Tempo Full	Built-in. Works out of the box.
Tempo Core	Opt-in. You must call Tempo.extend(ParseModule) to enable natural language support.

Enabling Smart Parsing in Core

If you are using @magmacomputing/tempo/core, the constructor only supports basic ISO strings by default. To enable "next Tuesday" style parsing, you must extend it:

import { Tempo } from '@magmacomputing/tempo/core';
import { ParseModule } from '@magmacomputing/tempo/parse';

Tempo.extend(ParseModule);

---

🌍 TimeZone & Locale Awareness

Tempo uses your configuration to resolve ambiguous dates.

US-Style Dates (MM/DD/YYYY)

If you parse a numeric string like 04012026, Tempo uses your timeZone to decide if it means April 1st (US) or 4th of January (UK/AU).

Tempo achieves this by dynamically checking if your current timeZone is associated with a locale that prefers Month-Day ordering (like en-US). It uses the Intl.Locale.prototype.getTimeZones() API where available, and maintains a robust hardcoded fallback list for environments (like Node.js CI or non-ICU environments) where the full Intl API is not present.

const us = new Tempo('04012026', { timeZone: 'America/New_York' }); // Apr 1
const au = new Tempo('04012026', { timeZone: 'Australia/Sydney' });  // Jan 4

Custom Aliases (Events & Periods)

You can teach the parser new words:

Tempo.init({
  event: {
    'launch': '2026-12-01',
    'party': () => 'next Friday 8pm'
  }
});

const t = new Tempo('party');

---

🛡️ Performance: The Master Guard

Tempo uses a "Scan-and-Consume" engine called the Master Guard. This allows it to check your input string against dozens of patterns (weekdays, months, custom events) in a single pass, ensuring that parsing remains $O(1)$ relative to the number of plugins you have active.