better-suncalc/dist/index.d.ts

A tiny TypeScript library for calculating sun/moon positions and phases.

// Generated by dts-bundle v0.7.3

declare module 'better-suncalc' {
    export { fromJulian, hoursLater, toDays, toJulian } from "better-suncalc/src/utils";
    export { addTime, altitude, approxTransit, astroRefraction, azimuth, declination, eclipticLongitude, getPosition, getSetJ, getTimes, hourAngle, julianCycle, PositionData, rightAscension, siderealTime, solarMeanAnomaly, solarTransitJ, sunCoords, TimesData, } from "better-suncalc/src/suncalc";
    export { getMoonIllumination, getMoonPosition, getMoonTimes, moonCoords, MoonIlluminationData, MoonPositionData, MoonTimesData, } from "better-suncalc/src/mooncalc";
    export { getSolstices, SolsticeData } from "better-suncalc/src/solstice";
    export { EquinoxData, getEquinoxes } from "better-suncalc/src/equinox";
}

declare module 'better-suncalc/src/utils' {
    /**
        * Converts a Date object to Julian date.
        * @param date - The date to convert.
        * @returns Julian date as a floating point number.
        */
    export function toJulian(date: Date): number;
    /**
        * Converts a Julian date to a Date object.
        * @param j - Julian date to convert.
        * @returns Corresponding Date object.
        */
    export function fromJulian(j: number): Date;
    /**
        * Converts a Date to days since the J2000 epoch.
        * @param date - Date to convert.
        * @returns Days since J2000 epoch.
        */
    export function toDays(date: Date): number;
    /**
        * Adds hours to a Date object.
        * @param date - Original date.
        * @param h - Hours to add.
        * @returns New Date object advanced by h hours.
        */
    export function hoursLater(date: Date, h: number): Date;
}

