selune

This package calculates which phase a moon is in on any given day.

As the moon orbits, the portion of its face that is lit by the sun grows and shrinks in a repeating cycle: new moon, waxing crescent, first quarter, waxing gibbous, full moon, waning gibbous, last quarter, waning crescent, and back to new. The length of one complete cycle is called the synodic period.

This package can calculate the phase of any moon, using any calendar system, but its name comes from the Forgotten Realms fantasy setting. Selûne is the goddess of the moon and the name of the moon itself in that setting.

This package can be especially useful if your Dungeons & Dragons campaign has rules such as: This door is magically locked and can only be opened on nights of the new moon. As each day passes in your campaign, you can check the moon phase.

Usage

This module's default export is a function. This function can be called with the new keyword as a constructor or called without the new keyword as a factory.

import _Selune from 'selune';

Constructor

The function accepts one optional argument, a config object. The config object may have a synodicPeriod property, the number of days in one complete cycle of the moon. It must be a positive number. When it is omitted, the synodic period defaults to 30.4375, the synodic period of Selûne.

const selune = _Selune();

const selune = _Selune({
    synodicPeriod: 29.530588853
});

Synodic period

Selûne's synodic period of 30.4375 days is exactly 365.25 divided by 12. Selûne therefore completes twelve whole cycles in a 365.25 day year, which is why the Calendar of Harptos divides a year into twelve tidy months of thirty days each.

The Earth's moon has a synodic period of roughly 29.53 days. Because that does not divide evenly into a year, an observer on Earth sees about 12.37 cycles per year rather than a whole number, which is the reason lunisolar calendars have to insert leap months. To model the Earth's moon, pass its synodic period, for example { synodicPeriod: 29.530588853 }. Any other moon, real or fictional, can be modeled the same way by passing its own synodic period.

This is a linear model: the phase is assumed to advance at a constant rate across the cycle. For the Earth's moon, that tracks the real phase to within about a day, which is fine for a calendar or a casual display but is not astronomically precise, because the real moon's orbit is elliptical and its apparent motion is not perfectly constant.

Instance Methods

• selune.phase(day) - Returns an object describing the phase of the moon on the given day. The day is an integer. Day 0 is a full moon, and every other day is counted as a whole number of days before or after it, so it can be negative, positive, or zero. A consumer brings its own calendar and converts one of its dates into this day number by choosing a full moon to be day 0. The returned object is frozen and has three read-only properties: icon, name, and value.

The value is a number that is greater than negative 1 and less than or equal to 1. This range can be expressed as (-1, 1]. The absolute value of this number correlates with the amount of the moon that is lit up. A value of 0 is a new moon and is completely dark. A value of 1 is a full moon and is completely bright. A negative value is a waning phase and a positive value is a waxing phase. A value of -.5 is the last quarter phase. A value of .5 is the first quarter phase.

The icon is a string containing a single unicode character, one of these: 🌕 🌖 🌗 🌘 🌑 🌒 🌓 🌔. The name is the string name of the moon phase, one of Full Moon, Waning Gibbous, Last Quarter, Waning Crescent, New Moon, Waxing Crescent, First Quarter, or Waxing Gibbous.

The four primary phases, new moon, first quarter, full moon, and last quarter, each fall on a single day of the cycle, the whole day nearest the exact moment of the phase. This makes it convenient to test for a specific phase. On a slowly phasing moon, the moon's face may look full to the eye for several days, but only one of those days is reported as the full moon.

const phase = _Selune().phase(0);

// phase is { icon: '🌕', name: 'Full Moon', value: 1 }

Instance Properties

• selune.synodicPeriod - The read-only number of days in one complete cycle of the moon, either the value that was passed to the constructor or the default.

License

This module uses material from the Selûne (moon) article on the Forgotten Realms Wiki at Fandom under the Creative Commons Attribution-Share Alike License.