natural-time-js
Version:
Natural time is a fresh, elegant, and coherent way of measuring the movements of time here on the Earth. This new time standard is based on common sense and the observation of natural cycles. Learn more: https://naturaltime.app. This JavaScript Class tran
105 lines (104 loc) • 3.24 kB
TypeScript
/**
* @module natural-time-js/celestial
* @description The cosmic heartbeat of natural time - precise astronomical calculations that connect us to the rhythms of sun and moon.
*
* While artificial time ignores the sky, natural time is anchored to celestial reality.
* This module provides the astronomical foundation that makes natural time truly natural:
* - Exact solar positions throughout the day
* - Precise lunar phases and cycles
* - Solstice and equinox calculations
* - Location-aware sunrise, sunset, moonrise and moonset times
*/
import { NaturalDate } from '../core/NaturalDate';
/**
* Hemisphere identifiers for geographical calculations.
*/
export declare enum HEMISPHERES {
/** Northern hemisphere (latitude >= 0) */
NORTH = "NORTH",
/** Southern hemisphere (latitude < 0) */
SOUTH = "SOUTH"
}
/**
* Day numbers marking the start and end of summer season.
*/
export declare const SEASONS: {
/** Day 91 (typically April 1st) - Start of summer in Northern hemisphere */
readonly SUMMER_START_DAY: 91;
/** Day 273 (typically September 30th) - End of summer in Northern hemisphere */
readonly SUMMER_END_DAY: 273;
};
/**
* Solar altitude thresholds in degrees for different daylight conditions.
*/
export declare const ANGLES: {
/** Altitude below which astronomical night begins (-12°) */
readonly NIGHT_ALTITUDE: -12;
/** Altitude below which golden hour lighting occurs (6°) */
readonly GOLDEN_HOUR_ALTITUDE: 6;
};
/**
* Interface for sun altitude information
*/
interface SunAltitude {
altitude: number;
highestAltitude: number;
}
/**
* Interface for sun events
*/
interface SunEvents {
sunrise: number;
sunset: number;
nightStart: number;
nightEnd: number;
morningGoldenHour: number;
eveningGoldenHour: number;
}
/**
* Interface for moon position information
*/
interface MoonPosition {
altitude: number;
phase: number;
illumination: number;
}
/**
* Interface for moon events
*/
interface MoonEvents {
moonrise: number;
moonset: number;
highestAltitude: number;
}
/**
* Interface for mustaches range information
*/
interface MustachesRange {
winterSunrise: number;
winterSunset: number;
summerSunrise: number;
summerSunset: number;
averageMustacheAngle: number;
}
/**
* Calculates the sun's altitude at a specific natural time and location.
*/
export declare function NaturalSunAltitude(naturalDate: NaturalDate, latitude: number): SunAltitude;
/**
* Calculates sun events for a specific natural date and location.
*/
export declare function NaturalSunEvents(naturalDate: NaturalDate, latitude: number): SunEvents;
/**
* Calculates the moon's position and phase.
*/
export declare function NaturalMoonPosition(naturalDate: NaturalDate, latitude: number): MoonPosition;
/**
* Calculates moon events for a specific natural date and location.
*/
export declare function NaturalMoonEvents(naturalDate: NaturalDate, latitude: number): MoonEvents;
/**
* Calculates the range of sun positions between winter and summer solstices (average mustaches angle)
*/
export declare function MustachesRange(naturalDate: NaturalDate, latitude: number): MustachesRange;
export {};