@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 stringconstdate=newLocalDate('2024-03-15');// Create from year, month, day (month is zero-based, or use the Month enum)constdate2=newLocalDate(2024,Month.MARCH,15);// Factory methodsconsttoday=LocalDate.now();constparsed=LocalDate.parse('2024-03-15');constspecific=LocalDate.of(2024,Month.MARCH,15);// Arithmetic (immutable)constnextWeek=date.plusDays(7);constlastMonth=date.minusMonths(1);constnextYear=date.plusYears(1);// Comparisondate.isBefore(nextWeek);// truedate.isAfter(nextWeek);// falsedate.isEqual(parsed);// true// Convert to native Date at midnightconstjsDate=date.atStartOfDay();// Combine with a LocalTimeconstjsDateTime=date.atTime(9,30);// 09:30 on 2024-03-15// Formatdate.toISOString();// "2024-03-15"date.toLocaleString('de-DE');// "15.3.2024"

LocalTime

import{LocalTime}from'@rytrox/time';// Create from ISO stringconsttime=newLocalTime('09:30:00.000');// Create from individual componentsconsttime2=newLocalTime(9,30,0,0);// Current timeconstnow=LocalTime.now();// Arithmetic (immutable)constlater=time.plusHours(2);constearlier=time.minusMinutes(15);// Comparisontime.isBefore(later);// truetime.isAfter(earlier);// falsetime.isEqual(time2);// true// Formattime.toISOString();// "09:30:00.000"time.toLocaleString('de-DE');// "09:30:00"

YearMonth

import{YearMonth,Month}from'@rytrox/time';// Create from year and monthconstym=newYearMonth(2024,Month.MARCH);// Factory methodsconstcurrent=YearMonth.now();constparsed=YearMonth.parse('2024-03');constspecific=YearMonth.of(2024,Month.MARCH);// Navigationconstnext=newYearMonth(2024,Month.APRIL);ym.isBefore(next);// trueym.isAfter(next);// falseym.isEqual(parsed);// true// Get dates within the monthconstlastDay=ym.atEndOfMonth();// LocalDate: 2024-03-31constfirstDay=ym.atDay(1);// LocalDate: 2024-03-01constdays=ym.lengthOfMonth();// 31// Formatym.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// 11DayOfWeek.SUNDAY// 0DayOfWeek.SATURDAY// 6

Type Guards

import{isLocalDateString,isLocalTimeString,isYearMonthString}from'@rytrox/time';isLocalDateString('2024-03-15');// trueisLocalTimeString('09:30:00');// trueisYearMonthString('2024-03');// true

Yup Schema Integration (optional)

Requires yup to be installed.

import{localDate,localTime,yearMonth}from'@rytrox/time/yup';import*asyupfrom'yup';constschema=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