### Install SunCalc3 via NPM (Bash)

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Installs the SunCalc3 library using the Node Package Manager (NPM). This is the recommended way to include the library in your JavaScript projects.

```bash
$ npm install suncalc3
```

--------------------------------

### Require SunCalc3 Module (JavaScript)

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Loads the SunCalc3 library into your Node.js project after it has been installed via NPM. This makes the library's functions available for use.

```javascript
let SunCalc = require('suncalc3');
```

--------------------------------

### Get Sunlight Times (JavaScript)

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Calculates sunrise and sunset times for a specified date and location. It returns an object containing various sunlight phases.

```javascript
let times = SunCalc.getSunTimes(new Date(), 51.5, -0.1);
let sunriseStr = times.sunriseStart.getHours() + ':' + times.sunrise.getMinutes();
```

--------------------------------

### Get Specific Sunlight Time (JavaScript)

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Calculates the precise time for sunrise and sunset at a given date, latitude, and longitude for a specific sun elevation angle. It supports observer height and allows calculations in degrees or radians, and in UTC or local time.

```javascript
/**
 * calculates sun times for a given date and latitude/longitude
 * calculates the time at which the sun will have a given elevation angle when rising and when setting for a given date and latitude/longitude.
 * @param {number|Date} dateValue Date object or timestamp for calculating sun-times
 * @param {number} lat latitude for calculating sun-times
 * @param {number} lng longitude for calculating sun-times
 * @param {number} elevationAngle sun angle for calculating sun-time
 * @param {number} [height=0]  the observer height (in meters) relative to the horizon
 * @param {boolean} [degree] defines if the elevationAngle is in degree not in radians
 * @param {boolean} [inUTC] defines if the calculation should be in utc or local time (default is local)
 * @return {ISunTimeSingle} result object of single sunTime
 */
SunCalc.getSunTime(dateValue, lat, lng, elevationAngle, height, degree, inUTC)
```

--------------------------------

### Get Moon Data (Position and Illumination)

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Calculates the moon's position and illumination for a specific date, latitude, and longitude. It returns an object with detailed positional data such as azimuth, altitude, distance, and zenith angle, along with illumination information.

```javascript
/**
 * calculations moon position and illumination for a given date and latitude/longitude of the moon,
 * @param {number|Date} dateValue Date object or timestamp for calculating moon-illumination
 * @param {number} lat latitude for calculating moon-position
 * @param {number} lng longitude for calculating moon-position
 * @return {IMoonData} result object of moon-illumination
 */
SunCalc.getMoonData(dateValue, lat, lng)
```

--------------------------------

### GET /suncalc/times

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Retrieves sunlight times for a given date, latitude, and longitude. Supports observer height, inclusion of deprecated times, and UTC calculation.

