natural-time-js 2.0.6 → 3.0.0

package/README.md

@@ -46,21 +46,35 @@ The core class for working with Natural Time:
 ```javascript
 import { NaturalDate } from 'natural-time-js';
 
-// Convert current time at longitude 5.2° E
-const naturalDate = new NaturalDate(new Date(), 5.2);
-console.log(naturalDate.toString()); // "004)04)01 113°00 NT+5.2"
+// Default (precision=0): longitude is truncated to the nearest integer zone
+// Paris 2.3522° → calculated as NT+2
+const naturalDate = new NaturalDate(new Date(), 2.3522);
+console.log(naturalDate.toString()); // "013)04)01 113°00 NT+2"
+
+// Analog mode (precision=Infinity): uses exact longitude
+const naturalDateAnalog = new NaturalDate(new Date(), 2.3522, Infinity);
 ```
 
+The third argument `precision` controls how many decimal places of longitude are used for calculations:
+
+| `precision` | Effective longitude | Zones |
+|-------------|--------------------:|------:|
+| `0` (default) | `Math.trunc(lon)` → e.g. 2.3° → 2° | 360 |
+| `1` | Truncated to 0.1° → e.g. 2.3522° → 2.3° | 3600 |
+| `Infinity` | Exact longitude — fully analog | ∞ |
+
 #### Properties
 
 ```javascript
 // Time Properties
-naturalDate.unixTime;    // Artificial gregorian date (UNIX timestamp)
-naturalDate.time;        // Current time in degrees (0-359.999...)
-naturalDate.nadir;       // Beginning of the day at current longitude (UNIX timestamp)
+naturalDate.unixTime;          // Artificial gregorian date (UNIX timestamp)
+naturalDate.time;              // Current time in degrees (0-359.999...)
+naturalDate.nadir;             // Beginning of the day at current longitude (UNIX timestamp)
 
 // Location
-naturalDate.longitude;   // Longitude (-180° to +180°)
+naturalDate.longitude;         // Raw longitude as provided (-180° to +180°)
+naturalDate.precision;         // Decimal places used in calculations (default: 0)
+naturalDate.effectiveLongitude;// Longitude actually used in calculations (truncated to precision)
 
 // Year Properties
 naturalDate.year;        // Current year (year 1: 2012/2013)
@@ -89,10 +103,12 @@ NaturalDate.MILLISECONDS_PER_DAY;   // 86400000 (24*60*60*1000)
 #### Utility Methods
 
 ```javascript
-naturalDate.toString();              // "004)04)01 113°00 NT+5.2"
+naturalDate.toString();              // "004)04)01 113°00 NT+5"  (precision=0 default)
 naturalDate.toDateString();          // "004)04)01"
 naturalDate.toTimeString();          // "113°00"
-naturalDate.toLongitudeString();     // "NT+5.2"
+naturalDate.toTimeString(0);         // "113°"                   (cut, never rounded)
+naturalDate.toLongitudeString();     // "NT+5"                   (matches precision)
+naturalDate.toLongitudeString(1);    // "NT+5.2"                 (explicit decimals)
 naturalDate.toYearString();          // "004"
 naturalDate.toMoonString();          // "04"
 naturalDate.toDayOfMoonString();     // "01"
