subtract()

Subtracts the specified amount of time from the date. Returns a new instance (immutable).

Syntax

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

Parameters

value: number - Amount to subtract
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 subtracted time

Examples

Subtracting Days

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

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

date.subtract(1, 'day');   // 2024-01-14
date.subtract(7, 'day');   // 2024-01-08
date.subtract(1, 'd');     // 2024-01-14 (short form)

Subtracting Months

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

date.subtract(1, 'month');   // 2023-12-15
date.subtract(6, 'month');   // 2023-07-15
date.subtract(1, 'M');       // 2023-12-15 (short form)

Subtracting Years

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

date.subtract(1, 'year');    // 2023-01-15
date.subtract(5, 'year');    // 2019-01-15
date.subtract(1, 'y');       // 2023-01-15 (short form)

Subtracting Time

const date = fdu('2024-01-15T14:30:45');

date.subtract(3, 'hour');      // 2024-01-15 11:30:45
date.subtract(30, 'minute');   // 2024-01-15 14:00:45
date.subtract(15, 'second');   // 2024-01-15 14:30:30

Subtracting Weeks

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

date.subtract(1, 'week');    // 2024-01-08
date.subtract(2, 'w');       // 2024-01-01 (short form)

Chaining

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

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

const past = date
  .subtract(1, 'month')
  .subtract(2, 'day')
  .subtract(3, 'hour');

date.format('YYYY-MM-DD HH:mm');    // '2024-01-15 00:00' (original unchanged)
past.format('YYYY-MM-DD HH:mm');    // '2023-12-12 21:00'

Unit Types

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

Month/Year Edge Cases

When subtracting 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-03-31');

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

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

Immutability

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

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

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

Common Patterns

Go back in time

const now = fdu();
const lastWeek = now.subtract(7, 'day');
const lastMonth = now.subtract(1, 'month');
const lastYear = now.subtract(1, 'year');

Calculate age from birthdate

const birthdate = fdu('1990-05-15');
const today = fdu();

// Calculate years ago
const yearsAgo = birthdate.subtract(-1 * today.diff(birthdate, 'year'), 'year');

// Or use diff directly (recommended)
const age = today.diff(birthdate, 'year');

Time range calculation

const endDate = fdu('2024-12-31');
const startDate = endDate.subtract(30, 'day');

console.log(`Range: ${startDate.format('YYYY-MM-DD')} to ${endDate.format('YYYY-MM-DD')}`);
// Range: 2024-12-01 to 2024-12-31

Deadline calculation

const dueDate = fdu('2024-12-25');
const startWork = dueDate.subtract(2, 'week');

console.log(`Start working by: ${startWork.format('MMMM D, YYYY')}`);

Historical date

const today = fdu();
const oneYearAgo = today.subtract(1, 'year');
const fiveYearsAgo = today.subtract(5, 'year');
const tenYearsAgo = today.subtract(10, 'year');

console.log('Historical dates:');
console.log(`1 year ago: ${oneYearAgo.format('YYYY-MM-DD')}`);
console.log(`5 years ago: ${fiveYearsAgo.format('YYYY-MM-DD')}`);
console.log(`10 years ago: ${tenYearsAgo.format('YYYY-MM-DD')}`);

@pyyupsk/fdu