Skip to content

Open-source personal finance manager. Self-hosted, privacy-first.

7.0 KB
Raw Blame
/**
 * Period window math for the Reports date range selector.
 *
 * Presets (6M, YTD, 1Y, ...) and the custom range are normally anchored to
 * today: the API derives the start from `months` / `period` / `days` (or the
 * page sends the picked custom dates). Period navigation (issue #519) steps
 * the same window back by its own length: the window keeps its shape and every
 * date inside it moves back together. Shifted windows are sent to the API as
 * explicit `start_date` / `end_date`.
 */

import { monthRange, shiftMonth } from './month-utils'

/** Explicit report window as timezone-naive `YYYY-MM-DD` strings. */
export interface PeriodWindow {
  from: string
  to: string
}

/** The five shapes a range preset can have. */
export type PeriodPreset =
  | { kind: 'month'; anchorDelta: number } // This Month (0) / Last Month (-1)
  | { kind: 'ytd'; fyStartMonth?: number } // YTD, start of the financial year (1 = January)
  | { kind: 'rolling'; months: number } // 6M / 1Y / 2Y ...
  | { kind: 'days'; days: number } // 30D rolling window
  | { kind: 'custom' } // user-picked from/to

function parseIso(iso: string): { y: number; m: number; d: number } {
  const [y, m, d] = iso.split('-').map(Number)
  return { y, m, d }
}

function iso(y: number, m: number, d: number): string {
  return `${y}-${String(m).padStart(2, '0')}-${String(d).padStart(2, '0')}`
}

/** Shift a date by whole days (calendar math, DST safe). */
export function addDaysIso(isoDate: string, delta: number): string {
  const { y, m, d } = parseIso(isoDate)
  const t = new Date(y, m - 1, d + delta)
  return iso(t.getFullYear(), t.getMonth() + 1, t.getDate())
}

/** Shift a date by whole months, clamping the day to the target month's end. */
export function addMonthsIso(isoDate: string, delta: number): string {
  const { y, m, d } = parseIso(isoDate)
  const target = new Date(y, m - 1 + delta, 1)
  const lastDay = new Date(target.getFullYear(), target.getMonth() + 1, 0).getDate()
  return iso(target.getFullYear(), target.getMonth() + 1, Math.min(d, lastDay))
}

/** Whole days from `from` to `to` (negative when `to` is earlier). */
export function daysBetween(fromIso: string, toIso: string): number {
  const f = parseIso(fromIso)
  const t = parseIso(toIso)
  return Math.round((Date.UTC(t.y, t.m - 1, t.d) - Date.UTC(f.y, f.m - 1, f.d)) / 86_400_000)
}

/**
 * Start of the rolling window for a `months` preset. Mirrors the backend:
 * first day of the current month, back by `months * 30` days, snapped to the
 * first day of that month (so 6M today means "since the 1st, ~6 months back").
 */
export function rollingStart(today: string, months: number): string {
  const { y, m } = parseIso(today)
  return addDaysIso(iso(y, m, 1), -(months * 30)).slice(0, 8) + '01'
}

/**
 * Whole calendar months a range covers, or null when it does not line up with
 * month boundaries. A range that starts on the 1st and ends on a month's last
 * day has an exact width in months; the day-based estimate below does not,
 * because a calendar year is 364 or 365 days and rounds up to thirteen.
 */
export function alignedSpanMonths(window: PeriodWindow): number | null {
  const s = parseIso(window.from)
  const t = parseIso(window.to)
  if (s.d !== 1) return null
  if (t.d !== new Date(t.y, t.m, 0).getDate()) return null
  return (t.y - s.y) * 12 + (t.m - s.m) + 1
}

/**
 * Window width in months: ceil of the span in days / 30, clamped to 1..24.
 * Same rule the page uses when it sends a custom range, so shifted windows
 * keep the `months` parameter the API expects.
 */
export function windowMonths(window: PeriodWindow): number {
  return Math.max(1, Math.min(24, Math.ceil(daysBetween(window.from, window.to) / 30)))
}

/**
 * Explicit window for a preset at a period offset.
 *
 * - Month presets (This Month / Last Month) always return dates: the API has
 *   no equivalent preset. `This Month` at offset 0 ends on `today`; every
 *   other combination is a full calendar month.
 * - `ytd` at offset 0 returns null (the API's `period=ytd` path); other
 *   offsets span whole previous financial years.
 * - `rolling` / `days` at offset 0 return null (the API's `months` / `days`
 *   path); negative offsets step back by whole windows of the same number
 *   of calendar months, each ending the day before the next one starts.
 *
 * `offset` counts periods of the preset (months, financial years, the
 * rolling length or the custom span), not calendar months.
 * - `custom` at offset 0 returns null (the page already sends the picked
 *   dates); negative offsets step the picked range back by its own length,
 *   in whole months when the range covers whole months, otherwise by its
 *   rounded span.
 */
export function periodWindow(
  preset: PeriodPreset,
  today: string,
  offset: number,
  customRange?: PeriodWindow,
): PeriodWindow | null {
  switch (preset.kind) {
    case 'month': {
      const anchor = shiftMonth(today.slice(0, 7), preset.anchorDelta + offset)
      const full = monthRange(anchor)
      if (offset === 0 && preset.anchorDelta === 0) {
        return { from: full.from, to: today }
      }
      return full
    }
    case 'ytd': {
      if (offset === 0) return null
      const fy = preset.fyStartMonth ?? 1
      const t = parseIso(today)
      const startYear = t.y - (t.m < fy ? 1 : 0) + offset
      const from = iso(startYear, fy, 1)
      return { from, to: addDaysIso(addMonthsIso(from, 12), -1) }
    }
    case 'rolling': {
      if (offset === 0) return null
      // The current window runs from the 1st of its first month to today, so
      // it spans whole calendar months. Earlier windows are that many full
      // months each and end the day before the next one starts: no overlap.
      const start = rollingStart(today, preset.months)
      const s = parseIso(start)
      const t = parseIso(today)
      const span = (t.y - s.y) * 12 + (t.m - s.m) + 1
      return {
        from: addMonthsIso(start, span * offset),
        to: addDaysIso(addMonthsIso(start, span * (offset + 1)), -1),
      }
    }
    case 'days': {
      if (offset === 0) return null
      const step = preset.days * offset
      return {
        from: addDaysIso(today, -(preset.days - 1) + step),
        to: addDaysIso(today, step),
      }
    }
    case 'custom': {
      if (offset === 0 || !customRange) return null
      // A range that covers whole months (the year picker sends one, and so
      // does any month-to-month pick) steps by exactly that many months, each
      // window ending the day before the next one starts. Rounding its day
      // span instead would move a year back by thirteen months.
      const aligned = alignedSpanMonths(customRange)
      if (aligned !== null) {
        return {
          from: addMonthsIso(customRange.from, aligned * offset),
          to: addDaysIso(addMonthsIso(customRange.from, aligned * (offset + 1)), -1),
        }
      }
      const spanMonths = Math.max(1, Math.ceil(daysBetween(customRange.from, customRange.to) / 30))
      return {
        from: addMonthsIso(customRange.from, spanMonths * offset),
        to: addMonthsIso(customRange.to, spanMonths * offset),
      }
    }
  }
}