feat: Added doesBodyRiseOrSet() to transit module in @observerly/astr…

…ometry.

feat: Added doesBodyRiseOrSet() to transit module in @observerly/astrometry. Includes associated test suite and expected API output.

src/transit.ts

@@ -15,7 +15,7 @@ import {
 } from './common'
 import { convertEquatorialToHorizontal } from './coordinates'
 
-import { getNormalizedInclinationDegree } from './utilities'
+import { getNormalizedInclinationDegree, convertDegreesToRadians as radians } from './utilities'
 
 /*****************************************************************************************************************/
 
@@ -131,3 +131,46 @@ export const isBodyAboveHorizon = (
 }
 
 /*****************************************************************************************************************/
+
+/**
+ *
+ * doesBodyRiseOrSet()
+ *
+ * An object rises or sets if it is above the observer's horizon at the time of observation.
+ *
+ * @param observer - The geographic coordinate of the observer.
+ * @param target - The equatorial or horizontal coordinate of the observed object.
+ * @returns false if the object never rises or sets for the observer, otherwise returns the Ar and H1 transit parameters.
+ *
+ */
+export const doesBodyRiseOrSet = (
+  observer: GeographicCoordinate,
+  target: EquatorialCoordinate
+): false | Parameters => {
+  // We only need to consider the latitude of the observer:
+  const { latitude } = observer
+
+  // We only need to consider the declination of the target object:
+  const { dec } = target
+
+  // If |Ar| > 1, the object will never rise or set for the observer.
+  const Ar = Math.sin(radians(dec)) / Math.cos(radians(latitude))
+
+  if (Math.abs(Ar) > 1) {
+    return false
+  }
+
+  // If |H1| > 1, the object will never rise or set for the observer.
+  const H1 = Math.tan(radians(latitude)) * Math.tan(radians(dec))
+
+  if (Math.abs(H1) > 1) {
+    return false
+  }
+
+  return {
+    Ar,
+    H1
+  }
+}
+
+/*****************************************************************************************************************/

tests/transit.spec.ts

@@ -14,7 +14,8 @@ import {
   type EquatorialCoordinate,
   isBodyCircumpolar,
   isBodyVisible,
-  isBodyAboveHorizon
+  isBodyAboveHorizon,
+  doesBodyRiseOrSet
 } from '../src'
 
 /*****************************************************************************************************************/
@@ -249,3 +250,38 @@ describe('isBodyAboveHorizon', () => {
 })
 
 /*****************************************************************************************************************/
+
+describe('doesBodyRiseOrSet', () => {
+  it('should be defined', () => {
+    expect(doesBodyRiseOrSet).toBeDefined()
+  })
+
+  it('should return transit parameters for a northerm hemisphere object for a postive latitude', () => {
+    expect(
+      doesBodyRiseOrSet(
+        {
+          latitude,
+          longitude
+        },
+        betelgeuse
+      )
+    ).toEqual({
+      Ar: 0.13703603027752978,
+      H1: 0.04685668461549029
+    })
+  })
+
+  it('should return false for a nothern hemisphere object for a negative latitude', () => {
+    expect(
+      doesBodyRiseOrSet(
+        {
+          latitude: -85,
+          longitude
+        },
+        polaris
+      )
+    ).toBe(false)
+  })
+})
+
+/*****************************************************************************************************************/