Dates

addDays

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

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

---

subtractDays

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

---

addHours

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

---

addMinutes

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

---

addMonths

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

---

diffInDays

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

---

diffInCalendarDays

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

---

diffInTaskDuration

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.

export function diffInTaskDuration(startDate: string, endDate: string): number;

---

diffInHours

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

---

diffInMinutes

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

---

compareIsoDates

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

---

isBefore

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

---

isAfter

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

---

minDate

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

---

maxDate

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

---

shiftDate

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

---

shiftDateRange

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

---

shiftDateRanges

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

---

startOfWeek

export function startOfWeek(date: string): ISODateString;

---

startOfMonth

export function startOfMonth(date: string): ISODateString;

---

startOfQuarter

export function startOfQuarter(date: string): ISODateString;

---

startOfYear

export function startOfYear(date: string): ISODateString;

---

getWeekStartIsoDate

Returns the UTC Monday for the week containing date.

export function getWeekStartIsoDate(date: Date): ISODateString;

---

getMonthStartIsoDate

export function getMonthStartIsoDate(date: Date): ISODateString;

---

getIsoWeekNumber

export function getIsoWeekNumber(date: Date): number;

---

todayIsoDate

export function todayIsoDate(): ISODateString;

---

createDateList

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

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.

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

---

rangesOverlap

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

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

---

startOfUtcDayMs

Returns the UTC midnight timestamp for the date containing value.

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

---

getDateDayBounds

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

export function getDateDayBounds(date: string):;

---

getDateRangeBounds

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

export function getDateRangeBounds(range: ISODateBoundsRange):;

---

MINUTE_IN_MS

MINUTE_IN_MS: number;

---

HOUR_IN_MS

HOUR_IN_MS: number;

---

DAY_IN_MS

DAY_IN_MS: number;

---

WEEK_IN_MS

WEEK_IN_MS: number;

---

MINUTE_IN_DAYS

MINUTE_IN_DAYS: number;

---

ISODateRange

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

---

ISODateBoundsRange

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

---

resolveDurationSettings

export function resolveDurationSettings(
  settings: DurationSettings | undefined,
  calendar?: Pick<CalendarEntity, 'hoursPerDay' | 'workingDays'> | null,
): ResolvedDurationSettings;

---

parseDuration

export function parseDuration(
  input: unknown,
  options?: ParseDurationOptions,
): ParsedDuration | null;

---

hasDurationUnitToken

Returns true when text explicitly contains a unit rather than a bare number.

export function hasDurationUnitToken(input: unknown): boolean;

---

durationToWorkingDays

export function durationToWorkingDays(
  value: number,
  unit: DurationUnit,
  settings: ResolvedDurationSettings,
): number;

---

durationToHours

Converts a displayed duration magnitude into canonical stored working hours.

export function durationToHours(
  value: number,
  unit: DurationUnit,
  settings: ResolvedDurationSettings,
): number;

---

workingDaysToDuration

export function workingDaysToDuration(
  workingDays: number,
  unit: DurationUnit,
  settings: ResolvedDurationSettings,
): number;

---

hoursToDuration

Converts canonical stored working hours into a display magnitude.

export function hoursToDuration(
  hours: number,
  unit: DurationUnit,
  settings: ResolvedDurationSettings,
): number;

---

durationToElapsedDays

Converts an elapsed duration to continuous 24-hour calendar days.

export function durationToElapsedDays(value: number, unit: DurationUnit): number;

---

durationToElapsedHours

Converts an elapsed display magnitude into canonical stored continuous hours.

export function durationToElapsedHours(value: number, unit: DurationUnit): number;

---

elapsedDaysToDuration

export function elapsedDaysToDuration(elapsedDays: number, unit: DurationUnit): number;

---

elapsedHoursToDuration

Converts canonical stored continuous hours into an elapsed display magnitude.

export function elapsedHoursToDuration(elapsedHours: number, unit: DurationUnit): number;

---

