Romcal
JavaScript library that generates liturgical calendars of the Roman Rite of the Roman Catholic Church.
Install / Use
/learn @romcal/RomcalREADME
[!NOTE] This project is still in beta (using the
devnpm distribution tag) until it reaches final version 3.0.0. There could be breaking changes between minor versions. Please refer to the changelog for significant updates and breaking changes.
Documentation
Quick start (below on this page)
- Description
- Getting started
- Basic samples
- Contribute
- Revisions & Release History
- Module Robustness & Data Integrity
- Credits
- License
Main usages
Contribute
- Install, Build, Run and Test romcal locally ⇗
- Localization ⇗
- Calendar definitions and contributions ⇗
- Codebase Documentation ⇗
Description
Romcal generates liturgical calendars of the Roman Rite of the Roman Catholic Church. 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), the General Norms for the Liturgical Year and the Calendar (GNLY), and the General Instructions of the Liturgy of the Hours (GILH).
-
:date: Perpetual calendar:<br> 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.
-
:gear: Configure and refine output:<br> output can be configured for the civil calendar year, i.e. the Gregorian year (
Jan 1toDec 31) or the liturgical year (First Sunday of AdventtoChrist 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. -
:globe_with_meridians: i18n, localization and calendars:<br> 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!
Getting started
Installation
Romcal can be added to your project using npm or yarn:
# npm
npm install romcal@dev
# yarn
yarn add romcal@dev
The default export is CommonJS compatible (cjs).
In the /dist folder you may find additional builds for es6 modules (esm) or to be used globally from the browser (iife).
The correct entry points are already configured in the package.json so there should be no extra setup to get the best build option.
Calendars installation
The romcal library only include the General Roman Calendar (GRC), and the Proper of Time. By default, there is no other calendars, neither translation (even in English) nor extra martyrology metadata.
The complete GRC, and any other particular calendar (for a country, a region or a diocese) are available as separated plugins, that contain a bundle of the calendar data, localizations, and a martyrology catalog (containing extra metadata).
For example, to install the General Roman Calendar and the calendar of France:
# npm
npm install @romcal/calendar.general-roman@dev
npm install @romcal/calendar.france@dev
# yarn
yarn add @romcal/calendar.general-roman@dev
yarn add @romcal/calendar.france@dev
The complete list of localized calendar is available here.
Load from CDN
You can also directly add a script tag loading romcal from one of the CDNs providing it:
unpkg.com
- https://unpkg.com/romcal/dist/iife/romcal.js
esm or cjs:
- https://unpkg.com/romcal/dist/esm/romcal.js
- https://unpkg.com/romcal/dist/cjs/romcal.js
Make sure to use a fixed version in production like https://unpkg.com/romcal@3.0.0-dev.29/dist/cjs/romcal.js as passing no version will redirect to the latest version which might contain breaking changes in the future.
cdnjs.com
https://cdnjs.com/libraries/romcal
Basic samples
Initialize a Romcal object
Before generating any kind of data, you must first generate a new Romcal() object.
1. Import Romcal
// as esm
import { Romcal } from 'romcal';
import { France_Fr } from '@romcal/calendar.france';
// or as cjs
const { Romcal } = require('romcal');
const { France_Fr } = require('@romcal/calendar.france');
<!-- or as iife in a web HTML page -->
<script src="https://unpkg.com/romcal@3.0.0-dev.29/dist/iife/romcal.js"></script>
<script src="https://unpkg.com/@romcal/calendar.france@3.0.0-dev.29/iife/fr.js"></script>
2. Initialize Romcal
With default options:
const romcal = new Romcal();
Or with any of the optional options:
// Initialize romcal (all options are optional)
const romcal = new Romcal({
localizedCalendar: France_Fr, // The localized calendar to use with romcal
scope: 'gregorian' | 'liturgical', // Default: 'gregorian' (Jan 1 to Dec 31). Optionally: 'liturgical' (the first Sunday of Advent to the last Saturday of Ordinary Time)
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)
elevatedMemorialIds: ['john_paul_ii_pope', 'our_lady_of_fatima'], // List of optional memorials to be elevated to mandatory memorials
});
For further information about romcal configuration and the default options: :books: Configuration options.
You can also take a look to the romcal/romcal-examples repository, which contain additional examples:
- html-web-page – loading romcal in a HTML script tag (
iife). - react-app – a basic React application loading and displaying romcal data.
- rest-api-with-express – a REST API using Node.js and Express, written as CommonJs (
cjs). - rest-api-with-fastify – a REST API using Node.js and Fastify, written as ES Module (
esm).
Generate a calendar .generateCalendar(year)
The year parameter is optional.
Below, 2 examples to generate a calendar for a specific year or the current year.
// Get a romcal calendar for 2030, using a Promise:
romcal.generateCalendar(2030).then((data1) => {
console.log(data1);
});
// Or get a romcal calendar for the current year, using async/await:
const data2 = await romcal.generateCalendar();
console.log(data2);
This method produces an Object of key/values, where the key is a date (as a ISO8601 string), and the value is an Array of LiturgicalDay objects that can occur on a specific day.
The first LiturgicalDay object is the default one, the following objects are optionals (e.g. optional memorials).
{
key: 'mary_mother_of_god',
name: 'Mary, Mother of God',
date: '2020-01-01',
precedence: 'GENERAL_SOLEMNITY_3',
rank: 'SOLEMNITY',
rankName: 'Solemnity',
isHolyDayOfObligation: true,
isOptional: false,
colors: ['WHITE'],
seasons: ['CHRISTMASTIDE'],
seasonNames: ['Christmas'],
periods: ['CHRISTMAS_OCTAVE'],
martyrology: [],
titles: [],
cycles: {
sundayCycle: 'YEAR_A',
weekdayCycle: 'YEAR_2',
psalterWeek: 'WEEK_2',
},
calendar: {
weekOfSeason: 2,
dayOfSeason: 8,
dayOfWeek: 3,
nthDayOfWeekInMonth: 1,
startOfSeason: '
