Configurable history window for forecast and actuals (Closes Issue #655)

[vedantvakharia]

Summary

This PR implements a configurable history window for both nowcasting-app and quartz-app, allowing users to control how far back in time the UI fetches forecast and actual data. This implementation addresses the issue completely for both apps and fixes all the mistakes from previous attempts. This PR supersedes #657, #659, and #660, consolidating the logic into a robust solution with full test coverage and environment validation.

Overview

Previously, the apps used hardcoded values to fetch the last 48 hours of data. This PR makes the history window configurable via environment variables, supporting two modes:

1. Rolling (default): N hours back from current time
2. Fixed: Midnight UTC N days ago

Implementation

Environment Variables

Both apps now support:

# Mode: "rolling" or "fixed"
NEXT_PUBLIC_HISTORY_START_MODE=rolling

# Offset in hours (default: 48)
# Examples: 48 = 2 days, 72 = 3 days
NEXT_PUBLIC_HISTORY_OFFSET_HOURS=48

Nowcasting App

Modified Files:

• components/helpers/data.ts

  • Added getHistoryStartMode() - validates and returns mode from environment
  • Added getHistoryOffsetHours() - validates and returns offset hours
  • Modified getEarliestForecastTimestamp() - now uses configurable modes
  • Preserves existing 6-hour rounding behavior for rolling mode

• components/helpers/historyConfig.test.ts (NEW)

  • Comprehensive test suite covering mode validation, offset validation, and timestamp calculations

• .env.example

  • Added configuration documentation

Quartz App

Modified Files:

• src/helpers/historyWindow.ts (NEW)

  • New helper module with configurable history window functions
  • Simpler implementation (no 6-hour rounding)

• src/data/queries.ts

  • Updated getGenerationQuery() to include start_datetime_utc parameter
  • Updated getForecastQuery() to include start_datetime_utc parameter
  • Uses as any type assertion for API parameter (schema doesn't define it yet)

• src/helpers/historyWindow.test.ts (NEW)

  • Test suite for history window helpers

• .env.example (NEW)

  • Added configuration documentation

Improvements

This PR addresses several limitations identified in previous iterations:

• Full Configuration: Replaces hardcoded values with validated environment variables.
• Correct Logic: Ensures "Fixed" and "Rolling" modes function correctly without early return issues.
• Scope: Applied consistently across both nowcasting-app and quartz-app (forecasts and actuals).
• Reliability: Added as any type assertions where API types were missing start_datetime_utc, and added full unit test suites.

Testing

What I Verified

1. TypeScript compilation succeeds
2. Prettier formatting passes for modified files
3. Helper functions return correct values
4. Environment variables are properly validated
5. Default values work (maintains backward compatibility)

For Maintainers to Verify

As I do not have Auth0 credentials or live API access, please verify:

1. API integration works with start_datetime_utc parameter
2. Data displays correctly in both apps
3. Rolling mode (default 48h) behaves as expected
4. Rolling mode with custom offset (e.g., 72h) works
5. Fixed mode returns midnight UTC timestamps
6. 6-hour rounding works correctly in nowcasting-app rolling mode

Type Safety Notes

The TypeScript warnings about start_datetime_utc not existing in the query types are expected. The API accepts this parameter (as evidenced by previous PR attempts and API schema comments), but the TypeScript types haven't been regenerated to include it. Using as any is a pragmatic solution until the types are updated.

Note on Build Failures

I noticed the repository contains some existing formatting inconsistencies (CRLF vs LF) in unrelated files. I have ensured my changes are properly formatted (verified via yarn lint --fix on modified files), but the build system might flag pre-existing linting issues in other parts of the codebase.

[vercel]

@vedantvakharia is attempting to deploy a commit to the Open Climate Fix Team on Vercel.

A member of the Team first needs to authorize it.

[vedantvakharia]

CI Notes

The CI failures are from pre-existing infrastructure issues, not this feature implementation. I've created separate PRs to fix both:

• Prettier/CRLF errors: Fixed in Fix: Normalize All Line Endings to LF (CRLF → LF Conversion) #671 (normalize line endings to LF)
• Cypress configuration: Fixed in Fix Cypress Cloud Recording Configuration #672 (fix Cypress Cloud Recording Configuration)

My feature changes are properly tested and isolated. Once #671 and #672 are merged, CI will pass for this PR as well.