# Dates
URL: https://pro.rv-grid.com/api/dates/
Source: src/content/docs/api/dates.md
### `addDays`

Adds calendar days using UTC math.
Datetime inputs preserve datetime output; date-only inputs return date-only output.

```ts
export function addDays(date: string, days: number): ISODateString;
```

---

### `subtractDays`

```ts
export function subtractDays(date: string, days: number): ISODateString;
```

---

### `addHours`

```ts
export function addHours(date: string, hours: number): ISODateTimeString;
```

---

### `addMinutes`

```ts
export function addMinutes(date: string, minutes: number): ISODateTimeString;
```

---

### `addMonths`

```ts
export function addMonths(date: string, months: number): ISODateString;
```

---

### `diffInDays`

```ts
export function diffInDays(startDate: string, endDate: string): number;
```

---

### `diffInCalendarDays`

```ts
export function diffInCalendarDays(startDate: string, endDate: string): number;
```

---

### `diffInTaskDurationDays`

Returns the Gantt duration between two task dates.
Date-only ranges are inclusive; datetime ranges use elapsed days and keep a
non-zero positive duration at one minute minimum.

```ts
export function diffInTaskDurationDays(startDate: string, endDate: string): number;
```

---

### `diffInHours`

```ts
export function diffInHours(startDate: string, endDate: string): number;
```

---

### `diffInMinutes`

```ts
export function diffInMinutes(startDate: string, endDate: string): number;
```

---

### `compareIsoDates`

```ts
export function compareIsoDates(left: string, right: string): number;
```

---

### `isBefore`

```ts
export function isBefore(left: string, right: string): boolean;
```

---

### `isAfter`

```ts
export function isAfter(left: string, right: string): boolean;
```

---

### `minDate`

```ts
export function minDate(left: string, right: string): ISODateString;
```

---

### `maxDate`

```ts
export function maxDate(left: string, right: string): ISODateString;
```

---

### `shiftDate`

```ts
export function shiftDate(date: string, deltaDays: number): ISODateString;
```

---

### `shiftDateRange`

```ts
export function shiftDateRange<T extends ISODateRange>(range: T, deltaDays: number): T;
```

---

### `shiftDateRanges`

```ts
export function shiftDateRanges<T extends ISODateRange>(
  ranges: readonly T[] | undefined,
  deltaDays: number,
): readonly T[] | undefined;
```

---

### `startOfWeek`

```ts
export function startOfWeek(date: string): ISODateString;
```

---

### `startOfMonth`

```ts
export function startOfMonth(date: string): ISODateString;
```

---

### `startOfQuarter`

```ts
export function startOfQuarter(date: string): ISODateString;
```

---

### `startOfYear`

```ts
export function startOfYear(date: string): ISODateString;
```

---

### `getWeekStartIsoDate`

Returns the UTC Monday for the week containing `date`.

```ts
export function getWeekStartIsoDate(date: Date): ISODateString;
```

---

### `getMonthStartIsoDate`

```ts
export function getMonthStartIsoDate(date: Date): ISODateString;
```

---

### `getIsoWeekNumber`

```ts
export function getIsoWeekNumber(date: Date): number;
```

---

### `todayIsoDate`

```ts
export function todayIsoDate(): ISODateString;
```

---

### `createDateList`

Returns an inclusive date list and throws when the range is invalid.

```ts
export function createDateList(
  startDate: string,
  endDate: string,
  options:;
```

---

### `createSafeDateList`

Returns an inclusive date list or `[]` for invalid input.
Use this when remote/user data should not throw during projection.

```ts
export function createSafeDateList(startDate: string, endDate: string): readonly ISODateString[];
```

---

### `rangesOverlap`

Tests overlap for half-open numeric ranges: `[start, end)` and `[rangeStart, rangeEnd)`.

```ts
export function rangesOverlap(start: number, end: number, rangeStart: number, rangeEnd: number): boolean;
```

---

### `startOfUtcDayMs`

Returns the UTC midnight timestamp for the date containing `value`.

```ts
export function startOfUtcDayMs(value: string | number | Date): number;
```

---

### `getDateDayBounds`

Returns the half-open UTC day bounds `[startMs, endMs)` for a date.

```ts
export function getDateDayBounds(date: string):;
```

---

### `getDateRangeBounds`

Returns half-open UTC bounds for an inclusive date range.

```ts
export function getDateRangeBounds(range: ISODateBoundsRange):;
```

---

