Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/V3RNE42/helios/llms.txt

Use this file to discover all available pages before exploring further.

computeRouteSections is the core algorithm of Helios, extracted from the UI layer into routeSolar.js so it can be tested in isolation. It takes all its dependencies as parameters — no DOM, no global state — and returns the sunrise/sunset event array that the UI renders into seat recommendations.

​
Function signature

export async function computeRouteSections({
    start,
    end,
    diasalida,
    diallegada,
    local,
    getDayInfo,
    getOffset
})

​
Parameters

​
start
Object
required
Origin coordinates { lat: number, lon: number }.
​
end
Object
required
Destination coordinates { lat: number, lon: number }.
​
diasalida
Date
required
Departure date/time as a JavaScript Date object.
​
diallegada
Date
required
Arrival date/time as a JavaScript Date object.
​
local
boolean
required
Whether to look up UTC offsets for local-time display. When true, getOffset is called for each section’s coordinates and the result is stored in offset.
​
getDayInfo
Function
required
Injected solar calculator with the signature (date, lat, lon) → { sunrise: { end }, sunset: { start } }. Provides the sunrise and sunset times at any point along the route.
​
getOffset
Function
required
Async injected UTC offset resolver with the signature async (coords) → number. Called only when local is true.

​
Return value

Returns Promise<{ sections: Array, night: Boolean }>.
​
night
boolean
true if the entire journey falls in darkness — the vehicle never experiences daylight between departure and arrival.
​
sections
Array
Ordered array of solar event objects spanning from departure to arrival. Each object in the array has the following shape:
PropertyTypeDescription
event"sunrise" | "sunset"Type of solar event. Absent on the synthetic departure and arrival boundary entries.
dateDateWhen the event occurs (or the departure/arrival time for boundary entries).
coords{ lat, lon }Geographic position of the vehicle at event time.
offsetnumber | nullUTC offset in hours at that position. Populated only when local: true; otherwise null.
ratenumberProgress fraction 0–1 along the journey. 0 for the departure entry, 1 for the arrival entry.

​
Constants

NameValuePurpose
MAX_DIFF2500 msMaximum acceptable convergence error for the iterative solar event search.
MAX_INNER_ITERATIONS100,000Cap on the inner convergence loop; prevents an infinite loop from hanging the browser tab.
MAX_LOOPSDynamicOuter loop cap, computed as limit ** 2 where limit = Math.floor(total_time × 2 / ONE_DAY) and total_time is the trip duration in milliseconds. limit falls back to 2 only when the floor result is 0 (trip shorter than half a day); otherwise the floor result is used as-is.

​
Error conditions

The function throws an Error in three situations:
  1. "El cálculo solar del trayecto no convergió (bucle interno)" — The inner convergence loop exceeded MAX_INNER_ITERATIONS iterations without satisfying the MAX_DIFF threshold. This indicates a degenerate getDayInfo input.
  2. "El cálculo solar del trayecto no convergió" — The outer loop exhausted MAX_LOOPS iterations before the date pointer reached the arrival time. The result would be incomplete and is not returned.
  3. "Ha habido algún error con las fechas!" — Duplicate timestamps were detected in the sections array after the main loop completed. This guards against an inconsistent internal state.
computeRouteSections is fully covered by Vitest tests in routeSolar.test.js. The test suite exercises daytime journeys, overnight journeys, multi-day journeys, and the convergence failure case. No API keys are required to run the tests.

​
Usage example

import { computeRouteSections } from './routeSolar.js';
import sunCalcFactory from './SunCalc_function.js';

const { getDayInfo } = sunCalcFactory();
const fakeOffset = async () => 0; // no timezone adjustment

const { sections, night } = await computeRouteSections({
    start: { lat: 40.4168, lon: -3.7038 },  // Madrid
    end:   { lat: 36.7213, lon: -4.4214 },  // Málaga
    diasalida:  new Date('2026-06-15T09:00:00Z'),
    diallegada: new Date('2026-06-15T15:00:00Z'),
    local: false,
    getDayInfo,
    getOffset: fakeOffset
});

Build docs developers (and LLMs) love

Get started for freeTalk to us