suncalc

Sun and moon position, times, and illumination calculations for Kit

Files

Dependencies

No Kit package dependencies.

Installation

kit add gitlab.com/kit-lang/packages/kit-suncalc.git

Usage

import Kit.Suncalc as SunCalc

main = fn =>
  # New York City on the 2026 June solstice at 16:00:00 UTC.
  timestamp = 1782057600000.0
  latitude = 40.7128
  longitude = 0.0 - 74.0060
  height = 10.0

  # Sun position is returned in radians.
  position = SunCalc.get-position timestamp latitude longitude
  azimuth-degrees = SunCalc.to-degrees position.azimuth
  altitude-degrees = SunCalc.to-degrees position.altitude

  println "Sun azimuth: ${azimuth-degrees} degrees"
  println "Sun altitude: ${altitude-degrees} degrees"
  println "Sun up?: ${SunCalc.sun-up? timestamp latitude longitude}"

  # Sun event times are Unix timestamps in milliseconds.
  times = SunCalc.get-times timestamp latitude longitude height
  println "Sunrise: ${times.sunrise}"
  println "Solar noon: ${times.solar-noon}"
  println "Sunset: ${times.sunset}"

  # Moon phase and illumination.
  illumination = SunCalc.get-moon-illumination timestamp
  phase-name = SunCalc.moon-phase-name illumination.phase
  percent-lit = SunCalc.moon-illumination-percent timestamp

  println "Moon phase: ${phase-name}"
  println "Moon illuminated: ${percent-lit}%"

main

API Notes

All timestamps are Unix timestamps in milliseconds. Latitude and longitude are decimal degrees, with east and north positive and west and south negative.

Angles returned by position APIs are radians. Use SunCalc.to-degrees when displaying them to users.

Key public APIs:

Development

Running Examples

Run examples with the interpreter:

kit run examples/basic.kit
kit run examples/moon.kit

Compile examples to native binaries:

kit build examples/basic.kit && ./basic
kit build examples/moon.kit && ./moon

Running Tests

Run the test suite:

kit test

Run the package test file directly:

kit test tests/suncalc.test.kit

Run the test suite with coverage:

kit test --coverage

Running Parity

Check that examples behave the same through the interpreter and compiled binaries:

kit parity --no-spinner --failures-only

Running kit dev

Run the standard development workflow (format, check, test):

kit dev

This will:

1. Format and check source files in src/
2. Run tests in tests/ with coverage

Generating Documentation

Generate API documentation from doc comments:

kit doc

