natural-time-js
Version:
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. Learn more: https://naturaltime.app. This JavaScript Class tran
157 lines (156 loc) • 6.28 kB
TypeScript
/**
* @module natural-time-js/core
* @description This module provides the core NaturalDate class that bridges between artificial Gregorian time and Natural Time.
*/
/**
* 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;
}
/**
* Clears the internal year context cache.
* Exposed for testing or advanced usage without exposing the cache itself.
*/
export declare function resetYearContextCache(): void;