Calendar value object

📅 CalendarDate Value Object

CalendarDate is an immutable date-only value object.

It represents a calendar date without time and timezone.

Perfect for:

• Birthdays

• Subscription periods

• Business deadlines

• Billing cycles

• Domain rules where time is irrelevant

---

Features

• Immutable YYYY-MM-DD representation

• Creation from string or native Date

• Validation of invalid dates

• Safe add/subtract days

• Comparison helpers

• Conversion to native Date (00:00:00 time)

---

Usage

import { CalendarDate } from '@nestjstools/clock';

// Create from string
const date1 = CalendarDate.fromString('2025-06-14');

// Create from native Date
const date2 = CalendarDate.fromDate(new Date());

// Get today
const today = CalendarDate.today();

// Manipulation
const nextWeek = today.addDays(7);
const yesterday = today.subtractDays(1);

// Comparison
if (date1.isBefore(nextWeek)) {
  console.log(`${date1.toString()} is before ${nextWeek.toString()}`);
}

// Convert to native Date
const nativeDate = date1.toDate();

---

🏗 Example: Using CalendarDate with IClock

import { Injectable } from '@nestjs/common';
import { IClock, Clock } from '@nestjstools/clock';

@Injectable()
export class ReturnToday {
  constructor(@Clock() private readonly clock: IClock) {}

  todayIs(): string {
    const today = this.clock.today();
    return today.toString(); // YYYY-MM-DD
  }
}