@@ -103,13 +119,18 @@ naturalDate.toDayOfMoonString();     // "01"
 Calculate precise celestial events and positions:
 
 ```javascript
-import { NaturalSunEvents, NaturalMoonPosition } from 'natural-time-js';
+import { NaturalDate, NaturalSunPosition, NaturalSunEvents, NaturalMoonPosition } from 'natural-time-js';
 
 // Giza Pyramid coordinates
 const latitude = 29.9791;
 const longitude = 31.1341;
 const naturalDate = new NaturalDate(new Date(), longitude);
 
+// Get current sun position
+const sunPosition = NaturalSunPosition(naturalDate, latitude);
+console.log(sunPosition.azimuth);    // 178.421° (clockwise from north)
+console.log(sunPosition.elevation);  // 64.323° (negative below horizon)
+
 // Get sun events for the day
 const sunEvents = NaturalSunEvents(naturalDate, latitude);
 console.log(sunEvents.sunrise);  // 70.567° (time in natural degrees)
@@ -117,29 +138,13 @@ console.log(sunEvents.sunset);   // 287.910°
 
 // Get current moon position and phase
 const moonInfo = NaturalMoonPosition(naturalDate, latitude);
-console.log(moonInfo.phase);     // 74.861° (percentage of lunar cycle)
+console.log(moonInfo.phase);     // 74.861° (0° new moon, 180° full moon)
 console.log(moonInfo.altitude);  // 64.323° (degrees above horizon)
 ```
 
-## Documentation
-
-The library is fully documented using JSDoc. Generate the documentation with:
-
-```bash
-npm run docs
-```
-
-For live documentation updates during development:
-
-```bash
-npm run docs:dev
-```
-
-This creates HTML documentation in the `docs` directory.
-
 ## Contribute
 
-Natural time is open to contributions from free-thinking minds. Find your way through Github or email at: [sylvain441@proton.me](mailto:sylvain441@proton.me) to get in touch.
+Natural time is open to contributions from free-thinking minds. Find your way through Github or email at: [sylvain@biquette.xyz](mailto:sylvain@biquette.xyz) to get in touch.
 
 ## License
 
@@ -158,4 +163,4 @@ It was a real pleasure to give birth of natural time during the spring/summer of
 
 🌍 One love 🌎
 
-🏔 🐐 🌞 🌈
+🏔 🐐 🌞 🌈

package/dist/NaturalDate.d.ts

@@ -0,0 +1,61 @@
+export declare function cached<T>(key: string, compute: () => T): T;
+export declare function resetCaches(): void;
+export declare class NaturalDate {
+    static readonly MILLISECONDS_PER_DAY = 86400000;
+    /** 2012-12-21 12:00 UTC: year 001 begins, artificial time ends. */
+    static readonly END_OF_ARTIFICIAL_TIME: number;
+    readonly unixTime: number;
+    /** As given, east positive. */
+    readonly longitude: number;
+    readonly precision: number;
+    /** The longitude the clock runs on: `longitude` cut to `precision` decimals. */
+    readonly effectiveLongitude: number;
+    readonly year: number;
+    /** 1 to 13, and 14 for the Rainbow day(s). */
+    readonly moon: number;
+    /** 1 to 53. */
+    readonly week: number;
+    /** 1 to 4. */
+    readonly weekOfMoon: number;
+    /** Days since END_OF_ARTIFICIAL_TIME. */
+    readonly day: number;
+    /** 1 to 366. */
+    readonly dayOfYear: number;
+    /** 1 to 28. */
+    readonly dayOfMoon: number;
+    /** 1 to 7. */
+    readonly dayOfWeek: number;
+    readonly isRainbowDay: boolean;
+    /** Degrees since natural midnight, 0 to 360: 180 is noon. */
+    readonly time: number;
+    /** Unix ms. */
+    readonly yearStart: number;
+    /** 365 or 366 days. */
+    readonly yearDuration: number;
+    /** Natural midnight that opened the day, unix ms. */
+    readonly nadir: number;
+    /**
+     * @param date `null` or `undefined` for now.
+     * @param longitude Degrees, -180 to 180, east positive.
+     * @param precision Decimals of longitude the clock runs on, cut and never rounded:
+     *   0 gives 360 zones (2.3522 runs on 2), 1 gives 3600 (2.3), `Infinity` the exact sun.
+     */
+    constructor(date?: Date | number | string | null, longitude?: number, precision?: number);
+    /** Degrees of `event` within this natural day, or false if it falls outside. */
+    getTimeOfEvent(event: Date | number | string): number | false;
+    /** `013)04)01 113°00 NT+2` */
+    toString(): string;
+    /** `013)04)01`, `013)RAINBOW`, `013)RAINBOW+` */
+    toDateString(separator?: string): string;
+    /** `202°99`: cut to `decimals`, never rounded. It is 202° until the sun reaches 203°. */
+    toTimeString(decimals?: number): string;
+    /**
+     * `NT+2.3`, `NT-73`, `NTZ` when nothing is left once cut. Decimals default to
+     * `precision` (0 when exact): the label names the longitude the clock runs on.
+     */
+    toLongitudeString(decimals?: number): string;
+    /** `013`, `-042` before year 1. */
+    toYearString(): string;
+    toMoonString(): string;
+    toDayOfMoonString(): string;
+}

