offset

function offset(date: Date, amount: number, unit: TimeUnit): Date;

A new Date is returned; the one passed in is untouched. A negative amount moves backwards.

Adding a month keeps the day of the month where it exists and clamps it where it does not: 31 January plus one month is 28 February, not 3 March.

Parameters

Parameter	Type	Description
`date`	`Date`	The date to read. It must be a valid `Date`.
`amount`	`number`	How many units to move. Negative moves backwards.
`unit`	`TimeUnit`	`"millisecond"` through `"year"`, as for `diff`.

Returns

Date — a new date, shifted.

Throws

Exception	Condition
`IllegalArgumentException`	an argument is not a valid `Date`.

Examples

Shifting a date

const start = new Date(2026, 0, 31);

offset(start, 1, "month"); // 28 February 2026 — the day is clamped
offset(start, -1, "day"); // 30 January 2026

Source

src/time/offset.ts

23 September 2026

This documentation was generated with AI (Claude) from the library's source code.

apps-script-utils 2.1.1 Help