natural-time-js 1.1.1 → 2.0.2

package/dist/utils/validators.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @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';
+/**
+ * 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;

package/dist/utils/validators.js

@@ -0,0 +1,231 @@
+/**
+ * @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';
+/**
+ * Valid range for latitude values in degrees
+ */
+const LATITUDE_RANGE = {
+    MIN: -90,
+    MAX: 90
+};
+/**
+ * Valid range for longitude values in degrees
+ */
+const LONGITUDE_RANGE = {
+    MIN: -180,
+    MAX: 180
+};
+/**
+ * Valid range for angle values in degrees
+ */
+const ANGLE_RANGE = {
+    MIN: 0,
+    MAX: 360
+};
+/**
+ * Valid ranges for natural date components
+ */
+const NATURAL_DATE_RANGES = {
+    /** Moon (month) number range (1-14) */
+    MOON: { MIN: 1, MAX: 14 },
+    /** Week of year range (1-53) */
+    WEEK: { MIN: 1, MAX: 53 },
+    /** Week within moon range (1-4) */
+    WEEK_OF_MOON: { MIN: 1, MAX: 4 },
+    /** Day of moon range (1-28) */
+    DAY_OF_MOON: { MIN: 1, MAX: 28 },
+    /** Day of week range (1-7) */
+    DAY_OF_WEEK: { MIN: 1, MAX: 7 }
+};
+/**
+ * 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 const isValidNumber = (value) => {
+    return typeof value === 'number' && Number.isFinite(value) && !Number.isNaN(value);
+};
+/**
+ * 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 const isValidLatitude = (latitude) => {
+    return isValidNumber(latitude) &&
+        latitude >= LATITUDE_RANGE.MIN &&
+        latitude <= LATITUDE_RANGE.MAX;
+};
+/**
+ * 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 const isValidLongitude = (longitude) => {
+    return isValidNumber(longitude) &&
+        longitude >= LONGITUDE_RANGE.MIN &&
+        longitude <= LONGITUDE_RANGE.MAX;
+};
+/**
+ * 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 const isValidAngle = (angle) => {
+    return isValidNumber(angle) &&
+        angle >= ANGLE_RANGE.MIN &&
+        angle <= ANGLE_RANGE.MAX;
+};
+/**
+ * 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 const isValidTimestamp = (timestamp) => {
+    return isValidNumber(timestamp) && timestamp > 0;
+};
+/**
+ * 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 const isValidNaturalDate = (date) => {
+    if (!(date instanceof NaturalDate)) {
+        return false;
+    }
+    // Basic property validations
+    if (!isValidTimestamp(date.unixTime) ||
+        !isValidLongitude(date.longitude) ||
+        !isValidNumber(date.year)) {
+        return false;
+    }
+    // Natural calendar validations
+    return (isValidNumber(date.moon) &&
+        date.moon >= NATURAL_DATE_RANGES.MOON.MIN &&
+        date.moon <= NATURAL_DATE_RANGES.MOON.MAX &&
+        isValidNumber(date.week) &&
+        date.week >= NATURAL_DATE_RANGES.WEEK.MIN &&
+        date.week <= NATURAL_DATE_RANGES.WEEK.MAX &&
+        isValidNumber(date.weekOfMoon) &&
+        date.weekOfMoon >= NATURAL_DATE_RANGES.WEEK_OF_MOON.MIN &&
+        date.weekOfMoon <= NATURAL_DATE_RANGES.WEEK_OF_MOON.MAX &&
+        isValidNumber(date.dayOfMoon) &&
+        date.dayOfMoon >= NATURAL_DATE_RANGES.DAY_OF_MOON.MIN &&
+        date.dayOfMoon <= NATURAL_DATE_RANGES.DAY_OF_MOON.MAX &&
+        isValidNumber(date.dayOfWeek) &&
+        date.dayOfWeek >= NATURAL_DATE_RANGES.DAY_OF_WEEK.MIN &&
+        date.dayOfWeek <= NATURAL_DATE_RANGES.DAY_OF_WEEK.MAX &&
+        isValidNumber(date.dayOfYear) &&
+        date.dayOfYear >= 1 &&
+        date.dayOfYear <= date.yearDuration &&
+        typeof date.isRainbowDay === 'boolean' &&
+        isValidAngle(date.time) &&
+        isValidTimestamp(date.yearStart) &&
+        isValidNumber(date.yearDuration) &&
+        isValidTimestamp(date.nadir));
+};
+/**
+ * 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 const isValidCacheKey = (key) => {
+    return typeof key === 'string' && key.length > 0;
+};
+/**
+ * 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 const throwValidationError = (paramName, value, expectedType) => {
+    throw new Error(`Invalid ${paramName}: ${value}. Expected ${expectedType}`);
+};
+//# sourceMappingURL=validators.js.map

package/dist/utils/validators.js.map

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

package/jest.config.cjs

@@ -0,0 +1,29 @@
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  extensionsToTreatAsEsm: ['.ts'],
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', {
+      useESM: true,
+    }],
+  },
+  testMatch: [
+    '**/__tests__/**/*.test.ts',
+    '**/__tests__/**/*.test.js',
+    '**/src/**/__tests__/**/*.test.ts',
+    '**/src/**/__tests__/**/*.test.js'
+  ],
+  collectCoverageFrom: [
+    'src/**/*.ts',
+    'src/**/*.js',
+    '!src/index.ts',
+    '!src/index.js',
+    '!**/node_modules/**',
+    '!**/dist/**'
+  ],
+  coverageDirectory: 'coverage',
+  verbose: true,
+}; 

