Add Units to Date

`addDate`

Adds one or more time units (years, months, weeks, days, hours, minutes, seconds, milliseconds) to a given date, returning a new Date object without mutating the original.

Import

import { addDate } from 'chronos-date/utils';

Function Signature

function addDate(date: Maybe<DateArgs>, units: UnitWithValue): Date

Parameters

Name	Type	Description
`date`	`Maybe<DateArgs>`	Date input as a `Date` object, date string, or timestamp number. If `undefined`, uses current date and time.
`units`	`UnitWithValue`	An object specifying which time units to add. At least one unit-value pair is required.

`UnitWithValue` Properties

Property	Type	Description
`year`	`Numeric`	Number of years to add.
`month`	`Numeric`	Number of months to add.
`week`	`Numeric`	Number of weeks to add.
`day`	`Numeric`	Number of days to add.
`hour`	`Numeric`	Number of hours to add.
`minute`	`Numeric`	Number of minutes to add.
`second`	`Numeric`	Number of seconds to add.
`millisecond`	`Numeric`	Number of milliseconds to add.

Important

All properties are optional, but at least one must be provided. Values accept both number and numeric string types (Numeric).

Return Value

Date — A new Date object with the specified units added.

Throws

TypeError — If the provided date is invalid (results in NaN timestamp).
TypeError — If any provided unit key or value is invalid.

Example Usage

playground.ts

Behavior

Creates a new Date object — the original date is never mutated.
When date is undefined, falls back to the current date and time (new Date()).
Multiple units can be combined in a single call; each is applied sequentially.
Supports negative values for subtraction (e.g., { day: -1 } subtracts one day).
Accepts numeric strings (e.g., '7') in addition to numbers for unit values.

Type Definitions

type DateArgs = string | number | Date;
type Maybe<T> = T | undefined;
type Numeric = number | `${number}`;

type TimeUnit = 'year' | 'month' | 'day' | 'week' | 'hour' | 'minute' | 'second' | 'millisecond';

type UnitWithValue = RequireAtLeast<{ [U in TimeUnit]?: Numeric }, 1>;

Note

RequireAtLeast<T, N> ensures at least N properties from T must be provided.

Edge Cases

Input Date	Units	Result	Notes
`Valid Date-time`	`{ day: -20 }`	`Provided Date-time - 20 days`	Negative (subtraction)
`Valid Date-time`	`{ }`	`Provided Date-time`	`Provided Date-time` as new `Date` instance
`undefined`	`{ second: 30 }`	`Current Date-time + 30 seconds`	Falls back to `new Date()`
`invalid-date`	`Valid UnitWithValue`	Throws `TypeError`	Invalid date input

Use Cases

Calculating future due dates or deadlines
Scheduling events relative to a base date
Building date pickers and calendars with navigation
Computing expiration timestamps

Conclusion

The addDate utility provides:

Immutable operations — never mutates the original date
Flexible inputs — accepts Date, string, number, or undefined
Multi-unit support — add years, months, weeks, days, hours, minutes, seconds, and milliseconds in one call
Type-safe — enforces at least one unit via RequireAtLeast and validates inputs at runtime

On this page