@openwaters/almanac 0.8.1 → 0.9.0

package/README.md

@@ -71,6 +71,8 @@ Migration guides for [SunCalc](docs/migrating-from-suncalc.md), [Astronomy Engin
 
 Angles use degrees. All three ports provide `degreesToRadians(angle)` and `radiansToDegrees(angle)` for callers that use radians. These functions preserve sign and full turns without wrapping or changing the angle's origin; non-finite inputs and conversion overflow raise validation errors. Swift calls use `try`.
 
+For an instantaneous day/night decision, `sunIsUp(time, observer, heightAboveGroundM = 0)` uses the same upper-limb convention as sunrise and sunset, including polar periods. See the [day/night recipe](docs/cookbook.md).
+
 ### JavaScript module loading
 
 The npm package is ESM and has no separate CommonJS build. Use Node 22.12 or later for the Node examples; CI and release checks load the packed package on Node 22.12 and Node 24. Browser applications can import it through their ESM bundler.
@@ -198,7 +200,7 @@ print(try equationOfTime(today))   // sundial minus clock, minutes
 
 ### Kotlin/JVM and Android
 
-The Kotlin library provides the same 37 functions and result fields, using `java.time.Instant` and immutable data classes. It targets JVM 8 and Android minSdk 26, builds with JDK 17, and has no runtime dependencies beyond the Kotlin standard library and platform APIs. Maven publication and a Kotlin benchmark runner are deferred; consume the source at a reviewed Git SHA as described in [`kotlin/README.md`](kotlin/README.md).
+The Kotlin library provides the same 38 functions and result fields, using `java.time.Instant` and immutable data classes. It targets JVM 8 and Android minSdk 26, builds with JDK 17, and has no runtime dependencies beyond the Kotlin standard library and platform APIs. Maven publication and a Kotlin benchmark runner are deferred; consume the source at a reviewed Git SHA as described in [`kotlin/README.md`](kotlin/README.md).
 
 ```kotlin
 import io.openwaters.almanac.*

package/dist/events.d.ts

@@ -69,6 +69,8 @@ export declare function quantizedUt(ut: number): number;
 export declare function assertReached(condition: boolean, what: string): void;
 /** Wrap a hour-angle difference into (−180, 180]. */
 export declare function angleOffset(diff: number): number;
+/** Whether the Sun's upper limb is above the modeled horizon, using the sunrise/set convention. */
+export declare function sunIsUp(time: Date, observer: Observer, heightAboveGroundM?: number): boolean;
 /**
  * Sun rise, set, the three twilights and upper transit within the half-open
  * window `[startUtc, endUtc)`, sorted ascending.

package/dist/events.js

@@ -478,6 +478,13 @@ const MOON_LEVELS = [
 function flatCycle(observer) {
     return Math.abs(observer.latitudeDeg) >= FLAT_CYCLE_LATITUDE_DEG;
 }
+/** Whether the Sun's upper limb is above the modeled horizon, using the sunrise/set convention. */
+export function sunIsUp(time, observer, heightAboveGroundM = 0) {
+    assertSupported(time);
+    const dip = horizonDip(observer, heightAboveGroundM);
+    const sample = sunSampler(observer, dip)(utDays(time));
+    return sample.altDeg > sample.riseSetAltDeg;
+}
 /**
  * Sun rise, set, the three twilights and upper transit within the half-open
  * window `[startUtc, endUtc)`, sorted ascending.

package/dist/index.d.ts

@@ -15,7 +15,7 @@ export { sunAltAz, moonAltAz, starAltAz } from './transforms.js';
 export type { MoonIllumination, MoonOrientation } from './illumination.js';
 export { moonIllumination, moonOrientation } from './illumination.js';
 export type { SunEvent, SunEventKind, MoonEvent, MoonEventKind, MoonPhaseEvent, MoonPhaseName, PlanetEvent, PlanetEventKind, AltitudeEvent, AltitudeEventKind, TransitEvent, TransitEventKind } from './events.js';
-export { sunEvents, moonEvents, searchMoonPhases, planetEvents, sunAltitudeEvents, sunTransits, moonTransits } from './events.js';
+export { sunIsUp, sunEvents, moonEvents, searchMoonPhases, planetEvents, sunAltitudeEvents, sunTransits, moonTransits } from './events.js';
 export type { LunarEclipse, LunarEclipseVisibility } from './eclipse.js';
 export { nextLunarEclipse, previousLunarEclipse, lunarEclipses, lunarEclipseVisibility } from './eclipse.js';
 export type { SolarEclipse, SolarEclipseKind, SolarEclipseSunAltitudes } from './solar.js';

package/dist/index.js

@@ -8,7 +8,7 @@ export { seasons } from './seasons.js';
 export { moonApsides } from './apsides.js';
 export { sunAltAz, moonAltAz, starAltAz } from './transforms.js';
 export { moonIllumination, moonOrientation } from './illumination.js';
-export { sunEvents, moonEvents, searchMoonPhases, planetEvents, sunAltitudeEvents, sunTransits, moonTransits } from './events.js';
+export { sunIsUp, sunEvents, moonEvents, searchMoonPhases, planetEvents, sunAltitudeEvents, sunTransits, moonTransits } from './events.js';
 export { nextLunarEclipse, previousLunarEclipse, lunarEclipses, lunarEclipseVisibility } from './eclipse.js';
 export { nextSolarEclipse, previousSolarEclipse, solarEclipses, solarObscuration } from './solar.js';
 export { nextGlobalSolarEclipse, previousGlobalSolarEclipse, globalSolarEclipses, solarEclipseAxisPoint, solarEclipseCentralLine } from './globalSolar.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openwaters/almanac",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Offline astronomy: Sun, Moon and planet positions, apparent horizon, rise/set, phases and eclipses.",
   "license": "MIT",
   "repository": {