harptos

Class for representing a date in the Calendar of Harptos

The primary calendar system of the Forgotten Realms is called The Calendar of Harptos, named after its creator. Groups of ten days are called a tenday. A group of three tendays is called a month. A year consists of twelve months plus an additional five or six festival days placed in-between the months. A leap year occurs every four years.

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 _Harptos from 'harptos';

Constructor

The function requires one argument. The argument may be a number, an object, or a string.

Number

A Harptos instance can be created from the number of days since Dalereckoning. It can be negative, positive, or zero but it must be an integer.

const harptos = _Harptos(505991);

Object

A Harptos instance can be created from a config object. If the config object has a day property, the value is the number of days since Dalereckoning. This is the same as a Number argument above. Otherwise the config object is expected to have three properties: dayOfMonth, monthOfYear, and year. All three values must be integers. dayOfMonth and monthOfYear must be positive and within a valid range.

const harptos = _Harptos({
    dayOfMonth: 29,
    monthOfYear: 4,
    year: 1385
});

A Harptos instance can be created from another Harptos instance.

const harptos = _Harptos(other);

String

A Harptos instance can be created from a date string. The date string contains the year, the month of year, and the day of month separated by dashes. These numbers may optionally be padded with leading zeros.

const harptos = _Harptos('1385-04-29');

Instance Properties

All properties are read-only.

• harptos.day - Integer number of days since Dalereckoning. The first day of Dalereckoning is 0.

• harptos.dayName - Optional string on certain named days. For example, Ches 19 is the Spring Equinox. This value is undefined on days that aren't named.

• harptos.dayOfMonth - Positive integer number day of month. The first day of the month is 1. The festival days are technically between months, but they will have day of month 31. The Shieldmeet leap day will have day of month 32.

• harptos.dayOfTenday - Optional positive integer number day of tenday. The first day of the tenday is 1. This value is undefined on festival days and the Shieldmeet leap day because they are not within a tenday.

• harptos.dayOfYear - Positive integer number day of year. The first day of the year is 1.

• harptos.daysInMonth - Positive integer number of days in this instance's month. Most months have 30 days. A month that is immediately followed by a festival day has 31, because that festival is counted as the 31st day of the month. Flamerule in a leap year has 32 to account for the Shieldmeet leap day.

• harptos.daysInYear - Positive integer number of days in this instance's year. This is 365, or 366 in a leap year.

• harptos.inLeapYear - Boolean whether this instance's year is a leap year.

• harptos.isFestival - Boolean whether this instance is one of the festival days that fall between the months. These days are not within a tenday.

• harptos.isShieldmeet - Boolean whether this instance is Shieldmeet, the leap day that occurs once every four years as the 32nd day of Flamerule.

• harptos.monthName - String name of the month.

• harptos.monthOfYear - Positive integer number month of year. The first month of the year is 1.

• harptos.moonPhase - Object containing information about the phase of Selûne. This object has three read-only properties: icon, name, and value. The value of the moon phase 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 Selûne 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.

• harptos.season - String name of one of the four seasons.

• harptos.tenday - Optional positive integer number tenday of the month. The first tenday of the month is 1 and the last is 3. This value is undefined on festival days because they are not within a tenday.

• harptos.year - Integer number Dalereckoning year.

• harptos.yearName - Optional string name of the year. Year names are defined by the roll of years. This value is undefined in years that do not have a name.

Instance Methods

• harptos.add(duration) - Returns a new Harptos instance advanced by the given duration. The duration is an optional object that may have any of four properties: days, tendays, months, and years. A tenday is ten days. Years and months are applied first, with the day of month constrained to the length of the target month, and then days and tendays are applied as an exact number of days. For example, adding one year to Shieldmeet lands on Midsummer, the 31st day of Flamerule, when the target year is not a leap year. Called with no argument it returns an equivalent copy.

