natural-time-js 1.1.1 → 2.0.2

package/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [2.0.1] - 2024-03-26
+
+### Fixed
+- Fixed Southern hemisphere mustache angle calculations
+- Added .npmignore file for better package distribution
+
+## [2.0.0]
+
+### Added
+- Switch to typescript
+- Documentation with JSDoc
+- Complete suite of test files with JEST
+- Reorganize files structure (breaking changes)
+
+## [1.1.1]
+
+### Fixed
+- Initial public release with basic functionality
+- Core natural time calculations
+- Basic formatting options 

package/README.md

@@ -1,161 +1,153 @@
-# Natural time - JavaScript
+# Natural Time JS
 
-Natural time is a fresh, elegant, and coherent way of measuring the movements of time here on the Earth.
+A revolutionary approach to time measurement, realigning human experience with nature's rhythms.
 
-This **new time standard** is based on common sense and the observation of natural cycles.
+## The Natural Time Paradigm
 
-![Natural time app](.github/natural-time-app.jpg)
-
-Play with natural time at [https://naturaltime.app/](https://naturaltime.app/)
-
-### JavaScript library
+Our current time system - the Gregorian calendar with its arbitrary months and 24-hour days - is a human construct disconnected from natural cycles. Natural Time proposes a return to cosmic truth:
 
-This repository contains the JavaScript implementation of natural time.  
 
-`index.js`: This class translates artificial dates to natural dates.  
-`context.js`: Collection of utility functions for calculating sky context and events like moon phase, sunrise and sunset ...
+- **Circular Time**: Days measured in 360 degrees, following the sun's continuous journey
+- **Location-Aware**: Time calculations adjusted to your longitude, acknowledging Earth's rotation
+- **Solar-Anchored Years**: Each year begins at winter solstice, nature's true new year marker
+- **13 Perfect Moons**: 28-day cycles matching the moon's natural rhythm (364 days)
+- **Rainbow Days**: 1-2 days outside the count to honor year completion and solar alignment
 
-### Natural time specifications
 
-How are natural years, moons, days, and time defined ?  
+This isn't just a calendar reform - it's a return to measuring time through observable celestial events that have guided humanity for millennia.
 
-Read the full specifications of natural time here: [github.com/sylvain441/natural-time](https://github.com/sylvain441/natural-time)
+## Try Natural Time
 
-### Web application
+🌟 **Experience it yourself!** The best way to understand Natural Time is to try it:
 
-You can play with natural time at [https://naturaltime.app/](https://naturaltime.app/). It both works online and offline thanks to this JavaScript library.
 
 ![Natural time app](.github/natural-time-app.jpg)
 
-# Javascript API
+- **Web App**: Visit [naturaltime.app](https://naturaltime.app/) to see it in action
+- **Source Code**: Explore the app's implementation at [github.com/sylvain441/natural-time-app](https://github.com/sylvain441/natural-time-app)
+- **Features**: 
+  - Works offline
+  - Location-aware time calculations
+  - Beautiful visualization of natural cycles
+  - Powered by this JavaScript library
 
-> If you know how to deal with typescript/typings/documentation this repo may appreciate your help. [Contribute here](#contribute)
-
-## Instalation
-
-Install NPM package with your terminal:
+## Installation
 
 ```console
 npm install natural-time-js
 ```
 
-## `NaturalDate` Class
+## Usage
+
+### NaturalDate Class
 
-The `NaturalDate` class translates artificial dates into natural dates.    
+The core class for working with Natural Time:
 
 ```javascript
 import { NaturalDate } from 'natural-time-js';
 
-let artificialDate = new Date();
-let longitude = 5.2;
-
-let naturalDate = new NaturalDate(artificialDate, longitude);
+// 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"
 ```
 
-Once instanciated, the `naturalDate` object holds many computed variables available for your usage:
+#### Properties
 
 ```javascript
-unixTime; // Artificial gregorian date (UNIX timestamp)
-longitude; // Longitude (between -180° to +180°)
-
-year; // Current year (year 1: 2012/2013)
-moon; // Current moon (between 1 and 14)
-
-week; // Current week (between 1 and 53)
-weekOfMoon; // Current week of the moon (between 1 and 4)
-
-day; // Number of days passed since END_OF_ARTIFICIAL_TIME
-dayOfYear; // Current day of the year (between 1 and 366)
-dayOfMoon; // Current day of the moon (between 1 and 28)
-dayOfWeek; // Current day of the week (between 1 and 7)
-
-isRainbowDay; // True if current day is rainbow day
-
-time; // Current time (between 0 and 359°999999...)
-
-yearStart; // Beginning of the year at the current longitude (UNIX timestamp)
-yearDuration; // Numbers of days in the current year (between 365 and 366)
-nadir; // Beginning of the day at the current longitude (UNIX timestamp)
-
-static END_OF_ARTIFICIAL_TIME = 1356091200000; // 2012-12-22 00:00:00 at +180° East;
-static MILLISECONDS_PER_DAY = 86400000; // 24*60*60*1000
+// 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)
+
+// Location
+naturalDate.longitude;   // Longitude (-180° to +180°)
+
+// Year Properties
+naturalDate.year;        // Current year (year 1: 2012/2013)
+naturalDate.yearStart;   // Beginning of the year at current longitude (UNIX timestamp)
+naturalDate.yearDuration;// Days in current year (365 or 366)
+naturalDate.dayOfYear;   // Current day of the year (1-366)
+
+// Moon Properties
+naturalDate.moon;        // Current moon (1-13, or 14 for rainbow days)
+naturalDate.dayOfMoon;   // Current day of the moon (1-28)
+naturalDate.weekOfMoon;  // Current week of the moon (1-4)
+
+// Week Properties
+naturalDate.week;        // Current week (1-53)
+naturalDate.dayOfWeek;   // Current day of the week (1-7)
+
+// Special Properties
+naturalDate.isRainbowDay;// True if current day is rainbow day
+naturalDate.day;         // Days since END_OF_ARTIFICIAL_TIME
+
+// Constants
+NaturalDate.END_OF_ARTIFICIAL_TIME; // 1356091200000 (2012-12-21 12:00:00 UTC)
+NaturalDate.MILLISECONDS_PER_DAY;   // 86400000 (24*60*60*1000)
 ```
 
-**Utility functions**  
+#### Utility Methods
 
-```javascript   
-naturalDate.toString() // "004)04)01 113°00 NT+5.2"
-naturalDate.toDateString(separator = ')') // "004)04)01"
-naturalDate.toTimeString(decimals = 2, rounding = 1) // "113°00"
-naturalDate.toLongitudeString(decimals = 1) // "NT+5.2"
-naturalDate.toYearString() // "004"
-naturalDate.toMoonString() // "04"
-naturalDate.toDayOfMoonString() // "01"
+```javascript
+naturalDate.toString();              // "004)04)01 113°00 NT+5.2"
+naturalDate.toDateString();          // "004)04)01"
+naturalDate.toTimeString();          // "113°00"
+naturalDate.toLongitudeString();     // "NT+5.2"
+naturalDate.toYearString();          // "004"
+naturalDate.toMoonString();          // "04"
+naturalDate.toDayOfMoonString();     // "01"
 ```
 
-More functions should be available later to make the NaturalDate class API mimic the native javascript Date class (ex: naturalDate.setYear(year)). Your help is welcome for this to happen ;-)
-
-## `NaturalDateContext` functions
-
-The NaturalDateContext.js file contains utility functions to bring some astronomical context to the natural date (ex: altitude of the sun, phase of the moon).
-
-```javascript 
-import { NaturalSunAltitude, NaturalSunEvents, NaturalMoonPosition, NaturalMoonEvents } from 'natural-time-js/context';
+### Astronomical Functions
 
-// Gizeh pyramide
-let latitude: 29.9791; 
-let longitude: 31.1341;
+Calculate precise celestial events and positions:
 
-let naturalDate = new NaturalDate(new Date(), longitude);
-
-NaturalSunAltitude(naturalDate, latitude);
-// altitude: 31.779736404754367, 
-// highestAltitude: 62.32114911751647
+```javascript
+import { 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 sun events for the day
+const sunEvents = NaturalSunEvents(naturalDate, latitude);
+console.log(sunEvents.sunrise);  // 70.567° (time in natural degrees)
+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.altitude);  // 64.323° (degrees above horizon)
+```
 
-NaturalSunEvents(naturalDate, latitude);
-// sunrise: 70.56708493448893,
-// sunset: 287.9105974344889,
-// nightStart: 306.43507660115563,
-// nightEnd: 52.13781826782227,
-// morningGoldenHour: 80.8551891011556,
-// eveningGoldenHour: 277.58920993448896
+## Documentation
 
-NaturalMoonPosition(naturalDate, latitude);
-// phase: 74.86175469141531,
-// altitude: 64.32391838504756,
-// highestAltitude: 69.53997976716451
+The library is fully documented using JSDoc. Generate the documentation with:
 
-NaturalMoonEvents(naturalDate, latitude);
-// moonrise: 139.14544743448894,
-// moonset: 10.624722434488932
+```bash
+npm run docs
 ```
 
-**Important !**  
-Utility functions return time-distance from 0° or false if the event does not occur during this day (ex: no sunrise at the north pole during winter).
+For live documentation updates during development:
 
-## Roadmap
+```bash
+npm run docs:dev
+```
 
-1. Test in real life
-2. Add typescript compatibility
-3. Make NaturalDate feel like the Javascript native Date Class by adding features like
-    - getTime()
-    - setMoon()
-    - ...
-4. Make NaturalTime available for other programming languages
+This creates HTML documentation in the `docs` directory.
 
-# Contribute
+## 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.
 
-# License
+## License
 
 Read [full license](./LICENSE) (Creative Common Zero)
 
 Natural time is completely free to use, play, transform, improve... It operates under the law of Love. Follow your heart, fork it, spoon it! There is no need to ask for permission to do anything with it.
 
-Natural time is supposed to bring joy and ease to human life, not the opposite. What you make out of it is up to you and the assistance of life forces.
-
-# Acknowledgments
+## Acknowledgments
 
 Natural time has been baking for a long time in a goat's mind while traveling around the world. Infinite gratitude to my beloved friends Uncle Skywalker and Ik: your precious insights into the Mayan universe were so inspiring.
 

package/babel.config.cjs

@@ -0,0 +1,9 @@
+module.exports = {
+  presets: [
+    ['@babel/preset-env', {
+      targets: {
+        node: 'current'
+      }
+    }]
+  ]
+}; 

package/dist/astronomy/celestial.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @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 '../core/NaturalDate';
+/**
+ * Hemisphere identifiers for geographical calculations.
+ */
+export declare enum HEMISPHERES {
+    /** Northern hemisphere (latitude >= 0) */
+    NORTH = "NORTH",
+    /** Southern hemisphere (latitude < 0) */
+    SOUTH = "SOUTH"
+}
+/**
+ * Day numbers marking the start and end of summer season.
+ */
+export declare const SEASONS: {
+    /** Day 91 (typically April 1st) - Start of summer in Northern hemisphere */
+    readonly SUMMER_START_DAY: 91;
+    /** Day 273 (typically September 30th) - End of summer in Northern hemisphere */
+    readonly SUMMER_END_DAY: 273;
+};
+/**
+ * Solar altitude thresholds in degrees for different daylight conditions.
+ */
+export declare const ANGLES: {
+    /** Altitude below which astronomical night begins (-12°) */
+    readonly NIGHT_ALTITUDE: -12;
+    /** Altitude below which golden hour lighting occurs (6°) */
+    readonly GOLDEN_HOUR_ALTITUDE: 6;
+};
+/**
+ * Interface for sun altitude information
+ */
+interface SunAltitude {
+    altitude: number;
+    highestAltitude: number;
+}
+/**
+ * Interface for sun events
+ */
+interface SunEvents {
+    sunrise: number;
+    sunset: number;
+    nightStart: number;
+    nightEnd: number;
+    morningGoldenHour: number;
+    eveningGoldenHour: number;
+}
+/**
+ * Interface for moon position information
+ */
+interface MoonPosition {
+    altitude: number;
+    phase: number;
+    illumination: number;
+}
+/**
+ * Interface for moon events
+ */
+interface MoonEvents {
+    moonrise: number;
+    moonset: number;
+    highestAltitude: number;
+}
+/**
+ * Interface for mustaches range information
+ */
+interface MustachesRange {
+    winterSunrise: number;
+    winterSunset: number;
+    summerSunrise: number;
+    summerSunset: number;
+    averageMustacheAngle: number;
+}
+/**
+ * Calculates the sun's altitude at a specific natural time and location.
+ */
+export declare function NaturalSunAltitude(naturalDate: NaturalDate, latitude: number): SunAltitude;
+/**
+ * Calculates sun events for a specific natural date and location.
+ */
+export declare function NaturalSunEvents(naturalDate: NaturalDate, latitude: number): SunEvents;
+/**
+ * Calculates the moon's position and phase.
+ */
+export declare function NaturalMoonPosition(naturalDate: NaturalDate, latitude: number): MoonPosition;
+/**
+ * Calculates moon events for a specific natural date and location.
+ */
+export declare function NaturalMoonEvents(naturalDate: NaturalDate, latitude: number): MoonEvents;
+/**
+ * Calculates the range of sun positions between winter and summer solstices (average mustaches angle)
+ */
+export declare function MustachesRange(naturalDate: NaturalDate, latitude: number): MustachesRange;
+export {};