package/dist/NaturalDate.js

@@ -0,0 +1,138 @@
+import { Seasons } from 'astronomy-engine';
+// One cache for everything the sky makes us compute twice. It forgets its oldest
+// entry beyond 512: a clock left open for years, or a longitude slider dragged
+// around the Earth, stays small.
+const cache = new Map();
+export function cached(key, compute) {
+    if (cache.has(key))
+        return cache.get(key);
+    const value = compute();
+    if (cache.size >= 512)
+        cache.delete(cache.keys().next().value);
+    cache.set(key, value);
+    return value;
+}
+export function resetCaches() {
+    cache.clear();
+}
+const DAY = 86400000;
+// Floats cannot hold 73.57: times 100 it is 7356.999999999999, and a plain cut would
+// move the observer to 73.56. One part in a million million, added before the cut,
+// puts it back. C and Python add the very same hair.
+const HAIR = 1.000000000001;
+// The natural year opens at noon UTC on the day of the winter solstice (the next
+// day if the solstice falls after noon), then waits for the sun to reach the longitude.
+const newYear = (artificialYear) => {
+    const solstice = Seasons(artificialYear).dec_solstice.date;
+    return Date.UTC(solstice.getUTCFullYear(), solstice.getUTCMonth(), solstice.getUTCDate() + (solstice.getUTCHours() >= 12 ? 1 : 0), 12);
+};
+const yearContext = (artificialYear, longitude) => cached(`YEAR_${artificialYear}_${longitude}`, () => {
+    const start = newYear(artificialYear);
+    return {
+        start: Math.trunc(start + (-longitude + 180) * DAY / 360),
+        duration: (newYear(artificialYear + 1) - start) / DAY
+    };
+});
+export class NaturalDate {
+    /**
+     * @param date `null` or `undefined` for now.
+     * @param longitude Degrees, -180 to 180, east positive.
+     * @param precision Decimals of longitude the clock runs on, cut and never rounded:
+     *   0 gives 360 zones (2.3522 runs on 2), 1 gives 3600 (2.3), `Infinity` the exact sun.
+     */
+    constructor(date, longitude, precision = 0) {
+        // NaN compares false to everything: only a positive test refuses it
+        if (longitude !== undefined && !(typeof longitude === 'number' && longitude >= -180 && longitude <= 180)) {
+            throw new Error('Longitude must be between -180 and +180');
+        }
+        // ?? and not ||: 0 is a moment like any other
+        const unixTime = new Date(date ?? Date.now()).getTime();
+        if (isNaN(unixTime)) {
+            throw new Error('Invalid date provided');
+        }
+        this.unixTime = unixTime;
+        this.longitude = longitude || 0;
+        this.precision = precision;
+        this.effectiveLongitude = precision === Infinity
+            ? this.longitude
+            : Math.trunc(this.longitude * Math.pow(10, precision) * HAIR) / Math.pow(10, precision);
+        // The natural year began at the last winter solstice, or at the one closing this artificial year
+        const artificialYear = new Date(unixTime).getUTCFullYear();
+        let context = yearContext(artificialYear - 1, this.effectiveLongitude);
+        if (unixTime - context.start >= context.duration * DAY) {
+            context = yearContext(artificialYear, this.effectiveLongitude);
+        }
+        this.yearStart = context.start;
+        this.yearDuration = context.duration;
+        // C and Python repeat these operations in this order: same floats, same answers
+        const elapsed = (unixTime - this.yearStart) / DAY;
+        const days = Math.floor(elapsed);
+        const weeks = Math.floor(elapsed / 7);
+        this.year = new Date(this.yearStart).getUTCFullYear() - 2011;
+        this.moon = Math.floor(elapsed / 28) + 1;
+        this.week = weeks + 1;
+        this.weekOfMoon = weeks % 4 + 1;
+        this.day = Math.floor((unixTime - (NaturalDate.END_OF_ARTIFICIAL_TIME + (-this.effectiveLongitude + 180) * DAY / 360)) / DAY);
+        this.dayOfYear = days + 1;
+        this.dayOfMoon = days % 28 + 1;
+        this.dayOfWeek = days % 7 + 1;
+        this.isRainbowDay = this.dayOfYear > 13 * 28;
+        this.nadir = this.yearStart + days * DAY;
+        this.time = (unixTime - this.nadir) * 360 / DAY;
+    }
+    /** Degrees of `event` within this natural day, or false if it falls outside. */
+    getTimeOfEvent(event) {
+        const eventTime = new Date(event).getTime();
+        if (eventTime < this.nadir || eventTime > this.nadir + DAY)
+            return false;
+        // 360 / DAY first, unlike `time`: the copies in C and Python do the same
+        return (eventTime - this.nadir) * (360 / DAY);
+    }
+    /** `013)04)01 113°00 NT+2` */
+    toString() {
+        return `${this.toDateString()} ${this.toTimeString()} ${this.toLongitudeString()}`;
+    }
+    /** `013)04)01`, `013)RAINBOW`, `013)RAINBOW+` */
+    toDateString(separator = ')') {
+        if (this.isRainbowDay) {
+            return `${this.toYearString()}${separator}RAINBOW${this.dayOfYear === 366 ? '+' : ''}`;
+        }
+        return `${this.toYearString()}${separator}${this.toMoonString()}${separator}${this.toDayOfMoonString()}`;
+    }
+    /** `202°99`: cut to `decimals`, never rounded. It is 202° until the sun reaches 203°. */
+    toTimeString(decimals = 2) {
+        // The hair added before the cut repairs floats (20263.999999999996 is 20264),
+        // it is far thinner than a millisecond of sun
+        const scale = Math.pow(10, Math.max(0, Math.trunc(decimals)));
+        const total = Math.floor(this.time * scale + 1e-6);
+        const whole = Math.floor(total / scale) % 360;
+        const fraction = scale > 1 ? (total % scale).toString().padStart(Math.trunc(decimals), '0') : '';
+        return `${whole.toString().padStart(3, '0')}°${fraction}`;
+    }
+    /**
+     * `NT+2.3`, `NT-73`, `NTZ` when nothing is left once cut. Decimals default to
+     * `precision` (0 when exact): the label names the longitude the clock runs on.
+     */
+    toLongitudeString(decimals = Number.isFinite(this.precision) ? this.precision : 0) {
+        const scale = Math.pow(10, Math.max(0, Math.trunc(decimals)));
+        const scaled = Math.trunc(Math.abs(this.longitude) * scale * HAIR);
+        if (scaled === 0)
+            return 'NTZ';
+        const sign = this.longitude >= 0 ? '+' : '-';
+        const fraction = scale > 1 ? '.' + (scaled % scale).toString().padStart(Math.trunc(decimals), '0') : '';
+        return `NT${sign}${Math.floor(scaled / scale)}${fraction}`;
+    }
+    /** `013`, `-042` before year 1. */
+    toYearString() {
+        return `${this.year < 0 ? '-' : ''}${Math.abs(this.year).toString().padStart(3, '0')}`;
+    }
+    toMoonString() {
+        return this.moon.toString().padStart(2, '0');
+    }
+    toDayOfMoonString() {
+        return this.dayOfMoon.toString().padStart(2, '0');
+    }
+}
+NaturalDate.MILLISECONDS_PER_DAY = DAY;
+/** 2012-12-21 12:00 UTC: year 001 begins, artificial time ends. */
+NaturalDate.END_OF_ARTIFICIAL_TIME = Date.UTC(2012, 11, 21, 12);

