Date Utils

1# shellcheck shell=bash
2# Portable date helpers shared by the daily-recap scripts. Sourced, not executed.
3#
4# Each helper tries GNU date syntax first and falls back to BSD date (macOS), so the
5# scripts behave the same on Linux, macOS, and macOS with GNU coreutils on PATH.
6# Local-time helpers honor the standard TZ environment variable.
7
8# local_to_epoch "YYYY-MM-DD HH:MM:SS" -> epoch seconds, interpreting the input in local time.
9# A time inside a spring-forward gap does not exist on the wall clock. BSD date reads it
10# with the UTC offset in effect before the gap, so 02:30 becomes 03:30 after the change.
11# GNU date rejects it, so the last fallback applies the previous day's offset to match.
12local_to_epoch() {
13  date -d "$1" +%s 2>/dev/null && return
14  date -j -f '%Y-%m-%d %H:%M:%S' "$1" +%s 2>/dev/null && return
15  local offset
16  offset=$(date -d "${1%% *} 12:00:00 yesterday" +%z 2>/dev/null) || return 1
17  date -d "$1 ${offset}" +%s 2>/dev/null
18}
19
20# utc_to_epoch "YYYY-MM-DDTHH:MM:SSZ" -> epoch seconds.
21utc_to_epoch() {
22  date -u -d "$1" +%s 2>/dev/null || date -j -u -f '%Y-%m-%dT%H:%M:%SZ' "$1" +%s 2>/dev/null
23}
24
25# epoch_fmt EPOCH FORMAT -> EPOCH formatted in local time.
26epoch_fmt() {
27  date -d "@$1" "+$2" 2>/dev/null || date -r "$1" "+$2" 2>/dev/null
28}
29
30# epoch_fmt_utc EPOCH FORMAT -> EPOCH formatted in UTC.
31epoch_fmt_utc() {
32  date -u -d "@$1" "+$2" 2>/dev/null || date -u -r "$1" "+$2" 2>/dev/null
33}
34
35# add_days YYYY-MM-DD N -> the date N days later (N may be negative).
36# Anchors on local noon so DST transitions never shift the result across a date line.
37add_days() {
38  local epoch
39  epoch=$(local_to_epoch "$1 12:00:00") || return 1
40  epoch_fmt "$((epoch + $2 * 86400))" '%Y-%m-%d'
41}
42
43# is_valid_date YYYY-MM-DD -> success only for a real calendar date in that exact form.
44# BSD date silently normalizes impossible dates (2026-02-30 becomes 2026-03-02), so the
45# round trip through add_days catches what parsing alone accepts.
46is_valid_date() {
47  [[ "$1" =~ ^[0-9]{4}-[0-9]{2}-[0-9]{2}$ ]] || return 1
48  [[ "$(add_days "$1" 0 2>/dev/null)" == "$1" ]]
49}