natural-time-js 1.0.5 → 1.1.0

package/context.js

@@ -1,171 +1,320 @@
+/**
+ * @module context
+ * @description Provides astronomical calculations and events for natural time, including sun and moon positions
+ */
+
 import { NaturalDate } from './index.js';
 import { Body, Observer, SearchHourAngle, SearchRiseSet, SearchAltitude, MoonPhase, Equator, Horizon, Seasons } from 'astronomy-engine';
+import { 
+    isValidLatitude, 
+    isValidLongitude, 
+    isValidNaturalDate, 
+    throwValidationError 
+} from './utils/validators.js';
 
-// Caching recuring astronomical calculations
-const ASTRO_CACHE = {};
+/**
+ * Hemisphere identifiers for geographical calculations
+ * @constant
+ * @enum {string}
+ * @readonly
+ */
+export const HEMISPHERES = {
+    NORTH: 'NORTH',
+    SOUTH: 'SOUTH'
+};
 
 /**
- * SUN ALTITUDE
- * 
- * Determine the sun altitude and max altitude from a specific naturalDate at given lat/long coordinates
- * @param {NaturalDate} naturalDate
- * @param {Number} latitude
- * @returns Object { altitude, highestAltitude }
+ * Day numbers marking the start and end of summer season
+ * Day 1 represents January 1st
+ * @constant
+ * @enum {number}
+ * @readonly
  */
-export function NaturalSunAltitude(naturalDate, latitude) {
+export const SEASONS = {
+    /** Day 91 (typically April 1st) */
+    SUMMER_START_DAY: 91,
+    /** Day 273 (typically September 30th) */
+    SUMMER_END_DAY: 273
+};
 
-    let observer = new Observer(latitude, naturalDate.longitude, 0);
-    let date = new Date(naturalDate.unixTime);
+/**
+ * Solar altitude thresholds in degrees for different daylight conditions
+ * @constant
+ * @enum {number}
+ * @readonly
+ */
+export const ANGLES = {
+    NIGHT_ALTITUDE: -12,
+    GOLDEN_HOUR_ALTITUDE: 6
+};
 
-    let sun = Equator(Body.Sun, date, observer, true, false);
-    let sunAltitude =  Math.max(Horizon(date, observer, sun.ra, sun.dec).altitude, 0);
-    let midday = SearchHourAngle(Body.Sun, observer, 0, new Date(naturalDate.nadir));
+// Move cache to its own module for better separation of concerns
+const astroCache = new Map();
 
-    return {
-        altitude: sunAltitude, // Current sun altitude
-        highestAltitude: midday.hor.altitude // Highest altitude of the sun during the day
-    }
-}
+/**
+ * Determines the hemisphere based on latitude
+ * @param {number} latitude - Latitude in degrees (-90 to 90)
+ * @returns {string} HEMISPHERES.NORTH or HEMISPHERES.SOUTH
+ * @private
+ */
+const getHemisphere = (latitude) => latitude >= 0 ? HEMISPHERES.NORTH : HEMISPHERES.SOUTH;
 
+/**
+ * Determines if the given day is in summer season for the specified latitude
+ * @param {number} dayOfYear - Day of the year (1-366)
+ * @param {number} latitude - Latitude in degrees (-90 to 90)
+ * @returns {boolean} True if the day is in summer season
+ * @private
+ */
+const isSummerSeason = (dayOfYear, latitude) => {
+    const hemisphere = getHemisphere(latitude);
+    return hemisphere === HEMISPHERES.NORTH 
+        ? (dayOfYear >= SEASONS.SUMMER_START_DAY && dayOfYear <= SEASONS.SUMMER_END_DAY)
+        : (dayOfYear <= SEASONS.SUMMER_START_DAY || dayOfYear >= SEASONS.SUMMER_END_DAY);
+}
 
 /**
- * SUN EVENTS
- * 
- * Determine natural day's main sun events like sunrise, sunset, nightStart ...
- * @param {NaturalDate} naturalDate
- * @param {Number} latitude
- * @returns Object { sunrise, sunset, nightStart, nightEnd, morningGoldenHour, eveningGoldenHour }
+ * Creates an astronomical observer at the specified coordinates
+ * @param {number} latitude - Latitude in degrees (-90 to 90)
+ * @param {number} longitude - Longitude in degrees (-180 to 180)
+ * @returns {Observer} Astronomy-engine observer instance
+ * @private
  */