### `MINUTE_IN_MS`

```ts
MINUTE_IN_MS: number;
```

---

### `HOUR_IN_MS`

```ts
HOUR_IN_MS: number;
```

---

### `DAY_IN_MS`

```ts
DAY_IN_MS: number;
```

---

### `WEEK_IN_MS`

```ts
WEEK_IN_MS: number;
```

---

### `MINUTE_IN_DAYS`

```ts
MINUTE_IN_DAYS: number;
```

---

### `ISODateRange`

```ts
interface ISODateRange {
  readonly startDate: ISODateString;
  readonly endDate: ISODateString
}
```

---

### `ISODateBoundsRange`

```ts
interface ISODateBoundsRange {
  readonly start: string;
  readonly end: string
}
```

---

### `parseIsoDate`

Parses date-only strings at UTC midnight instead of local midnight.
Datetime strings are delegated to the JavaScript `Date` parser.

```ts
export function parseIsoDate(date: string): Date;
```

---

### `isIsoDateTimeInput`

```ts
export function isIsoDateTimeInput(value: string): boolean;
```

---

### `getIsoWeekdayUtc`

```ts
export function getIsoWeekdayUtc(date: Date): number;
```

---

### `getUtcWeekday`

```ts
export function getUtcWeekday(value: string | Date): number;
```

---

### `getIsoWeekday`

```ts
export function getIsoWeekday(value: string | Date): number;
```

---

### `isValidIsoWeekday`

```ts
export function isValidIsoWeekday(value: number): boolean;
```

---

### `formatIsoDate`

```ts
export function formatIsoDate(date: Date): ISODateString;
```

---

### `formatIsoDateTime`

```ts
export function formatIsoDateTime(date: Date): ISODateTimeString;
```

---

### `isValidIsoDate`

```ts
export function isValidIsoDate(value: string | undefined): value is ISODateString;
```

---

### `isValidIsoDateTime`

```ts
export function isValidIsoDateTime(value: string | undefined): value is ISODateTimeString;
```

---

### `isValidIsoDateValue`

Validates either a date-only ISO value or a UTC datetime value.
Date-only values must round-trip as `YYYY-MM-DD`; datetimes must round-trip
exactly through `toISOString()`.

```ts
export function isValidIsoDateValue(value: string | undefined): value is ISODateString;
```

---

### `normalizeIsoDate`

Returns a valid `YYYY-MM-DD` value or throws with a user-facing message.

```ts
export function normalizeIsoDate(value: string): ISODateString;
```

---

### `parseDateTime`

Parses scheduler datetime input as UTC.
Values without a trailing `Z` are treated as UTC, not local time.

```ts
export function parseDateTime(value: string): Date;
```

---

### `toISODate`

```ts
export function toISODate(date: Date): ISODateString;
```

---

### `toIsoDate`

```ts
export function toIsoDate(date: Date): ISODateString;
```

---

### `ISODateString`

```ts
export type ISODateString = `${number}-${number}-${number}` | `${number}-${number}-${number}T${string}`;
```

---

### `ISODateTimeString`

```ts
export type ISODateTimeString = `${number}-${number}-${number}T${string}`;
```

---

### `ISO_DATE_ONLY_PATTERN`

```ts
ISO_DATE_ONLY_PATTERN: RegExp;
```

---

### `ISO_DATE_PATTERN`

```ts
ISO_DATE_PATTERN: RegExp;
```

---

### `ISO_DATE_PREFIX_PATTERN`

```ts
ISO_DATE_PREFIX_PATTERN: RegExp;
```

---

### `ISO_DATETIME_PATTERN`

```ts
ISO_DATETIME_PATTERN: RegExp;
```

---

### `ISO_DATETIME_INPUT_PATTERN`

```ts
ISO_DATETIME_INPUT_PATTERN: RegExp;
```

---

### `ISO_LOCAL_DATETIME_INPUT_PATTERN`

```ts
ISO_LOCAL_DATETIME_INPUT_PATTERN: RegExp;
```

---

### `ISO_UTC_DATETIME_WITHOUT_ZONE_PATTERN`

```ts
ISO_UTC_DATETIME_WITHOUT_ZONE_PATTERN: RegExp;
```

---

### `parseTimeOfDay`

Parses `HH:mm` or `h:mm AM/PM` into minutes from midnight.
`24:00` is accepted only when `allowEndOfDay` is enabled.

```ts
export function parseTimeOfDay(value: string, options:;
```