package/dist/ephemeris.d.ts

@@ -0,0 +1,47 @@
+import { NaturalDate } from './NaturalDate.js';
+/** Azimuth clockwise from north; elevation signed, altitude clamped to the horizon. */
+export declare function NaturalSunPosition(naturalDate: NaturalDate, latitude: number): {
+    azimuth: number;
+    elevation: number;
+    altitude: number;
+    highestAltitude: number;
+    isAboveHorizon: boolean;
+};
+export declare function NaturalSunAltitude(naturalDate: NaturalDate, latitude: number): {
+    altitude: number;
+    highestAltitude: number;
+};
+/**
+ * When the sun rises, sets, crosses -12° (night) and 6° (golden hour) this natural day.
+ * Where it never does, the day runs from 0° to 360° in summer and shrinks to 180° in winter.
+ */
+export declare function NaturalSunEvents(naturalDate: NaturalDate, latitude: number): {
+    sunrise: number;
+    sunset: number;
+    nightStart: number;
+    nightEnd: number;
+    morningGoldenHour: number;
+    eveningGoldenHour: number;
+};
+/** Altitude clamped to the horizon; phase 0° new moon, 180° full. */
+export declare function NaturalMoonPosition(naturalDate: NaturalDate, latitude: number): {
+    altitude: number;
+    phase: number;
+};
+/** Moonrise and moonset this natural day, 0 when the moon skips one. */
+export declare function NaturalMoonEvents(naturalDate: NaturalDate, latitude: number): {
+    moonrise: number;
+    moonset: number;
+    highestAltitude: number;
+};
+/**
+ * The mustaches: sunrise and sunset at both solstices of the year, seen from NT 0,
+ * and how far they swing on average (0 to 90).
+ */
+export declare function MustachesRange(naturalDate: NaturalDate, latitude: number): {
+    winterSunrise: number;
+    winterSunset: number;
+    summerSunrise: number;
+    summerSunset: number;
+    averageMustacheAngle: number;
+};

