@rytrox/time

A TypeScript library providing Java-inspired date and time types — LocalDate, LocalTime, and YearMonth — with optional yup schema support for form validation.

Features

• 📅 LocalDate — A date without a time component (YYYY-MM-DD)
• 🕐 LocalTime — A time without a date component (hh:mm, hh:mm:ss, hh:mm:ss.SSS)
• 📆 YearMonth — A year and month combination (YYYY-MM)
• 🗓️ Month enum & DayOfWeek enum
• ✅ Yup schema support via LocalDateSchema, LocalTimeSchema, and YearMonthSchema (optional)
• 🔒 Immutable — all manipulation methods return new instances
• 💡 Fully typed — includes TypeScript string literal types like LocalDateString, LocalTimeString, and YearMonthString

---

Installation

npm install @rytrox/time

Usage

LocalDate

import {LocalDate, Month} from '@rytrox/time';

// Create from ISO string
const date = new LocalDate('2024-03-15');

// Create from year, month, day (month is zero-based, or use the Month enum)
const date2 = new LocalDate(2024, Month.MARCH, 15);

// Factory methods
const today = LocalDate.now();
const parsed = LocalDate.parse('2024-03-15');
const specific = LocalDate.of(2024, Month.MARCH, 15);

// Arithmetic (immutable)
const nextWeek = date.plusDays(7);
const lastMonth = date.minusMonths(1);
const nextYear = date.plusYears(1);

// Comparison
date.isBefore(nextWeek);  // true
date.isAfter(nextWeek);   // false
date.isEqual(parsed);     // true

// Convert to native Date at midnight
const jsDate = date.atStartOfDay();

// Combine with a LocalTime
const jsDateTime = date.atTime(9, 30); // 09:30 on 2024-03-15

// Format
date.toISOString();                     // "2024-03-15"
date.toLocaleString('de-DE');           // "15.3.2024"

LocalTime

import {LocalTime} from '@rytrox/time';

// Create from ISO string
const time = new LocalTime('09:30:00.000');

// Create from individual components
const time2 = new LocalTime(9, 30, 0, 0);

// Current time
const now = LocalTime.now();

// Arithmetic (immutable)
const later = time.plusHours(2);
const earlier = time.minusMinutes(15);

// Comparison
time.isBefore(later);   // true
time.isAfter(earlier);  // false
time.isEqual(time2);    // true

// Format
time.toISOString();                     // "09:30:00.000"
time.toLocaleString('de-DE');           // "09:30:00"

YearMonth

import {YearMonth, Month} from '@rytrox/time';

// Create from year and month
const ym = new YearMonth(2024, Month.MARCH);

// Factory methods
const current = YearMonth.now();
const parsed = YearMonth.parse('2024-03');
const specific = YearMonth.of(2024, Month.MARCH);

// Navigation
const next = new YearMonth(2024, Month.APRIL);
ym.isBefore(next);   // true
ym.isAfter(next);    // false
ym.isEqual(parsed);  // true

// Get dates within the month
const lastDay = ym.atEndOfMonth();   // LocalDate: 2024-03-31
const firstDay = ym.atDay(1);        // LocalDate: 2024-03-01
const days = ym.lengthOfMonth();     // 31

// Format
ym.toISOString();           // "2024-03"
ym.toLocaleString('de-DE'); // "03/2024"

Month & DayOfWeek

import {Month, DayOfWeek} from '@rytrox/time';

Month.JANUARY   // 0 (zero-based, compatible with JS Date)
Month.DECEMBER  // 11

DayOfWeek.SUNDAY    // 0
DayOfWeek.SATURDAY  // 6

Type Guards

import {isLocalDateString, isLocalTimeString, isYearMonthString} from '@rytrox/time';

isLocalDateString('2024-03-15');    // true
isLocalTimeString('09:30:00');      // true
isYearMonthString('2024-03');       // true

Yup Schema Integration (optional)

Requires yup to be installed.

import {localDate, localTime, yearMonth} from '@rytrox/time/yup';
import * as yup from 'yup';

const schema = yup.object({
    startDate: localDate().required('Start date is required'),
    endDate: localDate()
        .required('End date is required')
        .min(yup.ref('startDate'), 'End date must be after start date'),
    meetingTime: localTime().required(),
    billingMonth: yearMonth().required(),
});

API Overview

LocalDate

Method	Description
LocalDate.now()	Returns today's date
LocalDate.parse(str)	Parses an ISO date string and validates
LocalDate.of(year, month, dayOfMonth)	Creates a date from components and validates
LocalDate#plusDays(n) / LocalDate#minusDays(n)	Add / subtract days
LocalDate#plusMonths(n) / LocalDate#minusMonths(n)	Add / subtract months
LocalDate#plusYears(n) / LocalDate#minusYears(n)	Add / subtract years
LocalDate#withDayOfMonth(d)	New instance with day of month
LocalDate#withMonth(m)	New instance with month
LocalDate#withYear(y)	New instance with year
LocalDate#isBefore(other) / LocalDate#isEqual(other) / LocalDate#isAfter(other)	Compare Date
LocalDate#atStartOfDay()	Convert to JS Date at midnight
LocalDate#atTime(h, m, s?, ms?)	Convert to JS Date at time
LocalDate#toISOString()	Convert to ISO string
LocalDate#toLocaleString(locale?, options?)	Convert to locale string

LocalTime

Method	Description
LocalTime.now()	Returns current time
LocalTime.parse(str)	Parses an ISO time string and validates
LocalTime.of(h, m, s?, ms?)	Creates a time from components and validates
LocalTime#plusHours(n) / LocalTime#minusHours(n)	Add / subtract hours
LocalTime#withHour(h)	New instance with hour
LocalTime#withMinute(m)	New instance with minute
LocalTime#withSecond(s)	New instance with second
LocalTime#withMilli(ms)	New instance with millisecond
LocalTime#isBefore(other) / LocalTime#isEqual(other) / LocalTime#isAfter(other)	Compare Time
LocalTime#toISOString()	Convert to ISO string
LocalTime#toLocaleString(locale?, options?)	Convert to locale string

YearMonth

Method	Description
YearMonth.of(y, m)	Creates a year-month from components and validates
YearMonth.now()	Returns current year-month
YearMonth.parse(str)	Parses an ISO year-month string and validates
YearMonth#plusYears(n) / YearMonth#minusYears(n)	Add / subtract years
YearMonth#plusMonths(n) / YearMonth#minusMonths(n)	Add / subtract months
YearMonth#withYear(y)	New instance with year
YearMonth#withMonth(m)	New instance with month
YearMonth#isBefore(other) / YearMonth#isEqual(other) / YearMonth#isAfter(other)	Compare YearMonth
YearMonth#toISOString()	Convert to ISO string
YearMonth#toLocaleString(locale?, options?)	Convert to locale string

License ISC — © The Rytrox Group