---

### `formatTimeOfDay`

```ts
export function formatTimeOfDay(totalMinutes: number): string;
```

---

### `formatCompactTimeOfDay`

```ts
export function formatCompactTimeOfDay(totalMinutes: number): string;
```

---

### `formatAmPmTimeOfDay`

```ts
export function formatAmPmTimeOfDay(totalMinutes: number): string;
```

---

### `formatDisplayTimeOfDay`

```ts
export function formatDisplayTimeOfDay(
  totalMinutes: number,
  options:;
```

---

### `formatDurationMinutes`

```ts
export function formatDurationMinutes(totalMinutes: number): string;
```

---

### `formatDurationDays`

```ts
export function formatDurationDays(
  durationDays: number | undefined | null,
  options:;
```

---

### `hasAmPmMarker`

```ts
export function hasAmPmMarker(value: string): boolean;
```

---

### `getDateMinutes`

```ts
export function getDateMinutes(date: Date): number;
```

---

### `createDateTime`

Creates a UTC datetime from a date-only value and minutes since midnight.

```ts
export function createDateTime(date: string, minutes: number): ISODateTimeString;
```

---

### `createDateTimeFromTimeOfDay`

```ts
export function createDateTimeFromTimeOfDay(date: string, time: string, dayOffset = 0): ISODateTimeString;
```

---

### `getLocalDateTimeAsUtcIsoDateTime`

Serializes a local `Date` clock value as a UTC ISO datetime.
This preserves the user's local wall-clock fields for scheduler form inputs.

```ts
export function getLocalDateTimeAsUtcIsoDateTime(date: Date): ISODateTimeString;
```

---

### `shiftDateTime`

```ts
export function shiftDateTime(value: string, deltaMinutes: number): ISODateTimeString;
```

---

### `getDateTimeDurationMinutes`

```ts
export function getDateTimeDurationMinutes(startDateTime: string, endDateTime: string): number;
```

---

### `getDurationMinutes`

```ts
export function getDurationMinutes(event:;
```

---

### `getClampedDateTimeDurationMinutes`

Returns an event duration in minutes, clamped to zero for inverted ranges.

```ts
export function getClampedDateTimeDurationMinutes(startDateTime: string, endDateTime: string): number;
```

---

### `snapMinutes`

```ts
export function snapMinutes(minutes: number, snap: number): number;
```

---

### `snapDateTime`

Snaps a UTC datetime to the nearest minute interval within the same UTC day.

```ts
export function snapDateTime(value: string, snap: number): ISODateTimeString;
```

---

### `normalizeTimelineWeekStartsOn`

```ts
export function normalizeTimelineWeekStartsOn(value: unknown): TimelineWeekStartsOn;
```

---

### `startOfTimelineWeek`

```ts
export function startOfTimelineWeek(date: string, weekStartsOn: TimelineWeekStartsOn): ISODateString;
```

---

### `parseTimelineDateValue`

Parses a timeline boundary as UTC for deterministic scale math.

```ts
export function parseTimelineDateValue(date: string): Date;
```

---

### `startOfTimelineUnit`

Returns the UTC-aligned start for a timeline unit.
Intraday units preserve datetime precision; day and larger units return date-only values.

```ts
export function startOfTimelineUnit(
  unit: TimelineUnit,
  date: string,
  weekStartsOn: TimelineWeekStartsOn = 0,
): ISODateString | ISODateTimeString;
```

---

### `addTimelineUnit`

Adds a timeline unit while preserving the timeline's UTC normalization rules.

```ts
export function addTimelineUnit(
  unit: TimelineUnit,
  date: string,
  amount: number,
): ISODateString | ISODateTimeString;
```

---

### `getTimelineEndExclusiveDate`

Converts an inclusive Gantt date boundary to an exclusive timeline boundary.
Datetime values already represent instants and are returned unchanged.

```ts
export function getTimelineEndExclusiveDate(date: string): ISODateString | ISODateTimeString;
```

---

### `getTimelineQuarter`

```ts
export function getTimelineQuarter(date: string): number;
```

---

### `formatTimelineDateLabel`

Formats timeline labels in UTC so headers do not drift by local timezone.

```ts
export function formatTimelineDateLabel(
  date: string,
  locale: string,
  options: Intl.DateTimeFormatOptions,
): string;
```

---

### `startOfHour`

```ts
export function startOfHour(date: string): ISODateTimeString;
```

---

### `startOfMinute`