package/dist/ephemeris.js

@@ -0,0 +1,111 @@
+import { Body, Equator, Horizon, MoonPhase, Observer, SearchAltitude, SearchHourAngle, SearchRiseSet, Seasons } from 'astronomy-engine';
+import { NaturalDate, cached } from './NaturalDate.js';
+// Every function here answers for a NaturalDate seen from a latitude in degrees.
+// Results are angles in degrees: events in natural degrees of the day (0 at
+// midnight, 180 at noon), positions as the sky gives them.
+function observer(naturalDate, latitude) {
+    if (!(naturalDate instanceof NaturalDate)) {
+        throw new Error(`Invalid naturalDate: ${naturalDate}. Expected NaturalDate instance`);
+    }
+    if (!(typeof latitude === 'number' && latitude >= -90 && latitude <= 90)) {
+        throw new Error(`Invalid latitude: ${latitude}. Expected number between -90 and 90`);
+    }
+    // The sky is seen from the longitude as given: precision shapes the clock, not the Earth
+    return new Observer(latitude, naturalDate.longitude, 0);
+}
+const at = (naturalDate, found, otherwise) => found ? naturalDate.getTimeOfEvent(found.date) || 0 : otherwise;
+/** Azimuth clockwise from north; elevation signed, altitude clamped to the horizon. */
+export function NaturalSunPosition(naturalDate, latitude) {
+    const place = observer(naturalDate, latitude);
+    const date = new Date(naturalDate.unixTime);
+    const sun = Equator(Body.Sun, date, place, true, false);
+    const { azimuth, altitude } = Horizon(date, place, sun.ra, sun.dec);
+    return {
+        azimuth,
+        elevation: altitude,
+        altitude: Math.max(altitude, 0),
+        highestAltitude: SearchHourAngle(Body.Sun, place, 0, new Date(naturalDate.nadir)).hor.altitude,
+        isAboveHorizon: altitude >= 0
+    };
+}
+export function NaturalSunAltitude(naturalDate, latitude) {
+    const { altitude, highestAltitude } = NaturalSunPosition(naturalDate, latitude);
+    return { altitude, highestAltitude };
+}
+/**
+ * When the sun rises, sets, crosses -12° (night) and 6° (golden hour) this natural day.
+ * Where it never does, the day runs from 0° to 360° in summer and shrinks to 180° in winter.
+ */
+export function NaturalSunEvents(naturalDate, latitude) {
+    const place = observer(naturalDate, latitude);
+    // Two precisions of one longitude share a date but not a midnight: the nadir tells them apart
+    return cached(`SUN_${naturalDate.nadir}_${latitude}_${naturalDate.longitude}`, () => {
+        const nadir = new Date(naturalDate.nadir);
+        // Natural days 91 to 273 are summer in the north; both ends belong to both hemispheres
+        const d = naturalDate.dayOfYear;
+        const summer = latitude >= 0 ? d >= 91 && d <= 273 : d <= 91 || d >= 273;
+        const rising = summer ? 0 : 180;
+        const setting = summer ? 360 : 180;
+        const crossing = (direction, altitude) => at(naturalDate, SearchAltitude(Body.Sun, place, direction, nadir, 2, altitude), direction > 0 ? rising : setting);
+        return {
+            sunrise: at(naturalDate, SearchRiseSet(Body.Sun, place, +1, nadir, 1), rising),
+            sunset: at(naturalDate, SearchRiseSet(Body.Sun, place, -1, nadir, 1), setting),
+            nightStart: crossing(-1, -12),
+            nightEnd: crossing(+1, -12),
+            morningGoldenHour: crossing(+1, 6),
+            eveningGoldenHour: crossing(-1, 6)
+        };
+    });
+}
+/** Altitude clamped to the horizon; phase 0° new moon, 180° full. */
+export function NaturalMoonPosition(naturalDate, latitude) {
+    const place = observer(naturalDate, latitude);
+    const date = new Date(naturalDate.unixTime);
+    const moon = Equator(Body.Moon, date, place, true, false);
+    return {
+        altitude: Math.max(Horizon(date, place, moon.ra, moon.dec).altitude, 0),
+        phase: MoonPhase(date)
+    };
+}
+/** Moonrise and moonset this natural day, 0 when the moon skips one. */
+export function NaturalMoonEvents(naturalDate, latitude) {
+    const place = observer(naturalDate, latitude);
+    return cached(`MOON_${naturalDate.nadir}_${latitude}_${naturalDate.longitude}`, () => {
+        const nadir = new Date(naturalDate.nadir);
+        return {
+            moonrise: at(naturalDate, SearchRiseSet(Body.Moon, place, +1, nadir, 1), 0),
+            moonset: at(naturalDate, SearchRiseSet(Body.Moon, place, -1, nadir, 1), 0),
+            highestAltitude: SearchHourAngle(Body.Moon, place, 0, nadir).hor.altitude
+        };
+    });
+}
+/**
+ * The mustaches: sunrise and sunset at both solstices of the year, seen from NT 0,
+ * and how far they swing on average (0 to 90).
+ */
+export function MustachesRange(naturalDate, latitude) {
+    observer(naturalDate, latitude);
+    // UTC year: the sky does not care which time zone the machine was sold in
+    const year = new Date(naturalDate.unixTime).getUTCFullYear();
+    try {
+        return cached(`MUSTACHES_${year}_${latitude}`, () => {
+            const seasons = Seasons(year);
+            const winter = NaturalSunEvents(new NaturalDate(seasons.dec_solstice.date, 0), latitude);
+            const summer = NaturalSunEvents(new NaturalDate(seasons.jun_solstice.date, 0), latitude);
+            const swing = latitude >= 0
+                ? (winter.sunrise - summer.sunrise + summer.sunset - winter.sunset) / 4
+                : (summer.sunrise - winter.sunrise + winter.sunset - summer.sunset) / 4;
+            return {
+                winterSunrise: winter.sunrise,
+                winterSunset: winter.sunset,
+                summerSunrise: summer.sunrise,
+                summerSunset: summer.sunset,
+                averageMustacheAngle: Math.min(Math.max(swing, 0), 90)
+            };
+        });
+    }
+    catch {
+        // Should the engine give up on a search, a clock without mustaches is still a clock (C does the same)
+        return { winterSunrise: 0, winterSunset: 0, summerSunrise: 0, summerSunset: 0, averageMustacheAngle: 0 };
+    }
+}

