Prayer Collection

A comprehensive collection of traditional Roman Catholic prayers in multiple languages, organized as structured JSON files with flexible label-based classification.

Overview

This NPM package provides 57 traditional Catholic prayers in 8 languages (Latin, English, Spanish, French, German, Italian, Portuguese, Polish) with rich metadata and a flexible multi-label classification system.

Key Features:

• 🌍 Multilingual Support - 8 languages per prayer
• 🏷️ Flexible Classification - Multi-label system with categories and tags
• 🌐 Universal Compatibility - Works in Node.js and browsers (React, Vue, etc.)
• 📦 Zero Runtime Dependencies - Pure static data imports
• 🔍 Type-Safe - Full TypeScript definitions included
• ⚡ Optimized - Tree-shakeable, bundler-friendly

Quick Start

Installation

npm install @codexcommunion/prayer-collection

Basic Usage

const { getPrayerById, getPrayersByLabel, getPrayerText } = require('@codexcommunion/prayer-collection');

// Get a specific prayer
const ourFather = getPrayerById('our-father');
console.log(ourFather.metadata.title); // "Our Father"

// Get all core prayers
const corePrayers = getPrayersByLabel('core');
console.log(corePrayers.length); // 4

// Get prayer text in a specific language
const prayerText = getPrayerText('hail-mary', 'la');
console.log(prayerText); // "Ave Maria..."

TypeScript

import { Prayer, getPrayerById, getPrayerText, LanguageCode } from '@codexcommunion/prayer-collection';

const prayer: Prayer | null = getPrayerById('hail-mary');
const text: string | null = getPrayerText('hail-mary', 'la' as LanguageCode);

Current Collection

57 prayers available across 11 theological categories with rich metadata and multilingual translations.

📋 Complete Prayer List: lib/prayer-index.json (generated by npm run build)
🔮 Planned Additions: pending_prayers.md

Documentation

For Users

• API Reference → Points to index.d.ts for complete API
• Usage Examples → Quick-start code for Node.js, React, Vue
• Prayer Organization → Classification system overview

For Contributors

• Contributing Guide → GitHub issue or PR workflow
• Data Structure → JSON prayer format
• Architecture → Build system and validation

Reference Files (Self-Documenting)

• index.d.ts → TypeScript types and JSDoc for all functions
• prayer-schema.json → JSON Schema for validation and IDE autocomplete
• lib/prayer-index.json → Auto-generated list of all prayers
• scripts/ → Build and validation implementation

Key Concepts

Prayer Classification

Prayers use a multi-label system:

• Primary Category: Main theological focus (e.g., marian, christological, saints)
• Labels: Multiple classification tags (e.g., ["core", "rosary", "daily"])
• Importance: Liturgical significance (essential, common, devotional)

See Prayer Organization for complete details.

Language Support

8 languages supported using ISO 639-1 codes:

• la (Latin), en (English), es (Spanish), fr (French)
• de (German), it (Italian), pt (Portuguese), pl (Polish)

Browser Compatibility

✅ Works everywhere - Node.js, React, Vue, Angular, Svelte, vanilla JavaScript
✅ No configuration needed - Works with all modern bundlers (Webpack, Vite, Rollup, etc.)
✅ Static data imports - No filesystem operations at runtime

API Quick Reference

// Core functions
getAllPrayers()                          // Get all prayers
getPrayerById(id)                        // Get specific prayer
getPrayerText(id, language)              // Get prayer text

// Filtering
getPrimaryCategories()                   // List all categories
getPrayersByPrimaryCategory(category)    // Filter by category
getPrayersByLabel(label)                 // Filter by label
getPrayersByImportance(importance)       // Filter by importance

// Utilities
searchPrayers(term, language)            // Search prayers
getSupportedLanguages()                  // List supported languages
getLabels()                              // List all labels

See API Reference for complete documentation.

Development

Build Commands

npm run build           # Generate static data and validate
npm run validate        # Run comprehensive validation
npm run validate:schema # Run JSON Schema validation (requires: npm install -D ajv)
npm test               # Run API function tests
npm run test:browser   # Test browser compatibility

IDE Support

VS Code users get automatic validation and auto-completion! The workspace is configured to use prayer-schema.json for all prayer files.

Adding New Prayers

1. Create JSON file in prayers/ directory (filename must match prayer ID)
2. Follow the data structure or use IDE auto-completion
3. Run npm run build and npm run validate
4. Commit changes

See Architecture for detailed development workflow.

Publishing

The prepublishOnly hook automatically runs validation before publishing:

npm version patch  # or minor, major
npm publish

See Architecture for the complete publishing workflow.

Examples

React Hook Example

import { useState, useEffect } from 'react';
import { getPrayersByLabel, getPrayerText } from '@codexcommunion/prayer-collection';

function DailyPrayers() {
  const [prayers, setPrayers] = useState([]);
  
  useEffect(() => {
    setPrayers(getPrayersByLabel('daily'));
  }, []);
  
  return (
    <div>
      {prayers.map(p => (
        <div key={p.metadata.id}>
          <h3>{p.metadata.title}</h3>
          <p>{getPrayerText(p.metadata.id, 'en')}</p>
        </div>
      ))}
    </div>
  );
}

More examples in Usage Examples.

License

CodexCommunion Digital Code License (CCCL) v1.0 - see LICENSE file for details.

This license permits free use, modification, and distribution for any lawful purpose, with restrictions against use that promotes blasphemy, heresy, or content hostile to the Catholic Church.

Contributing

Contributions welcome! See CONTRIBUTING.md for guidelines.