```APIDOC
## GET /suncalc/times

### Description
Calculates various sun times (e.g., sunrise, sunset, golden hour, civil twilight) for a specific date and geographical coordinates. It allows for optional parameters to refine the calculation, such as observer height and time format.

### Method
GET

### Endpoint
/suncalc/times

### Parameters
#### Query Parameters
- **dateValue** (number | Date) - Required - The date or timestamp for which to calculate sun times.
- **lat** (number) - Required - The latitude for the calculation.
- **lng** (number) - Required - The longitude for the calculation.
- **height** (number) - Optional - The observer's height in meters above the horizon. Defaults to 0.
- **addDeprecated** (boolean) - Optional - If true, deprecated sun times will also be included in the result. Defaults to false.
- **inUTC** (boolean) - Optional - If true, calculations are performed in UTC. Otherwise, local time is used. Defaults to false.

### Response
#### Success Response (200)
Returns an object containing various sun times. The structure is defined by `ISunTimeList`.

```javascript
{
  "solarNoon": "2023-10-27T12:30:00.000Z",
  "nadir": "2023-10-27T00:30:00.000Z",
  "goldenHourDawnStart": "2023-10-27T06:15:00.000Z",
  "goldenHourDawnEnd": "2023-10-27T07:00:00.000Z",
  "goldenHourDuskStart": "2023-10-27T17:30:00.000Z",
  "goldenHourDuskEnd": "2023-10-27T18:15:00.000Z",
  "sunriseStart": "2023-10-27T07:00:00.000Z",
  "sunriseEnd": "2023-10-27T07:05:00.000Z",
  "sunsetStart": "2023-10-27T17:55:00.000Z",
  "sunsetEnd": "2023-10-27T18:00:00.000Z",
  "blueHourDawnStart": "2023-10-27T05:45:00.000Z",
  "blueHourDawnEnd": "2023-10-27T06:15:00.000Z",
  "blueHourDuskStart": "2023-10-27T18:15:00.000Z",
  "blueHourDuskEnd": "2023-10-27T18:45:00.000Z",
  "civilDawn": "2023-10-27T06:45:00.000Z",
  "civilDusk": "2023-10-27T18:15:00.000Z",
  "nauticalDawn": "2023-10-27T06:15:00.000Z",
  "nauticalDusk": "2023-10-27T18:45:00.000Z",
  "amateurDawn": "2023-10-27T05:45:00.000Z",
  "amateurDusk": "2023-10-27T19:15:00.000Z",
  "astronomicalDawn": "2023-10-27T05:15:00.000Z",
  "astronomicalDusk": "2023-10-27T19:45:00.000Z"
}
```

#### Response Example
```json
{
  "solarNoon": "2023-10-27T12:30:00.000Z",
  "nadir": "2023-10-27T00:30:00.000Z",
  "goldenHourDawnStart": "2023-10-27T06:15:00.000Z",
  "goldenHourDawnEnd": "2023-10-27T07:00:00.000Z",
  "goldenHourDuskStart": "2023-10-27T17:30:00.000Z",
  "goldenHourDuskEnd": "2023-10-27T18:15:00.000Z",
  "sunriseStart": "2023-10-27T07:00:00.000Z",
  "sunriseEnd": "2023-10-27T07:05:00.000Z",
  "sunsetStart": "2023-10-27T17:55:00.000Z",
  "sunsetEnd": "2023-10-27T18:00:00.000Z",
  "blueHourDawnStart": "2023-10-27T05:45:00.000Z",
  "blueHourDawnEnd": "2023-10-27T06:15:00.000Z",
  "blueHourDuskStart": "2023-10-27T18:15:00.000Z",
  "blueHourDuskEnd": "2023-10-27T18:45:00.000Z",
  "civilDawn": "2023-10-27T06:45:00.000Z",
  "civilDusk": "2023-10-27T18:15:00.000Z",
  "nauticalDawn": "2023-10-27T06:15:00.000Z",
  "nauticalDusk": "2023-10-27T18:45:00.000Z",
  "amateurDawn": "2023-10-27T05:45:00.000Z",
  "amateurDusk": "2023-10-27T19:15:00.000Z",
  "astronomicalDawn": "2023-10-27T05:15:00.000Z",
  "astronomicalDusk": "2023-10-27T19:45:00.000Z"
}
```

#### Error Response
- **400 Bad Request**: If required parameters are missing or invalid.
- **500 Internal Server Error**: If there is a server-side issue during calculation.
```

--------------------------------

### Get Sun Position (JavaScript)

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Determines the sun's azimuth and altitude for a given date, time, and location. This is useful for understanding the sun's orientation in the sky.

```javascript
let sunrisePos = SunCalc.getPosition(times.sunrise, 51.5, -0.1);
let sunriseAzimuth = sunrisePos.azimuth * 180 / Math.PI;
```

--------------------------------

### Get Moon Illumination Data

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Calculates illumination parameters of the moon based on a given date. It returns an object containing the illuminated fraction, moon phase details, and information about upcoming moon phases. This function is based on formulas from 'idlastro.gsfc.nasa.gov' and Jean Meeus' 'Astronomical Algorithms'.

```javascript
/**
 * calculations for illumination parameters of the moon,
 * based on http://idlastro.gsfc.nasa.gov/ftp/pro/astro/mphase.pro formulas and
 * Chapter 48 of "Astronomical Algorithms" 2nd edition by Jean Meeus (Willmann-Bell, Richmond) 1998.
 * @param {number|Date} dateValue Date object or timestamp for calculating moon-illumination
 * @return {IMoonIllumination} result object of moon-illumination
 */
SunCalc.getMoonIllumination(dateValue)
```

--------------------------------

### Calculate Moon Data (Position + Illumination)

Source: https://context7.com/hypnos3/suncalc3/llms.txt

Get comprehensive moon information by combining position and illumination data in a single call. This endpoint provides a consolidated view for planning moon observations or related activities.

```APIDOC
## GET /suncalc3/moon/data

### Description
Retrieves comprehensive moon data, including position (azimuth, altitude, distance), illumination fraction, phase, and zenith angle for a given date and location.

### Method
GET

### Endpoint
`/suncalc3/moon/data`

### Parameters
#### Query Parameters
- **date** (Date) - Required - The date for which to calculate moon data.
- **latitude** (Number) - Required - The latitude of the location.
- **longitude** (Number) - Required - The longitude of the location.

### Request Example
```javascript
const date = new Date();
const lat = 48.8566;
const lng = 2.3522;

// Assuming a function `callAPI` that makes GET requests
callAPI('/suncalc3/moon/data', { date: date.toISOString(), latitude: lat, longitude: lng })
  .then(moonData => {
    console.log('Moon azimuth (degrees):', moonData.azimuthDegrees);
    console.log('Moon altitude (degrees):', moonData.altitudeDegrees);
    console.log('Illuminated fraction:', moonData.illumination.fraction);
    console.log('Current phase:', moonData.illumination.phase.name);
    console.log('Zenith angle:', moonData.zenithAngle);
  });
