suncalc.d.ts

// 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;
    };
}