Skip to content
BranchesTags

Repository files navigation

Event Dates Calendar

A Node.js application to create and manage a personalized calendar TXT file by combining events from multiple sources including Israeli holidays, US holidays, birthdays, anniversaries, and recurring tasks.

Built in March 2021. This JavaScript application scrapes calendar data from online sources, processes previous year calendar files, validates and normalizes events, and generates a comprehensive daily calendar file with automated yearly task management, backups, and consistent formatting for yearly planning.

Features

  • 🗓️ Fetches Israeli calendar events and holidays from online sources
  • 🇺🇸 Imports US holidays and events
  • 📅 Manages birthdays, death anniversaries, and marriage anniversaries with age/year calculations
  • ⏰ Tracks expiration dates for services, subscriptions, and documents
  • ✅ Generates recurring tasks (daily, weekly, weekend patterns)
  • 🔄 Processes previous year's calendar data to carry forward events
  • 📊 Scans calendar files for unmarked tasks
  • 💾 Creates automatic backups of the entire project

Core Capabilities

  • Multi-source Event Collection: Combines Israeli holidays, US holidays, birthdays, anniversaries, expiration dates, and recurring tasks
  • Age/Year Calculation: Automatically calculates ages for birthdays and years since for death anniversaries
  • Previous Year Data Processing: Carries forward events from previous year's calendar
  • Task Scanning: Validates and identifies unmarked tasks in calendar files
  • Automatic Backups: Creates timestamped backups of the entire project
  • Customizable Configuration: Flexible settings for year, paths, URLs, and limits

Technical Excellence

  • Modular Architecture: Clean separation of concerns with services, models, utilities, and scripts
  • Validation System: Comprehensive validation for URLs, file paths, and event data
  • Backup Management: Automated backup creation with versioning
  • File Operations: Enhanced file system operations using fs-extra
  • Web Scraping: HTML parsing with jsdom for calendar data collection
  • Rate Limiting: Polite crawling practices with delays between requests

Developer Experience

  • Clear Separation of Concerns: Organized into core, services, scripts, utils, and settings
  • Configuration Management: Centralized settings in a single file
  • Error Handling: Structured error handling with user-friendly messages
  • Logging System: Detailed logging for debugging and monitoring
  • Sandbox Testing: Test environment for experimental features

System Architecture

flowchart TB
    subgraph Input["📥 Input Sources"]
        A1[Previous Year Calendar<br/>event-dates-YYYY.txt]
        A2[Israeli Calendar<br/>calendar.2net.co.il]
        A3[US Holidays<br/>timeanddate.com]
    end

    subgraph Processing["⚙️ Processing Engine"]
        B1[Create Logic]
        B2[Event Service]
        B3[Validation Service]
        B4[Separator Service]

        B1 --> B2
        B1 --> B3
        B2 --> B4
    end

    subgraph Services["🔧 Core Services"]
        C1[Path Service<br/>File Management]
        C2[Log Service<br/>Logging]
        C3[Confirmation Service<br/>User Prompts]
        C4[Application Service<br/>State Management]
    end

    subgraph Output["📤 Output"]
        D1[New Calendar<br/>dist/event-dates-YYYY.txt]
        D2[Backups<br/>Timestamped Copies]
        D3[Logs<br/>Execution Reports]
    end

    A1 --> B2
    A2 --> B2
    A3 --> B2

    B1 --> C1
    B1 --> C2
    B1 --> C3
    B1 --> C4

    B2 --> D1
    C1 --> D2
    C2 --> D3

    style Input fill:#e1f5ff
    style Processing fill:#fff4e1
    style Services fill:#f0f0f0
    style Output fill:#e8f5e9
Loading

Getting Started

Prerequisites

  • Node.js (v20.0.0 or higher)
  • npm (comes with Node.js)
  • Internet connection (for fetching online calendar data)

Installation

  1. Clone the repository:
git clone https://github.com/orassayag/event-dates-calendar.git
cd event-dates-calendar
  1. Install dependencies:
npm install

Configuration

Edit the settings in src/settings/settings.js:

  • YEAR: The year to create the calendar for (e.g., 2025)
  • SOURCE_PATH: Path to the previous year's source events file
  • CALENDAR_IL_LINK: Israeli calendar data source URL
  • CALENDAR_US_LINK: US holidays data source URL
  • DIST_FILE_NAME: Name for the output file (default: 'event-dates')
  • OUTER_APPLICATION_PATH: Parent directory path for backups and sources

Usage

Run Main Script

Creates a new calendar file for the target year:

npm start

Run Other Scripts Directly

You can also run other available scripts directly:

npm run scan      # Scan for unmarked tasks
npm run backup    # Create project backup
npm run sand      # Run sandbox tests

Available Scripts

Create New Calendar

Creates a new calendar file for the target year by combining all event sources:

Features:

  • Fetches Israeli calendar events and holidays
  • Fetches US holidays and events
  • Processes birthdays, death anniversaries, and expiration dates
  • Creates recurring tasks (daily, weekly, weekend patterns)
  • Combines all events into a single organized calendar file
  • Saves output to dist/event-dates-YYYY.txt

Usage:

npm start

Scan for Unmarked Tasks

Validates and identifies unmarked tasks in calendar files:

Features:

  • Scans calendar files for tasks without proper markers
  • Identifies formatting issues
  • Reports statistics

Usage:

npm run scan

Create Backup

Creates a timestamped backup of the entire project:

Features:

  • Automatically excludes directories: .git, dist, node_modules, sources
  • Includes hidden files like .gitignore
  • Creates versioned backups in the configured backups directory

Usage:

npm run backup

Sandbox Testing

Runs sandbox tests for experimental features:

Usage:

npm run sand

Directory Structure

event-dates-calendar/
├── src/
│   ├── core/           # Models, enums, and core structures
│   │   ├── enums/      # Enumeration types
│   │   └── models/     # Data models
│   ├── culture/        # Text constants and dictionaries
│   ├── logics/         # Main business logic orchestration
│   ├── scripts/        # Entry point scripts
│   ├── services/       # Service layer (events, paths, logs, etc.)
│   ├── settings/       # Configuration settings
│   ├── tests/          # Test files
│   └── utils/          # Utility functions
├── sources/            # Source calendar files (previous years)
├── dist/               # Generated output files
├── CONTRIBUTING.md     # Contribution guidelines
├── INSTRUCTIONS.md     # Detailed usage instructions
├── LICENSE             # MIT License
└── package.json

Architecture Principles

This project follows clean architecture principles:

  1. Separation of Concerns: Code organized by purpose (models, services, scripts, utils, settings)
  2. Service-Oriented Architecture: Business logic encapsulated in services
  3. Configuration Management: Centralized settings for easy customization
  4. Error Handling: Structured error handling with meaningful messages
  5. Validation System: Comprehensive validation for inputs and data
  6. Testability: Modular design for easy testing

Design Patterns

  • Service Pattern: Business logic encapsulated in services (EventService, PathService, etc.)
  • Singleton Pattern: Service instances managed for consistency
  • Factory Pattern: Dynamic event creation based on types
  • Strategy Pattern: Different validation strategies for various data types

Best Practices

  • Configuration First: Always check and validate settings before execution
  • Backup Before Changes: Automatic backups prevent data loss
  • Source Data Validation: Validate all input data before processing
  • Polite Crawling: Rate limiting and proper user agents for web scraping
  • Logging Everything: Detailed logs for debugging and monitoring
  • Consistent Formatting: Standardized event formats across sources

Support

For questions, issues, or contributions:

How It Works

  1. Configuration: User sets the target year and source file path in settings
  2. Validation: Application validates internet connection and URLs
  3. Data Collection:
    • Reads previous year's calendar file for recurring events
    • Fetches Israeli holidays and events from online source
    • Fetches US holidays from online source
    • Processes birthdays, anniversaries, and expiration dates
  4. Event Processing:
    • Calculates ages for birthdays
    • Calculates years since for death anniversaries
    • Generates recurring tasks based on patterns
    • Combines all events into daily entries
  5. Output Generation: Creates organized TXT file with all events for the entire year
  6. Backup: Optionally creates timestamped project backup

Event Types

The calendar supports various event types:

  • Birthdays: With automatic age calculation
  • Death Anniversaries: With years since calculation
  • Expiration Dates: For subscriptions, documents, services
  • Israeli Holidays: Fetched from online calendar
  • US Holidays: Fetched and included in calendar
  • Recurring Tasks: Daily, weekly, or monthly patterns
  • Weekend Tasks: Every weekend or every second weekend
  • Static Events: Manually defined special dates

Calendar Format

The generated calendar file contains:

  • Daily entries for the entire year
  • Clear date headers (e.g., "01/01/2025 - יום ראשון")
  • Event descriptions with markers and symbols
  • Automatic age/year calculations
  • Organized sections for different event types
  • Hebrew and English text support

Development

The project uses:

  • JavaScript ES6+ with modern module syntax
  • ESLint for code quality
  • jsdom for HTML parsing and web scraping
  • fs-extra for enhanced file operations
  • is-reachable for URL validation

Contributing

Contributions to this project are released to the public under the project's open source license.

Everyone is welcome to contribute. Contributing doesn't just mean submitting pull requests—there are many different ways to get involved, including answering questions, reporting issues, improving documentation, or suggesting new features.

Please read CONTRIBUTING.md for details on the code of conduct and the process for submitting pull requests.

For detailed usage instructions, see INSTRUCTIONS.md.

Versioning

We use SemVer for versioning. For the versions available, see the tags on this repository.

Author

License

This application has an MIT license - see the LICENSE file for details.

Acknowledgments

  • Built for educational and research purposes
  • Respects robots.txt and implements rate limiting
  • Uses user-agent rotation to avoid detection
  • Implements polite crawling practices

About

A Node.js app that creates and manages a personal yearly calendar TXT file by combining Israeli holidays, US holidays, birthdays, anniversaries, expiration dates, and recurring tasks. Built in March 2021, it scrapes sources, processes previous year files, validates data, and generates a full daily calendar with backups and automated task handling

linkedin.com/in/orassayag

Topics

anniversariesautomationbirthdayscalendarevent-managementeventsholidaysisraeli-calendarjavascriptjsdomnodejsschedulertasksus-holidaysweb-scraping

Resources

Readme
MIT license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity

Stars

1 star

Watchers

1 watching

Forks

0 forks
Report repository

Releases

Packages

Used by

Contributors

Languages