```

### Response
#### Success Response (200)
- **azimuthDegrees** (Number) - Azimuth of the moon in degrees.
- **altitudeDegrees** (Number) - Altitude of the moon in degrees.
- **distance** (Number) - Distance to the moon in kilometers.
- **parallacticAngleDegrees** (Number) - Parallactic angle of the moon in degrees.
- **illumination** (Object) - Object containing illumination details:
  - **fraction** (Number) - Illuminated fraction of the moon (0.0 to 1.0).
  - **phase** (Object) - Details about the current phase:
    - **name** (String) - The name of the moon phase.
    - **emoji** (String) - An emoji representing the moon phase.
    - **id** (String) - An identifier for the moon phase.
    - **css** (String) - A CSS class name for the moon phase.
- **zenithAngle** (Number) - Zenith angle of the moon.

#### Response Example
```json
{
  "azimuthDegrees": 180.5,
  "altitudeDegrees": 45.2,
  "distance": 380000,
  "parallacticAngleDegrees": 15.5,
  "illumination": {
    "fraction": 0.75,
    "phase": {
      "name": "waxingGibbousMoon",
      "emoji": "🌔",
      "id": "waxingGibbousMoon",
      "css": "moon-waxing-gibbous"
    }
  },
  "zenithAngle": 44.8
}
```
```

--------------------------------

### Get Sunlight Time by Azimuth (JavaScript)

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Calculates the specific time when the sun reaches a given azimuth angle for a specified date, latitude, and longitude. The angle can be provided in degrees or radians.

```javascript
/**
 * calculates time for a given azimuth angle for a given date and latitude/longitude
 * @param {Date} date start date for calculating sun-position
 * @param {number} nazimuth azimuth for calculating sun-position
 * @param {number} lat latitude for calculating sun-position
 * @param {number} lng longitude for calculating sun-position
 * @param {boolean} [degree] true if the angle is in degree and not in rad
 * @return {Date} result time of sun-position
*/
SunCalc.getSunTimeByAzimuth(date, lat, lng, nazimuth,  degree)
```

--------------------------------

### Access Moon Phase Cycles Configuration - JavaScript

Source: https://context7.com/hypnos3/suncalc3/llms.txt

Provides access to the predefined moon phase cycle configurations used by the SunCalc3 library. It allows developers to iterate through each phase, retrieving details like name, emoji, range, and CSS class, useful for building calendar widgets or phase displays. Requires the 'suncalc3' library.

```javascript
const SunCalc = require('suncalc3');

// Access all moon phase definitions
console.log('Moon phase cycles:', SunCalc.moonCycles);

// Each phase has: from, to, id, emoji, code, name, weight, css
SunCalc.moonCycles.forEach(phase => {
  console.log(`${phase.emoji} ${phase.name}`);
  console.log(`  Phase range: ${phase.from} to ${phase.to}`);
  console.log(`  ID: ${phase.id}`);
  console.log(`  CSS class: ${phase.css}`);
  console.log(`  Emoji code: ${phase.code}`);
});

// Use case: build a moon phase calendar widget
function getMoonPhaseForDate(date) {
  const illum = SunCalc.getMoonIllumination(date);
  return {
    emoji: illum.phase.emoji,
    name: illum.phase.name,
    illumination: Math.round(illum.fraction * 100) + '%',
    phaseValue: illum.phaseValue
  };
}

const today = getMoonPhaseForDate(new Date());
console.log('Today:', today.emoji, today.name, '-', today.illumination, 'illuminated');
```

--------------------------------

### SunCalc.getMoonTimes

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Calculates the moon rise and set times for a given date, latitude, and longitude. It can optionally perform calculations in UTC.

```APIDOC
## GET SunCalc.getMoonTimes

### Description
Calculates moon rise and set times for a specified date and location. The calculation can be performed in local time or UTC.

### Method
GET (conceptual, as it's a library function)

### Endpoint
N/A (Library Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **dateValue** (number|Date) - The date or timestamp for which to calculate moon times.
- **lat** (number) - The latitude for the calculation.
- **lng** (number) - The longitude for the calculation.
- **inUTC** (boolean, optional) - If true, calculations are performed in UTC. Defaults to local time.

### Request Example
```javascript
SunCalc.getMoonTimes(new Date(), 45.123, -75.456, true);
```

### Response
#### Success Response (200)
- **rise** (Date|NaN) - A Date object representing the moon rise time, or NaN if not applicable.
- **set** (Date|NaN) - A Date object representing the moon set time, or NaN if not applicable.
- **alwaysUp** (boolean) - True if the moon is always above the horizon.
- **alwaysDown** (boolean) - True if the moon is always below the horizon.

#### Response Example
```json
{
  "rise": "2023-10-27T07:30:00.000Z",
  "set": "2023-10-27T19:00:00.000Z",
  "alwaysUp": false,
  "alwaysDown": false
}
```
```

