natural-time-js 1.1.1 → 2.0.1

package/{context.js → dist/astronomy/celestial.js}

@@ -1,96 +1,68 @@
 /**
- * @module context
- * @description Provides astronomical calculations and events for natural time, including sun and moon positions
+ * @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 './index.js';
+import { NaturalDate } from '../core/NaturalDate';
 import { Body, Observer, SearchHourAngle, SearchRiseSet, SearchAltitude, MoonPhase, Equator, Horizon, Seasons } from 'astronomy-engine';
-import { 
-    isValidLatitude, 
-    isValidLongitude, 
-    isValidNaturalDate, 
-    throwValidationError 
-} from './utils/validators.js';
-
+import { isValidLatitude, isValidNaturalDate, throwValidationError } from '../utils/validators';
 /**
- * Hemisphere identifiers for geographical calculations
- * @constant
- * @enum {string}
- * @readonly
+ * Hemisphere identifiers for geographical calculations.
  */
-export const HEMISPHERES = {
-    NORTH: 'NORTH',
-    SOUTH: 'SOUTH'
-};
-
+export var HEMISPHERES;
+(function (HEMISPHERES) {
+    /** Northern hemisphere (latitude >= 0) */
+    HEMISPHERES["NORTH"] = "NORTH";
+    /** Southern hemisphere (latitude < 0) */
+    HEMISPHERES["SOUTH"] = "SOUTH";
+})(HEMISPHERES || (HEMISPHERES = {}));
 /**
- * Day numbers marking the start and end of summer season
- * Day 1 represents January 1st
- * @constant
- * @enum {number}
- * @readonly
+ * Day numbers marking the start and end of summer season.
  */
 export const SEASONS = {
-    /** Day 91 (typically April 1st) */
+    /** Day 91 (typically April 1st) - Start of summer in Northern hemisphere */
     SUMMER_START_DAY: 91,
-    /** Day 273 (typically September 30th) */
+    /** Day 273 (typically September 30th) - End of summer in Northern hemisphere */
     SUMMER_END_DAY: 273
 };
-
 /**
- * Solar altitude thresholds in degrees for different daylight conditions
- * @constant
- * @enum {number}
- * @readonly
+ * Solar altitude thresholds in degrees for different daylight conditions.
  */
 export const ANGLES = {
+    /** Altitude below which astronomical night begins (-12°) */
     NIGHT_ALTITUDE: -12,
+    /** Altitude below which golden hour lighting occurs (6°) */
     GOLDEN_HOUR_ALTITUDE: 6
 };
-
-// Move cache to its own module for better separation of concerns
+/**
+ * Cache for astronomical calculations to improve performance.
+ */
 const astroCache = new Map();
-
 /**
- * Determines the hemisphere based on latitude
- * @param {number} latitude - Latitude in degrees (-90 to 90)
- * @returns {string} HEMISPHERES.NORTH or HEMISPHERES.SOUTH
- * @private
+ * Determines the hemisphere based on latitude.
  */
 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
+ * Determines if the current day is in the summer season based on hemisphere.
  */
 const isSummerSeason = (dayOfYear, latitude) => {
     const hemisphere = getHemisphere(latitude);
-    return hemisphere === HEMISPHERES.NORTH 
+    return hemisphere === HEMISPHERES.NORTH
         ? (dayOfYear >= SEASONS.SUMMER_START_DAY && dayOfYear <= SEASONS.SUMMER_END_DAY)
         : (dayOfYear <= SEASONS.SUMMER_START_DAY || dayOfYear >= SEASONS.SUMMER_END_DAY);
-}
-
+};
 /**
- * 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
+ * Creates an observer object for astronomical calculations.
  */
 const createObserver = (latitude, longitude) => new Observer(latitude, longitude, 0);
-
 /**
- * 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
+ * Calculates the sun's altitude at a specific natural time and location.
  */
 export function NaturalSunAltitude(naturalDate, latitude) {
     // Validate inputs
@@ -100,35 +72,22 @@ export function NaturalSunAltitude(naturalDate, latitude) {
     if (!isValidLatitude(latitude)) {
         throwValidationError('latitude', latitude, 'number between -90 and 90');
     }
-
     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) {
+        };
+    }
+    catch (error) {
         console.error('Error in NaturalSunAltitude:', error);
         throw error;
     }
 }
