// Type definitions for suncalc 1.8.0
// Project: https://www.npmjs.com/package/suncalc
// Definitions by: Zorbing <https://github.com/Zorbing>

/* =================== USAGE ===================

    import * as SunCalc from "suncalc";

 =============================================== */

declare module "suncalc"
{
	/**
	 * Adds a custom time when the sun reaches the given angle to results returned by `SunCalc.getTimes`.
	 * `SunCalc.times` property contains all currently defined times.
	 */
	function addTime(angle: number, riseName: string, setName: string): void;

	/**
	 * Returns the sun position at the given date, time, and position.
	 */
	function getPosition(date: Date, latitude: number, longitude: number): {
		/**
		 * Sun altitude above the horizon in radians, e.g. `0` at the horizon and `PI/2` at the zenith (straight over your head)
		 */
		altitude: number;
		/**
		 * Sun azimuth in radians (direction along the horizon, measured from south to west), e.g. `0` is south and `Math.PI * 3/4` is northwest
		 */
		azimuth: number;
	};

	/**
	 * Returns a times-object where each property is a `Date` object.
	 */
	function getTimes(date: Date, latitude: number, longitude: number): {
		/**
		 * Sunrise - top edge of the sun appears on the horizon
		 */
		sunrise: Date;
		/**
		 * Sunrise ends - bottom edge of the sun touches the horizon
		 */
		sunriseEnd: Date;
		/**
		 * Morning golden hour ends - soft light, best time for photography
		 */
		goldenHourEnd: Date;
		/**
		 * Solar noon - sun is in the highest position
		 */
		solarNoon: Date;
		/**
		 * Evening golden hour starts
		 */
		goldenHour: Date;
		/**
		 * Sunset starts - bottom edge of the sun touches the horizon
		 */
		sunsetStart: Date;
		/**
		 * Sunset - sun disappears below the horizon, evening civil twilight starts
		 */
		sunset: Date;
		/**
		 * Dusk - evening nautical twilight starts
		 */
		dusk: Date;
		/**
		 * Nautical dusk - evening astronomical twilight starts
		 */
		nauticalDusk: Date;
		/**
		 * Night starts - dark enough for astronomical observations
		 */
		night: Date;
		/**
		 * Nadir - darkest moment of the night, sun is in the lowest position
		 */
		nadir: Date;
		/**
		 * Night ends - morning astronomical twilight starts
		 */
		nightEnd: Date;
		/**
		 * Nautical dawn - morning nautical twilight starts
		 */
		nauticalDawn: Date;
		/**
		 * Dawn - morning nautical twilight ends, morning civil twilight starts
		 */
		dawn: Date;
	};

	/**
	 * Returns the moon position at the given date, time, and position.
	 */
	function getMoonPosition(timeAndDate: Date, latitude: number, longitude: number): {
		/**
		 * Moon altitude above the horizon in radians
		 */
		altitude: number;
		/**
		 * Moon azimuth in radians
		 */
		azimuth: number;
		/**
		 * Distance to moon in kilometers
		 */
		distance: number;
		/**
		 * Parallactic angle of the moon in radians
		 */
		parallacticAngle: number;
	};

	/**
	 * Returns the moon illumination at the given date and time.
	 *
	 * By subtracting the `parallacticAngle` from the `angle` one can get the zenith angle of the moons bright limb (anticlockwise).
	 * The zenith angle can be used do draw the moon shape from the observers perspective (e.g. moon lying on its back).
	 */
	function getMoonIllumination(timeAndDate: Date): {
		/**
		 * Illuminated fraction of the moon; varies from `0.0` (new moon) to `1.0` (full moon)
		 */
		fraction: number;
		/**
		 * Moon phase; varies from `0.0` to `1.0`.
		 * From New Moon (`0`) -> Waxing Crescent -> First Quarter (`0.25`) -> Waxing Gibbous -> Full Moon (`0.5`) -> Waning Gibbous -> Last Quarter (`0.75`) -> Waning Crescent
		 */
		phase: number;
		/**
		 * Midpoint angle in radians of the illuminated limb of the moon reckoned eastward from the north point of the disk; the moon is waxing if the angle is negative, and waning if positive
		 */
		angle: number;
	};

	/**
	 * Returns the moon times (kind of equivalent to `getTimes`).
	 *
	 * By default, it will search for moon rise and set during local user's day (frou 0 to 24 hours).
	 * If `inUTC` is set to `true`, it will instead search the specified date from 0 to 24 UTC hours.
	 */
	function getMoonTimes(date: Date, latitude: number, longitude: number, inUTC?: boolean): {
		/**
		 * Moonrise time as `Date`
		 */
		rise?: Date;
		/**
		 * Moonset time as `Date`
		 */
		set?: Date;
		/**
		 * `true` if the moon never rises/sets and is always _above_ the horizon during the day
		 */
		alwaysUp?: boolean;
		/**
		 * `true` if the moon is always _below_ the horizon
		 */
		alwaysDown?: boolean;
	};
}