package/dist/index.d.ts

@@ -1,80 +1,2 @@
-/**
- * @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 2.0.2
- */
-import { resetAstronomyCache } from './astronomy/celestial.js';
-export { NaturalDate, resetYearContextCache } from './core/NaturalDate.js';
-/**
- * Astronomical functions and constants for natural time calculations
- */
-export { NaturalSunAltitude, NaturalSunEvents, NaturalMoonPosition, NaturalMoonEvents, MustachesRange, HEMISPHERES, SEASONS, ANGLES } from './astronomy/celestial.js';
-export { resetAstronomyCache };
-/**
- * Resets all internal caches used by the library.
- */
-export declare function resetCaches(): void;
-/**
- * Utility functions for validation and error handling
- */
-export { isValidLatitude, isValidLongitude, isValidAngle, isValidTimestamp, isValidNaturalDate, isValidCacheKey, throwValidationError } from './utils/validators.js';
+export { NaturalDate, resetCaches } from './NaturalDate.js';
+export { NaturalSunPosition, NaturalSunAltitude, NaturalSunEvents, NaturalMoonPosition, NaturalMoonEvents, MustachesRange } from './ephemeris.js';

package/dist/index.js

@@ -1,91 +1,3 @@
-/**
- * @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 2.0.2
- */
-import { resetYearContextCache } from './core/NaturalDate.js';
-import { resetAstronomyCache } from './astronomy/celestial.js';
-// Export the core NaturalDate class
-export { NaturalDate, resetYearContextCache } from './core/NaturalDate.js';
-/**
- * Astronomical functions and constants for natural time calculations
- */
-export { NaturalSunAltitude, NaturalSunEvents, NaturalMoonPosition, NaturalMoonEvents, MustachesRange, HEMISPHERES, SEASONS, ANGLES } from './astronomy/celestial.js';
-export { resetAstronomyCache };
-/**
- * Resets all internal caches used by the library.
- */
-export function resetCaches() {
-    // Directly call the exported reset functions to clear caches
-    resetYearContextCache();
-    resetAstronomyCache();
-}
-/**
- * Utility functions for validation and error handling
- */
-export { isValidLatitude, isValidLongitude, isValidAngle, isValidTimestamp, isValidNaturalDate, isValidCacheKey, throwValidationError } from './utils/validators.js';
-// NOTE: Consumers using Node ESM require explicit .js extensions for relative imports.
-// Keep all internal re-exports using the ".js" suffix to ensure SSR compatibility.
-// NOTE: Consumers using Node ESM require explicit .js extensions for relative imports.
-// Keep all internal re-exports using the ".js" suffix to ensure SSR compatibility.
-//# sourceMappingURL=index.js.map
+// Relative imports keep their .js: Node ESM (and SSR) will not guess it
+export { NaturalDate, resetCaches } from './NaturalDate.js';
+export { NaturalSunPosition, NaturalSunAltitude, NaturalSunEvents, NaturalMoonPosition, NaturalMoonEvents, MustachesRange } from './ephemeris.js';