-
 /**
- * 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
+ * Calculates sun events for a specific natural date and location.
  */
 export function NaturalSunEvents(naturalDate, latitude) {
     // Validate inputs
@@ -138,29 +97,22 @@ export function NaturalSunEvents(naturalDate, latitude) {
     if (!isValidLatitude(latitude)) {
         throwValidationError('latitude', latitude, 'number between -90 and 90');
     }
-
     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 cachedResult = astroCache.get(cacheKey);
+        if (cachedResult && 'sunrise' in cachedResult) {
+            return cachedResult;
         }
-
         const observer = createObserver(latitude, naturalDate.longitude);
         const nadir = new Date(naturalDate.nadir);
         const isSummer = isSummerSeason(naturalDate.dayOfYear, latitude);
-
         // Helper function to handle edge cases
         const getEventTime = (searchResult, isSummerDefault) => {
             if (!searchResult) {
                 return isSummer ? (isSummerDefault ? 360 : 0) : 180;
             }
-            return naturalDate.getTimeOfEvent(searchResult);
+            return naturalDate.getTimeOfEvent(searchResult.date) || 0;
         };
-
         const events = {
             sunrise: getEventTime(SearchRiseSet(Body.Sun, observer, +1, nadir, 1), false),
             sunset: getEventTime(SearchRiseSet(Body.Sun, observer, -1, nadir, 1), true),
@@ -169,24 +121,16 @@ export function NaturalSunEvents(naturalDate, latitude) {
             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)
         };
-
         astroCache.set(cacheKey, events);
         return events;
-    } catch (error) {
+    }
+    catch (error) {
         console.error('Error in NaturalSunEvents:', error);
         throw error;
     }
 }
-
 /**
- * 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
+ * Calculates the moon's position and phase.
  */
 export function NaturalMoonPosition(naturalDate, latitude) {
     // Validate inputs
@@ -196,107 +140,85 @@ export function NaturalMoonPosition(naturalDate, latitude) {
     if (!isValidLatitude(latitude)) {
         throwValidationError('latitude', latitude, 'number between -90 and 90');
     }
-
     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) {
+            phase: MoonPhase(date),
+            illumination: Math.cos(MoonPhase(date) * Math.PI / 180)
+        };
+    }
+    catch (error) {
         console.error('Error in NaturalMoonPosition:', error);
-        return {
-            phase: 0,
-            altitude: 0,
-            highestAltitude: 0
-        }
+        throw error;
     }
 }
