v4.0.0

Changes

• break(timestamp): 💥 Use calendar arithmetic for months and years

Release details

• npm: https://www.npmjs.com/package/@haskou/value-objects/v/4.0.0
• Pull request: #52
• Source branch: break/timestamp-calendar-arithmetic
• Version bump: major

Pull request notes

Summary

• change Timestamp.addMonths() from fixed 30-day arithmetic to UTC calendar-month arithmetic
• change Timestamp.addYears() from fixed 365-day arithmetic to UTC calendar-year arithmetic
• preserve the day-of-month when possible and clamp to the last valid day of the target month otherwise
• require integer month/year deltas and reject fractional calendar units with InvalidIntegerError
• avoid out-of-range intermediate Date values at the ECMAScript minimum/maximum timestamp boundaries
• preserve fractional millisecond precision across calendar operations, including negative sub-millisecond timestamps
• split negative fractional timestamps with Math.floor() so the source calendar day is preserved before clamping
• reuse the existing Year leap-year rules instead of duplicating them
• keep addDays(), addWeeks(), addHours(), and smaller units as fixed-duration arithmetic
• add regression coverage for month-end clamping, leap-day clamping, negative months, Date range boundaries, fractional deltas, positive/negative sub-millisecond values

Semver

Breaking / major. Existing callers that rely on a month meaning exactly 30 days or a year meaning exactly 365 days will observe different timestamps. Fractional month/year deltas that previously relied on JavaScript Date normalization now throw explicitly.

Examples:

• 2026-01-31T12:34:56.789Z + 1 month → 2026-02-28T12:34:56.789Z
• 2024-02-29T12:34:56.789Z + 1 year → 2025-02-28T12:34:56.789Z

Validation

• full CI passes on the current PR head
• lint, unit tests with 100% coverage, and package build pass
• all five review threads have been addressed and resolved