add()

Adds the specified amount of time to the date. Returns a new instance (immutable).

Syntax

.add(value: number, unit: UnitType): FduInstance

Parameters

value: number - Amount to add
unit: UnitType - Time unit ('year'|'y', 'month'|'M', 'week'|'w', 'day'|'d', 'hour'|'h', 'minute'|'m', 'second'|'s', 'millisecond'|'ms')

Returns

FduInstance - New instance with the added time

Examples

Adding Days

import { fdu } from '@pyyupsk/fdu';

const date = fdu('2024-01-15');

date.add(1, 'day');   // 2024-01-16
date.add(7, 'day');   // 2024-01-22
date.add(1, 'd');     // 2024-01-16 (short form)

Adding Months

const date = fdu('2024-01-15');

date.add(1, 'month');   // 2024-02-15
date.add(6, 'month');   // 2024-07-15
date.add(1, 'M');       // 2024-02-15 (short form)

Adding Years

const date = fdu('2024-01-15');

date.add(1, 'year');    // 2025-01-15
date.add(5, 'year');    // 2029-01-15
date.add(1, 'y');       // 2025-01-15 (short form)

Adding Time

const date = fdu('2024-01-15T00:00:00');

date.add(3, 'hour');         // 2024-01-15 03:00:00
date.add(30, 'minute');      // 2024-01-15 00:30:00
date.add(45, 'second');      // 2024-01-15 00:00:45
date.add(500, 'millisecond'); // 2024-01-15 00:00:00.500

Adding Weeks

const date = fdu('2024-01-15');

date.add(1, 'week');    // 2024-01-22
date.add(2, 'w');       // 2024-01-29 (short form)

Chaining

Since .add() returns a new instance, you can chain multiple operations:

const date = fdu('2024-01-15');

const future = date
  .add(1, 'month')
  .add(2, 'day')
  .add(3, 'hour');

date.format('YYYY-MM-DD HH:mm');    // '2024-01-15 00:00' (original unchanged)
future.format('YYYY-MM-DD HH:mm');  // '2024-02-17 03:00'

Unit Types

Full Name	Short	Example
`year`	`y`	`.add(1, 'year')`
`month`	`M`	`.add(1, 'month')`
`week`	`w`	`.add(1, 'week')`
`day`	`d`	`.add(1, 'day')`
`hour`	`h`	`.add(1, 'hour')`
`minute`	`m`	`.add(1, 'minute')`
`second`	`s`	`.add(1, 'second')`
`millisecond`	`ms`	`.add(1, 'millisecond')`

Month/Year Edge Cases

When adding months or years, if the resulting day doesn't exist in the target month, it will be clamped to the last valid day:

const date = fdu('2024-01-31');

// January 31 + 1 month = February 29 (2024 is a leap year)
date.add(1, 'month').format('YYYY-MM-DD');  // '2024-02-29'

// January 31 + 2 months = March 31
date.add(2, 'month').format('YYYY-MM-DD');  // '2024-03-31'

const date2 = fdu('2023-01-31');
// January 31 + 1 month = February 28 (2023 is not a leap year)
date2.add(1, 'month').format('YYYY-MM-DD'); // '2023-02-28'

Immutability

.add() returns a new instance and never modifies the original:

const original = fdu('2024-01-15');
const modified = original.add(1, 'day');

original.format('YYYY-MM-DD');  // '2024-01-15' (unchanged)
modified.format('YYYY-MM-DD');  // '2024-01-16'

Common Patterns

Add business days

function addBusinessDays(date: FduInstance, days: number): FduInstance {
  let result = date;
  let added = 0;

  while (added < days) {
    result = result.add(1, 'day');
    const dayOfWeek = result.day();
    if (dayOfWeek !== 0 && dayOfWeek !== 6) {  // Not weekend
      added++;
    }
  }

  return result;
}

const start = fdu('2024-01-15');  // Monday
const end = addBusinessDays(start, 5);  // Following Monday

Schedule future event

const now = fdu();
const reminder = now.add(7, 'day').add(9, 'hour');  // 7 days from now at 9 AM

console.log(`Reminder set for: ${reminder.format('YYYY-MM-DD HH:mm')}`);

Calculate expiration date

const purchaseDate = fdu('2024-01-15');
const warranty = purchaseDate.add(2, 'year');

console.log(`Warranty expires: ${warranty.format('MMMM D, YYYY')}`);

@pyyupsk/fdu