natural-time-js 1.1.1 → 2.0.2

package/dist/core/NaturalDate.js

@@ -0,0 +1,254 @@
+/**
+ * @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);
+export { yearContextCache };
+//# sourceMappingURL=NaturalDate.js.map

package/dist/core/NaturalDate.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,74 @@
+/**
+ * @module natural-time-js
+ * @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.
+ * Our current Gregorian calendar is an artificial construct disconnected from natural cycles.
+ * Natural time realigns us with the observable patterns of the cosmos:
+ * It's time to return to the cosmic rhythms that have guided humanity for millennia.
+ * Learn more: https://naturaltime.app
+ *
+ * # Natural Time JavaScript Library
+ *
+ * This JavaScript library translates Gregorian (artificial) datetime to natural datetime.
+ * Natural time is defined by:
+ *
+ * - 360° circular time - replacing arbitrary hours with continuous movement
+ * - Make the sun back as the main source of time
+ * - Years beginning at the winter solstice
+ * - 13 perfect moons of 28 days = 364 days
+ * - "Rainbow day(s)" - Day out of time to make the year 365 or 366 days
+ *
+ * This is mathematical beauty aligned with astronomical reality.
+ *
+ * ## Basic Usage
+ *
+ * ```typescript
+ * import { NaturalDate } from 'natural-time-js';
+ *
+ * // Create a natural date for the current time at longitude 0
+ * const naturalDate = new NaturalDate(new Date(), 0);
+ *
+ * // Display the natural date
+ * console.log(naturalDate.toString());
+ * // Example output: "011)04)15 113°25 NTZ"
+ *
+ * // Get specific components
+ * console.log(`Year: ${naturalDate.year}`);
+ * console.log(`Moon: ${naturalDate.moon}`);
+ * console.log(`Day of moon: ${naturalDate.dayOfMoon}`);
+ * console.log(`Time: ${naturalDate.time}°`);
+ * ```
+ *
+ * ## Astronomical Functions
+ *
+ * The library provides astronomical functions for calculating sun and moon positions:
+ *
+ * ```typescript
+ * import { NaturalDate, NaturalSunEvents, NaturalMoonPosition } from 'natural-time-js';
+ *
+ * const naturalDate = new NaturalDate(new Date(), 0);
+ * const latitude = 45; // 45° North
+ *
+ * // Get sun events for the day
+ * const sunEvents = NaturalSunEvents(naturalDate, latitude);
+ * console.log(`Sunrise: ${sunEvents.sunrise}°`);
+ * console.log(`Sunset: ${sunEvents.sunset}°`);
+ *
+ * // Get moon position and phase
+ * const moonInfo = NaturalMoonPosition(naturalDate, latitude);
+ * console.log(`Moon phase: ${moonInfo.phase}°`);
+ * ```
+ *
+ * @author Sylvain 441
+ * @license CC0-1.0
+ * @version 1.1.1
+ */
+export { NaturalDate, yearContextCache } from './core/NaturalDate';
+/**
+ * Astronomical functions and constants for natural time calculations
+ */
+export { NaturalSunAltitude, NaturalSunEvents, NaturalMoonPosition, NaturalMoonEvents, MustachesRange, HEMISPHERES, SEASONS, ANGLES } from './astronomy/celestial';
+/**
+ * Utility functions for validation and error handling
+ */
+export { isValidLatitude, isValidLongitude, isValidAngle, isValidTimestamp, isValidNaturalDate, isValidCacheKey, throwValidationError } from './utils/validators';

package/dist/index.js

@@ -0,0 +1,76 @@
+/**
+ * @module natural-time-js
+ * @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.
+ * Our current Gregorian calendar is an artificial construct disconnected from natural cycles.
+ * Natural time realigns us with the observable patterns of the cosmos:
+ * It's time to return to the cosmic rhythms that have guided humanity for millennia.
+ * Learn more: https://naturaltime.app
+ *
+ * # Natural Time JavaScript Library
+ *
+ * This JavaScript library translates Gregorian (artificial) datetime to natural datetime.
+ * Natural time is defined by:
+ *
+ * - 360° circular time - replacing arbitrary hours with continuous movement
+ * - Make the sun back as the main source of time
+ * - Years beginning at the winter solstice
+ * - 13 perfect moons of 28 days = 364 days
+ * - "Rainbow day(s)" - Day out of time to make the year 365 or 366 days
+ *
+ * This is mathematical beauty aligned with astronomical reality.
+ *
+ * ## Basic Usage
+ *
+ * ```typescript
+ * import { NaturalDate } from 'natural-time-js';
+ *
+ * // Create a natural date for the current time at longitude 0
+ * const naturalDate = new NaturalDate(new Date(), 0);
+ *
+ * // Display the natural date
+ * console.log(naturalDate.toString());
+ * // Example output: "011)04)15 113°25 NTZ"
+ *
+ * // Get specific components
+ * console.log(`Year: ${naturalDate.year}`);
+ * console.log(`Moon: ${naturalDate.moon}`);
+ * console.log(`Day of moon: ${naturalDate.dayOfMoon}`);
+ * console.log(`Time: ${naturalDate.time}°`);
+ * ```
+ *
+ * ## Astronomical Functions
+ *
+ * The library provides astronomical functions for calculating sun and moon positions:
+ *
+ * ```typescript
+ * import { NaturalDate, NaturalSunEvents, NaturalMoonPosition } from 'natural-time-js';
+ *
+ * const naturalDate = new NaturalDate(new Date(), 0);
+ * const latitude = 45; // 45° North
+ *
+ * // Get sun events for the day
+ * const sunEvents = NaturalSunEvents(naturalDate, latitude);
+ * console.log(`Sunrise: ${sunEvents.sunrise}°`);
+ * console.log(`Sunset: ${sunEvents.sunset}°`);
+ *
+ * // Get moon position and phase
+ * const moonInfo = NaturalMoonPosition(naturalDate, latitude);
+ * console.log(`Moon phase: ${moonInfo.phase}°`);
+ * ```
+ *
+ * @author Sylvain 441
+ * @license CC0-1.0
+ * @version 1.1.1
+ */
+// Export the core NaturalDate class
+export { NaturalDate, yearContextCache } from './core/NaturalDate';
+/**
+ * Astronomical functions and constants for natural time calculations
+ */
+export { NaturalSunAltitude, NaturalSunEvents, NaturalMoonPosition, NaturalMoonEvents, MustachesRange, HEMISPHERES, SEASONS, ANGLES } from './astronomy/celestial';
+/**
+ * Utility functions for validation and error handling
+ */
+export { isValidLatitude, isValidLongitude, isValidAngle, isValidTimestamp, isValidNaturalDate, isValidCacheKey, throwValidationError } from './utils/validators';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AAEH,oCAAoC;AACpC,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAEnE;;GAEG;AACH,OAAO,EACH,kBAAkB,EAClB,gBAAgB,EAChB,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,WAAW,EACX,OAAO,EACP,MAAM,EACT,MAAM,uBAAuB,CAAC;AAE/B;;GAEG;AACH,OAAO,EACH,eAAe,EACf,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,oBAAoB,EACvB,MAAM,oBAAoB,CAAC"}

package/dist/types/index.d.ts

@@ -0,0 +1,118 @@
+/**
+ * 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

@@ -0,0 +1,12 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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"}