resolveAutomaticDurationUnit

export function resolveAutomaticDurationUnit(
  workingDays: number,
  settings: ResolvedDurationSettings,
): DurationUnit;

---

resolveAutomaticDurationUnitFromHours

Selects the automatic display unit for a canonical working-hour value.

export function resolveAutomaticDurationUnitFromHours(
  hours: number,
  settings: ResolvedDurationSettings,
): DurationUnit;

---

formatDurationValue

export function formatDurationValue(
  value: number,
  unit: DurationUnit,
  options?: FormatDurationValueOptions,
): string;

---

formatWorkingDuration

export function formatWorkingDuration(
  workingDays: number,
  settings: ResolvedDurationSettings,
  options?: FormatWorkingDurationOptions,
): string;

---

DurationUnit

Unit retained with an authored task duration.

/** Unit retained with an authored task duration. */
export type DurationUnit = 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';

---

DurationSettings

Project-level duration display and working-time conversion settings.

interface DurationSettings {
  /** Unit used for bare input and display. `auto` chooses minutes, hours, or days by magnitude. */
    readonly defaultUnit?: DurationUnit | 'auto';
  /** Unit used for bare Work input and display. Defaults to `auto`, independently from task Duration. */
    readonly defaultWorkUnit?: DurationUnit | 'auto';
  /** Working hours represented by one duration day. Defaults to the effective calendar, then 8. */
    readonly hoursPerDay?: number;
  /** Working hours represented by one duration week. Defaults to the effective workweek, then 40. */
    readonly hoursPerWeek?: number;
  /** Working days represented by one duration month. Defaults to 20. */
    readonly daysPerMonth?: number;
  /** Maximum digits shown after the decimal separator. Defaults to 1. */
    readonly maximumFractionDigits?: number
}

---

ResolvedDurationSettings

interface ResolvedDurationSettings {
  readonly defaultUnit: DurationUnit | 'auto';
  readonly defaultWorkUnit: DurationUnit | 'auto';
  readonly hoursPerDay: number;
  readonly hoursPerWeek: number;
  readonly daysPerMonth: number;
  readonly maximumFractionDigits: number
}

---

ParsedDuration

interface ParsedDuration {
  readonly value: number;
  readonly unit: DurationUnit;
  readonly elapsed: boolean
}

---

ParseDurationOptions

interface ParseDurationOptions {
  readonly defaultUnit?: DurationUnit;
  readonly allowElapsed?: boolean
}

---

FormatDurationValueOptions

interface FormatDurationValueOptions {
  readonly elapsed?: boolean;
  /** Maximum digits shown after the decimal separator. Defaults to 1. */
    readonly maximumFractionDigits?: number
}

---

FormatWorkingDurationOptions (Extended from duration.ts)

interface FormatWorkingDurationOptions {
  readonly unit?: DurationUnit
}

---

parseIsoDate

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

export function parseIsoDate(date: string): Date;

---

parseIsoDateOnly

Parses the YYYY-MM-DD prefix of a date or datetime at UTC midnight.

export function parseIsoDateOnly(value: string): Date;

---

isIsoDateTimeInput

export function isIsoDateTimeInput(value: string): boolean;

---

getIsoWeekdayUtc

export function getIsoWeekdayUtc(date: Date): number;

---

getUtcWeekday

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

---

getIsoWeekday

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

---

isValidIsoWeekday

export function isValidIsoWeekday(value: number): boolean;

---

formatIsoDate

export function formatIsoDate(date: Date): ISODateString;

---

formatLocalIsoDate

Serializes the local calendar fields of a valid Date as YYYY-MM-DD.

export function formatLocalIsoDate(value: Date): ISODateString;

---

toLocalIsoDate

Returns local calendar fields as YYYY-MM-DD, or null for a missing/invalid date.

export function toLocalIsoDate(value: Date | undefined): ISODateString | null;

---

formatIsoDateTime

export function formatIsoDateTime(date: Date): ISODateTimeString;