```ts
export function startOfMinute(date: string): ISODateTimeString;
```

---

### `TimelineUnit`

```ts
export type TimelineUnit = 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
```

---

### `TimelineWeekStartsOn`

```ts
export type TimelineWeekStartsOn = 0 | 1;
```

---

### `isWorkingDate`

Checks a date against calendar working weekdays and holiday exclusions.

```ts
export function isWorkingDate(
  date: ISODateString,
  calendar: WorkingCalendar | null | undefined,
): boolean;
```

---

### `moveToNextWorkingDate`

Moves forward until a working date is found.
Returns the original date when no working date is found before `iterationLimit`.

```ts
export function moveToNextWorkingDate(
  date: ISODateString,
  calendar: WorkingCalendar | null | undefined,
  iterationLimit = 3660,
): ISODateString;
```

---

### `moveToNextWorkingDateTime`

```ts
export function moveToNextWorkingDateTime(
  date: ISODateString,
  calendar: WorkingCalendar | null | undefined,
  iterationLimit = 3660,
): ISODateString;
```

---

### `moveToPreviousWorkingDate`

Moves backward until a working date is found.
Returns the original date when no working date is found before `iterationLimit`.

```ts
export function moveToPreviousWorkingDate(
  date: ISODateString,
  calendar: WorkingCalendar | null | undefined,
  iterationLimit = 3660,
): ISODateString;
```

---

### `addWorkingDays`

Adds working days, excluding the start date from the counted offset.

```ts
export function addWorkingDays(
  startDate: ISODateString,
  days: number,
  calendar: WorkingCalendar | null | undefined,
): ISODateString;
```

---

### `subtractWorkingDays`

Subtracts working days, excluding the start date from the counted offset.

```ts
export function subtractWorkingDays(
  startDate: ISODateString,
  days: number,
  calendar: WorkingCalendar | null | undefined,
): ISODateString;
```

---

### `offsetByLagCalendar`

Applies dependency lag using either calendar days or working days.

```ts
export function offsetByLagCalendar(
  date: ISODateString,
  days: number,
  calendar: WorkingCalendar | null | undefined,
  options: LagCalendarOptions,
): ISODateString;
```

---

### `resolveTaskEndDate`

Resolves a task end date from start and duration.
Date-only durations are inclusive; datetime durations support fractional days.

```ts
export function resolveTaskEndDate(
  startDate: ISODateString,
  durationDays: number,
  calendar: WorkingCalendar | null | undefined,
  options: WorkingDayOptions,
): ISODateString;
```

---

### `resolveTaskStartDateFromEnd`

Resolves a task start date from end and duration.
Date-only durations are inclusive; datetime durations support fractional days.

```ts
export function resolveTaskStartDateFromEnd(
  endDate: ISODateString,
  durationDays: number,
  calendar: WorkingCalendar | null | undefined,
  options: WorkingDayOptions,
): ISODateString;
```

---

### `countWorkingDaysInclusive`

Counts working dates inclusively between start and end.

```ts
export function countWorkingDaysInclusive(
  startDate: ISODateString,
  endDate: ISODateString,
  calendar: WorkingCalendar | null | undefined,
): number;
```

---

### `countWorkingDurationDays`

```ts
export function countWorkingDurationDays(
  startDate: ISODateString,
  endDate: ISODateString,
  calendar: WorkingCalendar | null | undefined,
): number;
```

---

### `snapToWorkingDate`

Snaps a date to the nearest working date in the requested direction.
Returns the original date when no working date is found before `iterationLimit`.

```ts
export function snapToWorkingDate(
  date: ISODateString,
  calendar: WorkingCalendar | null | undefined,
  direction: 'forward' | 'back' = 'forward',
  iterationLimit = 366,
): ISODateString;
```

---

### `WorkingTimeRange`

```ts
interface WorkingTimeRange {
  readonly start: string;
  readonly end: string
}
```

---

### `WorkingCalendar`

```ts
interface WorkingCalendar {
  readonly workingDays: readonly number[];
  readonly holidays: readonly string[];
  readonly workingHours?: WorkingTimeRange | readonly WorkingTimeRange[]
}
```

---

### `WorkingDayOptions`

```ts
interface WorkingDayOptions {
  readonly excludeHolidaysFromDuration: boolean
}
```

---

### `LagCalendarOptions`

```ts
interface LagCalendarOptions {
  readonly lagCalendar: 'calendar-days' | 'working-days'
}
```
