hooks/useHeatstrokeMonitor.ts

Purpose

This module provides real-time and background heatstroke risk monitoring with automated alerting based on a temperature-derived risk score.

It is responsible for:

• detecting elevated heatstroke risk conditions
• enforcing cooldown-based alert throttling
• triggering user notifications when risk thresholds are exceeded
• supporting both React lifecycle and background execution contexts

The alerting system is built around a configurable risk threshold and time-based rate limiting to prevent notification spam.

Architecture Overview

The module exposes two monitoring strategies:

Both share the same core logic:

• risk threshold check
• cooldown enforcement
• alert dispatch via notification service

Core Constants

Risk Threshold

const WATCH_MIN = 38.0;
const RISK_TEMP_TRESHOLD = WATCH_MIN;

Represents the minimum risk score required to trigger an alert.

Meaning

If:

riskScore >= 38.0

then the system enters alert evaluation mode.

Alert Cooldown

const ALERT_COOLDOWN_MS = 5 * 60 * 1000;

Value

Logger

makeLogger("useHeatstrokeMonitor.ts")

Used for structured diagnostics and execution tracing.

Invariants

The module maintains the following invariants.

1. Alerts Only Trigger Above Threshold

No alert is ever sent unless:

riskScore >= 38.0

This ensures:

• no false positives
• stable baseline behavior
• predictable notification triggers

2. Alerts Are Rate-Limited

Both foreground and background flows enforce:

at least 5 minutes between alerts

This prevents:

• notification spam
• battery drain
• redundant alert flooding

3. Foreground and Background Maintain Separate State

Foreground State

lastAlertTime (useRef)

Background State

backgroundLastAlertTime (module-level variable)

This separation ensures:

• UI lifecycle isolation
• background independence
• no cross-instance interference

4. Side Effects Only Trigger on Valid Risk State

Alerts are only triggered when:

• threshold is exceeded
• cooldown has elapsed

Otherwise, execution is a no-op.

5. Alerts Are Idempotent Within Cooldown Window

Repeated evaluations within the cooldown window do not produce additional notifications.

Variants

Execution Context Variants

Foreground Monitoring

useHeatstrokeMonitor(riskScore)

• React hook-based
• uses useEffect
• lifecycle-bound
• per-component state tracking

Background Monitoring

useBackgroundHeatstrokeMonitor(riskScore)

• non-hook function
• global state tracking
• safe for background task loops
• no React dependency

State Variants

Cooldown Active

• alerts suppressed
• only logging occurs

Cooldown Expired

• alert is emitted
• timestamp updated

Exported Functions

useHeatstrokeMonitor(riskScore)

export function useHeatstrokeMonitor(
  riskScore: number
): void

React hook for monitoring heatstroke risk in UI context.

Parameters

Behavior

Triggered on every riskScore change:

1. checks threshold
2. evaluates cooldown
3. sends alert if conditions are met

Internal State

Uses:

useRef<number | null>(null)

to persist cooldown timing across renders without triggering re-renders.

Example Usage

useHeatstrokeMonitor(coreTempRiskScore);

Exported Functions

useBackgroundHeatstrokeMonitor(riskScore)

export function useBackgroundHeatstrokeMonitor(
  riskScore: number
): void

Background-safe heatstroke monitoring function.

Parameters

Behavior

Runs immediately on invocation:

1. evaluates threshold
2. checks global cooldown
3. triggers alert if allowed

State Storage

Uses module-level variable:

let backgroundLastAlertTime: number | null = null;

This ensures persistence across:

• background task invocations
• repeated function calls
• non-React execution cycles

Example Usage

useBackgroundHeatstrokeMonitor(riskScore);

Notification System

Alerts are dispatched via:

sendHeatstrokeAlert(riskScore)

Responsibility

• deliver user-facing heatstroke warning
• include risk score context
• trigger device notification system

Logging Behavior

The module logs:

Below threshold

Not within the risk threshold

Alert triggered

Within the risk threshold, sending alert

Logging is handled through:

makeLogger(...)

Timing Behavior

Threshold Evaluation

riskScore >= 38.0

Cooldown Logic

now - lastAlertTime > 5 minutes

or:

lastAlertTime === null

Lifecycle Behavior

Foreground Hook

Mount

• initializes useRef

Update

• evaluates risk score changes

Unmount

• ref is discarded (no cleanup required)

Background Function

• no lifecycle tracking
• relies entirely on module state
• persists across calls

Concurrency Notes

Foreground

Each hook instance maintains independent cooldown state.

Multiple components may therefore:

• trigger independent alerts
• respect per-component cooldowns

Background

All calls share a single global cooldown tracker:

backgroundLastAlertTime

This ensures:

• cross-task throttling
• system-wide alert suppression

Safety Considerations

The system is intentionally conservative:

• high threshold (38.0)
• strict cooldown (5 minutes)
• single-alert-per-window behavior

This reduces:

• alert fatigue
• redundant notifications
• background spam behavior

Example Integration

Foreground

useHeatstrokeMonitor(temperatureRiskScore);

Background

useBackgroundHeatstrokeMonitor(temperatureRiskScore);