Note: Kit sources with doc comments (##) will generate HTML documents in docs/*.html

Cleaning Build Artifacts

Remove generated files, caches, parity results, and build artifacts:

kit task clean

Note: Defined in kit.toml.

Local Installation

To install this package locally for development:

kit install

This installs the package to ~/.kit/packages/@kit/suncalc/, making it available for import as Kit.Suncalc in other projects.

License

This package is released under the MIT License - see LICENSE for details.

SunCalc was ported from mourner/suncalc, which is released under the BSD-2-Clause License.

Exported Functions & Types

day-ms

SunCalc - Sun and moon position calculations for Kit

Ported from https://github.com/mourner/suncalc (BSD-2-Clause license) Original author: Vladimir Agafonkin

Sun calculations based on https://aa.quae.nl/en/reken/zonpositie.html Moon calculations based on https://aa.quae.nl/en/reken/hemelpositie.html

to-radians

Convert degrees to radians.

Float -> Float

to-degrees

Convert radians to degrees.

Float -> Float

sun-coords

Calculate sun coordinates for a given day number

moon-coords

Calculate moon coordinates for a given day number

get-position

Get sun position for a given timestamp and location

Parameters:

Returns a record with: - azimuth: Sun azimuth in radians (direction along the horizon, south = 0, west = positive) - altitude: Sun altitude in radians (above the horizon)

Float -> Float -> Float -> {azimuth: Float, altitude: Float}

pos = get-position 1362441600000.0 50.5 30.5
azimuth-degrees = to-degrees pos.azimuth

get-times

Get sun times for a given date and location

Parameters:

Returns a record with timestamps (ms) for various sun events: - solar-noon: Sun is at highest point - nadir: Sun is at lowest point (opposite of noon) - sunrise/sunset: Sun appears/disappears on horizon (-0.833 degrees) - sunrise-end/sunset-start: Bottom edge of sun touches horizon (-0.3 degrees) - dawn/dusk: Civil twilight (-6 degrees) - nautical-dawn/nautical-dusk: Nautical twilight (-12 degrees) - night-end/night: Astronomical twilight (-18 degrees) - golden-hour-end/golden-hour: Golden hour (6 degrees)

Float -> Float -> Float -> Float -> {solar-noon: Float, nadir: Float, sunrise: Float, sunset: Float, sunrise-end: Float, sunset-start: Float, dawn: Float, dusk: Float, nautical-dawn: Float, nautical-dusk: Float, night-end: Float, night: Float, golden-hour-end: Float, golden-hour: Float}

times = get-times 1362441600000.0 50.5 30.5 0.0
sunrise-ms = times.sunrise

get-moon-position

Get moon position for a given timestamp and location

Parameters:

Returns a record with: - azimuth: Moon azimuth in radians - altitude: Moon altitude in radians (includes atmospheric refraction) - distance: Distance to moon in kilometers - parallactic-angle: Parallactic angle in radians

Float -> Float -> Float -> {azimuth: Float, altitude: Float, distance: Float, parallactic-angle: Float}

pos = get-moon-position 1362441600000.0 50.5 30.5
distance-km = pos.distance

get-moon-illumination

Get moon illumination for a given timestamp

Parameters:

Returns a record with: - fraction: Illuminated fraction (0 to 1) - phase: Moon phase (0 = new moon, 0.25 = first quarter, 0.5 = full moon, 0.75 = last quarter) - angle: Midpoint angle in radians of the illuminated limb

Float -> {fraction: Float, phase: Float, angle: Float}

illum = get-moon-illumination 1362441600000.0
percent-lit = illum.fraction * 100.0

get-moon-times

Get moon rise and set times for a given date and location

Parameters:

Returns a record with: - rise: Option Float - moonrise time in ms (Some value or None) - set: Option Float - moonset time in ms (Some value or None) - always-up?: Bool - moon never sets on this day - always-down?: Bool - moon never rises on this day

Float -> Float -> Float -> {rise: Option Float, set: Option Float, always-up?: Bool, always-down?: Bool}

times = get-moon-times 1362441600000.0 50.5 30.5
match times.rise
  | Some r -> IO.println "Moonrise: ${Float.to-string r}"
  | None -> IO.println "No moonrise today"

moon-phase-name

Get the name of a moon phase from a phase value

Parameters:

Returns a string describing the moon phase: - "new-moon" (0 and 1) - "waxing-crescent" (0-0.25) - "first-quarter" (0.25) - "waxing-gibbous" (0.25-0.5) - "full-moon" (0.5) - "waning-gibbous" (0.5-0.75) - "last-quarter" (0.75) - "waning-crescent" (0.75-1)

Float -> String

illum = get-moon-illumination 1362441600000.0
name = moon-phase-name illum.phase

sun-up?

Check if the sun is up (above horizon) at a given time and location.

Float -> Float -> Float -> Bool

night?

Check if it's night (sun below -18 degrees) at a given time and location.

Float -> Float -> Float -> Bool

twilight?

Check if it's twilight at a given time and location.

Float -> Float -> Float -> Bool

golden-hour?

Check if it's golden hour at a given time and location.

Float -> Float -> Float -> Bool

full-moon?

Check if it's a full moon (within 10% of full).

Float -> Bool

new-moon?

Check if it's a new moon (within 10% of new).

Float -> Bool

moon-illumination-percent

Get moon illumination as a percentage.

Float -> Float