--------------------------------

### Deprecated Sun Event Properties Mapping

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Maps deprecated sun event property names to their current equivalents for backward compatibility. This ensures older code using original names continues to function correctly.

```markdown
| Property            | will equal to                                                            |
| ------------------- | ------------------------------------------------------------------------ |
| `dawn`              | `civilDawn` |
| `dusk`              | `civilDusk` |
| `nightEnd`          | `astronomicalDawn` |
| `night`             | `astronomicalDusk` |
| `nightStart`        | `astronomicalDusk` |
| `sunrise`           | `sunriseStart` |
| `sunset`            | `sunsetEnd` |
| `goldenHour`        | `goldenHourDuskStart` |
| `goldenHourEnd`     | `goldenHourDawnEnd` |
| `goldenHourStart`   | `goldenHourDuskStart` |
```

--------------------------------

### SunCalc.moonTransit

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Calculates the moon transit time based on provided rise and set times, latitude, and longitude.

```APIDOC
## GET SunCalc.moonTransit

### Description
Calculates the transit time of the moon for a given location and moon rise/set times.

### Method
GET (conceptual, as it's a library function)

### Endpoint
N/A (Library Function)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Parameters
- **rise** (number|Date) - The rise time of the moon as a Date object or timestamp.
- **set** (number|Date) - The set time of the moon as a Date object or timestamp.
- **lat** (number) - The latitude for the calculation.
- **lng** (number) - The longitude for the calculation.

### Request Example
```javascript
const moonTimes = SunCalc.getMoonTimes(new Date(), 45.123, -75.456);
SunCalc.moonTransit(moonTimes.rise, moonTimes.set, 45.123, -75.456);
```

### Response
#### Success Response (200)
- **main** (Date|NaN) - The primary moon transit date, or NaN if not applicable.
- **invert** (Date|NaN) - The inverted moon transit date, or NaN if not applicable.

#### Response Example
```json
{
  "main": "2023-10-27T13:15:00.000Z",
  "invert": "2023-10-27T01:45:00.000Z"
}
```
```

--------------------------------

### Calculate Moon Rise and Set Times - JavaScript

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Calculates the moon rise and set times for a given date, latitude, and longitude. It can perform calculations in local time or UTC. The result is an object indicating rise and set times, or if the moon is always up or down.

```javascript
/**
 * calculations for moon rise/set times are based on http://www.stargazing.net/kepler/moonrise.html article
 * @param {number|Date} dateValue Date object or timestamp for calculating moon-times
 * @param {number} lat latitude for calculating moon-times
 * @param {number} lng longitude for calculating moon-times
 * @param {boolean} [inUTC] defines if the calculation should be in utc or local time (default is local)
 * @return {IMoonTimes} result object of sunTime
 */
SunCalc.getMoonTimes(dateValue, lat, lng, inUTC)
```

```javascript
/**
 * @typedef {Object} IMoonTimes
 * @property {Date|NaN} rise - a Date object if the moon is rising on the given Date, otherwise NaN
 * @property {Date|NaN} set - a Date object if the moon is setting on the given Date, otherwise NaN
 * @property {boolean} alwaysUp - is true if the moon never rises/sets and is always _above_ the horizon during the day
 * @property {boolean} alwaysDown - is true if the moon is always _below_ the horizon
 */
```

--------------------------------

### Calculate Moon Illumination and Phase

Source: https://context7.com/hypnos3/suncalc3/llms.txt

Obtain the current moon phase, illumination fraction, and dates for upcoming lunar events like new moon and full moon. This helps in understanding the moon's appearance and planning photography.

```APIDOC
## GET /suncalc3/moon/illumination

### Description
Retrieves the current moon phase, illumination fraction, and dates of the next lunar events (new moon, full moon, etc.).

### Method
GET

### Endpoint
`/suncalc3/moon/illumination`

### Parameters
#### Query Parameters
- **date** (Date) - Required - The date for which to calculate illumination and phase.

### Request Example
```javascript
const date = new Date();

// Assuming a function `callAPI` that makes GET requests
callAPI('/suncalc3/moon/illumination', { date: date.toISOString() })
  .then(moonIllum => {
    console.log('Illuminated fraction:', moonIllum.fraction);
    console.log('Phase name:', moonIllum.phase.name);
    console.log('Next full moon:', new Date(moonIllum.next.fullMoon.value));
  });
