@magmacomputing/tempo-plugin-astro

This is a premium plugin for the Tempo library that calculates the exact astronomical season (Equinoxes and Solstices) for any date using the Jean Meeus polynomial algorithm.

Because it is a true astronomical calculation rather than a fixed calendar date, it precisely determines the exact minute the sun crosses the celestial equator. It is also hemisphere-aware: by configuring your Tempo instance with a sphere (e.g., sphere: 'south'), the plugin accurately flips the Vernal Equinox from Spring to Autumn.

Meteorological vs Astronomical

Unlike Tempo's built-in Meteorological season Term — which rigidly snaps to the 1st day of calendar months — this Astronomical plugin calculates the dynamic, true solar boundaries that shift slightly year-over-year.

Installation

npm install @magmacomputing/tempo-plugin-astro

Note: This plugin requires @magmacomputing/tempo version 2.10.0 or higher.

Usage

import { Tempo } from '@magmacomputing/tempo';
import { AstroTerm } from '@magmacomputing/tempo-plugin-astro';

// A valid premium license token is required to use this plugin
// Pass the plugin to `Tempo.init` to ensure it registers securely alongside the license.
Tempo.init({ 
  license: 'YOUR_LICENSE_TOKEN',
  plugins: [AstroTerm] 
});

const t = new Tempo('2026-03-20');

// Get the Astronomical Event mapping
console.log(t.term.astro);
// Output: 'Vernal'

Response Payload

When resolving the term, the plugin intelligently returns the correct astronomical event and its corresponding traditional season based on your configured hemisphere (sphere):

{
  key: 'Vernal',     // Flips to 'Autumnal' if sphere is set to 'south'
  season: 'Spring',  // Flips to 'Autumn' if sphere is set to 'south'
  sphere: 'north',   // Flips to 'south' if sphere is set to 'south'
  event: 'Equinox',
  group: 'astronomy',
  year: 2026,
  month: 3,
  day: 20,
  hour: 14,
  minute: 45,
  second: 0
}

You can also access the full metadata object containing the sub-second precision fields via the astronomy term:

console.log(t.term.astronomy);
// Output: { key: 'Vernal', group: 'astronomy', year: 2026, month: 3, day: 20, hour: 14, minute: 45, ... }

Did you know?

Seasons: t.term.astronomy.season returns the Astronomical season calculated by the precise timing of solstices and equinoxes. This will often differ from t.term.season.key in the core library, which uses standard Meteorological/Civil calendar boundaries (e.g., 1st of the month).

Licensing

This is a Premium plugin. Usage requires an active, cryptographically signed Tempo license token with the astro scope enabled.

For commercial licensing options, please contact Magma Computing Solutions.