Utility library that outputs the Liturgical Calendar used by the Roman Rite (Western Church)
All contributions are most welcome!
Please fork/raise merge requests or issues to improve the quality of this module.
I especially reach out to you all for help with translations/localizations of celebration names so that this module can cater to a wider audience.
- Description
- Credits
- Features
- Module Robustness & Data Integrity
- Revisions
- Usage
- Celebration Types
- Celebration Titles
- Liturgical Seasons
- Liturgical Cycles
- Liturgical Colors
- Psalter Weeks
- Calendar Sources
- Queries
- Overriding dates
- Localizing celebration names
Romcal is a module that generates the General Roman Calendar used in the Roman Catholic Rite. This module conforms to the revised liturgical calendar for the Western Church as approved by Paul VI in Mysterii Paschalis dated 14 February 1969.
This module can output dates based on the standard calendar year (Jan, 1st - Dec, 31st) or the liturgical year (First Sunday of Advent - Christ the King) alongside many other features for fine-tuning output as described below.
This node module is inspired by the C program romcal written by Kenneth G. Bath. This module, while exhibiting similar output, is written ground up using different tools and technologies and exposes many new functionalities.
- Able to query liturgical dates for any year in the gregorian calendar (1582 - now). Note that dates for years before 1969 will still be returned in a format conforming to Mysterii Paschalis even though those years came before the calendar reforms in 1969.
- Filter queries to allow more streamlined date results to be obtained for the year.
- Localization of liturgical date names to cater for different languages
- National liturgical calendars for country specific.
- Richly commented code to help developers and contributors understand how the module works.
NOTE: This module depends on Moment and lodash for most of its calculations and operations. Several Moment plugins such as Range and Recur are used to extend date computation functionality. Familiarity with these libraries makes reading the code much easier.
Calendar entries for this module are pulled from various sources from the net. As such their accuracy cannot be ensured. If you find an incorrect calendar entry (e.g. wrong date, wrong feast type, spelling issue, typos), you are most welcome to contribute to the source code or inform me so that the necessary changes can be made to make this a more robust and reliable module
Romcal's code logic is developed according to calendar requirements descibed in various church documents sourced from the internet (and even from Wikipedia). If you notice discrepancies between romcal's output and actual liturgical dates, please do contribute your fixes or submit an issue on GitHub.
romcal logic is tested using mocha and should.
Run npm test
in your console to view test output.
Travis CI is used to validate romcal builds to ensure functionality is working as expected.
See history
Add romcal to your project via npm:
$ npm install romcal
Then require romcal in your node project:
var romcal = require('romcal');
Invoke the calendarFor
method to retrieve an array of liturgical dates and celebrations in the Roman Calendar. This method accepts an object (optional) representing configuration properties to customize the output.
romcal.calendarFor({
year: 2015,
country 'unitedStates',
locale: 'pl',
christmastideEnds: 't|o|e',
epiphanyOnJan6: true|false,
corpusChristiOnThursday: true|false,
ascensionOnSunday: true|false,
type: 'calendar|liturgical',
query: {
day: 0 - 6, // 0 - Sunday, 6 - Saturday (week beginning with Sunday)
month: 0 - 11, // 0 - Jan, 11 - Dec (month begining with Jan)
group: '',
title: '',
}
},
true|false );
year
: Retrieve calendar dates for the given year (year should be an integer). Defaults to the current system year if not specifiedcountry
: Include celebration dates requested by the Episcopal council(s) of the given country that have been approved by the Holy See. If not specified, no National dates are included in the calendar output. If an unrecognized country is specified, romcal will silently ignore the property and will not return any National dates in the calendar output.locale
: Defaults to 'en' (english) if not set. Romcal celebration names can be localized to different languages. If a given locale does not have the localized name for a celebration in that language, romcal will fallback to use the celebration name in English.christmastideEnds
: Specifies the end of the Christmas season. Can be either 't' (traditional where Christmastide ends on Epiphany), 'o' (ordinary where Christmastide ends on the Baptism of the Lord) and 'e' (extraordinary where Christmastide ends on the Presentation of the Lord). Defaults to 'o' (ordinary) if not specifiedepiphanyOnJan6
: If true, fixes Epiphany on January 6th always. By default, Epiphany will be set to a Sunday between 2 - 8 Jan based on an internal calculation.corpusChristiOnThursday
: Determines if Corpus Christi should be celebrated on Thursday on the 7th week of Easter (60 days after Easter) or Sunday (63 days after Easter).ascensionOnSunday
: Determines if Ascension should replace the 7th Sunday of Easter (42 days after Easter). Defaults to false where Ascension will be on Thursday, 39 days after Easter, if value not recognized or specified.type
: Determines the type of calendar output. Can either beliturgical
orcalendar
. Defaults tocalendar
if value not recognized or specified. The 'liturgical' year runs from 1st Sunday of Advent of the given year to Saturday of the 34th Week of Ordinary Time in the following year. The 'calendar' year on the other hand refers to the standard year from Jan 1 - Dec 31.query
: A nested query object which filters the dates according to the given criteria. For more details on how to use queries, see this section.
The second parameter that can be passed to the romcal.calendarFor()
method.
It is an optional parameter: If true, skip converting dates to ISO8601 strings and return dates as moment objects. Defaults to false if not specified.
romcal returns an array of liturgical date objects in the following structure
[
{
"key": "",
"name": "",
"type": "",
"moment": "",
"source": "",
"data": {
"prioritized": boolean
"season": "",
"meta": {
"liturgicalColor": {}
"titles": []
}
}
}
]
key
: A camel case string which serves as a unique identifier for the celebration. This key is an essential element in overriding datesname
: The localizable name of the celebrationtype
: A key representing the celebration typemoment
: Moment object or ISO8601 string of the date of the celebrationsource
: The internal calendar source of this celebrationdata
: An object that holds additional information about the celebration- prioritized: A optional boolean that when true, gives the celebration higher priority over another coinciding celebration even thought that celebration has a higher ranking type. This flag should be used with caution.
- season: Required: A string that identifies the liturgical season this celebration belongs to
- meta:
- liturgicalColor: The liturgical color assigned for this celebration (usually follows the liturgical season but may defer if this celebration is a solemnity, feast or memorial)
- titles: An array of titles that may be assigned to this celebration
Each date in the liturgical calendar is assigned a types. romcal defines these types in data/types.json
which are:
SOLEMNITY
SUNDAY
TRIDUUM
HOLY_WEEK
FEAST
MEMORIAL
OPT_MEMORIAL
COMMEMORATION
WEEKDAY
Where the importance or rank of the celebration is in descending order (Solemnity being of highest importance and weekday being the lowest).
Types play an important role in determining which celebration should take precendence over another when two or more celebrations coincide on the same date. Certain celebration types will also have different liturgical colors applied to them.
On top of having a celebration type, liturgical dates may also have one or more titles of significance assigned to it.
For example, the feast of Saint Catherine of Siena is assigned the titles PATRON_OF_EUROPE
(for national calendars of countries in Europe only) and DOCTOR_OF_THE_CHURCH
due to those titles being conferred on her by the Church.
romcal defines liturgical seasons in data/titles.json
which are:
The titles available for:
FEAST_OF_THE_LORD
PATRON_OF_EUROPE
DOCTOR_OF_THE_CHURCH
MARTYR
The liturgical calendar is divided into various seasons that occur throughout the liturgical year.
romcal defines liturgical seasons in data/seasons.json
which are:
ADVENT
CHRISTMASTIDE
EARLY_ORDINARY_TIME
LATER_ORDINARY_TIME
LENT
HOLY_WEEK
EASTER
The methods in lib/seasons.js
assigns seasons to the dates it generates to indicate the season to which the range of dates generated belong.
A liturgical year consists of a cycles (either A, B, C) that determines which portions of scripture are to be read. romcal automatically calculates the correct cycle for the given liturgical year and includes it in the meta information of each liturgical date for that year.
This information can be extracted via the dates[idx].data.meta.cycle
property.
romcal defines 6 colors in data/liturgicalColors.json
which are:
WHITE
GOLD
RED
ROSE
PURPLE
GREEN
More information on how these colors are used for celebration can be found here
This information can be extracted via the dates[idx].data.meta.liturgicalColor
property.
With the exception of the Easter Octave, each week in the liturgical year is assigned readings from the Psalter. There are also some rules that govern the set of Psalter readings used for particular occasions or seasons in the year.
romcal defines the Psalter Weeks used in the liturgical year in data/psalterWeeks.json
which are:
Week I
Week II
Week III
Week IV
Easter
(sepeate set of readings only used during the Octave of Easter)
This information can be extracted via the dates[idx].data.meta.psalterWeek
property.
romcal generates dates that come from 4 different internal sources:
l
: liturgicalc
: celebrationsg
: generaln
: national
Each date is assigned a source with one of the four calendar sources above.
Calendar sources play an important role in how romcal manages coinciding dates (see overriding dates).
Represents a standard date in the liturgical year. Dates from this source build the basic structure of the liturgical calendar from the start of the liturgical year to its end.
Dates from lib/seasons.js
will be assigned the source l
The module responsible for generating the liturgical
dates is lib/seasons.js
.
It is highly unlikely that this module will need customization or overriding of any kind.
Represents central celebrations observed in the Roman Catholic rite. They take precendence and will replace coinciding dates from the liturgical
calendar or general
calendar. Date objects from this calendar will contain the source c
.
The module responsible for generating celebrations
is lib/celebrations.js
. It is highly unlikely that this module will need customization or overriding of any kind.
A prioritized date defined in the national
calendar can replace a date in the celebrations
calendar when:
- the key of the
national
date matches a key incelebrations
- the
national
date is prioritized However, this is not recommended becausecelebration
dates are significant in the liturgical year and are usually never changed by the national calendars used in other countries. Be very sure if and when overriding acelebrations
date from thenational
calendar.
The following are a list of dates defined in the celebrations
calendar:
- Immaculate Conception
- Christmas
- Mary Mother of God
- Epiphany
- Trinity Sunday
- Corpus Christi
- Sacred Heart of Jesus
- Birth of John the Baptist
- Peter and Paul, Apostles
- Assumption
- All Saints
- Christ the King
- Joseph, Husband of Mary
- Annunciation
- Easter
- Divine Mercy Sunday
- Ascension
- Pentecost Sunday
- Ash Wednesday
- Palm Sunday
- Holy Thursday
- Good Friday
- Holy Saturday
- Holy Family
- Baptism of the Lord
- Presentation of the Lord
- Transfiguration
- Triumph of the Cross
- Immaculate Heart of Mary
Represents general celebrations that are celebrated throughout the liturgical year. Dates from the general
calendar will override dates from the liturgical
calendar.
Dates from calendars/general.js
will be assigned the source g
The module responsible for generating the general
dates is lib/calendars/general.js
.
general
calendar dates will always be overwritten by celebration
or national
calendar dates even if they are prioritized. Hence, it is not recommended to edit or add new dates into this calendar.
In situations where a given celebration must override one in the general calendar, define it in the national
calendar instead.
Represents specific liturgical dates that have been approved for use by the Holy See for a particular country. It can be used to define unique celebrations celebrated by that particular country or existing celebrations that have been transferred to another date.
A prioritized celebration in the national
calendar takes precedence over celebrations in general
, celebrations
and liturgical
calendars. As such, this marker should be used with caution lest it overrides an important celebration that should not be overriden leading to an erroneous calendar output.
In situations when there are 2 celebrations from national
calendar that coincide on the same date, the one with the higher ranking celebration type will take precendence.
A new national
calendar for a country can be defined by creating a new .js
file with the country name in upper case, lower case or camel case in the lib/calendars
folder (i.e. malaysia.js). This new file will automatically be picked up by the module and will be used when the user supplies the matching key in the country argument in the calendarFor
method.
Dates from calendars/countryName.js
will be assigned the source n
See [Overriding dates](#Overriding dates) for more examples.
Romcal can filter calendarFor
results if a query object is passed along with the initial configuration object:
romcal.calendarFor({
query: {
month: 0 // 0 - 11
}
});
or
romcal.calendarFor({
query: {
day: 0, // 0 - 6
}
});
romcal.calendarFor({
query: {
group: 'days|months|daysByMonth|weeksByMonth|cycles|types|liturgicalSeasons|liturgicalColors|psalterWeeks'
}
});
romcal.calendarFor({
query: {
title: 'PATRON_OF_EUROPE'
}
});
Possible values can be checked here.
Warning: Passing more than one criteria to the query object may cause errors or unpredictable results.
Romcal has been designed with extensibility in mind to cater for specific scenarios that are commonplace in the liturgical calendar. The sections below describe the methods employed by romcal when overriding dates.
The order of importance of calendar sources are: celebrations > national > general > liturgical.
Prioritized dates may override dates of higher ranking celebration types and also prevent itself from being overriden by other coinciding dates. For example, dates in lib/celebrations.js
(Christmas, Easter) are all prioritized as they can override any other date in the liturgical calendar and may not be overriden by any other coinciding date regardless of rank unless the coinciding date is itself prioritized (for example, allSaints
in 'lib/celebrations.js' can be overriden by
allSaintsin
calendars/england.js`).
Caveat:
If a coinciding date's source is from the
celebration
ornational
calendars, and the prioritized date is from thegeneral
calendar, it will still be overidden by the coinciding date ascelebration
andnational
calendar sources have higher precedence.
In most other countries, All Saints and All Souls are celebrated on the 1st and 2nd of November respectively. However, in England and Wales, when All Saints (1 November) falls on a Saturday, it is transferred to the Sunday and All Souls is transferred to Monday 3rd Novemeber.
Romcal achieves this difference by redefining the allSouls
and allSaints
celebrations in the national calendars of calendars/england.js
and calendars/wales.js
(the original definition was in calendars/general.js
). Since national calendar dates have higher precendence than general calendar dates, the national date definitions for All Saints and All Souls will override the ones in the general calendar.
Therefore, it is important that the key in the national calendar is exactly the same as the one in the general calendar so that romcal recognizes it for overriding.
Celebration names in Romcal can be localized to any language that is already supported by Moment i18n. Locales are stored as .json
files in the locales
directory where the name of the file corresponds to the locale name of a given language.
en
is the default locale in romcal and serves as the fallback when the user specified locale has not been defined in the locales
directory or the given key does not exist in the locale.
The structure of the locale file is typically like so:
{
"advent": {
},
"christmastide": {
},
"epiphany": {
},
"ordinaryTime": {
},
"lent": {
},
"holyWeek": {
},
"eastertide": {
},
"celebrations": {
},
"general": {
},
"national": {
}
}
The first 7 objects define locale keys used by lib/seasons.js
when generating litugical dates.
The celebrations
, general
and national
objects will hold localizations for lib/celebrations.js
, calendars/general.js
and calendars/country.js
respectively where the celebrations key
is used as the identifier for localization purposes.
See the end of these files to see the function that localizes the dates according to their keys.
romcal uses the utility function Utils.localize()
to resolve the correct locale string based on the given key.
The function accepts several parameters:
Utils.localize({
key: '',
week: 0,
count: 0
});
key
: A dot deliminated string representing the locale key (celebrations.christmas
)week
: A non zero integer for weeks which will be converted to its ordinal representation (1st Sunday of Advent)count
: A non zero integer for days which will be converted to its ordinal representation (2nd Sunday of Christmas)