```

### Response
#### Success Response (200)
- **fraction** (Number) - The illuminated fraction of the moon (0.0 to 1.0).
- **phaseValue** (Number) - A value representing the moon phase (0.0 to 1.0).
- **phase** (Object) - An object containing details about the current phase:
  - **name** (String) - The name of the moon phase (e.g., "fullMoon").
  - **emoji** (String) - An emoji representing the moon phase.
  - **id** (String) - An identifier for the moon phase.
  - **css** (String) - A CSS class name for the moon phase.
- **angle** (Number) - The angle related to the moon's illumination.
- **next** (Object) - An object containing dates of upcoming lunar events:
  - **type** (String) - The type of the next event.
  - **date** (Date) - The date of the next lunar event.
  - **newMoon** (Object) - Details for the next new moon.
  - **fullMoon** (Object) - Details for the next full moon.
  - **firstQuarter** (Object) - Details for the next first quarter.
  - **thirdQuarter** (Object) - Details for the next third quarter.

#### Response Example
```json
{
  "fraction": 0.98,
  "phaseValue": 0.99,
  "phase": {
    "name": "waningGibbousMoon",
    "emoji": "🌔",
    "id": "waningGibbousMoon",
    "css": "moon-waning-gibbous"
  },
  "angle": -0.05,
  "next": {
    "type": "fullMoon",
    "date": "2024-03-25T07:00:00.000Z",
    "newMoon": {"value": "2024-03-10T09:01:00.000Z"},
    "fullMoon": {"value": "2024-03-25T07:00:00.000Z"},
    "firstQuarter": {"value": "2024-03-16T03:11:00.000Z"},
    "thirdQuarter": {"value": "2024-03-02T17:17:00.000Z"}
  }
}
```
```

--------------------------------

### Access Sun Times Configuration - JavaScript

Source: https://context7.com/hypnos3/suncalc3/llms.txt

Allows viewing and managing the sun time angle definitions used by the SunCalc3 library. Developers can inspect the angles corresponding to various astronomical times (e.g., golden hour, sunrise, civil twilight) and access deprecated time name mappings. Useful for understanding the library's internal time calculations. Requires 'suncalc3'.

```javascript
const SunCalc = require('suncalc3');

// Access current sun time definitions
console.log('Sun time configurations:');
SunCalc.times.forEach(time => {
  console.log(`Angle ${time.angle}°: ${time.riseName} / ${time.setName}`);
});

// Example output:
// Angle 6°: goldenHourDawnEnd / goldenHourDuskStart
// Angle -0.3°: sunriseEnd / sunsetStart
// Angle -0.833°: sunriseStart / sunsetEnd
// Angle -1°: goldenHourDawnStart / goldenHourDuskEnd
// Angle -4°: blueHourDawnEnd / blueHourDuskStart
// Angle -6°: civilDawn / civilDusk
// ...and more

// View deprecated time name mappings
console.log('Deprecated time names:', SunCalc.timesDeprecated);
// [['dawn', 'civilDawn'], ['dusk', 'civilDusk'], ...]

// Use case: understanding what each time represents
const times = SunCalc.getSunTimes(new Date(), 51.5, -0.1);
SunCalc.times.forEach(time => {
  if (times[time.riseName]) {
    console.log(`${time.riseName} (${time.angle}°):`, times[time.riseName].value);
  }
});
```

--------------------------------

### Sun Times Data Structure (ISunTimeList)

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

The `ISunTimeList` object returned by `getSunTimes` contains detailed sun times for a given location and date. It includes properties like `solarNoon`, `nadir`, `goldenHourDawnStart`, `sunriseStart`, `sunsetEnd`, and various twilight times. Some properties are deprecated alternatives.