package/package.json

@@ -1,11 +1,19 @@
 {
   "name": "natural-time-js",
-  "version": "1.1.1",
+  "version": "2.0.2",
   "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. Learn more: https://naturaltime.app. This JavaScript Class translates gregorian artificial datetime to natural datetime",
-  "main": "index.js",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "type": "module",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsc",
+    "build:watch": "tsc --watch",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage",
+    "docs": "jsdoc -c jsdoc.json",
+    "docs:dev": "jsdoc -c jsdoc.json -w",
+    "typecheck": "tsc --noEmit"
   },
   "repository": {
     "type": "git",
@@ -26,5 +34,17 @@
   "homepage": "https://github.com/sylvain441/natural-time-js#readme",
   "dependencies": {
     "astronomy-engine": "^2.1.19"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.26.9",
+    "@babel/preset-env": "^7.26.9",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^22.13.9",
+    "babel-jest": "^29.7.0",
+    "clean-jsdoc-theme": "^4.3.0",
+    "jest": "^29.7.0",
+    "jsdoc": "^4.0.4",
+    "ts-jest": "^29.2.6",
+    "typescript": "^5.8.2"
   }
 }

package/index.js

@@ -1,241 +0,0 @@
-/**
- * @module natural-time-js
- * @description Natural time implementation for JavaScript - translates artificial dates to natural dates
- */
-
-import { Seasons } from 'astronomy-engine';
-
-const yearContextCache = new Map();
-
-/**
- * Calculates year context for natural date calculations
- * @param {number} artificialYear - Gregorian calendar year
- * @param {number} longitude - Longitude in degrees (-180 to 180)
- * @returns {{
- *   start: number,
- *   duration: number
- * }} Year context 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(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
- * @class
- */
-export class NaturalDate {
-	/**
-	 * Number of milliseconds in a day
-	 * @constant {number}
-	 */
-	static MILLISECONDS_PER_DAY = 86400000; // 24 * 60 * 60 * 1000
-
-	/**
-	 * End date of the artificial time era (December 21, 2012 12:00 UTC)
-	 * @constant {number}
-	 */
-	static END_OF_ARTIFICIAL_TIME = Date.UTC(2012, 11, 21, 12, 0, 0);
-
-	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)
-
-	/**
-	 * Creates a new natural date instance
-	 * @param {Date|number} date - JavaScript Date object or Unix timestamp
-	 * @param {number} longitude - Longitude in degrees (-180 to 180)
-	 * @throws {Error} If inputs are invalid
-	 */
-	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');
-		}
-		
-		date = new Date(date || Date.now());
-		if (isNaN(date.getTime())) {
-			throw new Error('Invalid date provided');
-		}
-		
-		this.unixTime = date.getTime();
-		this.longitude = longitude || 0;
-		
-		if (Number.isFinite(this.unixTime)) {
-			// YEAR START & DURATION
-			let yearContext = calculateYearContext(date.getUTCFullYear()-1, 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(date.getUTCFullYear(), longitude);
-			
-			this.yearStart = yearContext.start;
-			this.yearDuration = yearContext.duration;
-
-			let 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 = parseInt(timeSinceLocalYearStart / 28) + 1; 
-			
-			// HEPTAD
-			this.week = parseInt(timeSinceLocalYearStart / 7) + 1;
-			this.weekOfMoon = parseInt(timeSinceLocalYearStart / 7) % 4 + 1;
-			
-			// DAY
-			this.day = parseInt((this.unixTime - (NaturalDate.END_OF_ARTIFICIAL_TIME + (-longitude + 180) * NaturalDate.MILLISECONDS_PER_DAY/360)) / NaturalDate.MILLISECONDS_PER_DAY);
-			this.dayOfYear = parseInt(timeSinceLocalYearStart) + 1;
-			this.dayOfMoon = parseInt(timeSinceLocalYearStart) % 28 + 1;
-			this.dayOfWeek = parseInt(timeSinceLocalYearStart) % 7 + 1;
-
-			// NADIR (i.e day start, midnight)
-			this.nadir = this.yearStart + parseInt(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 'Argument must be a Date object or a Unix timestamp';
-	}
-
-	/**
-	 * Gets the time of an astronomical event in natural degrees
-	 * @param {Date|number} event - Event timestamp
-	 * @returns {number|false} Event time in natural degrees (0-360) or false if out of range
-	 */
-	getTimeOfEvent(event) {
-		// Make sure it's a unix timestamp
-		event = new Date(event).getTime();
-
-		// Check if not out of range
-		if(event < this.nadir || event > this.nadir + NaturalDate.MILLISECONDS_PER_DAY) 
-			return false;
-
-		return (event - this.nadir) * (360 / NaturalDate.MILLISECONDS_PER_DAY);
-	}
-	
-	/**
-	 * Exports current date as a full ISO formatted string
-	 * @returns ex: "004)04)01 113°00 NT+95"
-	 */
-	toString() {
-		return `${this.toDateString()} ${this.toTimeString()} ${this.toLongitudeString()}`;
-	}
-
-	/**
-	 * Exports current date as a formatted string
-	 * @param {String} separator Default: ')'
-	 * @returns ex: "004)04)01"
-	 */
-	toDateString(separator = ')') {
-		if(this.isRainbowDay) {
-			return `${this.toYearString()}${separator}RAINBOW${this.dayOfYear === 366 ? "+" : ""}`;
-		}
-		return `${this.toYearString()}${separator}${this.toMoonString()}${separator}${this.toDayOfMoonString()}`;
-	}
-
-	/**
-	 * Exports current time as a formatted string
-	 * @param {*} decimals Number of decimals (precision) Default: 2
-	 * @param {*} rounding Allows granular incrementation of time (ex: 100°10 => 100°15 => 100°20) Default: 1
-	 * @returns ex: "113°00" "202°" "63°1234"
-	 */
-	toTimeString(decimals = 2, rounding = 1) { 
-		let timeUnity = parseInt(this.time);
-		let timeDecimals = parseInt((this.time % 1) * Math.pow(10, decimals));
-		timeDecimals = Math.floor(timeDecimals / rounding) * rounding;
-
-		return String(timeUnity).padStart(3, '0') + "°" + (decimals ? String(timeDecimals).padStart(decimals, '0') : '');
-	}
-
-	/**
-	 * Exports current longitude as a formatted string
-	 * @param {Number} decimals Number of decimals (precision) Default: 1
-	 * @returns ex: "NT+95.4" "NT-78"
-	 */
-	toLongitudeString(decimals = 1) {
-		if(Math.abs(Math.round(this.longitude)) == 0)
-			return "NTZ"
-			
-		return "NT" + (this.longitude > 0 ? "+" : "") + this.longitude.toFixed(decimals) + "";
-	}
-
-	/**
-	 * Exports current year as a formatted string
-	 * @returns ex: "004"
-	 */
-	toYearString() {
-		return (this.year < 0 ? "-" : "") + String(Math.abs(this.year)).padStart(3, '0');
-	}
-
-	/**
-	 * Exports current moon as a formatted string
-	 * @returns ex: "04"
-	 */
-	toMoonString() {
-		return String(this.moon).padStart(2, '0');
-	}
-
-	/**
-	 * Exports current day of the moon as a formatted string
-	 * @returns ex: "01"
-	 */
-	toDayOfMoonString() {
-		return String(this.dayOfMoon).padStart(2, '0');
-	}
-}