declare module 'better-suncalc/src/suncalc' {
    /**
        * Represents the sun's position at a specific time and location.
        */
    export type PositionData = {
            /** Azimuth angle in radians (clockwise from true north) */
            azimuth: number;
            /** Altitude angle in radians above horizon (0 at horizon, positive upwards).
                *  Includes correction for atmospheric refraction.
                */
            altitude: number;
    };
    /**
        * Contains calculated solar times for a specific date and location.
        */
    export type TimesData = {
            /** Solar noon (sun at highest position) */
            solarNoon: Date;
            /** Nadir (darkest moment of night, solar midnight) */
            nadir: Date;
            /** Additional time events defined through addTime() such as:
                * - sunrise/sunset (center at horizon)
                * - dawn/dusk (when sun reaches 6° below horizon)
                * - golden hour boundaries
                */
            [key: string]: Date;
    };
    /**
        * Calculates right ascension from ecliptic coordinates.
        * @param l - Ecliptic longitude in radians.
        * @param b - Ecliptic latitude in radians.
        * @returns Right ascension in radians.
        */
    export function rightAscension(l: number, b: number): number;
    /**
        * Calculates declination from ecliptic coordinates.
        * @param l - Ecliptic longitude in radians.
        * @param b - Ecliptic latitude in radians.
        * @returns Declination in radians.
        */
    export function declination(l: number, b: number): number;
    /**
        * Calculates azimuth angle for a celestial body.
        * @param H - Hour angle in radians.
        * @param phi - Observer's latitude in radians.
        * @param dec - Declination of the celestial body in radians.
        * @returns Azimuth angle in radians (clockwise from north).
        */
    export function azimuth(H: number, phi: number, dec: number): number;
    /**
        * Calculates altitude angle for a celestial body.
        * @param H - Hour angle in radians.
        * @param phi - Observer's latitude in radians.
        * @param dec - Declination of celestial body in radians.
        * @returns Altitude angle in radians.
        */
    export function altitude(H: number, phi: number, dec: number): number;
    /**
        * Calculates sidereal time for given Julian days.
        * @param d - Days since J2000 epoch.
        * @param lw - Longitude west in radians.
        * @returns Sidereal time in radians.
        */
    export function siderealTime(d: number, lw: number): number;
    /**
        * Corrects altitude for atmospheric refraction.
        * @param h - Altitude angle in radians (geometric).
        * @returns Refraction correction in radians.
        */
    export function astroRefraction(h: number): number;
    /**
        * Calculates the solar mean anomaly.
        * @param d - Days since J2000 epoch.
        * @returns Solar mean anomaly in radians.
        */
    export function solarMeanAnomaly(d: number): number;
    /**
        * Calculates ecliptic longitude from solar mean anomaly.
        * @param M - Solar mean anomaly in radians.
        * @returns Ecliptic longitude in radians.
        */
    export function eclipticLongitude(M: number): number;
    /**
        * Calculates sun coordinates for given days since J2000.
        * @param d - Days since J2000 epoch.
        * @returns Object containing sun's declination and right ascension.
        */
    export function sunCoords(d: number): {
            dec: number;
            ra: number;
    };
    /**
        * Calculates sun position for given date and location.
        * @param date - Date/time of observation.
        * @param lat - Observer's latitude in degrees.
        * @param lng - Observer's longitude in degrees.
        * @returns Object containing azimuth and altitude in radians.
        */
    export function getPosition(date: Date, lat: number, lng: number): PositionData;
    /**
        * Adds a custom time definition to sun time calculations.
        * @param angle - Altitude angle in degrees.
        * @param riseName - Name for the rise time property.
        * @param setName - Name for the set time property.
        */
    export function addTime(angle: number, riseName: string, setName: string): void;
    /**
        * Calculates Julian cycle for given days and longitude.
        * @param d - Days since J2000 epoch.
        * @param lw - Longitude west in radians.
        * @returns Julian cycle number.
        */
    export function julianCycle(d: number, lw: number): number;
    /**
        * Approximates the transit time.
        * @param Ht - Hour angle.
        * @param lw - Longitude west in radians.
        * @param n - Julian cycle number.
        * @returns Approximate transit time in Julian days.
        */
    export function approxTransit(Ht: number, lw: number, n: number): number;
    /**
        * Calculates the precise solar transit time.
        * @param ds - Days since J2000 epoch.
        * @param M - Solar mean anomaly.
        * @param L - Ecliptic longitude.
        * @returns Julian date of solar transit.
        */
    export function solarTransitJ(ds: number, M: number, L: number): number;
    /**
        * Calculates the hour angle for a given altitude.
        * @param h - Altitude angle in radians.
        * @param phi - Observer's latitude in radians.
        * @param dec - Sun declination in radians.
        * @returns Hour angle in radians.
        */
    export function hourAngle(h: number, phi: number, dec: number): number;
    /**
        * Calculates the Julian date for a sun altitude event.
        * @param h - Altitude angle in radians.
        * @param lw - Longitude west in radians.
        * @param phi - Observer's latitude in radians.
        * @param dec - Sun declination in radians.
        * @param n - Julian cycle number.
        * @param M - Solar mean anomaly.
        * @param L - Ecliptic longitude.
        * @returns Julian date of the event.
        */
    export function getSetJ(h: number, lw: number, phi: number, dec: number, n: number, M: number, L: number): number;
    /**
        * Calculates sun times (e.g., sunrise, sunset, dawn etc.) for given date and location.
        * @param date - Date of observation.
        * @param lat - Observer's latitude in degrees.
        * @param lng - Observer's longitude in degrees.
        * @returns Object containing calculated sun times as Date objects.
        */
    export function getTimes(date: Date, lat: number, lng: number): TimesData;
}