```javascript
/**
* @typedef {Object} ISunTimeList
* @property {ISunTimeDef} solarNoon - The sun-time for the solar noon (sun is in the highest position)
* @property {ISunTimeDef} nadir - The sun-time for nadir (darkest moment of the night, sun is in the lowest position)
* @property {ISunTimeDef} goldenHourDawnStart - The sun-time for morning golden hour (soft light, best time for photography)
* @property {ISunTimeDef} goldenHourDawnEnd - The sun-time for morning golden hour (soft light, best time for photography)
* @property {ISunTimeDef} goldenHourDuskStart - The sun-time for evening golden hour starts
* @property {ISunTimeDef} goldenHourDuskEnd - The sun-time for evening golden hour starts
* @property {ISunTimeDef} sunriseStart - The sun-time for sunrise starts (top edge of the sun appears on the horizon)
* @property {ISunTimeDef} sunriseEnd - The sun-time for sunrise ends (bottom edge of the sun touches the horizon)
* @property {ISunTimeDef} sunsetStart - The sun-time for sunset starts (bottom edge of the sun touches the horizon)
* @property {ISunTimeDef} sunsetEnd - The sun-time for sunset ends (sun disappears below the horizon, evening civil twilight starts)
* @property {ISunTimeDef} blueHourDawnStart - The sun-time for blue Hour start (time for special photography photos starts)
* @property {ISunTimeDef} blueHourDawnEnd - The sun-time for blue Hour end (time for special photography photos end)
* @property {ISunTimeDef} blueHourDuskStart - The sun-time for blue Hour start (time for special photography photos starts)
* @property {ISunTimeDef} blueHourDuskEnd - The sun-time for blue Hour end (time for special photography photos end)
* @property {ISunTimeDef} civilDawn - The sun-time for dawn (morning nautical twilight ends, morning civil twilight starts)
* @property {ISunTimeDef} civilDusk - The sun-time for dusk (evening nautical twilight starts)
* @property {ISunTimeDef} nauticalDawn - The sun-time for nautical dawn (morning nautical twilight starts)
* @property {ISunTimeDef} nauticalDusk - The sun-time for nautical dusk end (evening astronomical twilight starts)
* @property {ISunTimeDef} amateurDawn - The sun-time for amateur astronomical dawn (sun at 12° before sunrise)
* @property {ISunTimeDef} amateurDusk - The sun-time for amateur astronomical dusk (sun at 12° after sunrise)
* @property {ISunTimeDef} astronomicalDawn - The sun-time for night ends (morning astronomical twilight starts)
* @property {ISunTimeDef} astronomicalDusk - The sun-time for night starts (dark enough for astronomical observations)
* @property {ISunTimeDef} [dawn] - Deprecated: alternate for civilDawn
* @property {ISunTimeDef} [dusk] - Deprecated: alternate for civilDusk
* @property {ISunTimeDef} [nightEnd] - Deprecated: alternate for astronomicalDawn
* @property {ISunTimeDef} [night] - Deprecated: alternate for astronomicalDusk
* @property {ISunTimeDef} [nightStart] - Deprecated: alternate for astronomicalDusk
* @property {ISunTimeDef} [goldenHour] - Deprecated: alternate for goldenHourDuskStart
* @property {ISunTimeDef} [sunset] - Deprecated: alternate for sunsetEnd
* @property {ISunTimeDef} [sunrise] - Deprecated: alternate for sunriseStart
* @property {ISunTimeDef} [goldenHourEnd] - Deprecated: alternate for goldenHourDawnEnd
* @property {ISunTimeDef} [goldenHourStart] - Deprecated: alternate for goldenHourDuskStart
*/

```

--------------------------------

### Sun Event Time Definitions

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Defines various sun event times and their corresponding angles below the horizon. These include blue hour, golden hour, sunrise, sunset, and twilight phases. The 'pos' property indicates the sun's angle in degrees below the horizon.

```markdown
| `blueHourDawnEnd`   | blue Hour end (time for special photography photos end)                  | 4     |
| `goldenHourDawnStart` | morning golden hour (soft light, best time for photography) starts     | -1    |
| `sunriseStart`      | sunrise (top edge of the sun appears on the horizon)                     | 0.833 |
| `sunriseEnd`        | sunrise ends (bottom edge of the sun touches the horizon)                | 0.3   |
| `goldenHourDawnEnd`   | morning golden hour (soft light, best time for photography) ends       | -6    |
| `solarNoon`         | solar noon (sun is in the highest position)                              |       |
| `goldenHourDuskStart` | evening golden hour (soft light, best time for photography) starts     | -6    |
| `sunsetStart`       | sunset starts (bottom edge of the sun touches the horizon)               | 0.3   |
| `sunsetEnd`         | sunset (sun disappears below the horizon, evening civil twilight starts) | 0.833 |
| `goldenHourDuskEnd` | evening golden hour (soft light, best time for photography) ends         | 1     |
| `blueHourDuskStart` | blue Hour start (time for special photography photos starts)             | 4     |
| `civilDusk`         | dusk (evening nautical twilight starts)                                  | 6     |
| `blueHourDuskEnd`   | blue Hour end (time for special photography photos end)                  | 8     |
| `nauticalDusk`      | nautical dusk end (evening astronomical twilight starts)                 | 12    |
| `amateurDusk`       | amateur astronomical dusk (sun at 12° after sunrise)                     | 15    |
| `astronomicalDusk`  | night starts (dark enough for astronomical observations)                 | 18    |
| `nadir`             | nadir (darkest moment of the night, sun is in the lowest position)       |       |

SunBH is the angle of the sun below the horizon
```

--------------------------------

### Add Custom Sunlight Times (JavaScript)

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Allows adding custom sun times based on a specific sun angle. It validates input parameters like angle, names, and optional positions. This function also cleans up deprecated time names to prevent conflicts.

```javascript
/** adds a custom time to the times config
 * @param {number} angleAltitude - angle of Altitude/elevation above the horizont of the sun in degrees
 * @param {string} riseName - name of sun rise (morning name)
 * @param {string} setName  - name of sun set (evening name)
 * @param {number} [risePos]  - (optional) position at rise (morning)
 * @param {number} [setPos]  - (optional) position at set (evening)
 * @param {boolean} [degree=true] defines if the elevationAngle is in degree not in radians
 * @return {Boolean} true if new time could be added, false if not (parameter missing; riseName or setName already existing)
 */
SunCalc.addTime(angleInDegrees, riseName, setName, risePos, setPos)
```