-
 /**
- * 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)
+ * Calculates moon events for a specific natural date and location.
  */
 export function NaturalMoonEvents(naturalDate, latitude) {
+    // Validate inputs
+    if (!isValidNaturalDate(naturalDate)) {
+        throwValidationError('naturalDate', naturalDate, 'NaturalDate instance');
+    }
+    if (!isValidLatitude(latitude)) {
+        throwValidationError('latitude', latitude, 'number between -90 and 90');
+    }
     const cacheKey = `MOON_${naturalDate.toDateString()}_${latitude}_${naturalDate.longitude}`;
-    
     try {
-        if (astroCache.has(cacheKey)) {
-            return astroCache.get(cacheKey);
+        const cachedResult = astroCache.get(cacheKey);
+        if (cachedResult && 'moonrise' in cachedResult) {
+            return cachedResult;
         }
-
         const observer = createObserver(latitude, naturalDate.longitude);
         const nadir = new Date(naturalDate.nadir);
-
-        const moonrise = SearchRiseSet(Body.Moon, observer, +1, nadir, 1);
-        const moonset = SearchRiseSet(Body.Moon, observer, -1, nadir, 1);
-
+        // Helper function to handle edge cases
+        const getEventTime = (searchResult) => {
+            if (!searchResult)
+                return 0;
+            return naturalDate.getTimeOfEvent(searchResult.date) || 0;
+        };
         const events = {
-            moonrise: naturalDate.getTimeOfEvent(moonrise),
-            moonset: naturalDate.getTimeOfEvent(moonset)
+            moonrise: getEventTime(SearchRiseSet(Body.Moon, observer, +1, nadir, 1)),
+            moonset: getEventTime(SearchRiseSet(Body.Moon, observer, -1, nadir, 1)),
+            highestAltitude: SearchHourAngle(Body.Moon, observer, 0, nadir).hor.altitude
         };
-
         astroCache.set(cacheKey, events);
         return events;
-    } catch (error) {
-        console.error('Error calculating moon events:', error);
-        return {
-            moonrise: null,
-            moonset: null
-        }
+    }
+    catch (error) {
+        console.error('Error in NaturalMoonEvents:', error);
+        throw error;
     }
 }
-
 /**
  * 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) {
-    const cacheKey = `MUSTACHES_${naturalDate.year}_${latitude}`;
-    
+    // Validate inputs
+    if (!isValidNaturalDate(naturalDate)) {
+        throwValidationError('naturalDate', naturalDate, 'NaturalDate instance');
+    }
+    if (!isValidLatitude(latitude)) {
+        throwValidationError('latitude', latitude, 'number between -90 and 90');
+    }
+    const currentYear = new Date(naturalDate.unixTime).getFullYear();
+    const cacheKey = `MUSTACHES_${currentYear}_${latitude}`;
     try {
-        if (astroCache.has(cacheKey)) {
-            return astroCache.get(cacheKey);
+        const cachedResult = astroCache.get(cacheKey);
+        if (cachedResult && 'winterSunrise' in cachedResult) {
+            return cachedResult;
         }
-
-        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
-        );
-
-        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 winterSolsticeSunEvents = NaturalSunEvents(new NaturalDate(currentSeasons.dec_solstice.date, 0), latitude);
+        const summerSolsticeSunEvents = NaturalSunEvents(new NaturalDate(currentSeasons.jun_solstice.date, 0), latitude);
+        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,
@@ -304,10 +226,10 @@ export function MustachesRange(naturalDate, latitude) {
             summerSunset: summerSolsticeSunEvents.sunset,
             averageMustacheAngle
         };
-
         astroCache.set(cacheKey, result);
         return result;
-    } catch (error) {
+    }
+    catch (error) {
         console.error('Error calculating mustaches range:', error);
         return {
             winterSunrise: 0,
@@ -315,6 +237,7 @@ export function MustachesRange(naturalDate, latitude) {
             summerSunrise: 0,
             summerSunset: 0,
             averageMustacheAngle: 0
-        }
+        };
     }
-}
+}
+//# sourceMappingURL=celestial.js.map

package/dist/astronomy/celestial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"celestial.js","sourceRoot":"","sources":["../../src/astronomy/celestial.ts"],"names":[],"mappings":"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"}

package/dist/core/NaturalDate.d.ts

@@ -0,0 +1,164 @@
+/**
+ * @module natural-time-js/core
+ * @description This module provides the core NaturalDate class that bridges between artificial Gregorian time and Natural Time.
+ */
+/**
+ * Year context interface for natural date calculations
+ */
+interface YearContext {
+    start: number;
+    duration: number;
+}
+/**
+ * Cache for year context calculations to improve performance
+ * @private
+ */
+declare const yearContextCache: Map<string, YearContext>;
+/**
+ * Natural date class for converting artificial (Gregorian) dates to natural time.
+ *
+ * The NaturalDate class provides a complete implementation of the natural time system,
+ * which is based on natural cycles:
+ * - Years begin at the winter solstice
+ * - Each year has 13 moons (months) of 28 days each, plus 1-2 "rainbow days"
+ * - Weeks are 7 days
+ * - Time is measured in 360 degrees for a full day cycle
+ *
+ * This class handles the conversion between Gregorian calendar dates and natural time,
+ * accounting for longitude adjustments to provide location-specific natural time.
+ */
+export declare class NaturalDate {
+    /**
+     * Number of milliseconds in a day
+     */
+    static readonly MILLISECONDS_PER_DAY: number;
+    /**
+     * End date of the artificial time era (December 21, 2012 12:00 UTC)
+     * This is the reference point for natural time calculations
+     */
+    static readonly END_OF_ARTIFICIAL_TIME: number;
+    /** Artificial gregorian date (UNIX timestamp) */
+    readonly unixTime: number;
+    /** Longitude in degrees (-180° to +180°) */
+    readonly longitude: number;
+    /** Current natural year (year 001: winter solstice 2012 > winter solstice 2013) */
+    readonly year: number;
+    /** Current moon (month) in the natural year (1-14) */
+    readonly moon: number;
+    /** Current week of the natural year (1-53) */
+    readonly week: number;
+    /** Current week within the current moon (1-4) */
+    readonly weekOfMoon: number;
+    /** Number of days passed since END_OF_ARTIFICIAL_TIME */
+    readonly day: number;
+    /** Current day of the natural year (1-366) */
+    readonly dayOfYear: number;
+    /** Current day of the moon (1-28) */
+    readonly dayOfMoon: number;
+    /** Current day of the week (1-7) */
+    readonly dayOfWeek: number;
+    /** True if current day is a rainbow day (day beyond the 13 moons) */
+    readonly isRainbowDay: boolean;
+    /** Current time in natural degrees (0-360°) */
+    readonly time: number;
+    /** Beginning of the natural year at the current longitude (UNIX timestamp) */
+    readonly yearStart: number;
+    /** Number of days in the current natural year (365 or 366) */
+    readonly yearDuration: number;
+    /** Beginning of the current natural day at the current longitude (UNIX timestamp) */
+    readonly nadir: number;
+    /**
+     * Creates a new natural date instance.
+     *
+     * Converts a Gregorian date to natural time based on the specified longitude.
+     * The longitude is used to adjust the natural time for the local position on Earth.
+     *
+     * @param date - JavaScript Date object, Unix timestamp, or date string
+     * @param longitude - Longitude in degrees (-180 to 180)
+     * @throws {Error} If inputs are invalid
+     *
+     * @example
+     * // Create a natural date for the current time in Paris (longitude 2.3522)
+     * const parisNaturalDate = new NaturalDate(new Date(), 2.3522);
+     *
+     * @example
+     * // Create a natural date for a specific time in Tokyo (longitude 139.6503)
+     * const tokyoNaturalDate = new NaturalDate('2023-06-21T12:00:00', 139.6503);
+     */
+    constructor(date: Date | number | string | null | undefined, longitude?: number);
+    /**
+     * Gets the time of an astronomical event in natural degrees.
+     *
+     * Converts an event timestamp to natural degrees (0-360°) within the current natural day.
+     * Returns false if the event occurs outside the current natural day.
+     *
+     * This is useful for calculating the position of celestial events like sunrise, sunset,
+     * moonrise, or moonset within the natural time system.
+     *
+     * @param event - Event timestamp (Date object, Unix timestamp, or date string)
+     * @returns Event time in natural degrees (0-360°) or false if out of range
+     *
+     * @example
+     * // Calculate sunrise time in natural degrees
+     * const naturalDate = new NaturalDate(new Date(), 0);
+     * const sunrise = '2023-01-01T06:00:00'; // Example sunrise at 6:00 AM
+     * const sunriseInDegrees = naturalDate.getTimeOfEvent(sunrise);
+     * console.log(`Sunrise occurs at ${sunriseInDegrees}°`);
+     */
+    getTimeOfEvent(event: Date | number | string): number | false;
+    /**
+     * Exports current date as a full ISO formatted string.
+     *
+     * The format is: "YYY)MM)DD TTT°DD NT±LLL.L"
+     * - YYY: Natural year (padded to 3 digits)
+     * - MM: Moon number (padded to 2 digits)
+     * - DD: Day of moon (padded to 2 digits)
+     * - TTT: Time in degrees (padded to 3 digits)
+     * - DD: Decimal degrees (2 digits)
+     * - ±LLL.L: Longitude with sign and 1 decimal
+     *
+     * @returns {string} Formatted natural date string
+     */
+    toString(): string;
+    /**
+     * Exports the date part of the natural date.
+     *
+     * @param separator - Separator character between components (default: ')')
+     * @returns Formatted date string
+     */
+    toDateString(separator?: string): string;
+    /**
+     * Exports the time part of the natural date.
+     *
+     * @param decimals - Number of decimal places for time (default: 2)
+     * @param rounding - Rounding increment for time (default: 1)
+     * @returns Formatted time string
+     */
+    toTimeString(decimals?: number, rounding?: number): string;
+    /**
+     * Exports the longitude part of the natural date.
+     *
+     * @param decimals - Number of decimal places for longitude (default: 1)
+     * @returns Formatted longitude string
+     */
+    toLongitudeString(decimals?: number): string;
+    /**
+     * Exports the year part of the natural date.
+     *
+     * @returns Formatted year string
+     */
+    toYearString(): string;
+    /**
+     * Exports the moon part of the natural date.
+     *
+     * @returns Formatted moon string
+     */
+    toMoonString(): string;
+    /**
+     * Exports the day of moon part of the natural date.
+     *
+     * @returns Formatted day of moon string
+     */
+    toDayOfMoonString(): string;
+}
+export { yearContextCache };