natural-time-js 2.0.6 → 3.0.0

package/dist/core/NaturalDate.js

@@ -1,260 +0,0 @@
-/**
- * @module natural-time-js/core
- * @description This module provides the core NaturalDate class that bridges between artificial Gregorian time and Natural Time.
- */
-import { Seasons } from 'astronomy-engine';
-/**
- * Cache for year context calculations to improve performance
- * @private
- */
-const yearContextCache = new Map();
-/**
- * Calculates year context for natural date calculations.
- *
- * The year context includes:
- * - The start timestamp of the natural year (winter solstice)
- * - The duration of the year in days (365 or 366)
- *
- * This function handles the conversion between Gregorian calendar years
- * and natural years, accounting for longitude adjustments.
- *
- * @param artificialYear - Gregorian calendar year
- * @param longitude - Longitude in degrees (-180 to 180)
- * @returns Year context object 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(String(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.
- *
- * 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 class NaturalDate {
-    /**
-     * 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, longitude) {
-        // Validate longitude
-        if (longitude !== undefined && (typeof longitude !== 'number' || longitude < -180 || longitude > 180)) {
-            throw new Error('Longitude must be between -180 and +180');
-        }
-        const dateObj = new Date(date || Date.now());
-        if (isNaN(dateObj.getTime())) {
-            throw new Error('Invalid date provided');
-        }
-        this.unixTime = dateObj.getTime();
-        this.longitude = longitude || 0;
-        if (Number.isFinite(this.unixTime)) {
-            // YEAR START & DURATION
-            let yearContext = calculateYearContext(dateObj.getUTCFullYear() - 1, this.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 = calculateYearContext(dateObj.getUTCFullYear(), this.longitude);
-            this.yearStart = yearContext.start;
-            this.yearDuration = yearContext.duration;
-            const timeSinceLocalYearStart = (this.unixTime - this.yearStart) / NaturalDate.MILLISECONDS_PER_DAY;
-            // YEAR
-            this.year = new Date(this.yearStart).getUTCFullYear() - new Date(NaturalDate.END_OF_ARTIFICIAL_TIME).getUTCFullYear() + 1;
-            // MOON
-            this.moon = Math.floor(timeSinceLocalYearStart / 28) + 1;
-            // HEPTAD
-            this.week = Math.floor(timeSinceLocalYearStart / 7) + 1;
-            this.weekOfMoon = Math.floor(timeSinceLocalYearStart / 7) % 4 + 1;
-            // DAY
-            this.day = Math.floor((this.unixTime - (NaturalDate.END_OF_ARTIFICIAL_TIME + (-this.longitude + 180) * NaturalDate.MILLISECONDS_PER_DAY / 360)) / NaturalDate.MILLISECONDS_PER_DAY);
-            this.dayOfYear = Math.floor(timeSinceLocalYearStart) + 1;
-            this.dayOfMoon = Math.floor(timeSinceLocalYearStart) % 28 + 1;
-            this.dayOfWeek = Math.floor(timeSinceLocalYearStart) % 7 + 1;
-            // NADIR (i.e day start, midnight)
-            this.nadir = this.yearStart + Math.floor(timeSinceLocalYearStart) * NaturalDate.MILLISECONDS_PER_DAY;
-            // TIME
-            this.time = (this.unixTime - this.nadir) * 360 / NaturalDate.MILLISECONDS_PER_DAY;
-            // RAINBOW DAY
-            this.isRainbowDay = this.dayOfYear > 13 * 28;
-            return;
-        }
-        throw new Error('Argument must be a Date object or a Unix timestamp');
-    }
-    /**
-     * 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) {
-        // Make sure it's a unix timestamp
-        const eventTime = new Date(event).getTime();
-        // Check if not out of range
-        if (eventTime < this.nadir || eventTime > this.nadir + NaturalDate.MILLISECONDS_PER_DAY)
-            return false;
-        return (eventTime - this.nadir) * (360 / NaturalDate.MILLISECONDS_PER_DAY);
-    }
-    /**
-     * 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() {
-        return `${this.toDateString()} ${this.toTimeString()} ${this.toLongitudeString()}`;
-    }
-    /**
-     * Exports the date part of the natural date.
-     *
-     * @param separator - Separator character between components (default: ')')
-     * @returns Formatted date string
-     */
-    toDateString(separator = ')') {
-        if (this.isRainbowDay) {
-            const isSecondRainbowDay = this.dayOfYear === 366;
-            return `${this.toYearString()}${separator}RAINBOW${isSecondRainbowDay ? '+' : ''}`;
-        }
-        return `${this.toYearString()}${separator}${this.toMoonString()}${separator}${this.toDayOfMoonString()}`;
-    }
-    /**
-     * 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 = 2, rounding = 0.01) {
-        let time = this.time;
-        // Round to the nearest decimal increment
-        if (rounding > 0) {
-            time = Math.round(time / rounding) * rounding;
-            // Handle edge case where rounding pushes us to 360°
-            if (time >= 360) {
-                time = 0;
-            }
-        }
-        // Format the integer part to 3 digits
-        const integerPart = Math.floor(time).toString().padStart(3, '0');
-        // Format the decimal part if needed
-        const decimalPart = decimals > 0
-            ? (time % 1).toFixed(decimals).substring(2).padEnd(decimals, '0')
-            : '';
-        return `${integerPart}°${decimalPart}`;
-    }
-    /**
-     * Exports the longitude part of the natural date.
-     *
-     * @param decimals - Number of decimal places for longitude (default: 1)
-     * @returns Formatted longitude string
-     */
-    toLongitudeString(decimals = 1) {
-        // Consider longitudes very close to 0 (within 0.5 degrees) as NTZ
-        if (Math.abs(this.longitude) < 0.5) {
-            return 'NTZ';
-        }
-        const prefix = 'NT';
-        const sign = this.longitude >= 0 ? '+' : '-';
-        const absLongitude = Math.abs(this.longitude);
-        const integerPart = Math.floor(absLongitude).toString().padStart(1, '0');
-        const decimalPart = decimals > 0
-            ? (absLongitude % 1).toFixed(decimals).substring(2)
-            : '';
-        return `${prefix}${sign}${integerPart}${decimals > 0 ? '.' + decimalPart : ''}`;
-    }
-    /**
-     * Exports the year part of the natural date.
-     *
-     * @returns Formatted year string
-     */
-    toYearString() {
-        const absYear = Math.abs(this.year);
-        const sign = this.year < 0 ? '-' : '';
-        return `${sign}${absYear.toString().padStart(3, '0')}`;
-    }
-    /**
-     * Exports the moon part of the natural date.
-     *
-     * @returns Formatted moon string
-     */
-    toMoonString() {
-        return this.moon.toString().padStart(2, '0');
-    }
-    /**
-     * Exports the day of moon part of the natural date.
-     *
-     * @returns Formatted day of moon string
-     */
-    toDayOfMoonString() {
-        return this.dayOfMoon.toString().padStart(2, '0');
-    }
-}
-/**
- * Number of milliseconds in a day
- */
-NaturalDate.MILLISECONDS_PER_DAY = 86400000; // 24 * 60 * 60 * 1000
-/**
- * End date of the artificial time era (December 21, 2012 12:00 UTC)
- * This is the reference point for natural time calculations
- */
-NaturalDate.END_OF_ARTIFICIAL_TIME = Date.UTC(2012, 11, 21, 12, 0, 0);
-/**
- * Clears the internal year context cache.
- * Exposed for testing or advanced usage without exposing the cache itself.
- */
-export function resetYearContextCache() {
-    yearContextCache.clear();
-}
-//# sourceMappingURL=NaturalDate.js.map