--------------------------------

### Calculate Sun Times with SunCalc3

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

The `getSunTimes` function calculates various sunlight-related times for a specified date and geographical location. It accepts date, latitude, longitude, observer height, a flag for deprecated times, and a flag for UTC time as input. It returns an object containing detailed sun times.

```javascript
/**
 * calculates sun times for a given date and latitude/longitude
 * @param {number|Date} dateValue Date object or timestamp for calculating sun-times
 * @param {number} lat latitude for calculating sun-times
 * @param {number} lng longitude for calculating sun-times
 * @param {number} [height=0]  the observer height (in meters) relative to the horizon
 * @param {boolean} [addDeprecated=false] if true to times from timesDeprecated array will be added to the object
 * @param {boolean} [inUTC=false] defines if the calculation should be in utc or local time (default is local)
 * @return {ISunTimeList} result object of sunTime
 */
SunCalc.getSunTimes(dateValue, lat, lng, height, addDeprecated, inUTC)
```

--------------------------------

### Calculate Moon Rise and Set Times - JavaScript

Source: https://context7.com/hypnos3/suncalc3/llms.txt

Calculates the times for moonrise and moonset for a given date and geographic coordinates. It also determines if the moon is always visible or always hidden, providing insights for astronomical observations. Dependencies include the 'suncalc3' library.

```javascript
const SunCalc = require('suncalc3');

// Get moon rise/set times for Oslo, Norway
const date = new Date('2024-07-15');
const lat = 59.9139;
const lng = 10.7522;
const inUTC = false; // use local time

const moonTimes = SunCalc.getMoonTimes(date, lat, lng, inUTC);

if (moonTimes.rise instanceof Date) {
  console.log('Moonrise:', moonTimes.rise);
} else {
  console.log('Moon does not rise today');
}

if (moonTimes.set instanceof Date) {
  console.log('Moonset:', moonTimes.set);
} else {
  console.log('Moon does not set today');
}

console.log('Always above horizon:', moonTimes.alwaysUp);
console.log('Always below horizon:', moonTimes.alwaysDown);

if (moonTimes.highest) {
  console.log('Moon highest at:', moonTimes.highest);
}

// Use case: night photography planning
if (moonTimes.set instanceof Date && moonTimes.rise instanceof Date) {
  const darkPeriodStart = moonTimes.set;
  const darkPeriodEnd = moonTimes.rise;
  console.log('Dark sky window for astrophotography:');
  console.log('From', darkPeriodStart, 'to', darkPeriodEnd);

  const darkHours = (darkPeriodEnd - darkPeriodStart) / (1000 * 60 * 60);
  console.log('Duration:', Math.round(darkHours), 'hours');
}

// Arctic/Antarctic special cases
if (moonTimes.alwaysUp) {
  console.log('Moon is visible all day (typical in polar summers)');
} else if (moonTimes.alwaysDown) {
  console.log('Moon is hidden all day (typical in polar winters)');
}
```

--------------------------------

### Calculate Comprehensive Moon Data with SunCalc3

Source: https://context7.com/hypnos3/suncalc3/llms.txt

Combines moon position and illumination calculations into a single function call, providing azimuth, altitude, distance, parallactic angle, illumination fraction, phase name, and zenith angle. This offers a complete view for moon observation planning.

```javascript
const SunCalc = require('suncalc3');

// Get complete moon data for Paris
const date = new Date();
const lat = 48.8566;
const lng = 2.3522;

const moonData = SunCalc.getMoonData(date, lat, lng);

// Position data
console.log('Moon azimuth (degrees):', moonData.azimuthDegrees);
console.log('Moon altitude (degrees):', moonData.altitudeDegrees);
console.log('Moon distance (km):', moonData.distance);
console.log('Parallactic angle (degrees):', moonData.parallacticAngleDegrees);

// Illumination data
console.log('Illuminated fraction:', moonData.illumination.fraction);
console.log('Current phase:', moonData.illumination.phase.name);
console.log('Phase emoji:', moonData.illumination.phase.emoji);

// Zenith angle (for drawing moon orientation)
console.log('Zenith angle:', moonData.zenithAngle);

// Use case: moon observation planning
if (moonData.altitudeDegrees > 15 && moonData.illumination.fraction > 0.5) {
  console.log('Good conditions for moon observation');
  console.log('Point instrument to:', moonData.azimuthDegrees, '° azimuth');
  console.log('Moon is', Math.round(moonData.distance), 'km away');
  console.log('Current phase:', moonData.illumination.phase.name);
}
```

--------------------------------

