temporal-date-time-utils

v0.0.2

Published

4 months ago

⏰ A modern, type-safe datetime utility library built on the JavaScript Temporal API. Perfect for date manipulation, formatting, and timezone handling.

Downloads

0High
0Medium
0Low

mhzmat

temporal date time datetime timezone utils utilities javascript typescript formatting date-manipulation temporal-api

⏰ Temporal DateTime Utils

A modern, elegant, and type-safe datetime utility library built on the JavaScript Temporal API. Perfect for precise date/time manipulation without the quirks of legacy JavaScript Date.

Why Temporal?

The legacy JavaScript Date has been a source of frustration for decades. The Temporal API fixes all of its problems:

✅ Immutable - No surprising side effects
✅ Timezone-aware - Handle timezones correctly
✅ Easy arithmetic - Add/subtract dates naturally
✅ Precise - Nanosecond precision
✅ Type-safe - Distinct types for different temporal concepts

Features

🎯 50+ methods covering all common datetime operations
📦 Zero dependencies (except Temporal polyfill)
🔒 Fully type-safe with TypeScript 5.3+
🌍 Timezone handling built-in
📅 Business day utilities
⏱️ Duration calculations and formatting

Installation

npm install temporal-date-time-utils

Quick Start

import { DateTimeUtils } from 'temporal-date-time-utils'

// Get today's date
const today = DateTimeUtils.today()

// Create a specific date
const date = DateTimeUtils.defineDate({ year: 2025, month: 1, day: 15 })

// Add 5 days
const futureDate = DateTimeUtils.add(date, { days: 5 })

// Format nicely
console.log(DateTimeUtils.formatDate(futureDate, 'long'))
// → "January 20, 2025"

// Calculate differences
const daysBetween = DateTimeUtils.daysBetween(date, futureDate)
// → 5

Type Annotations

Use types via the DateTimeUtils namespace for explicit, unified API:

import { DateTimeUtils } from 'temporal-date-time-utils'

// Type annotations
const today: DateTimeUtils.DateType = DateTimeUtils.today()
const now: DateTimeUtils.InstantType = DateTimeUtils.now()
const duration: DateTimeUtils.DurationType = DateTimeUtils.createDuration({ days: 5 })

// Function parameters
function processDate(date: DateTimeUtils.DateType): string {
  return DateTimeUtils.formatDate(date, 'long')
}

Common Operations

Creating & Getting Time

const today = DateTimeUtils.today()
const now = DateTimeUtils.now()
const tomorrow = DateTimeUtils.tomorrow()
const nextMonth = DateTimeUtils.nextMonth()

// Create specific dates
const date = DateTimeUtils.defineDate({ year: 2025, month: 12, day: 25 })
const parsed = DateTimeUtils.toDate('2025-01-15')

Formatting

DateTimeUtils.formatDate(date, 'iso')       // "2025-01-15"
DateTimeUtils.formatDate(date, 'long')      // "January 15, 2025"
DateTimeUtils.formatDate(date, 'short')     // "Jan 15, 2025"

DateTimeUtils.formatDateTime(instant)       // "Jan 15, 2025, 2:30:45 PM EST"
DateTimeUtils.formatDateRange(start, end)   // "Jan 15 - 22, 2025"
DateTimeUtils.formatTimeAgo(past)           // "2 hours ago"

Arithmetic

DateTimeUtils.add(date, { days: 5 })
DateTimeUtils.add(date, { months: 1 })
DateTimeUtils.subtract(date, { days: 3 })

Boundaries

DateTimeUtils.startOfMonth(date)   // First day of current month
DateTimeUtils.endOfMonth(date)     // Last day of current month
DateTimeUtils.startOfYear(date)    // January 1

Comparisons

DateTimeUtils.isSame(date1, date2)
DateTimeUtils.isBefore(date1, date2)
DateTimeUtils.isAfter(date1, date2)
DateTimeUtils.isPast(instant)
DateTimeUtils.isFuture(instant)

Business Days

DateTimeUtils.isBusinessDay(monday)
DateTimeUtils.addBusinessDays(monday, 5)  // Next Friday

Utilities

DateTimeUtils.daysBetween(date1, date2)
DateTimeUtils.ageInYears(birthDate)
DateTimeUtils.createDuration({ days: 1, hours: 5 })

API Reference

| Category | Methods | |----------|---------| | Current Time | now(), today(), currentYearMonth() | | Creation | defineDate(), defineInstant(), defineYearMonth(), defineZonedDateTime() | | Parsing | toDate(), toInstant(), toYearMonth() | | Formatting | formatDate(), formatDateTime(), formatDuration(), formatTimeAgo(), formatDateRange() | | Arithmetic | add(), subtract() | | Boundaries | startOfDay(), endOfDay(), startOfMonth(), endOfMonth(), startOfYear() | | Comparisons | isSame(), isBefore(), isAfter(), isPast(), isFuture() | | Business Days | isBusinessDay(), addBusinessDays(), getDayOfWeek() | | Utilities | daysBetween(), monthsBetween(), ageInYears(), durationBetween() | | Sorting | sortByDate(), sortByInstant(), dateComparator(), instantComparator() | | Legacy | fromTemporalToLegacyDate(), fromLegacyDateToTemporalInstant() |

Development

npm run build      # Build once
npm run dev        # Watch mode
npm run clean      # Remove build artifacts

Project Structure

src/
├── index.ts              # Main entry point
├── types.ts              # Type definitions
└── DateTimeUtils.ts      # Core utility class

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.