skills/plugins/document-navigator/docs/foundation/timing/datetime/README.md

@suaveplan/datetime - Timezone-aware date/time utilities with business-day arithmetic, recurrence rules, calendar math, and relative time formatting

Summary

Timezone-aware date/time utilities covering the most common application-layer date operations that the native Date API leaves unaddressed. The package provides calendar math (addDuration, subtractDuration, startOf, endOf, getCalendarMonth, leap-year detection), business-day arithmetic with configurable holiday calendars and custom weekend definitions, an RRULE-subset recurrence engine (DAILY/WEEKLY/MONTHLY/YEARLY with BYDAY/BYMONTH/COUNT/UNTIL), and human-readable relative time formatting ("3 hours ago", "in 2 days"). All stateful entry points accept an injectable Clock for deterministic testing. Use this package for scheduling UIs, calendar components, invoice date calculations, and any domain where "next business day" or "every other Monday" has real meaning. For low-level stopwatches, throttle/debounce, or vector clocks use @suaveplan/timing.

Documentation tree

• business-days — (no submodules)
  • business-days — (no submodules)
• calendar — (no submodules)
  • calendar-boundary — calendar-boundary provides startOf and endOf functions for @suaveplan/datetime, computing the precise first and…
  • calendar-core — calendar-core provides the foundational date primitives for @suaveplan/datetime: coercing heterogeneous DateInput…
  • calendar-duration — calendar-duration provides duration arithmetic for @suaveplan/datetime: adding and subtracting Duration bags from…
  • calendar-grid — calendar-grid provides getCalendarMonth, which builds a full calendar month grid for use in UI calendar components…
  • calendar — (no submodules)
• errors — (no submodules)
  • datetime-error — (no submodules)
• otel — (no submodules)
  • datetime-otel — (no submodules)
• recurrence — (no submodules)
  • recurrence-generate — recurrence-generate provides the internal generator functions that produce infinite sequences of candidate dates for…
  • recurrence-helpers — recurrence-helpers provides the internal constants and low-level date arithmetic utilities shared across the recurren…
  • recurrence — (no submodules)
• relative — (no submodules)
  • relative — (no submodules)

- [business-days](./src/business-days/business-days.md) — _(no submodules)_- [calendar](./src/calendar/calendar.md) — _(no submodules)_- [calendar-boundary](./src/calendar/calendar-boundary.md) — `calendar-boundary` provides `startOf` and `endOf` functions for `@suaveplan/datetime`, computing the precise first and…

• calendar-core — calendar-core provides the foundational date primitives for @suaveplan/datetime: coercing heterogeneous DateInput…
• calendar-duration — calendar-duration provides duration arithmetic for @suaveplan/datetime: adding and subtracting Duration bags from…
• calendar-grid — calendar-grid provides getCalendarMonth, which builds a full calendar month grid for use in UI calendar components…
• calendar — (no submodules)- errors — (no submodules)- datetime-error — (no submodules)- otel — (no submodules)- datetime-otel — (no submodules)- recurrence — (no submodules)- recurrence-generate — recurrence-generate provides the internal generator functions that produce infinite sequences of candidate dates for…
• recurrence-helpers — recurrence-helpers provides the internal constants and low-level date arithmetic utilities shared across the recurren…
• recurrence — (no submodules)- relative — (no submodules)- relative — (no submodules)- business-days — (no submodules)- calendar — (no submodules)- calendar-boundary — calendar-boundary provides startOf and endOf functions for @suaveplan/datetime, computing the precise first and…
• calendar-core — calendar-core provides the foundational date primitives for @suaveplan/datetime: coercing heterogeneous DateInput…
• calendar-duration — calendar-duration provides duration arithmetic for @suaveplan/datetime: adding and subtracting Duration bags from…
• calendar-grid — calendar-grid provides getCalendarMonth, which builds a full calendar month grid for use in UI calendar components…
• calendar — (no submodules)- errors — (no submodules)- datetime-error — (no submodules)- otel — (no submodules)- datetime-otel — (no submodules)- recurrence — (no submodules)- recurrence-generate — recurrence-generate provides the internal generator functions that produce infinite sequences of candidate dates for…
• recurrence-helpers — recurrence-helpers provides the internal constants and low-level date arithmetic utilities shared across the recurren…
• recurrence — (no submodules)- relative — (no submodules)- relative — (no submodules)- business-days — (no submodules)- calendar — (no submodules)- calendar-boundary — calendar-boundary provides startOf and endOf functions for @suaveplan/datetime, computing the precise first and…
• calendar-core — calendar-core provides the foundational date primitives for @suaveplan/datetime: coercing heterogeneous DateInput…
• calendar-duration — calendar-duration provides duration arithmetic for @suaveplan/datetime: adding and subtracting Duration bags from…
• calendar-grid — calendar-grid provides getCalendarMonth, which builds a full calendar month grid for use in UI calendar components…
• calendar — (no submodules)- errors — (no submodules)- datetime-error — (no submodules)- otel — (no submodules)- datetime-otel — (no submodules)- recurrence — (no submodules)- recurrence-generate — recurrence-generate provides the internal generator functions that produce infinite sequences of candidate dates for…
• recurrence-helpers — recurrence-helpers provides the internal constants and low-level date arithmetic utilities shared across the recurren…
• recurrence — (no submodules)- relative — (no submodules)- relative — (no submodules)- business-days — (no submodules)- calendar — (no submodules) - calendar-boundary — calendar-boundary provides startOf and endOf functions for @suaveplan/datetime, computing the precise first and…
• calendar-core — calendar-core provides the foundational date primitives for @suaveplan/datetime: coercing heterogeneous DateInput…
• calendar-duration — calendar-duration provides duration arithmetic for @suaveplan/datetime: adding and subtracting Duration bags from…
• calendar-grid — calendar-grid provides getCalendarMonth, which builds a full calendar month grid for use in UI calendar components…
• calendar — (no submodules)- errors — (no submodules) - datetime-error — (no submodules)- otel — (no submodules) - datetime-otel — (no submodules)- recurrence — (no submodules) - recurrence-generate — recurrence-generate provides the internal generator functions that produce infinite sequences of candidate dates for…
• recurrence-helpers — recurrence-helpers provides the internal constants and low-level date arithmetic utilities shared across the recurren…
• recurrence — (no submodules)- relative — (no submodules) - relative — (no submodules)

Modules

Module	Description
calendar	Core date arithmetic: toDate, addDuration, subtractDuration, startOf, endOf, getCalendarMonth, daysInMonth, isLeapYear, isSameDay, isSameMonth
business-days	Working-day arithmetic with holiday and custom-weekend support
recurrence	RRULE parse/format/expand engine (DAILY/WEEKLY/MONTHLY/YEARLY)
relative	Human-readable relative time: formatRelative, timeAgo, timeUntil, diffInUnits
errors	DatetimeError + DATETIME_CODES registry
otel	OpenTelemetry histogram and counter instrumentation

Quick start

import { addDuration, getCalendarMonth, businessDaysBetween, expandRecurrence, parseRRule, formatRelative } from "@suaveplan/datetime";

// Calendar math
const nextMonth = addDuration(new Date(), { months: 1 });
const march2024 = getCalendarMonth(2024, 3);

// Business days
const tradingDays = businessDaysBetween("2024-01-01", "2024-04-01");

// Recurrence
const meetings = expandRecurrence(parseRRule("FREQ=WEEKLY;BYDAY=MO,WE;COUNT=8"));

// Relative time
console.log(formatRelative(new Date(Date.now() - 3 * 3600_000))); // "3 hours ago"

Installation

bun add @suaveplan/datetime

License

MIT