Sanctus

Sanctus is an open-source saints martyrology that generates saints' information for the Roman Catholic Church. It supports Node.js v18+ and modern browsers (desktop and mobile).

Ejemplo: aplicación web que utiliza la librería: santoral.breviarium.es

Installation

Install the module using npm:

npm i sanctus

Usage

Here are some examples of how to use Sanctus:

Importing and Initializing

import { Sanctus } from "sanctus";

const sanctus = new Sanctus();

Getting a Single Saint by Date

import { SaintInfo, Sanctus } from "sanctus";

const sanctus = new Sanctus();
const saint: SaintInfo | undefined = sanctus.getSaint(new Date(2025, 1, 17));
console.log(saint?.name); // "San Teodoro de Bizancio"

Getting a Saint by Month and Day

import { SaintInfo, Sanctus } from "sanctus";

const sanctus = new Sanctus();
const saintByDate: SaintInfo | undefined = sanctus.getSaintFromMonthDay(2, 17);
console.log(saintByDate?.name); // "San Teodoro de Bizancio"

Getting All Saints of the Current Day

import { SaintInfo, Sanctus } from "sanctus";

const sanctus = new Sanctus();
const saintsOfDay: SaintInfo[] = sanctus.getSaintsOfDay();
console.log(saintsOfDay);

Setting a New Date and Getting Saints

import { SaintInfo, Sanctus } from "sanctus";

const sanctus = new Sanctus();
sanctus.setDate(new Date(2025, 5, 1));
const saintsFromNewDate: SaintInfo[] = sanctus.getSaintsOfDay();
console.log(saintsFromNewDate);

Testing

To run the test suite (using vitest), execute:

# Linux and macOS users:
make test

# Windows users:
npm run test

SanctusInterface Documentation

The SanctusInterface provides methods to retrieve information about saints based on dates or direct month/day lookups.

Interface Definition

export interface SanctusInterface {
  getSaint: (date?: Date) => SaintInfo | undefined;
  getSaintFromMonthDay: (month: number, day: number) => SaintInfo | undefined;
  getSaintsOfDay: (date?: Date) => SaintInfo[];
  getAllSaints: () => SaintInfo[];
  getCurrentDate: () => Date;
  setDate: (date: Date) => void;
}

Function Documentation

Method	Description	Parameters	Return Type	Example Call
getSaint	Get a single saint's info for a date.	date?: Date	SaintInfo | undefined	sanctus.getSaint(new Date(2025, 1, 17));
getSaintFromMonthDay	Get a single saint by month and day.	month: number, day: number	SaintInfo | undefined	sanctus.getSaintFromMonthDay(2, 17);
getSaintsOfDay	Get all saints for a given date.	date?: Date	SaintInfo[]	sanctus.getSaintsOfDay();
getAllSaints	Get all saints in the database.	None	SaintInfo[]	sanctus.getAllSaints();
getCurrentDate	Get the currently set date.	None	Date	sanctus.getCurrentDate();
setDate	Set a new date.	date: Date	void	sanctus.setDate(new Date(2025, 5, 1));

SaintInfo Type Definition

export type SaintInfo = {
  month: number;
  day: number;
  category: number;
  name: string;
  birth?: string;
  dead?: string;
  meaning?: string;
  shortDescription?: string;
  description?: string;
};

SaintInfo Properties

Property	Type	Required	Description
month	number	✅ Yes	Month of the saint's feast day (1-12).
day	number	✅ Yes	Day of the saint's feast day (1-31).
category	number	✅ Yes	Category or rank of the saint.
name	string	✅ Yes	Name of the saint.
birth	string	❌ No	Birth year or approximate time.
dead	string	❌ No	Death year or approximate time.
meaning	string	❌ No	Meaning or significance of the saint's name.
shortDescription	string	❌ No	Brief summary of the saint.
description	string	❌ No	Detailed description of the saint's life.