🌐 Overview

Standard time (Clock Time) is a political construct designed for social coordination. However, the physical sun position—the True Solar Time—depends precisely on your geographic longitude and the Earth's orbital variance.

@openfate/true-solar-time implements the rigorous Jean Meeus Astronomical Algorithms to calculate the physical apparent solar time with second-level precision, bridging the gap between political and physical time.

🚀 Key Capabilities

• 🔭 High-Precision Engine – Based on Jean Meeus - Astronomical Algorithms for sub-minute accuracy.
• 🌍 World-Class Timezone Resolution – Native IANA timezone support. Correctly handles Daylight Saving Time (DST) gaps, overlaps, and historical shifts.
• 📐 Dual Engine Design – Toggle between the rigorous meeus engine (accuracy) and the approx engine (performance).
• 🛡️ Robust & Verified – Over 20+ regression tests covering international date lines, century epochs, and complex timezone transitions.

📦 Installation

npm install @openfate/true-solar-time

📖 Usage Guide

A. Calculating from local wall-clock time

Use this if you have a local time and timezone (e.g., from a user input form).

import { calculateTrueSolarTime } from '@openfate/true-solar-time';

const result = calculateTrueSolarTime({
    year: 2024, month: 7, day: 1, hour: 12, minute: 0,
    timeZoneId: 'America/New_York'
}, {
    longitude: -74.006, // New York
    algorithm: 'meeus'
});

console.log(`Physically, the time is: ${result.trueSolarTime}`); // e.g., "11:43:22"

B. Calculating from a UTC Instant

Use this if you have an absolute Date object or a Unix timestamp.

import { getTrueSolarTimeFromInstant } from '@openfate/true-solar-time';

const result = getTrueSolarTimeFromInstant({
    date: new Date(),
    timeZoneId: 'Asia/Shanghai'
}, { longitude: 121.47 });

🛠️ API Reference

calculateTrueSolarTime(input, options)

The primary entry point. Resolves a civil (local) time to a true solar moment.

| Input Field | Type | Description | | :--- | :--- | :--- | | year, month, day | number | The calendar date. | | hour, minute | number | The wall-clock time. | | timeZoneId | string | IANA Timezone (e.g., Asia/Tokyo). | | timeZoneOffset | number? | Semi-fixed numeric offset in hours (optional). |

| Options | Type | Description | | :--- | :--- | :--- | | longitude | number | Precise longitude (East positive, West negative). | | algorithm | string | 'meeus' (default) or 'approx'. |

resolveCivilTime(input)

Low-level timezone resolver. Converts ambiguous local times (overlaps/gaps) into deterministic UTC instants.

🧪 Physics & Core Logic

The engine computes True Solar Time (真太阳时) using the following formula:

True Solar Time = Civil Time + Longitude Correction + Equation of Time (EoT) - DST

1. Longitude Correction: Corrects the ~4 minute difference per 1° away from the timezone's standard meridian.
2. Equation of Time (EoT): Corrects for the tilt of Earth's axis and its elliptical orbit around the sun.

🗺️ City Reference

| City | Longitude | Common Timezone | | :--- | :--- | :--- | | Beijing | 116.40 | UTC+8 | | Shanghai | 121.47 | UTC+8 | | London | 0.12 | UTC+0 | | New York | -74.00 | UTC-5 | | Tokyo | 139.69 | UTC+9 |

🔧 Development

npm test          # Run the 20+ regression test suite
npm run build     # Generate distribution files

📜 License

MIT — Engineered by OpenFate Engineering