Generates liturgical calendars of the Roman Rite of the Roman Catholic Church.

Supports Node v12+, Browsers (IE11+).

Quick start (below on this page)

• Description
• Install
• Usage
• Contribute
• Revisions & Release History
• Module Robustness & Data Integrity
• Credits
• License

Main usages

• General use of romcal ⇗
• Output data and JSON schema ⇗

Contribute

• Install, Build, Run and Test romcal locally ⇗
• Localization ⇗
• Calendar definitions and contributions ⇗
• Codebase Documentation ⇗

romcal generates the liturgical calendar of the Catholic Church used by the Roman Rite (post-Vatican II). Output conforms to the revised liturgical calendar as approved by Paul VI in Mysterii Paschalis dated 14 February 1969. The rules are defined in the General Instruction on the Roman Missal (GIRM) and the General Norms for the Liturgical Year and the Calendar.

• 📅 Perpetual calendar:
  romcal allows querying liturgical dates for any year in the standard calendar. Note that dates for years before 1969 will still be returned in a format conforming to the calendar reforms of 1969, even though those years came before this calendar reform.

• ⚙️ Configure and refine output:
  output can be configured for the civil calendar year, i.e. the Gregorian year (Jan 1 to Dec 31) or the liturgical year (First Sunday of Advent to Christ the King). You can filter queries to allow more streamlined date results to be obtained for the year. Additional output options are described below in the usage section.

• 🌐 i18n, localization and calendars:
  romcal aims to have your liturgical calendars and contents in your native language, and support various liturgical calendars (national, diocesan...). You are more than welcome to contribute, add new localization, and improve the quality of this library!

Install via npm:

$ npm install romcal

Install via Yarn:

$ yarn add romcal

Additionally, romcal is also available for installation via various "release tags" that represent different stages of development for a given version of the code.

• latest The latest, stable and production-ready version of romcal is always released on the master branch. Releases on this branch are tagged in npm using the latest tag and can be installed via npm install romcal@latest or simply npm install romcal which defaults to the latest tag.

• beta The release candidate for production. Code here is mostly stable but may still lack some tests and so may be subject to some unexpected behavior. Install via npm install romcal@beta.

• alpha The unstable development release tag. Code here might be unstable and untested. Use at your own risk! Normally, only developers would use this release for testing purposes. Install via npm install romcal@alpha.

• canary Bleeding edge features; high levels of code instability. Consumers should almost always never need to install these releases as they contain ongoing work that is not complete for general use. Install via npm install romcal@canary.

Require romcal in your project:

var Romcal = require('romcal');

or as a CommonJS module:

import Romcal from 'romcal';

or in a webpage for direct usage on browsers:

<script type="text/javascript" src="node_modules/romcal/dist/es5/romcal.bundle.min.js"></script>

Including romcal directly in the browser will result in an object called romcal being attached to the DOM window object. All the functions below will exist as properties of the Romcal object.

Invoke the .calendarFor method to retrieve an array of liturgical dates and celebrations in the Roman Calendar. This method accepts an object of configuration properties to obtain customized output.

Romcal.calendarFor({
  year: 2020,                               // the calendar year to compute.
  scope: 'gregorian' | 'liturgical',        // 'gregorian': Jan 1 to Dec 31 ; or 'liturgical': the first Sunday of Advent to the last Saturday of Ordinary Time
  country: 'unitedStates',                  // the 'general' calendar or any particular calendar
  locale: 'en',                             // to get calendar data in the desired locale
  epiphanyOnSunday: true | false,           // Epiphany always a Sunday (between January 2 - 8), or on January 6
  corpusChristiOnSunday: true | false,      // Corpus Christi always a Sunday, or the Thursday after Trinity Sunday
  ascensionOnSunday: true | false,          // Ascension always a Sunday, or the 40th day of Easter (a Thursday)
  strictMode: true | false,                 // if true, only output one object per day ; optional memorials are not outputed
  verbose: true | false,                    // enable logging output from romcal
  prettyPrint: true | false,                // prettify logs printed in the console, for a better experience in development environnements
}).then(function (calendar) {
  console.log(calendar);
});

For further information about these properties and the default options: 📚 Configuration options.

A similar .liturgicalDayFor method is also available to retrieve data for a specific date only. The first parameter is a Date object, the second is the optional configuration properties (as for the .calendarFor).

e.g. to obtain today's liturgical day:

Romcal.liturgicalDayFor(new Date(), {
  country: 'france',
  locale: 'fr',
}).then(function (today) {
  console.log(today);
});

Please note that .calendarFor and .liturgicalDayFor are async. For further information in general: 📚 General use of romcal.

This 2 methods produces an Array of LiturgicalDay objects (by default, one object per each day of the year):

[
  {
    key: 'mary_mother_of_god',
    name: 'Mary, Mother of God',
    date: '2020-01-01T00:00:00.000Z',
    rank: 'SOLEMNITY',
    rankName: 'Solemnity',
    liturgicalColors: ['WHITE'],
    seasons: ['CHRISTMASTIDE'],
    seasonNames: ['Christmas'],
    periods: ['CHRISTMAS_OCTAVE'],
    cycles: {
      sundayCycle: 'YEAR_A',
      weekdayCycle: 'YEAR_2',
      psalterWeek: 'WEEK_2',
    },
    calendar: {
      totalWeeksInGregorianYear: 53,
      totalWeeksInLiturgicalYear: 52,
      weekOfGregorianYear: 1,
      weekOfLiturgicalYear: 5,
      weekOfSeason: 2,
      dayOfGregorianYear: 1,
      dayOfLiturgicalYear: 32,
      dayOfSeason: 8,
      dayOfWeek: 3,
      dayOfWeekCountInMonth: 1,
      startOfLiturgicalYear: '2019-12-01T00:00:00.000Z',
      endOfLiturgicalYear: '2020-11-28T00:00:00.000Z',
      easter: '2020-04-12T00:00:00.000Z',
    },
    fromCalendar: 'general',
    fromExtendedCalendars: [],
    metadata: {
      titles: [],
    },
  },
  // ...
]

For further information: 📚 Output data and JSON schema.

romcal is an open source project, this means you are more than welcome to contribute! Especially to find bugs or write new tests, verify or complete calendars, or pull new localization.

To jump into romcal’s codebase more easily, you might be interested in reading:

• 📚 Contributing Guide.
• 📚 Install, Build, Run and Test romcal locally.
• 📚 Localization.
• 📚 Codebase Documentation.

See history for the latest updates and important/breaking changes.

romcal’s code logic aim to be fully compliant with the General Instruction on the Roman Missal (GIRM) and the General Norms for the Liturgical Year and the Calendar.

Calendar entries are pulled from the missal and official sources for the General Roman Calendar. Other calendar entries are pulled from various liturgical books and sources from the internet (when we don't have access to the missal or official proper books of the country / region). As such the accuracy for all calendars might not be ensured. If you find an incorrect calendar entry (e.g. wrong date, wrong feast rank, spelling issue, typos), you are most welcome to contribute or inform the team on the GitHub issue tracker, so that the necessary changes can be made to make this a more robust and reliable module.

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.

Additional credits for bug fixes, localization and suggestions can be seen at here.

MIT