### Calculate Moon Illumination and Phase with SunCalc3

Source: https://context7.com/hypnos3/suncalc3/llms.txt

Retrieves the moon's current illumination fraction, phase value, phase name, emoji representation, and dates for upcoming lunar events like new moon and full moon. This is useful for understanding the moon's appearance and planning photography.

```javascript
const SunCalc = require('suncalc3');

// Get moon illumination data for current date
const date = new Date();
const moonIllum = SunCalc.getMoonIllumination(date);

console.log('Illuminated fraction:', moonIllum.fraction); // 0.0 to 1.0
console.log('Phase value:', moonIllum.phaseValue); // 0.0 to 1.0
console.log('Phase name:', moonIllum.phase.name);
console.log('Phase emoji:', moonIllum.phase.emoji);
console.log('Phase ID:', moonIllum.phase.id);
console.log('Phase CSS class:', moonIllum.phase.css);
console.log('Angle:', moonIllum.angle);

console.log('Next moon event:', moonIllum.next.type, 'on', moonIllum.next.date);
console.log('Next new moon:', new Date(moonIllum.next.newMoon.value));
console.log('Next full moon:', new Date(moonIllum.next.fullMoon.value));
console.log('Next first quarter:', new Date(moonIllum.next.firstQuarter.value));
console.log('Next third quarter:', new Date(moonIllum.next.thirdQuarter.value));

// Phase IDs: newMoon, waxingCrescentMoon, firstQuarterMoon, waxingGibbousMoon,
//            fullMoon, waningGibbousMoon, thirdQuarterMoon, waningCrescentMoon

// Example: determine if moon is waxing or waning
if (moonIllum.angle < 0) {
  console.log('Moon is waxing (growing)');
} else {
  console.log('Moon is waning (shrinking)');
}

// Example: moon photography readiness
if (moonIllum.fraction > 0.95 && moonIllum.phase.id === 'fullMoon') {
  console.log('Perfect conditions for full moon photography!');
}
```

--------------------------------

### Calculate Sun Position - JavaScript

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Calculates the sun's position (altitude and azimuth) for a given date, latitude, and longitude. It returns an object containing various positional details in both radians and degrees. This is useful for astronomical calculations and determining the sun's path.

```javascript
/**
 * calculates sun position for a given date and latitude/longitude
 * @param {number|Date} dateValue Date object or timestamp for calculating sun-position
 * @param {number} lat latitude for calculating sun-position
 * @param {number} lng longitude for calculating sun-position
 * @return {ISunPosition} result object of sun-position
*/
SunCalc.getPosition(dateValue, lat, lng)
```

--------------------------------

### Add Deprecated Sunlight Time Name (JavaScript)

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Enables the addition of an alternate or deprecated name for an existing sun time. It validates the alternate name and ensures the original name exists within the SunCalc.times array.

```javascript
/**
 * add an alternate name for a sun time
 * @param {string} alternameName    - alternate or deprecated time name
 * @param {string} originalName     - original time name from SunCalc.times array
 * @return {Boolean} true if could be added, false if not (parameter missing; originalName does not exists; alternameName already existis)
 */
SunCalc.addDeprecatedTimeName(alternameName, originalName)
```

--------------------------------

### ISunTimeDef JavaScript Type Definition

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Defines the structure of the `ISunTimeDef` object used to represent calculated sun times. It includes properties for the time name, Date object, Unix timestamp, sun position, elevation, Julian calendar value, and validity.

```javascript
/**
* @typedef {Object} ISunTimeDef
* @property {string} name - The Name of the time
* @property {Date} value - Date object with the calculated sun-time
* @property {number} ts - The time as Unix timestamp
* @property {number} pos - The position of the sun on the time
* @property {number} [elevation] - Angle of the sun on the time (except for solarNoon / nadir)
* @property {number} julian - The time as Julian calendar
* @property {boolean} valid - indicates if the time is valid or not
* @property {boolean} [deprecated] - indicates if the time is a deprecated time name
* @property {string} [nameOrg] - if it is a deprecated name, the original property name
* @property {number} [posOrg] - if it is a deprecated name, the original position
*/
```

--------------------------------

### Calculate Solar Time - JavaScript

Source: https://github.com/hypnos3/suncalc3/blob/master/README.md

Calculates the solar time for a given date, latitude, and UTC offset. It takes a Date object or timestamp and returns a Date object representing the solar time. Ensure the correct UTC offset and longitude are provided for accurate results.

```javascript
/**
 * Calculaes the solar time of the given date in the given latitude and UTC offset.
 * @param {number|Date} dateValue Date object or timestamp for calculating solar time
 * @param {number} utcOffset
 * @param {number} lng
 * @returns Returns the solar time of the given date in the given latitude and UTC offset.
 */
SunCalc.getSolarTime(dateValue, utcOffset, lng)
```