• harptos.endOfMonth() - Returns a new Harptos instance for the last day of this instance's month. Because a festival day is counted as the final day of the month it follows, this is that festival day in the months that have one, and it is Shieldmeet for Flamerule in a leap year.

• harptos.endOfTenday() - Returns a new Harptos instance for the last day, the tenth, of this instance's tenday. This value is undefined on festival days because they are not within a tenday.

• harptos.endOfYear() - Returns a new Harptos instance for the last day of this instance's year, which is always the 30th day of Nightal.

• harptos.equals(other) - Returns true if the argument is a Harptos instance that refers to the same date as this instance. Returns false for any other value, including values that are not Harptos instances.

• harptos.since(other) - Returns the duration from another date to this date as an object with a days property. The argument may be anything the constructor accepts. The result is positive when this instance is the later date. Because months are not a uniform length, the duration is expressed only in days.

• harptos.startOfMonth() - Returns a new Harptos instance for the first day of this instance's month.

• harptos.startOfTenday() - Returns a new Harptos instance for the first day of this instance's tenday. This value is undefined on festival days because they are not within a tenday.

• harptos.startOfYear() - Returns a new Harptos instance for the first day of this instance's year, which is always the 1st day of Hammer.

• harptos.subtract(duration) - Returns a new Harptos instance moved back by the given duration. This is the inverse of add and accepts the same duration object.

• harptos.toJSON() - Returns a plain JavaScript object with three properties: dayOfMonth, monthOfYear, and year.

• harptos.toString() - Returns a date string containing the year, the month of year, and the day of month separated by dashes.

• harptos.until(other) - Returns the duration from this date to another date as an object with a days property. The argument may be anything the constructor accepts. The result is positive when the argument is the later date. Because months are not a uniform length, the duration is expressed only in days.

• harptos.with(fields) - Returns a new Harptos instance with the given fields replaced by the values in the argument. The argument is an optional object that may have any of three properties: dayOfMonth, monthOfYear, and year. Fields that are omitted are carried over from this instance. It throws a RangeError if the resulting date is not valid. Combined with daysInMonth this is a convenient way to find the boundaries of a period, such as harptos.with({ dayOfMonth: 1 }) for the first day of the month.

Static Methods

• _Harptos.compare(a, b) - Requires two arguments which should both be Harptos instances. If the date referred to by instance a is before the date referred to by instance b, it returns -1. If the date referred to by instance a is after the date referred to by instance b, it returns 1. If the date referred to by instance a is the same as the date referred to by instance b, it returns 0. It throws a TypeError if either argument is not a Harptos instance. This method could be used with Array.prototype.sort to sort an array of Harptos instances.

• _Harptos.range(start, end) - Returns an iterable iterator that yields a Harptos instance for each day from start up to but not including end. Both arguments may be anything the constructor accepts. The range is empty when start is not before end. The iterator is lazy, so it can describe a very large span of days without creating them all at once.

The iterator can be used anywhere an iterable is expected, such as a for...of loop, the spread operator, or Array.from. This example collects the names of the festival days that occur during the year 1492.

const festivals = [];

for (const date of _Harptos.range('1492-01-01', '1493-01-01')) {
    if (date.isFestival) {
        festivals.push(date.dayName);
    }
}

Type Coercion

Number

Harptos instances can be coerced to a number. The number value is the same as harptos.day, the number of days since Dalereckoning. This can be used to create a new instance by adding or subtracting a number of days.

const today = _Harptos({
        dayOfMonth: 23,
        monthOfYear: 3,
        year: 1492
    }),
    tomorrow = _Harptos(today + 1),
    yesterday = _Harptos(today - 1);

String

Harptos instances can be coerced to a string. The string value is the same as harptos.toString().

const date = _Harptos({
        dayOfMonth: 31,
        monthOfYear: 11,
        year: 1451
    }),
    string = `The next full moon is during the Feast of the Moon on ${date}.`;

License

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