---

isValidIsoDate

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

---

isValidIsoDateTime

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().

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

---

normalizeIsoDate

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

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.

export function parseDateTime(value: string): Date;

---

toISODate

export function toISODate(date: Date): ISODateString;

---

toIsoDate

export function toIsoDate(date: Date): ISODateString;

---

ISODateString

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

---

ISODateTimeString

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

---

ISO_DATE_ONLY_PATTERN

ISO_DATE_ONLY_PATTERN: RegExp;

---

ISO_DATE_PATTERN

ISO_DATE_PATTERN: RegExp;

---

ISO_DATE_PREFIX_PATTERN

ISO_DATE_PREFIX_PATTERN: RegExp;

---

ISO_DATETIME_PATTERN

ISO_DATETIME_PATTERN: RegExp;

---

ISO_DATETIME_INPUT_PATTERN

ISO_DATETIME_INPUT_PATTERN: RegExp;

---

ISO_LOCAL_DATETIME_INPUT_PATTERN

ISO_LOCAL_DATETIME_INPUT_PATTERN: RegExp;

---

ISO_UTC_DATETIME_WITHOUT_ZONE_PATTERN

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.

export function parseTimeOfDay(value: string, options:;

---

formatTimeOfDay

export function formatTimeOfDay(totalMinutes: number): string;

---

formatCompactTimeOfDay

export function formatCompactTimeOfDay(totalMinutes: number): string;

---

formatAmPmTimeOfDay

export function formatAmPmTimeOfDay(totalMinutes: number): string;

---

formatDisplayTimeOfDay

export function formatDisplayTimeOfDay(
  totalMinutes: number,
  options:;

---

formatDurationMinutes

export function formatDurationMinutes(totalMinutes: number): string;

---

formatDuration

export function formatDuration(
  duration: number | undefined | null,
  options:;

---

hasAmPmMarker

export function hasAmPmMarker(value: string): boolean;

---

getDateMinutes

export function getDateMinutes(date: Date): number;

---

createDateTime

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

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

---

createDateTimeFromTimeOfDay

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.

export function getLocalDateTimeAsUtcIsoDateTime(date: Date): ISODateTimeString;

---

shiftDateTime

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

---

getDateTimeDurationMinutes

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

---

getDurationMinutes

export function getDurationMinutes(event:;

---

getClampedDateTimeDurationMinutes

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

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

---

snapMinutes

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

---

snapDateTime

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

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

---

normalizeTimelineWeekStartsOn

export function normalizeTimelineWeekStartsOn(value: unknown): TimelineWeekStartsOn;

---

startOfTimelineWeek

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

---

parseTimelineDateValue

Parses a timeline boundary as UTC for deterministic scale math.

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.

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.

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.

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

---

getTimelineQuarter

export function getTimelineQuarter(date: string): number;

---

formatTimelineDateLabel

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

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

---

startOfHour

export function startOfHour(date: string): ISODateTimeString;

---

startOfMinute

export function startOfMinute(date: string): ISODateTimeString;

---

TimelineUnit

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

---

TimelineWeekStartsOn

export type TimelineWeekStartsOn = 0 | 1;

---

isWorkingDate

Checks a date against calendar working weekdays and holiday exclusions.

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.

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

---

moveToNextWorkingDateTime

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.

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

---

addWorkingDays

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

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

---

subtractWorkingDays

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

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

---

offsetByLagCalendar

Applies dependency lag using either calendar days or working days.

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.

export function resolveTaskEndDate(
  startDate: ISODateString,
  duration: 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.

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

---

countWorkingDaysInclusive

Counts working dates inclusively between start and end.

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

---

countWorkingDuration

export function countWorkingDuration(
  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.

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

---

WorkingTimeRange

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

---

WorkingCalendar

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

---

WorkingDayOptions

interface WorkingDayOptions {
  readonly excludeHolidaysFromDuration: boolean
}

---

LagCalendarOptions

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