subDays

SubDays is a date manipulation function used to subtract a specified number of days from a given date, returning a new date object without mutating the input. It is most commonly associated with the date-fns library, where the function is named subDays.

The typical signature is subDays(date, amount), where date is a Date object (or a date-like value) and amount is a non-negative integer representing how many days to subtract. If amount is zero, the function returns the original date. If amount is negative, the operation effectively adds days. The result is a new Date instance, preserving the time of day and the local time zone of the input, and it automatically handles transitions across months and years.

Considerations include how daylight saving time and time zones can influence the interpretation of the time component, though the day count remains exact. SubDays does not mutate the input date, which helps preserve immutability in functional programming patterns and in applications that rely on predictable date arithmetic.

Example usage (conceptual): subDays(new Date(2023, 4, 15), 7) yields a date representing May 8, 2023. In practice, the exact string representation will depend on the environment’s locale and time zone.

Related functions include addDays, and similar operations exist in other libraries (such as subtracting days in Moment.js). SubDays is part of a broader set of utilities for date arithmetic that emphasize pure functions and predictable results.

---