declare module 'better-suncalc/src/mooncalc' {
    /**
        * Represents the moon's position and related parameters at a specific time and location.
        */
    export type MoonPositionData = {
            /** Azimuth angle in radians (clockwise from true north) */
            azimuth: number;
            /** Altitude angle in radians above horizon (includes atmospheric refraction correction) */
            altitude: number;
            /** Distance to moon in kilometers */
            distance: number;
            /** Parallactic angle - angle between moon position and local zenith,
                *  useful for lunar observations and photography (radians)
                */
            parallacticAngle: number;
    };
    /**
        * Describes the moon's illumination phase and visibility.
        */
    export type MoonIlluminationData = {
            /** Illuminated fraction (0 = new moon, 1 = full moon) */
            fraction: number;
            /** Moon phase (0-1):
                * - 0 = New Moon
                * - 0.25 = First Quarter
                * - 0.5 = Full Moon
                * - 0.75 = Last Quarter
                */
            phase: number;
            /** Angle of the illuminated terminator (radians, eastward from north) */
            angle: number;
    };
    /**
        * Moon rise/set times and visibility status.
        */
    export type MoonTimesData = {
            /** Moonrise time (if occurs on date) */
            rise?: Date;
            /** Moonset time (if occurs on date) */
            set?: Date;
            /** True if moon never sets (polar day) */
            alwaysUp?: boolean;
            /** True if moon never rises (polar day) */
            alwaysDown?: boolean;
    };
    /**
        * Calculates moon coordinates for a given number of days since J2000.
        * @param d - Days since J2000 epoch.
        * @returns Object containing moon's right ascension, declination, and distance.
        */
    export function moonCoords(d: number): {
            ra: number;
            dec: number;
            dist: number;
    };
    /**
        * Calculates moon position for provided date and location.
        * @param date - Date/time of observation.
        * @param lat - Observer's latitude in degrees.
        * @param lng - Observer's longitude in degrees.
        * @returns Object containing moon position data.
        */
    export function getMoonPosition(date: Date, lat: number, lng: number): MoonPositionData;
    /**
        * Calculates moon illumination parameters.
        * @param date - Date/time of observation.
        * @returns Object containing illumination data.
        */
    export function getMoonIllumination(date: Date): MoonIlluminationData;
    /**
        * Calculates moon rise and set times for given date and location.
        * @param date - Date of observation.
        * @param lat - Observer's latitude in degrees.
        * @param lng - Observer's longitude in degrees.
        * @param inUTC - Whether to use UTC time.
        * @returns Object containing moon times data.
        */
    export function getMoonTimes(date: Date, lat: number, lng: number, inUTC: boolean): MoonTimesData;
}

declare module 'better-suncalc/src/solstice' {
    /**
        * Contains solar solstice dates within a specified time range.
        */
    export type SolsticeData = {
            /** Summer solstice dates (northern hemisphere) in UTC */
            summer: Date[];
            /** Winter solstice dates (northern hemisphere) in UTC */
            winter: Date[];
    };
    /**
        * Finds all solstice events (summer and winter) that occur within the given datetime range.
        * The algorithm uses a per-year approximate guess, then refines via Newton’s method applied
        * to the derivative of the sun's declination.
        *
        * The function returns an object containing arrays of Date objects for summer and winter solstices.
        *
        * @param rangeStart - Starting Date of the range.
        * @param rangeEnd - Ending Date of the range.
        * @returns Object with keys 'summer' and 'winter', each an array of Date instances.
        */
    export function getSolstices(rangeStart: Date, rangeEnd: Date): SolsticeData;
}

declare module 'better-suncalc/src/equinox' {
    /**
        * Contains vernal/autumnal equinox dates within a specified time range.
        */
    export type EquinoxData = {
            /** Vernal (spring) equinox dates (northern hemisphere) in UTC */
            vernal: Date[];
            /** Autumnal (fall) equinox dates (northern hemisphere) in UTC */
            autumnal: Date[];
    };
    /**
        * Finds all equinox events (vernal and autumnal) occurring within the given date range.
        * The algorithm uses an approximate guess per year then refines the guess via Newton’s method.
        *
        * The returned object contains arrays of Date objects for the vernal and autumnal equinoxes.
        *
        * @param rangeStart - Starting Date of the search range.
        * @param rangeEnd - Ending Date of the search range.
        * @returns Object with keys 'vernal' and 'autumnal', each an array of Date instances.
        */
    export function getEquinoxes(rangeStart: Date, rangeEnd: Date): EquinoxData;
}