package/dist/core/NaturalDate.js.map

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

package/dist/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA0B,CAAC;AAE/D,oCAAoC;AACpC,OAAO,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAE3E;;GAEG;AACH,OAAO,EACH,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,OAAO,EACP,MAAM,EACT,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,mBAAmB,EAAE,CAAC;AAE/B;;GAEG;AACH,MAAM,UAAU,WAAW;IACvB,6DAA6D;IAC7D,qBAAqB,EAAE,CAAC;IACxB,mBAAmB,EAAE,CAAC;AAC1B,CAAC;AAED;;GAEG;AACH,OAAO,EACH,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACvB,MAAM,uBAAuB,CAAC;AAC/B,uFAAuF;AACvF,mFAAmF;AACnF,uFAAuF;AACvF,mFAAmF"}

package/dist/types/index.d.ts

@@ -1,118 +0,0 @@
-/**
- * Type definitions for natural-time-js
- */
-/**
- * Interface for NaturalDate class to avoid circular dependencies
- */
-export interface INaturalDate {
-    /** Artificial gregorian date (UNIX timestamp) */
-    unixTime: number;
-    /** Longitude in degrees (-180 to 180) */
-    longitude: number;
-    /** Current year (year 1: 2012/2013) */
-    year: number;
-    /** Current moon (between 1 and 14) */
-    moon: number;
-    /** Current week (between 1 and 53) */
-    week: number;
-    /** Current week of the moon (between 1 and 4) */
-    weekOfMoon: number;
-    /** Number of days passed since END_OF_ARTIFICIAL_TIME */
-    day: number;
-    /** Current day of the year (between 1 and 366) */
-    dayOfYear: number;
-    /** Current day of the moon (between 1 and 28) */
-    dayOfMoon: number;
-    /** Current day of the week (between 1 and 7) */
-    dayOfWeek: number;
-    /** True if current day is rainbow day */
-    isRainbowDay: boolean;
-    /** Current time (between 0 and 359.999...) */
-    time: number;
-    /** Beginning of the year at the current longitude (UNIX timestamp) */
-    yearStart: number;
-    /** Numbers of days in the current year (between 365 and 366) */
-    yearDuration: number;
-    /** Beginning of the day at the current longitude (UNIX timestamp) */
-    nadir: number;
-}
-/**
- * Year context for natural date calculations
- */
-export interface YearContext {
-    /** Start timestamp of the year */
-    start: number;
-    /** Duration of the year in days */
-    duration: number;
-}
-/**
- * Sun altitude information
- */
-export interface SunAltitude {
-    /** Current altitude of the sun in degrees */
-    altitude: number;
-    /** Highest altitude the sun will reach on this day */
-    highestAltitude: number;
-}
-/**
- * Sun events throughout the day
- */
-export interface SunEvents {
-    /** Time of sunrise in degrees (0-360) or false if no sunrise */
-    sunrise: number | false;
-    /** Time of sunset in degrees (0-360) or false if no sunset */
-    sunset: number | false;
-    /** Time when night starts in degrees (0-360) or false if no night start */
-    nightStart: number | false;
-    /** Time when night ends in degrees (0-360) or false if no night end */
-    nightEnd: number | false;
-    /** Time when morning golden hour starts in degrees (0-360) or false if no morning golden hour */
-    morningGoldenHour: number | false;
-    /** Time when evening golden hour starts in degrees (0-360) or false if no evening golden hour */
-    eveningGoldenHour: number | false;
-}
-/**
- * Moon position information
- */
-export interface MoonPosition {
-    /** Moon phase in degrees (0-360) */
-    phase: number;
-    /** Current altitude of the moon in degrees */
-    altitude: number;
-    /** Highest altitude the moon will reach on this day */
-    highestAltitude: number;
-}
-/**
- * Moon events throughout the day
- */
-export interface MoonEvents {
-    /** Time of moonrise in degrees (0-360) or false if no moonrise */
-    moonrise: number | false;
-    /** Time of moonset in degrees (0-360) or false if no moonset */
-    moonset: number | false;
-}
-/**
- * Hemisphere identifiers
- */
-export declare enum Hemisphere {
-    NORTH = "NORTH",
-    SOUTH = "SOUTH"
-}
-/**
- * Season day markers
- */
-export interface Seasons {
-    /** Day 91 (typically April 1st) */
-    SUMMER_START_DAY: number;
-    /** Day 273 (typically September 30th) */
-    SUMMER_END_DAY: number;
-}
-/**
- * Solar altitude thresholds
- */
-export interface Angles {
-    /** Night altitude threshold in degrees */
-    NIGHT_ALTITUDE: number;
-    /** Golden hour altitude threshold in degrees */
-    GOLDEN_HOUR_ALTITUDE: number;
-}

