dsh-plugin-show-me-data 0.1.0

package/src/core/time/range.js

@@ -0,0 +1,242 @@
+/**
+ * Calendar helpers and range resolution — pure, no system time
+ * (docs/03 §1.6, docs/07 T1.1).
+ *
+ * Every function takes the reference "today" as an argument. The Clock port
+ * supplies it at the edges; nothing here reads the clock or the host timezone.
+ *
+ * @module core/time/range
+ */
+
+/** Range presets offered by the panel. */
+export const RANGE_PRESETS = ['1M', '3M', '6M', 'YTD', '1Y', '3Y', '5Y', 'MAX', 'CUSTOM']
+
+/** Milliseconds in one day, for date-only arithmetic on UTC midnights. */
+const DAY_MS = 86400000
+
+/** Days per month, indexed by month number (0-based). */
+const MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31]
+
+/**
+ * Parse a 'YYYY-MM-DD' string into its numeric parts.
+ *
+ * @param {string} date - calendar date.
+ * @returns {{ y: number, m: number, d: number }} parts (month 1-based).
+ */
+export function parseDate(date) {
+  const y = Number(date.slice(0, 4))
+  const m = Number(date.slice(5, 7))
+  const d = Number(date.slice(8, 10))
+  return { y, m, d }
+}
+
+/**
+ * Format numeric parts back into 'YYYY-MM-DD'.
+ *
+ * @param {number} y - year.
+ * @param {number} m - month (1-based).
+ * @param {number} d - day.
+ * @returns {string} calendar date.
+ */
+export function formatDate(y, m, d) {
+  return `${String(y).padStart(4, '0')}-${String(m).padStart(2, '0')}-${String(d).padStart(2, '0')}`
+}
+
+/**
+ * Normalize out-of-range month/day parts into a real calendar date, using the
+ * 'Date' object purely as a proleptic-Gregorian calculator over UTC fields.
+ * This reads no clock (the epoch value is a constant), which the layering test
+ * enforces by forbidding bare 'new Date()' / 'Date.now()' in 'core/'.
+ *
+ * @param {number} y - year.
+ * @param {number} m - month (1-based, may overflow).
+ * @param {number} d - day of month (may overflow).
+ * @returns {string} normalized 'YYYY-MM-DD'.
+ */
+function normalizeDate(y, m, d) {
+  const at = new Date(0)
+  at.setUTCFullYear(y, m - 1, d)
+  return formatDate(at.getUTCFullYear(), at.getUTCMonth() + 1, at.getUTCDate())
+}
+
+/**
+ * Whether a year is a leap year.
+ *
+ * @param {number} y - year.
+ * @returns {boolean} leap-year flag.
+ */
+export function isLeapYear(y) {
+  return (y % 4 === 0 && y % 100 !== 0) || y % 400 === 0
+}
+
+/**
+ * Number of days in a month.
+ *
+ * @param {number} y - year.
+ * @param {number} m - month (1-based).
+ * @returns {number} day count.
+ */
+export function daysInMonth(y, m) {
+  if (m === 2 && isLeapYear(y)) return 29
+  return MONTH_DAYS[m - 1]
+}
+
+/**
+ * Clamp a day to the last valid day of its month, so '2026-02-31' becomes
+ * '2026-02-28' rather than rolling into March (docs/07 T1.1: pick one
+ * convention; this is the frozen one).
+ *
+ * @param {number} y - year.
+ * @param {number} m - month (1-based).
+ * @param {number} d - day of month.
+ * @returns {string} valid calendar date.
+ */
+export function clampDay(y, m, d) {
+  const limit = daysInMonth(y, m)
+  return formatDate(y, m, Math.min(Math.max(d, 1), limit))
+}
+
+/**
+ * Add whole months to a calendar date, clamping the day.
+ *
+ * @param {string} date - base date 'YYYY-MM-DD'.
+ * @param {number} months - signed month delta.
+ * @returns {string} resulting date.
+ */
+export function addMonths(date, months) {
+  const { y, m, d } = parseDate(date)
+  const total = (y * 12 + (m - 1)) + months
+  const ny = Math.floor(total / 12)
+  const nm = (total % 12 + 12) % 12 + 1
+  return clampDay(ny, nm, d)
+}
+
+/**
+ * Add whole days to a calendar date.
+ *
+ * @param {string} date - base date 'YYYY-MM-DD'.
+ * @param {number} days - signed day delta.
+ * @returns {string} resulting date.
+ */
+export function addDays(date, days) {
+  const { y, m, d } = parseDate(date)
+  return normalizeDate(y, m, d + days)
+}
+
+/**
+ * Whole days from 'a' to 'b' (negative when 'b' precedes 'a').
+ *
+ * @param {string} a - start date.
+ * @param {string} b - end date.
+ * @returns {number} day difference.
+ */
+export function daysBetween(a, b) {
+  const pa = parseDate(a)
+  const pb = parseDate(b)
+  const from = Date.UTC(pa.y, pa.m - 1, pa.d)
+  const to = Date.UTC(pb.y, pb.m - 1, pb.d)
+  return Math.round((to - from) / DAY_MS)
+}
+
+/**
+ * Whole months from 'a' to 'b' (calendar-month difference).
+ *
+ * @param {string} a - start date.
+ * @param {string} b - end date.
+ * @returns {number} month difference.
+ */
+export function monthsBetween(a, b) {
+  const pa = parseDate(a)
+  const pb = parseDate(b)
+  return (pb.y * 12 + pb.m) - (pa.y * 12 + pa.m)
+}
+
+/**
+ * Resolve a range preset into a concrete 'Range'.
+ *
+ * Conventions frozen by tests:
+ * - '1M'/'3M'/'6M'/'1Y'/'3Y'/'5Y' subtract whole months and clamp the day
+ *   ('1M' from '2026-03-31' → '2026-02-28').
+ * - 'YTD' starts at January 1st of the reference year.
+ * - 'MAX' and 'CUSTOM' are not resolvable from a preset alone: 'MAX' returns a
+ *   sentinel 'from' far in the past, 'CUSTOM' requires explicit bounds.
+ *
+ * @param {'1M'|'3M'|'6M'|'YTD'|'1Y'|'3Y'|'5Y'|'MAX'|'CUSTOM'} preset - preset id.
+ * @param {string} today - reference calendar date.
+ * @param {{ from?: string, to?: string }} [custom] - explicit bounds for 'CUSTOM'.
+ * @returns {{ preset: string, from: string, to: string }} resolved range.
+ */
+export function resolveRange(preset, today, custom = {}) {
+  if (!RANGE_PRESETS.includes(preset)) {
+    throw new RangeError(`unknown range preset: ${JSON.stringify(preset)}`)
+  }
+  if (preset === 'CUSTOM') {
+    const { from, to } = custom
+    if (typeof from !== 'string' || typeof to !== 'string') {
+      throw new RangeError('CUSTOM range requires both `from` and `to`')
+    }
+    if (from > to) throw new RangeError(`CUSTOM range is inverted: from ${from} > to ${to}`)
+    return { preset, from, to }
+  }
+  if (preset === 'MAX') return { preset, from: '1900-01-01', to: today }
+  if (preset === 'YTD') {
+    const { y } = parseDate(today)
+    return { preset, from: formatDate(y, 1, 1), to: today }
+  }
+  const months = { '1M': 1, '3M': 3, '6M': 6, '1Y': 12, '3Y': 36, '5Y': 60 }[preset]
+  return { preset, from: addMonths(today, -months), to: today }
+}
+
+/**
+ * Whether a calendar date falls inside a closed range.
+ *
+ * @param {string} date - candidate date.
+ * @param {{ from: string, to: string }} range - closed bounds.
+ * @returns {boolean} membership.
+ */
+export function inRange(date, range) {
+  return date >= range.from && date <= range.to
+}
+
+/**
+ * Keep only the points inside a closed range (docs/07 T1.2).
+ *
+ * @param {Array<{ t: string, v: number }>} points - ascending points.
+ * @param {{ from: string, to: string }} range - closed bounds.
+ * @returns {Array<{ t: string, v: number }>} filtered points.
+ */
+export function filterRange(points, range) {
+  return points.filter((point) => inRange(point.t, range))
+}
+
+/**
+ * The window length in months for a preset, used for comparison ranges.
+ *
+ * @param {string} preset - range preset.
+ * @returns {number} months, or '0' for 'MAX'/'CUSTOM'.
+ */
+export function presetMonths(preset) {
+  return { '1M': 1, '3M': 3, '6M': 6, 'YTD': 12, '1Y': 12, '3Y': 36, '5Y': 60 }[preset] ?? 0
+}
+
+/**
+ * The previous comparable window, used for "vs previous period" comparisons.
+ *
+ * @param {{ preset: string, from: string, to: string }} range - current range.
+ * @returns {{ from: string, to: string }} previous window (same length, ending the day before 'from').
+ */
+export function previousRange(range) {
+  if (range.preset === 'MAX' || range.preset === 'CUSTOM') {
+    const span = daysBetween(range.from, range.to)
+    const to = addDays(range.from, -1)
+    return { from: addDays(to, -span), to }
+  }
+  const to = addDays(range.from, -1)
+  if (range.preset === 'YTD') {
+    // "Year to date" compares against the same calendar window one year
+    // earlier (2026-01-01…2026-09-11 → 2025-01-01…2025-09-11).
+    return { from: addMonths(range.from, -12), to: addMonths(range.to, -12) }
+  }
+  const months = presetMonths(range.preset)
+  return { from: addMonths(to, -months), to }
+}