DateTimeBuddy

A lightweight, UTC-based date/time utility class for JavaScript and TypeScript. Wraps native Date with a clean, chainable API for formatting, comparisons, date math, timezone support, and more.

✨ Features

• Create instances from Date, ISO string, number, or Unix timestamp
• Specify and work with any IANA timezone (e.g., America/New_York, Asia/Tokyo)
• Add or subtract days, hours, and minutes
• Get start/end of day, month, and year in the specified timezone
• Compare dates (isBefore, isAfter, isSame)
• Format using tokens: YYYY, MM, DD, HH, mm, ss (all in the chosen timezone)
• Convert to/from Unix timestamps
• Clone and safely modify instances
• Generate human-readable relative times (fromNow, timeAgo)
• Fully typed, tree-shakable, and supports both ESM & CommonJS

📦 Installation

npm install datetimebuddy

🚀 Usage

TypeScript / ESM

import { DateTimeBuddy } from 'datetimebuddy';

// Specify a timezone on creation (defaults to 'UTC')
const dt = new DateTimeBuddy('2025-07-26T15:04:05Z', 'America/New_York');

console.log(dt.format('YYYY-MM-DD HH:mm:ss')); // Outputs date/time in America/New_York timezone

dt.addDays(3).subtractHours(2);

console.log(dt.toISOString()); // ISO string in UTC (native Date behavior)

CommonJS / JavaScript

const { DateTimeBuddy } = require('datetimebuddy');

const dt = new DateTimeBuddy(new Date(), 'Asia/Tokyo');

console.log(dt.format('YYYY-MM-DD HH:mm:ss')); // Outputs date/time in Asia/Tokyo timezone

🔧 API Reference

Constructor

new DateTimeBuddy(date?: Date | string | number, timeZone?: string)

Creates a new instance with optional date and timezone.

• date: Can be a Date, ISO string, number (timestamp), or omitted for current time.
• timeZone: IANA timezone string (defaults to 'UTC').

Static Methods

| Method | Description | | --------------------------------------------------------------------- | -------------------------------------------------------------------------- | | DateTimeBuddy.now(timeZone?: string) | Returns current date/time instance in specified timezone (default 'UTC') | | DateTimeBuddy.parse(dateStr: string, timeZone?: string) | Parses a date string with timezone support | | DateTimeBuddy.fromUnixTimestamp(seconds: number, timeZone?: string) | Creates from Unix timestamp (seconds) in specified timezone |

Instance Methods

Timezone

• setTimeZone(tz: string): this — Change the timezone of the instance
• getTimeZone(): string — Get the current timezone string

Add / Subtract

• addWeeks(n: number)
• subtractWeeks(n: number)
• addDays(days: number)
• subtractDays(days: number)
• addHours(hours: number)
• subtractHours(hours: number)
• addMinutes(minutes: number)
• subtractMinutes(minutes: number)

Get Date Parts (all respect the instance timezone)

• year()
• month() — 1 to 12
• day()
• hour()
• minute()
• second()
• getWeekday() — Returns weekday name (e.g. 'Monday')
• getISOWeekday() — Returns 1 (Monday) to 7 (Sunday)
• getWeekNumber() — ISO week number of the year
• isLeapYear() — Checks if year is a leap year
• daysInMonth() — Returns number of days in current month
• isWeekend() — Returns true if Saturday or Sunday

Comparison

• isBefore(other: Date | DateTimeBuddy)
• isAfter(other: Date | DateTimeBuddy)
• isSame(other: Date | DateTimeBuddy)
• compare(other: Date | DateTimeBuddy) — Returns -1, 0, or 1
• equalsDateOnly(other: Date | DateTimeBuddy) — Compares only year/month/day
• daysBetween(other: Date | DateTimeBuddy)
• diffIn(other: Date | DateTimeBuddy, unit?: 'seconds' | 'minutes' | 'hours' | 'days') — Returns signed difference

Boundary Helpers (based on timezone)

• startOfDay()
• endOfDay()
• currentWeek()
• previousWeek()
• nextWeek()
• startOfMonth()
• endOfMonth()
• startOfYear()
• endOfYear()

Relative Time

• fromNow() — e.g., in 3 minutes, 2 days ago
• timeAgo() — e.g., 5 days ago, just now

Utilities

• setDateComponents({ year?, month?, day?, hour?, minute?, second? })
• clone()
• toDate() — returns native Date (UTC)
• toISOString() — ISO string representation (UTC)
• toUTCString() — Returns standard UTC string
• toJSON() — Same as .toISOString()
• toLocaleString(locale?: string) — Locale-aware string (date and time)
• toLocaleDateString(locale?: string) — Locale-aware date string only
• toUnixTimestamp() — seconds since Unix epoch

Formatting

• format(fmt: string) — Token-based custom formatting
• formatFriendly(locale?: string) — Returns user-friendly string (e.g., "Saturday, July 26, 2025 at 15:04:05")

✅ Examples

const dt = DateTimeBuddy.now('Europe/London')
  .startOfDay()
  .addHours(9)
  .addMinutes(30);

console.log(dt.format("YYYY-MM-DD HH:mm")); // e.g., 2025-07-26 09:30 in London time

dt.setTimeZone('America/Los_Angeles');
console.log(dt.format("YYYY-MM-DD HH:mm")); // Same instant in LA timezone

const future = dt.clone().addDays(10);
console.log(dt.daysBetween(future)); // 10

console.log(future.fromNow()); // e.g., "in 10 days"
console.log(dt.timeAgo());     // e.g., "2 minutes ago"

📄 License

MIT © MuerteSeguraZ