package/dist/types/index.js

@@ -1,12 +0,0 @@
-/**
- * Type definitions for natural-time-js
- */
-/**
- * Hemisphere identifiers
- */
-export var Hemisphere;
-(function (Hemisphere) {
-    Hemisphere["NORTH"] = "NORTH";
-    Hemisphere["SOUTH"] = "SOUTH";
-})(Hemisphere || (Hemisphere = {}));
-//# sourceMappingURL=index.js.map

package/dist/types/index.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAkGH;;GAEG;AACH,MAAM,CAAN,IAAY,UAGX;AAHD,WAAY,UAAU;IACpB,6BAAe,CAAA;IACf,6BAAe,CAAA;AACjB,CAAC,EAHW,UAAU,KAAV,UAAU,QAGrB"}

package/dist/utils/validators.d.ts

@@ -1,140 +0,0 @@
-/**
- * @module natural-time-js/validators
- * @description Validation utilities for natural time calculations.
- * This module provides functions to validate inputs for natural time operations,
- * ensuring that values are within acceptable ranges and of the correct types.
- */
-import { NaturalDate } from '../core/NaturalDate.js';
-/**
- * Validates if a value is a finite number.
- *
- * This is a utility function that checks if a value is a valid number
- * (not NaN, not Infinity, and actually a number type).
- *
- * @param value - Value to validate
- * @returns True if value is a valid number
- *
- * @example
- * isValidNumber(42); // true
- * isValidNumber('42'); // false (string, not number)
- * isValidNumber(NaN); // false
- * isValidNumber(Infinity); // false
- */
-export declare const isValidNumber: (value: unknown) => value is number;
-/**
- * Validates if a latitude value is within the valid range.
- *
- * Latitude must be a number between -90° (South Pole) and 90° (North Pole).
- *
- * @param latitude - Latitude in degrees to validate
- * @returns True if latitude is valid
- *
- * @example
- * isValidLatitude(45.5); // true
- * isValidLatitude(-90); // true (South Pole)
- * isValidLatitude(90); // true (North Pole)
- * isValidLatitude(91); // false (out of range)
- */
-export declare const isValidLatitude: (latitude: unknown) => latitude is number;
-/**
- * Validates if a longitude value is within the valid range.
- *
- * Longitude must be a number between -180° and 180°, where:
- * - 0° is the Prime Meridian (Greenwich)
- * - Positive values are East longitude
- * - Negative values are West longitude
- *
- * @param longitude - Longitude in degrees to validate
- * @returns True if longitude is valid
- *
- * @example
- * isValidLongitude(0); // true (Prime Meridian)
- * isValidLongitude(180); // true (International Date Line)
- * isValidLongitude(-180); // true (International Date Line)
- * isValidLongitude(181); // false (out of range)
- */
-export declare const isValidLongitude: (longitude: unknown) => longitude is number;
-/**
- * Validates if an angle value is within the valid range.
- *
- * Angles in natural time are measured in degrees from 0° to 360°,
- * representing a full circle. This is used for time of day and
- * celestial positions.
- *
- * @param angle - Angle in degrees to validate
- * @returns True if angle is valid
- *
- * @example
- * isValidAngle(180); // true (half circle)
- * isValidAngle(360); // true (full circle)
- * isValidAngle(0); // true (beginning of circle)
- * isValidAngle(361); // false (out of range)
- * isValidAngle(-1); // false (out of range)
- */
-export declare const isValidAngle: (angle: unknown) => angle is number;
-/**
- * Validates if a timestamp is a valid Unix time.
- *
- * Unix timestamps represent the number of milliseconds since
- * January 1, 1970, 00:00:00 UTC (the Unix epoch).
- * Valid timestamps must be positive numbers.
- *
- * @param timestamp - Unix timestamp in milliseconds
- * @returns True if timestamp is valid
- *
- * @example
- * isValidTimestamp(Date.now()); // true
- * isValidTimestamp(0); // false (Unix epoch exactly)
- * isValidTimestamp(-1); // false (before Unix epoch)
- */
-export declare const isValidTimestamp: (timestamp: unknown) => timestamp is number;
-/**
- * Validates if an object is a properly initialized NaturalDate instance.
- *
- * This function performs a comprehensive check of a NaturalDate object,
- * verifying that all properties are present and within valid ranges.
- * It's used to ensure that only valid NaturalDate objects are used in calculations.
- *
- * @param date - Value to validate
- * @returns True if value is a valid NaturalDate instance
- *
- * @example
- * const naturalDate = new NaturalDate(new Date(), 0);
- * isValidNaturalDate(naturalDate); // true
- *
- * isValidNaturalDate({}); // false (not a NaturalDate instance)
- * isValidNaturalDate(null); // false
- */
-export declare const isValidNaturalDate: (date: unknown) => date is NaturalDate;
-/**
- * Validates if a string is a valid cache key.
- *
- * Cache keys are used for storing and retrieving calculated values
- * to improve performance. Valid keys must be non-empty strings.
- *
- * @param key - Cache key to validate
- * @returns True if key is valid
- *
- * @example
- * isValidCacheKey('SUN_2023_45.5_0'); // true
- * isValidCacheKey(''); // false (empty string)
- * isValidCacheKey(123); // false (not a string)
- */
-export declare const isValidCacheKey: (key: unknown) => key is string;
-/**
- * Throws a formatted error for invalid parameters.
- *
- * This utility function creates consistent error messages for validation failures,
- * making it easier to identify and fix issues with invalid inputs.
- *
- * @param paramName - Name of the invalid parameter
- * @param value - Invalid value
- * @param expectedType - Description of expected type/format
- * @throws {Error} Formatted validation error
- *
- * @example
- * // If latitude is invalid:
- * throwValidationError('latitude', 95, 'number between -90 and 90');
- * // Throws: "Error: Invalid latitude: 95. Expected number between -90 and 90"
- */
-export declare const throwValidationError: (paramName: string, value: unknown, expectedType: string) => never;