Range Manipulation

/**
 * Add (merge) this range with another range if they overlap
 * @param other - Range to merge with
 * @param options - Options for considering adjacent ranges
 * @returns New DateRange spanning both ranges, or null if no overlap
 */
add(other: DateRange, options?: AddOptions): DateRange | null;

interface AddOptions {
  adjacent?: boolean; // Consider adjacent ranges as mergeable
}

const range1 = moment.range('2024-01-01', '2024-01-15');
const range2 = moment.range('2024-01-10', '2024-01-25');

// Merge overlapping ranges
const merged = range1.add(range2);
console.log(merged.toString()); // "2024-01-01T00:00:00Z/2024-01-25T23:59:59Z"

// Try to merge non-overlapping ranges
const range3 = moment.range('2024-01-20', '2024-01-31');
const notMerged = range1.add(range3);
console.log(notMerged); // null

// Merge adjacent ranges
const range4 = moment.range('2024-01-16', '2024-01-31');
const adjacentMerged = range1.add(range4, { adjacent: true });
console.log(adjacentMerged.toString()); // "2024-01-01T00:00:00Z/2024-01-31T23:59:59Z"

/**
 * Subtract another range from this range
 * @param other - Range to subtract
 * @returns Array of remaining DateRange objects (0-2 ranges)
 */
subtract(other: DateRange): DateRange[];

const range = moment.range('2024-01-01', '2024-01-31');

// Subtract from middle (splits range)
const middle = moment.range('2024-01-10', '2024-01-20');
const split = range.subtract(middle);
console.log(split.length); // 2
console.log(split[0].toString()); // "2024-01-01T00:00:00Z/2024-01-10T00:00:00Z"
console.log(split[1].toString()); // "2024-01-20T00:00:00Z/2024-01-31T23:59:59Z"

// Subtract from beginning
const beginning = moment.range('2024-01-01', '2024-01-10');
const fromStart = range.subtract(beginning);
console.log(fromStart.length); // 1
console.log(fromStart[0].toString()); // "2024-01-10T00:00:00Z/2024-01-31T23:59:59Z"

// Subtract entire range
const entire = range.subtract(range);
console.log(entire.length); // 0 (empty array)

// Subtract non-overlapping range
const noOverlap = moment.range('2024-02-01', '2024-02-28');
const unchanged = range.subtract(noOverlap);
console.log(unchanged.length); // 1 (original range unchanged)

/**
 * Create a deep copy of this range
 * @returns New DateRange instance with cloned start and end moments
 */
clone(): DateRange;

const original = moment.range('2024-01-01', '2024-01-31');
const copy = original.clone();

// Modify copy without affecting original
copy.start.add(1, 'day');
console.log(original.start.format('YYYY-MM-DD')); // "2024-01-01" (unchanged)
console.log(copy.start.format('YYYY-MM-DD'));     // "2024-01-02" (modified)

/**
 * Snap range boundaries to the boundaries of a time interval
 * @param interval - Time unit to snap to (year, month, day, etc.)
 * @returns New DateRange with snapped boundaries
 */
snapTo(interval: IntervalUnit): DateRange;

type IntervalUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';

// Snap to day boundaries
const range = moment.range('2024-01-15T14:30:00', '2024-01-20T09:45:00');
const daySnapped = range.snapTo('day');
console.log(daySnapped.start.format()); // "2024-01-15T00:00:00Z"
console.log(daySnapped.end.format());   // "2024-01-20T23:59:59Z"

// Snap to month boundaries
const monthSnapped = range.snapTo('month');
console.log(monthSnapped.start.format()); // "2024-01-01T00:00:00Z"
console.log(monthSnapped.end.format());   // "2024-01-31T23:59:59Z"

// Open-ended ranges are not snapped
const openRange = moment.range(null, '2024-01-15T14:30:00');
const openSnapped = openRange.snapTo('day');
console.log(openSnapped.start.valueOf()); // -8640000000000000 (unchanged)
console.log(openSnapped.end.format());    // "2024-01-15T23:59:59Z" (snapped)

/**
 * Get the center moment of this range
 * @returns Moment representing the midpoint of the range
 */
center(): Moment;

const range = moment.range('2024-01-01', '2024-01-31');
const centerPoint = range.center();
console.log(centerPoint.format('YYYY-MM-DD')); // "2024-01-16"

// Works with time ranges too
const timeRange = moment.range('2024-01-01T00:00:00', '2024-01-01T12:00:00');
const timeCenter = timeRange.center();
console.log(timeCenter.format('HH:mm')); // "06:00"

/**
 * Get the difference between end and start in specified units
 * @param unit - Unit to measure difference in (optional)
 * @param precise - Whether to use precise calculation (optional)
 * @returns Numeric difference
 */
diff(unit?: string, precise?: boolean): number;

/**
 * Alias for diff method
 * @param unit - Unit to measure duration in (optional)
 * @param precise - Whether to use precise calculation (optional)
 * @returns Numeric duration
 */
duration(unit?: string, precise?: boolean): number;

/**
 * Get the duration in milliseconds
 * @returns Duration in milliseconds
 */
valueOf(): number;

const range = moment.range('2024-01-01', '2024-01-31');

// Get difference in various units
console.log(range.diff('days'));    // 30
console.log(range.diff('weeks'));   // 4
console.log(range.diff('months'));  // 1

// Duration is an alias for diff
console.log(range.duration('days')); // 30

// Get milliseconds
console.log(range.valueOf()); // 2678400000 (30 days in ms)

// Precise calculations
const preciseRange = moment.range('2024-01-01', '2024-01-01T12:00:00');
console.log(preciseRange.diff('days', true)); // 0.5

/**
 * Convert range to ISO 8601 interval string
 * @returns String in format "start/end"
 */
toString(): string;

/**
 * Convert range to array of native Date objects
 * @returns Array containing [startDate, endDate]
 */
toDate(): [Date, Date];

const range = moment.range('2024-01-01', '2024-01-31');

// Convert to ISO string
console.log(range.toString()); // "2024-01-01T00:00:00Z/2024-01-31T23:59:59Z"

// Convert to native Date objects
const [startDate, endDate] = range.toDate();
console.log(startDate instanceof Date); // true
console.log(endDate instanceof Date);   // true

interface AddOptions {
  adjacent?: boolean;
}

type IntervalUnit = 'year' | 'quarter' | 'month' | 'week' | 'day' | 'hour' | 'minute' | 'second';