-export function NaturalSunEvents(naturalDate, latitude) {
+const createObserver = (latitude, longitude) => new Observer(latitude, longitude, 0);
 
-    let cache_id = `SUN_${naturalDate.toDateString()}_${latitude}_${naturalDate.longitude}`;
-    
-    if (ASTRO_CACHE[cache_id]) {
-        return ASTRO_CACHE[cache_id];
+/**
+ * Calculates sun altitude data for a given natural date and latitude
+ * @param {NaturalDate} naturalDate - Natural date instance
+ * @param {number} latitude - Latitude in degrees (-90 to 90)
+ * @returns {{
+ *   altitude: number,
+ *   highestAltitude: number
+ * }} Sun altitude data
+ * @throws {Error} If inputs are invalid or calculation fails
+ */
+export function NaturalSunAltitude(naturalDate, latitude) {
+    // Validate inputs
+    if (!isValidNaturalDate(naturalDate)) {
+        throwValidationError('naturalDate', naturalDate, 'NaturalDate instance');
+    }
+    if (!isValidLatitude(latitude)) {
+        throwValidationError('latitude', latitude, 'number between -90 and 90');
     }
 
-    let observer = new Observer(latitude, naturalDate.longitude, 0);
-    let nadir = new Date(naturalDate.nadir);
-
-    let isSummer = 
-        latitude >= 0 && (naturalDate.dayOfYear >= 91 && naturalDate.dayOfYear <= 273) || // Northern hemisphere summer
-        latitude <= 0 && (naturalDate.dayOfYear <= 91 || naturalDate.dayOfYear >= 273); // Southern hemisphere summer
-
-    // SUNRISE & SUNSET
-    let sunrise = naturalDate.getTimeOfEvent(SearchRiseSet(Body.Sun, observer, +1, nadir, 1));
-    if(!sunrise) sunrise = isSummer ? 0 : 180;
-    let sunset = naturalDate.getTimeOfEvent(SearchRiseSet(Body.Sun, observer, -1, nadir, 1));
-    if(!sunset) sunset = isSummer ? 360 : 180;
-
-    // NIGHT (-12° altitude)
-    let nightStart = naturalDate.getTimeOfEvent(SearchAltitude(Body.Sun, observer, -1, nadir, 2, -12));
-    if(!nightStart) nightStart = isSummer ? 360 : 180;
-    let nightEnd = naturalDate.getTimeOfEvent(SearchAltitude(Body.Sun, observer, +1, nadir, 2, -12));
-    if(!nightEnd) nightEnd = isSummer ? 0 : 180;
-
-    // GOLDEN HOUR (+6° altitude)
-    let morningGoldenHour = naturalDate.getTimeOfEvent(SearchAltitude(Body.Sun, observer, +1, nadir, 2, +6));
-    if(!morningGoldenHour) morningGoldenHour = isSummer ? 0 : 180;
-    let eveningGoldenHour = naturalDate.getTimeOfEvent(SearchAltitude(Body.Sun, observer, -1, nadir, 2, +6));
-    if(!eveningGoldenHour) eveningGoldenHour = isSummer ? 360 : 180;
-    
-	return ASTRO_CACHE[cache_id] = {
-        sunrise: sunrise,
-        sunset: sunset,
-        nightStart: nightStart,
-        nightEnd: nightEnd,
-        morningGoldenHour: morningGoldenHour,
-        eveningGoldenHour: eveningGoldenHour
+    try {
+        const observer = createObserver(latitude, naturalDate.longitude);
+        const date = new Date(naturalDate.unixTime);
+        const sun = Equator(Body.Sun, date, observer, true, false);
+        
+        return {
+            altitude: Math.max(Horizon(date, observer, sun.ra, sun.dec).altitude, 0),
+            highestAltitude: SearchHourAngle(Body.Sun, observer, 0, new Date(naturalDate.nadir)).hor.altitude
+        }
+    } catch (error) {
+        console.error('Error in NaturalSunAltitude:', error);
+        throw error;
     }
 }
 
 /**
- * MOON PHASE & POSITION
- * 
- * Determines moon's position in the sky at specific natural date and lat/long position
- * @param {NaturalDate} naturalDate
- * @param {Number} latitude
- * @returns Object { position, phase, altitude, highestAltitude }
+ * Calculates sun-related events for a given natural date and latitude
+ * @param {NaturalDate} naturalDate - Natural date instance
+ * @param {number} latitude - Latitude in degrees (-90 to 90)
+ * @returns {{
+ *   sunrise: number,
+ *   sunset: number,
+ *   nightStart: number,
+ *   nightEnd: number,
+ *   morningGoldenHour: number,
+ *   eveningGoldenHour: number
+ * }} Sun events in natural degrees (0-360)
+ * @throws {Error} If inputs are invalid or calculation fails
  */
-export function NaturalMoonPosition(naturalDate, latitude) {
+export function NaturalSunEvents(naturalDate, latitude) {
+    // Validate inputs
+    if (!isValidNaturalDate(naturalDate)) {
+        throwValidationError('naturalDate', naturalDate, 'NaturalDate instance');
+    }
+    if (!isValidLatitude(latitude)) {
+        throwValidationError('latitude', latitude, 'number between -90 and 90');
+    }
 
-    let observer = new Observer(latitude, naturalDate.longitude, 0);
-    let date = new Date(naturalDate.unixTime);
+    const cacheKey = `SUN_${naturalDate.toDateString()}_${latitude}_${naturalDate.longitude}`;
+    
+    try {
+        if (astroCache.has(cacheKey)) {
+            const cachedResult = astroCache.get(cacheKey);
+            if (cachedResult && typeof cachedResult === 'object') {
+                return cachedResult;
+            }
+        }
+
+        const observer = createObserver(latitude, naturalDate.longitude);
+        const nadir = new Date(naturalDate.nadir);
+        const isSummer = isSummerSeason(naturalDate.dayOfYear, latitude);
 
-    // PHASE
-    let moonPhase = MoonPhase(date);
-    let moon = Equator(Body.Moon, date, observer, true, false);
+        // Helper function to handle edge cases
+        const getEventTime = (searchResult, isSummerDefault) => {
+            if (!searchResult) {
+                return isSummer ? (isSummerDefault ? 360 : 0) : 180;
+            }
+            return naturalDate.getTimeOfEvent(searchResult);
+        };
 
-    // POSITION & ALTITUDE
-    let moonAltitude = Math.max(Horizon(date, observer, moon.ra, moon.dec).altitude, 0);
-    let midmoon = SearchHourAngle(Body.Moon, observer, 0, new Date(naturalDate.nadir));
+        const events = {
+            sunrise: getEventTime(SearchRiseSet(Body.Sun, observer, +1, nadir, 1), false),
+            sunset: getEventTime(SearchRiseSet(Body.Sun, observer, -1, nadir, 1), true),
+            nightStart: getEventTime(SearchAltitude(Body.Sun, observer, -1, nadir, 2, ANGLES.NIGHT_ALTITUDE), true),
+            nightEnd: getEventTime(SearchAltitude(Body.Sun, observer, +1, nadir, 2, ANGLES.NIGHT_ALTITUDE), false),
+            morningGoldenHour: getEventTime(SearchAltitude(Body.Sun, observer, +1, nadir, 2, ANGLES.GOLDEN_HOUR_ALTITUDE), false),
+            eveningGoldenHour: getEventTime(SearchAltitude(Body.Sun, observer, -1, nadir, 2, ANGLES.GOLDEN_HOUR_ALTITUDE), true)
+        };
 
-    return {
-        phase: moonPhase, // 0 = new-moon, 90 = first quarter, 180 = full-moon, 270 = last quarter
-        altitude: moonAltitude, // Current moon altitude
-        highestAltitude: midmoon.hor.altitude // Highest altitude of the moon during the day
+        astroCache.set(cacheKey, events);
+        return events;
+    } catch (error) {
+        console.error('Error in NaturalSunEvents:', error);
+        throw error;
     }
 }
 
 /**
- * MOON EVENTS
- * 
- * Determine natural day's moonrise and moonset
- * @param {NaturalDate} naturalDate
- * @param {Number} latitude
- * @returns Object { moonrise, moonset }
+ * Calculates moon position and phase data for a given natural date and latitude
+ * @param {NaturalDate} naturalDate - Natural date instance
+ * @param {number} latitude - Latitude in degrees (-90 to 90)
+ * @returns {{
+ *   phase: number,
+ *   altitude: number,
+ *   highestAltitude: number
+ * }} Moon position and phase data
  */
-export function NaturalMoonEvents(naturalDate, latitude) {
+export function NaturalMoonPosition(naturalDate, latitude) {
+    // Validate inputs
+    if (!isValidNaturalDate(naturalDate)) {
+        throwValidationError('naturalDate', naturalDate, 'NaturalDate instance');
+    }
+    if (!isValidLatitude(latitude)) {
+        throwValidationError('latitude', latitude, 'number between -90 and 90');
+    }
 
-    let cache_id = `MOON_${naturalDate.toDateString()}_${latitude}_${naturalDate.longitude}`;
-    
-    if (ASTRO_CACHE[cache_id]) {
-        return ASTRO_CACHE[cache_id];
+    try {
+        const observer = createObserver(latitude, naturalDate.longitude);
+        const date = new Date(naturalDate.unixTime);
+        const moon = Equator(Body.Moon, date, observer, true, false);
+        
+        return {
+            phase: MoonPhase(date),
+            altitude: Math.max(Horizon(date, observer, moon.ra, moon.dec).altitude, 0),
+            highestAltitude: SearchHourAngle(Body.Moon, observer, 0, new Date(naturalDate.nadir)).hor.altitude
+        }
+    } catch (error) {
+        console.error('Error in NaturalMoonPosition:', error);
+        return {
+            phase: 0,
+            altitude: 0,
+            highestAltitude: 0
+        }
     }
+}
 
-    let observer = new Observer(latitude, naturalDate.longitude, 0);
+/**
+ * Calculates moon rise and set events for a given natural date and latitude
+ * @param {NaturalDate} naturalDate - Natural date instance
+ * @param {number} latitude - Latitude in degrees (-90 to 90)
+ * @returns {{
+ *   moonrise: number|null,
+ *   moonset: number|null
+ * }} Moon events in natural degrees (0-360)
+ */
+export function NaturalMoonEvents(naturalDate, latitude) {
+    const cacheKey = `MOON_${naturalDate.toDateString()}_${latitude}_${naturalDate.longitude}`;
+    
+    try {
+        if (astroCache.has(cacheKey)) {
+            return astroCache.get(cacheKey);
+        }
 
-    // MOONRISE & MOONSET
-	let moonrise = SearchRiseSet(Body.Moon, observer, +1, new Date(naturalDate.nadir), 1);
-    let moonset = SearchRiseSet(Body.Moon, observer, -1, new Date(naturalDate.nadir), 1);
+        const observer = createObserver(latitude, naturalDate.longitude);
+        const nadir = new Date(naturalDate.nadir);
 
-    return ASTRO_CACHE[cache_id] = {
-        moonrise: naturalDate.getTimeOfEvent(moonrise),
-        moonset: naturalDate.getTimeOfEvent(moonset),
+        const moonrise = SearchRiseSet(Body.Moon, observer, +1, nadir, 1);
+        const moonset = SearchRiseSet(Body.Moon, observer, -1, nadir, 1);
+
+        const events = {
+            moonrise: naturalDate.getTimeOfEvent(moonrise),
+            moonset: naturalDate.getTimeOfEvent(moonset)
+        };
+
+        astroCache.set(cacheKey, events);
+        return events;
+    } catch (error) {
+        console.error('Error calculating moon events:', error);
+        return {
+            moonrise: null,
+            moonset: null
+        }
     }
 }
 
 /**
- * MUSTACHES RANGE
- * 
- * The mustaches represents the shortest and longest day/night length
- * @param {Number} latitude
- * @returns Object { winterSunrise, winterSunset, summerSunrise, summerSunset }
+ * Calculates the range of sun positions between winter and summer solstices (average mustaches angle)
+ * @param {NaturalDate} naturalDate - Natural date instance
+ * @param {number} latitude - Latitude in degrees (-90 to 90)
+ * @returns {{
+ *   winterSunrise: number,
+ *   winterSunset: number,
+ *   summerSunrise: number,
+ *   summerSunset: number,
+ *   averageMustacheAngle: number
+ * }} Solstice sun positions and mustache angle
  */
 export function MustachesRange(naturalDate, latitude) {
-    let cache_id = `MUSTACHES_${naturalDate.year}_${latitude}`;
+    const cacheKey = `MUSTACHES_${naturalDate.year}_${latitude}`;
     
-    if (ASTRO_CACHE[cache_id]) {
-        return ASTRO_CACHE[cache_id];
-    }
+    try {
+        if (astroCache.has(cacheKey)) {
+            return astroCache.get(cacheKey);
+        }
 
-    // Get the solstices for the current year
-    const currentSeasons = Seasons(new Date(naturalDate.unixTime).getFullYear());
-    let winterSolsticeSunEvents = NaturalSunEvents(new NaturalDate(currentSeasons.dec_solstice.date, 0), latitude);
-    let summerSolsticeSunEvents = NaturalSunEvents(new NaturalDate(currentSeasons.jun_solstice.date, 0), latitude);
+        const currentYear = new Date(naturalDate.unixTime).getFullYear();
+        const currentSeasons = Seasons(currentYear);
+        
+        const winterSolsticeSunEvents = NaturalSunEvents(
+            new NaturalDate(currentSeasons.dec_solstice.date, 0), 
+            latitude
+        );
+        const summerSolsticeSunEvents = NaturalSunEvents(
+            new NaturalDate(currentSeasons.jun_solstice.date, 0), 
+            latitude
+        );
 
-    // Calculate average mustache angle from 90° and 270° (usefull for farnorth and farsouth locations where mustaches become unsymetric)
-    let averageMustacheAngle = latitude >= 0 ? 
-        (winterSolsticeSunEvents.sunrise - summerSolsticeSunEvents.sunrise + summerSolsticeSunEvents.sunset - winterSolsticeSunEvents.sunset) / 4 : 
-        (summerSolsticeSunEvents.sunrise - winterSolsticeSunEvents.sunrise + winterSolsticeSunEvents.sunset - summerSolsticeSunEvents.sunset) / 4;
-    
-    averageMustacheAngle = Math.min(Math.max(averageMustacheAngle, 0), 90);
-    
-    return ASTRO_CACHE[cache_id] = {
-        winterSunrise: winterSolsticeSunEvents.sunrise,
-        winterSunset: winterSolsticeSunEvents.sunset,
-        summerSunrise: summerSolsticeSunEvents.sunrise,
-        summerSunset: summerSolsticeSunEvents.sunset,
-        averageMustacheAngle: averageMustacheAngle
-    };
+        const averageMustacheAngle = Math.min(Math.max(
+            latitude >= 0 
+                ? (winterSolsticeSunEvents.sunrise - summerSolsticeSunEvents.sunrise + 
+                   summerSolsticeSunEvents.sunset - winterSolsticeSunEvents.sunset) / 4
+                : (summerSolsticeSunEvents.sunrise - winterSolsticeSunEvents.sunrise + 
+                   winterSolsticeSunEvents.sunset - summerSolsticeSunEvents.sunset) / 4,
+            0
+        ), 90);
+
+        const result = {
+            winterSunrise: winterSolsticeSunEvents.sunrise,
+            winterSunset: winterSolsticeSunEvents.sunset,
+            summerSunrise: summerSolsticeSunEvents.sunrise,
+            summerSunset: summerSolsticeSunEvents.sunset,
+            averageMustacheAngle
+        };
+
+        astroCache.set(cacheKey, result);
+        return result;
+    } catch (error) {
+        console.error('Error calculating mustaches range:', error);
+        return {
+            winterSunrise: 0,
+            winterSunset: 0,
+            summerSunrise: 0,
+            summerSunset: 0,
+            averageMustacheAngle: 0
+        }
+    }
 }

package/index.js

@@ -1,28 +1,71 @@
+/**
+ * @module natural-time-js
+ * @description Natural time implementation for JavaScript - translates artificial dates to natural dates
+ */
+
 import { Seasons } from 'astronomy-engine';
 
-const NT_CACHE = {};
+const yearContextCache = new Map();
 
 /**
- * NATURAL TIME
- * 
- * 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 translates gregorian artificial datetime to natural datetime
- * https://github.com/sylvain441/natural-time-js
- * 
- * Special thanks to Don Cross, author of the Astronomy Library to calculate celestial body events
- * https://github.com/cosinekitty/astronomy
- * 
- * @author Biquette 🐐 
- * @contact sylvain441@proton.me
- * 
+ * Calculates year context for natural date calculations
+ * @param {number} artificialYear - Gregorian calendar year
+ * @param {number} longitude - Longitude in degrees (-180 to 180)
+ * @returns {{
+ *   start: number,
+ *   duration: number
+ * }} Year context with start timestamp and duration
+ * @private
+ */
+const calculateYearContext = (artificialYear, longitude) => {
+	const cacheKey = `${artificialYear}_${longitude}`;
+	
+	if (yearContextCache.has(cacheKey)) {
+		return yearContextCache.get(cacheKey);
+	}
+	
+	const startSolstice = Seasons(artificialYear).dec_solstice.date;
+	const endSolstice = Seasons(artificialYear + 1).dec_solstice.date;
+	
+	const startNewYear = Date.UTC(
+		startSolstice.getUTCFullYear(),
+		startSolstice.getUTCMonth(),
+		startSolstice.getUTCDate() + (startSolstice.getUTCHours() >= 12 ? 1 : 0),
+		12, 0, 0
+	);
+	
+	const endNewYear = Date.UTC(
+		endSolstice.getUTCFullYear(),
+		endSolstice.getUTCMonth(),
+		endSolstice.getUTCDate() + (endSolstice.getUTCHours() >= 12 ? 1 : 0),
+		12, 0, 0
+	);
+	
+	const context = {
+		start: parseInt(startNewYear + (-longitude + 180) * NaturalDate.MILLISECONDS_PER_DAY/360),
+		duration: (endNewYear - startNewYear) / NaturalDate.MILLISECONDS_PER_DAY
+	};
+	
+	yearContextCache.set(cacheKey, context);
+	return context;
+}
+
+/**
+ * Natural date class for converting artificial (Gregorian) dates to natural time
+ * @class
  */
 export class NaturalDate {
+	/**
+	 * Number of milliseconds in a day
+	 * @constant {number}
+	 */
+	static MILLISECONDS_PER_DAY = 86400000; // 24 * 60 * 60 * 1000
 
-	static END_OF_ARTIFICIAL_TIME = 1356091200000; // 2012-12-22 00:00:00 at +180°;
-	static MILLISECONDS_PER_DAY = 86400000; // 24*60*60*1000
+	/**
+	 * End date of the artificial time era (December 21, 2012 12:00 UTC)
+	 * @constant {number}
+	 */
+	static END_OF_ARTIFICIAL_TIME = Date.UTC(2012, 11, 21, 12, 0, 0);
 
 	unixTime; // Artificial gregorian date (UNIX timestamp)
 	longitude; // Longitude (between -180° to +180°)
@@ -47,54 +90,32 @@ export class NaturalDate {
 	nadir; // Beginning of the day at the current longitude (UNIX timestamp)
 
 	/**
-	 * Computes natural date from gregorian date and longitude
-	 * @param {Date} date Date object or Unix timestamp
-	 * @param {Number} longitude From -180 to + 180
+	 * Creates a new natural date instance
+	 * @param {Date|number} date - JavaScript Date object or Unix timestamp
+	 * @param {number} longitude - Longitude in degrees (-180 to 180)
+	 * @throws {Error} If inputs are invalid
 	 */
 	constructor(date, longitude) {
-
+		// Validate longitude
+		if (longitude !== undefined && (typeof longitude !== 'number' || longitude < -180 || longitude > 180)) {
+			throw new Error('Longitude must be between -180 and +180');
+		}
+		
 		date = new Date(date || Date.now());
+		if (isNaN(date.getTime())) {
+			throw new Error('Invalid date provided');
+		}
+		
 		this.unixTime = date.getTime();
 		this.longitude = longitude || 0;
 		
 		if (Number.isFinite(this.unixTime)) {
-
-			const getYearContext = (artificialYear, longitude) => {
-
-				// We cache astronomical calculations
-				let cache_id = `${artificialYear}_${longitude}`;
-				if(NT_CACHE?.[cache_id])
-					return NT_CACHE[cache_id];
-
-				// Search for December solstices
-				let startSolstice = Seasons(artificialYear).dec_solstice.date;
-				let endSolstice = Seasons(artificialYear + 1).dec_solstice.date;
-		
-				// Calculate next time it's midnight at the 180th meridian after solstice (mean time)
-				// NB: Midnight at +180° equals midday the previous day at +0°
-				let startNewYear = Date.UTC(
-						startSolstice.getUTCFullYear(), 
-						startSolstice.getUTCMonth(), 
-						startSolstice.getUTCDate() + (startSolstice.getUTCHours() >= 12 ? 1 : 0),
-						12, 0, 0);
-				let endNewYear = Date.UTC(
-						endSolstice.getUTCFullYear(), 
-						endSolstice.getUTCMonth(), 
-						endSolstice.getUTCDate() + (endSolstice.getUTCHours() >= 12 ? 1 : 0),
-						12, 0, 0);
-		
-				return NT_CACHE[cache_id] = {
-					start: parseInt(startNewYear + (-longitude + 180) * NaturalDate.MILLISECONDS_PER_DAY/360),
-					duration: (endNewYear - startNewYear) / NaturalDate.MILLISECONDS_PER_DAY
-				};
-			}
-
 			// YEAR START & DURATION
-			let yearContext = getYearContext(date.getUTCFullYear()-1, longitude);
+			let yearContext = calculateYearContext(date.getUTCFullYear()-1, longitude);
 			
 			// Correction if between the beginning of natural year and the end of the artificial year
 			if(this.unixTime - yearContext.start >= yearContext.duration * NaturalDate.MILLISECONDS_PER_DAY)
-				yearContext = getYearContext(date.getUTCFullYear(), longitude);
+				yearContext = calculateYearContext(date.getUTCFullYear(), longitude);
 			
 			this.yearStart = yearContext.start;
 			this.yearDuration = yearContext.duration;
@@ -133,9 +154,9 @@ export class NaturalDate {
 	}
 
 	/**
-	 * Returns the time at specified event's date
-	 * @param {Date} event 
-	 * @returns Time on a 360° scale or null if out of range
+	 * Gets the time of an astronomical event in natural degrees
+	 * @param {Date|number} event - Event timestamp
+	 * @returns {number|false} Event time in natural degrees (0-360) or false if out of range
 	 */
 	getTimeOfEvent(event) {
 		// Make sure it's a unix timestamp
@@ -153,7 +174,7 @@ export class NaturalDate {
 	 * @returns ex: "004)04)01 113°00 NT+95"
 	 */
 	toString() {
-		return this.toDateString() + " " + this.toTimeString() + " " + this.toLongitudeString();
+		return `${this.toDateString()} ${this.toTimeString()} ${this.toLongitudeString()}`;
 	}
 
 	/**
@@ -162,10 +183,10 @@ export class NaturalDate {
 	 * @returns ex: "004)04)01"
 	 */
 	toDateString(separator = ')') {
-		if(this.isRainbowDay)
-			return `${this.toYearString()}${separator}RAINBOW${this.dayOfYear == 366 ? "+" : ""}`;
-		else
-			return `${this.toYearString()}${separator}${this.toMoonString()}${separator}${this.toDayOfMoonString()}`;
+		if(this.isRainbowDay) {
+			return `${this.toYearString()}${separator}RAINBOW${this.dayOfYear === 366 ? "+" : ""}`;
+		}
+		return `${this.toYearString()}${separator}${this.toMoonString()}${separator}${this.toDayOfMoonString()}`;
 	}
 
 	/**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "natural-time-js",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "description": "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 translates gregorian artificial datetime to natural datetime",
   "main": "index.js",
   "scripts": {

package/utils/validators.js

@@ -0,0 +1,136 @@
+/**
+ * @module validators
+ * @description Validation utilities for natural time calculations
+ */
+
+import { NaturalDate } from '../index.js';
+
+const LATITUDE_RANGE = { MIN: -90, MAX: 90 };
+const LONGITUDE_RANGE = { MIN: -180, MAX: 180 };
+const ANGLE_RANGE = { MIN: 0, MAX: 360 };
+
+// Add ranges based on NaturalDate class constraints
+const NATURAL_DATE_RANGES = {
+    MOON: { MIN: 1, MAX: 14 },
+    WEEK: { MIN: 1, MAX: 53 },
+    WEEK_OF_MOON: { MIN: 1, MAX: 4 },
+    DAY_OF_MOON: { MIN: 1, MAX: 28 },
+    DAY_OF_WEEK: { MIN: 1, MAX: 7 }
+};
+
+/**
+ * Validates if a value is a finite number
+ * @param {*} value - Value to validate
+ * @returns {boolean} True if value is a valid number
+ */
+export const isValidNumber = (value) => {
+    return typeof value === 'number' && Number.isFinite(value) && !Number.isNaN(value);
+};
+
+/**
+ * Validates latitude value
+ * @param {number} latitude - Latitude to validate
+ * @returns {boolean} True if latitude is valid
+ */
+export const isValidLatitude = (latitude) => {
+    return isValidNumber(latitude) && 
+           latitude >= LATITUDE_RANGE.MIN && 
+           latitude <= LATITUDE_RANGE.MAX;
+};
+
+/**
+ * Validates longitude value
+ */
+export const isValidLongitude = (longitude) => {
+    return isValidNumber(longitude) && 
+           longitude >= LONGITUDE_RANGE.MIN && 
+           longitude <= LONGITUDE_RANGE.MAX;
+};
+
+/**
+ * Validates angle value (0-360 degrees)
+ */
+export const isValidAngle = (angle) => {
+    return isValidNumber(angle) && 
+           angle >= ANGLE_RANGE.MIN && 
+           angle <= ANGLE_RANGE.MAX;
+};
+
+/**
+ * Validates unix timestamp
+ */
+export const isValidTimestamp = (timestamp) => {
+    return isValidNumber(timestamp) && timestamp > 0;
+};
+
+/**
+ * Validates NaturalDate instance with complete property checks
+ * @param {*} date - Value to validate
+ * @returns {boolean} True if value is a valid NaturalDate instance
+ */
+export const isValidNaturalDate = (date) => {
+    if (!(date instanceof NaturalDate)) {
+        return false;
+    }
+    
+    // Basic property validations
+    if (!isValidTimestamp(date.unixTime) || 
+        !isValidLongitude(date.longitude) ||
+        !isValidNumber(date.year)) {
+        return false;
+    }
+
+    // Natural calendar validations
+    return (
+        isValidNumber(date.moon) &&
+        date.moon >= NATURAL_DATE_RANGES.MOON.MIN &&
+        date.moon <= NATURAL_DATE_RANGES.MOON.MAX &&
+        
+        isValidNumber(date.week) &&
+        date.week >= NATURAL_DATE_RANGES.WEEK.MIN &&
+        date.week <= NATURAL_DATE_RANGES.WEEK.MAX &&
+        
+        isValidNumber(date.weekOfMoon) &&
+        date.weekOfMoon >= NATURAL_DATE_RANGES.WEEK_OF_MOON.MIN &&
+        date.weekOfMoon <= NATURAL_DATE_RANGES.WEEK_OF_MOON.MAX &&
+        
+        isValidNumber(date.dayOfMoon) &&
+        date.dayOfMoon >= NATURAL_DATE_RANGES.DAY_OF_MOON.MIN &&
+        date.dayOfMoon <= NATURAL_DATE_RANGES.DAY_OF_MOON.MAX &&
+        
+        isValidNumber(date.dayOfWeek) &&
+        date.dayOfWeek >= NATURAL_DATE_RANGES.DAY_OF_WEEK.MIN &&
+        date.dayOfWeek <= NATURAL_DATE_RANGES.DAY_OF_WEEK.MAX &&
+        
+        isValidNumber(date.dayOfYear) &&
+        date.dayOfYear >= 1 &&
+        date.dayOfYear <= date.yearDuration &&
+        
+        typeof date.isRainbowDay === 'boolean' &&
+        isValidAngle(date.time) &&
+        isValidTimestamp(date.yearStart) &&
+        isValidNumber(date.yearDuration) &&
+        isValidTimestamp(date.nadir)
+    );
+};
+
+/**
+ * Validates cache key string
+ */
+export const isValidCacheKey = (key) => {
+    return typeof key === 'string' && key.length > 0;
+};
+
+/**
+ * Throws formatted error for invalid parameters
+ * @param {string} paramName - Name of the invalid parameter
+ * @param {*} value - Invalid value
+ * @param {string} expectedType - Description of expected type/format
+ * @throws {Error} Formatted validation error
+ */
+export const throwValidationError = (paramName, value, expectedType) => {
+    throw new Error(
+        `Invalid ${paramName}: ${value}. ` +
+        `Expected ${expectedType}`
+    );
+};