temporal_native 0.0.2

TC39 Temporal date/time API for Dart, backed by temporal_rs (Rust) via a Diplomat-generated FFI layer. Immutable, unambiguous date and time types with full IANA timezone and calendar support.

temporal

A Dart port of the TC39 Temporal proposal — modern, immutable date and time types with unambiguous ISO 8601 calendar arithmetic.

Dart's built-in DateTime conflates local time, UTC, and timezone handling in ways that regularly cause bugs. temporal provides a suite of distinct types that make the intent of your code explicit and eliminates an entire class of date/time errors.

Features

• PlainDate — a calendar date (year, month, day) with no time or timezone
• PlainTime — a wall-clock time with no date or timezone
• PlainDateTime — a combined calendar date and wall-clock time
• Instant — an exact UTC point in time, backed by microseconds since the Unix epoch
• TemporalDuration — a duration spanning both calendar units (years, months, days) and time units (hours, minutes, seconds)

All types are immutable and comparable; arithmetic operations return new instances.

Getting started

Add to your pubspec.yaml:

dependencies:
  temporal_native: ^0.1.0

Usage

import 'package:temporal_native/temporal.dart';

// Calendar date with no time ambiguity
final birthday = PlainDate(1990, 6, 15);
final nextBirthday = birthday.add(TemporalDuration(years: 34));

// Wall-clock time with no date or timezone
final meetingTime = PlainTime(14, 30);

// Combined date and time, still no timezone
final deadline = PlainDateTime(2025, 12, 31, 23, 59, 59);

// Exact moment in time — always UTC
final now = Instant.now();
final later = now.add(TemporalDuration(hours: 2));

// Durations span both calendar and time units
final duration = TemporalDuration(years: 1, months: 6, hours: 3);

Why not DateTime?

DateTime is either local or UTC, and mixing them silently produces wrong results. There is no type that represents "just a date" or "just a time" — you always carry dead-weight fields. temporal models each concept as its own type, so the compiler catches category errors at compile time rather than runtime.

Additional information

• TC39 Temporal proposal — the specification this package implements
• Temporal cookbook — usage patterns from the JS proposal that translate directly to this package
• File issues at the GitHub issue tracker
• Contributions welcome — see the repository for guidelines