Calendar Aggregation: Domain Explainer#

What Problem Does This Solve?#

People have calendars everywhere. A work calendar on Google, a personal one on iCloud, a shared family calendar, a kid’s school calendar published as an ICS link, maybe a Outlook calendar from a client. The problem: seeing all of these in one place.

“Calendar aggregation” means pulling events from multiple calendar sources and combining them into a unified view. It sounds simple – just smash the events together – but the details are devilish.

The Hardware Store Analogy#

Imagine you want to build a water system that combines flow from three separate pipes into one. You need:

1. Fittings (adapters for each pipe diameter) – these are the parsers and protocol clients that speak each calendar’s language
2. A manifold (where pipes meet) – this is the merge layer that combines events
3. A pressure gauge (flow monitoring) – this is conflict detection and free/busy calculation
4. An output valve (controlled release) – this is the presentation layer

No single product at the hardware store does all four. You buy components and assemble them. Calendar aggregation works the same way.

Why Is It Hard?#

Recurring Events#

“Team standup every weekday at 9am except holidays” is a single calendar entry with an RRULE (recurrence rule). To check if someone is free at 9am next Tuesday, you must expand that rule into concrete dates. This expansion must handle:

• RRULE (the pattern: “every weekday”)
• EXDATE (exceptions: “except Dec 25”)
• RDATE (additions: “also this Saturday”)
• RECURRENCE-ID (overrides: “moved to 10am on March 5”)

Getting this wrong means double-bookings or phantom free time.

Timezone Chaos#

A meeting created in “America/New_York” that recurs weekly must be evaluated against another meeting in “Europe/Berlin” to detect conflicts. Some calendar providers use the non-standard X-WR-TIMEZONE header instead of proper VTIMEZONE components. Libraries must handle both.

Duplicate Detection#

If the same event appears in two source calendars (e.g., a shared team calendar and a personal copy), naive merging creates duplicates. Events have UIDs for deduplication, but some providers mangle UIDs when sharing.

The Microsoft Problem#

Google, Apple, and most open-source calendar servers speak CalDAV (a standard protocol). Microsoft Outlook/Exchange does not. It uses EWS or Microsoft Graph API. Any real-world aggregation system must handle at least two completely different APIs.

The Standards#

Most calendar aggregation lives at the iCalendar (format) and CalDAV (protocol) layers.

Who Needs This?#

1. Individuals juggling personal + work + family calendars
2. Scheduling tools (Calendly, cal.com) that check availability across multiple calendars before offering time slots
3. Team dashboards that show everyone’s availability in one view
4. Room/resource booking that checks physical space availability
5. Healthcare/service providers that manage appointments across locations
6. Privacy-conscious users who want to share “busy/free” status without revealing meeting details

The Current State (2026)#

The parsing and protocol layers are mature and well-maintained. The merge layer – the actual “put calendars together” part – is surprisingly thin. Most production systems write custom merge logic tailored to their specific requirements (which calendars? what deduplication rules? how to handle conflicts?). The few dedicated merge libraries that exist are small, single-maintainer projects.

This is an opportunity space: a well-designed, composable calendar aggregation library with middleware-style architecture could serve a large unmet need.

ICS Parsing Libraries - JavaScript#

ical.js (Mozilla)#

What it does: Low-level iCalendar parser and generator. Handles RFC 5545 (iCalendar), RFC 7265 (jCal), RFC 6350 (vCard), RFC 7095 (jCard). Zero dependencies. Works in both browser and Node.js.

Key features:

• Full RFC 5545 compliance including VTIMEZONE
• RRULE expansion built-in
• jCal (JSON representation) round-trip support
• Online validator and recurrence testing tools
• Used by Mozilla Thunderbird / Lightning

Aggregation relevance: Foundation layer. You parse individual ICS feeds with ical.js, then write your own merge logic. No built-in merge or multi-source handling.

Limitations:

• Low-level API – verbose for simple tasks
• MPL-2.0 license (file-level copyleft, not MIT)
• No URL fetching – you bring your own HTTP client

node-ical#

What it does: Higher-level ICS parser for Node.js. Fork of the original ical package with better API, RRULE expansion, and async URL fetching.

Key features:

• Parse from string, file, or URL (async)
• Automatic RRULE expansion with timezone awareness
• EXDATE and RECURRENCE-ID handling
• Sync and async APIs
• JSDoc type annotations

Aggregation relevance: Good convenience layer for fetching and parsing multiple ICS feeds. You would loop over URLs, parse each, then merge events yourself.

Limitations:

• Node.js only (no browser)
• No merge logic
• Less granular control than ical.js

ical-generator#

What it does: Creates valid ICS files/feeds programmatically. Does NOT parse. Complementary to node-ical (generation vs parsing).

Key features:

• Fluent API for building calendars and events
• RRULE, VALARM, VTIMEZONE support
• Express/Koa middleware for serving ICS feeds
• TypeScript types included

Aggregation relevance: Output layer. After merging events from multiple sources, use ical-generator to produce a combined ICS feed.

Limitations:

• Generation only – cannot parse existing ICS
• No merge logic

ical-expander#

What it does: Wraps ical.js to expand recurring events into concrete instances within a date range. Handles RRULE, EXDATE, and RECURRENCE-ID overrides automatically.

Key features:

• Date range queries (“give me all events in March 2026”)
• Handles exceptions (EXDATE) and overrides (RECURRENCE-ID)
• Returns expanded events as ical.js components
• Timezone-aware

Aggregation relevance: Critical middleware layer. After parsing ICS feeds, you expand recurring events before merging – otherwise you cannot detect overlaps or calculate free/busy time.

Limitations:

• No new releases in 12+ months
• Depends on ical.js (if ical.js changes API, this breaks)
• No merge logic

rrule#

What it does: Standalone recurrence rule engine. Ported from Python’s dateutil. Calculates occurrences from RRULE strings without needing full ICS parsing.

Key features:

• RRule, RRuleSet (with EXDATE/RDATE)
• Natural language serialization (“every weekday”)
• Between/after/before date queries
• No iCalendar dependency – works standalone

Aggregation relevance: Useful if you have extracted RRULE strings and need to compute occurrences. Less useful than ical-expander for full ICS aggregation because it does not handle RECURRENCE-ID overrides.

Limitations:

• RRULE-only – no VEVENT/VFREEBUSY/ICS awareness
• No new releases since 2023
• Known timezone edge cases

ICS Parsing Libraries - Python#

icalendar#

What it does: The foundational Python iCalendar library. RFC 5545 compliant parser and generator. Used by 10,800+ projects on GitHub.

Key features:

• Full RFC 5545 component model (VCALENDAR, VEVENT, VTODO, VFREEBUSY, etc.)
• Multiple timezone backends (zoneinfo, dateutil.tz, pytz)
• Property-level access with type coercion
• Calendar creation and serialization
• Maintained by the Plone Foundation

Aggregation relevance: THE foundation layer for Python calendar work. Every Python merge library (mergecal, camerge) builds on this. To aggregate calendars, you parse each feed into icalendar.Calendar objects, then combine their subcomponents.

Limitations:

• No recurrence expansion (use recurring-ical-events for that)
• No URL fetching (bring your own requests/httpx)
• No merge/deduplication logic built in
• API is functional but not as “pythonic” as ics-py

ics-py#

What it does: A more “pythonic” alternative to icalendar. Emphasizes developer ergonomics with a cleaner object model.

Key features:

• Clean object-oriented API (Event, Calendar, Attendee classes)
• Arrow-based datetime handling
• Works with Google Calendar, Apple Calendar, Android
• Easy creation and parsing

Aggregation relevance: Alternative foundation layer. Simpler API than icalendar but smaller ecosystem – fewer libraries build on it. The merge libraries (mergecal, camerge) use icalendar, not ics-py.

Limitations:

• Smaller ecosystem than icalendar (713 vs 1,100 stars; much lower downloads)
• No recurrence expansion
• Fewer third-party integrations
• Less RFC 5545 edge-case coverage

recurring-ical-events#

What it does: The Python equivalent of ical-expander. Takes icalendar Calendar objects and expands recurring events, todos, alarms, and journals into concrete instances for a given date range.

Key features:

• Date range queries: “all events between March 1-31”
• Handles RRULE, EXDATE, RDATE, RECURRENCE-ID
• Supports VEVENT, VTODO, VJOURNAL, VALARM
• Timezone-aware
• Builds on icalendar + python-dateutil

Aggregation relevance: Critical middleware. After parsing multiple ICS feeds with icalendar, use recurring-ical-events to expand them before merging. Essential for conflict detection and free/busy calculation.

Limitations:

• LGPL-3.0 (must preserve license for distribution, though fine for server-side)
• Read-only – expands but does not generate
• No merge logic

vobject#

What it does: Full-featured parser for vCard and vCalendar/iCalendar formats. Older alternative to icalendar.

Key features:

• Parses both vCard and iCalendar
• RRULE support via dateutil
• Used by some CalDAV servers (e.g., Radicale)

Aggregation relevance: Legacy option. The pyicalmerge tool uses vobject rather than icalendar. Generally superseded by icalendar for new projects.

Limitations:

• Less actively maintained than icalendar
• Smaller community
• API less documented

CalDAV Client Libraries#

CalDAV (RFC 4791) is the standard protocol for calendar synchronization. It provides features that raw ICS polling cannot: incremental sync via ctag/etag, server-side free/busy queries, write-back, and multi-user sharing. For calendar aggregation, CalDAV clients represent the “subscription protocol” layer.

JavaScript/TypeScript#

tsdav#

What it does: TypeScript CalDAV/CardDAV/WebDAV client for Node.js and browser. The most actively maintained JS CalDAV library. Used by cal.com (the open-source Calendly alternative).

Key features:

• CalDAV calendar CRUD (create, read, update, delete)
• Event synchronization with sync tokens
• OAuth2 and Basic authentication
• Google Calendar, iCloud, Nextcloud tested
• Both ESM and CJS builds
• VFREEBUSY queries via CalDAV protocol

Aggregation relevance: HIGH. tsdav enables multi-source sync via CalDAV – you can connect to multiple CalDAV servers (Google, iCloud, Fastmail, Nextcloud) and pull events incrementally. Combined with ical.js for parsing the returned ICS data, this is the most robust JS aggregation approach.

Limitations:

• CalDAV only – does not handle raw ICS URL polling
• No built-in merge/overlay logic
• Some providers (Outlook) use EWS/Graph API instead of CalDAV

dav#

What it does: WebDAV/CalDAV/CardDAV client for Node.js and browser. Predecessor to tsdav in the ecosystem.

Key features:

• High-level CalDAV abstractions (accounts, calendars, events)
• Request sandboxing
• Browser and Node.js support
• Basic and OAuth2 auth

Aggregation relevance: MEDIUM. Same CalDAV approach as tsdav but less actively maintained. Adequate for projects already using it; new projects should prefer tsdav.

Limitations:

• Low maintenance activity since ~2020
• Less TypeScript support than tsdav
• 44 open issues
• Lower-level API undergoing changes

ts-caldav (KlautNet)#

What it does: Lightweight, promise-based TypeScript CalDAV client. Focused on sync with change detection via getctag/etag.

Key features:

• Calendar discovery and listing
• Event CRUD with recurring event support
• Change detection via ctag/etag comparison
• Sync function returns diff (changed events only)
• Works in browser, Node.js, and React Native

Aggregation relevance: NICHE. The change detection (syncChanges) feature is useful for efficient polling, but the library is very new and unproven.

Limitations:

• Very few stars/users
• Unknown license
• Limited documentation
• Unproven at scale

@nextcloud/cdav-library#

What it does: CalDAV/CardDAV client built for the Nextcloud calendar app.

Key features:

• Nextcloud-specific optimizations
• Calendar and contact sync
• Maintained by Nextcloud team

Aggregation relevance: LOW (unless targeting Nextcloud). AGPL-3.0 license is restrictive for commercial use. Better to use tsdav which works with Nextcloud and other providers.

Limitations:

• AGPL-3.0 license
• Nextcloud-centric design
• Less generic than tsdav/dav

Python#

caldav#

What it does: The definitive Python CalDAV client. Supports the full RFC 4791 specification including free/busy queries.

Key features:

• Calendar CRUD operations
• Event search by date range
• Free/busy queries (CALDAV:free-busy-query REPORT)
• Sync tokens for incremental sync
• Async/await support via caldav.aio module (v3.0+)
• Auto-detection via RFC 6764 (SRV/well-known)
• Tested with Google, iCloud, Fastmail, Nextcloud, Radicale, etc.

Aggregation relevance: HIGH. The most complete CalDAV client in any language. Supports free/busy queries natively (the CalDAV server does the aggregation). Combined with icalendar for parsing, this is the strongest Python aggregation foundation.

Limitations:

• CalDAV only – no raw ICS URL polling
• Dual license may complicate some commercial uses
• Some providers (Outlook) prefer EWS/Graph API

Calendar Merge Libraries#

These are the libraries specifically designed for combining multiple calendar sources into a single output. This is the thinnest layer of the ecosystem – most developers build merge logic themselves on top of parsing libraries.

JavaScript#

@jacobmischka/ical-merger#

What it does: Suite of tools to merge multiple ICS files into one. The npm package exports a single function that takes multiple ICS strings and returns a merged ICS string. Also includes a web service endpoint (/combine.ics) that accepts calendar URLs.

Key features:

• Simple function: merge([icsString1, icsString2, ...]) returns merged ICS
• CLI tool for merging files
• Web service with Docker support
• Configurable calendar name, description, timezone
• Color coding for subcalendars

Aggregation relevance: HIGH for JavaScript. This is the closest thing to a “calendar merge library” in the JS ecosystem. However, it is simple concatenation with some deduplication – it does not handle recurrence expansion, conflict detection, or free/busy generation.

Limitations:

• No activity since Dec 2022 (3+ years)
• No recurrence expansion
• No conflict detection
• No free/busy generation
• Simple concatenation approach – may produce duplicate UIDs if source calendars share events

Python#

mergecal (python-mergecal)#

What it does: Purpose-built Python library for merging iCalendar feeds. The most feature-rich merge library found in any ecosystem.

Key features:

• Google Calendar X-WR-TIMEZONE compatibility
• Proper timezone placement in merged output
• Duplicate event handling (deduplication)
• Event modification tracking (detect additions and deletions)
• Both library API and CLI interface
• 363 commits, CI/CD, Codecov coverage tracking

Aggregation relevance: HIGH for Python. Handles the tricky edge cases that naive concatenation misses: duplicate UIDs, timezone normalization, Google Calendar quirks. Still does not handle recurrence expansion or free/busy.

Limitations:

• GPL-3.0 license (copyleft – cannot be used in proprietary software without releasing source)
• Only 8 stars – very small community
• No recurrence expansion
• No free/busy generation
• No CalDAV integration (ICS files/URLs only)

camerge#

What it does: Merges multiple iCalendar files into one, with optional event anonymization. The anonymization feature makes it uniquely useful for sharing availability without revealing event details.

Key features:

• Multi-calendar merge into single output
• Event anonymization (hide summaries/descriptions selectively)
• Date range filtering
• Per-source anonymization control
• Built on icalendar library

Aggregation relevance: MEDIUM. The anonymization feature is genuinely useful for the “share my availability” use case. However, the library is minimal and has not been updated in 3+ years.

Limitations:

• No updates since 2022
• Only 24 commits total
• No duplicate handling
• No recurrence expansion
• Minimal feature set

calendar_merger#

What it does: Converts multiple calendars into a single “busy-time” calendar. Events from all sources become generic “Busy” blocks.

Key features:

• Multi-source aggregation (URLs and local files)
• Converts all events to “Busy” status (privacy)
• TTL caching for performance
• Timezone normalization
• Overlapping event consolidation
• Deployable on Replit

Aggregation relevance: LOW as a library (it is an application, not an importable package). But the architectural pattern is interesting: it demonstrates free/busy aggregation from ICS feeds without a CalDAV server.

Limitations:

• Application, not a library
• Only 2 stars
• GPL-3.0
• No deduplication beyond overlap consolidation

pyicalmerge#

What it does: Simple script to merge multiple ICS files into one. Uses vobject instead of icalendar.

Aggregation relevance: LOW. Historical interest only. Use mergecal instead.

merge_ics#

What it does: Merge RFC 5545 calendar files. Accepts “sources” and processes them into “sinks” (output calendars).

Aggregation relevance: LOW. Minimal documentation and community.

Landscape Summary#

Key insight: No merge library handles recurrence expansion or free/busy calculation. These must be added via separate libraries (ical-expander / recurring-ical-events) in the pipeline before merging.

Architectural Patterns for Calendar Aggregation#

The Four-Layer Model#

Calendar aggregation is not a single-library problem. It decomposes into four distinct layers, each with its own library choices:

Layer 4: PRESENTATION
  └─ Render merged events in UI, serve combined ICS feed
  └─ Libraries: ical-generator (JS), icalendar (Python)

Layer 3: MERGE / OVERLAY
  └─ Combine events, deduplicate, resolve conflicts
  └─ Libraries: mergecal, camerge, @jacobmischka/ical-merger
  └─ Often: custom code

Layer 2: EXPANSION
  └─ Resolve recurring events to concrete instances
  └─ Libraries: ical-expander (JS), recurring-ical-events (Python), rrule (JS)

Layer 1: FETCH + PARSE
  └─ Retrieve and parse calendar data from sources
  └─ CalDAV: tsdav (JS), caldav (Python)
  └─ ICS: ical.js (JS), node-ical (JS), icalendar (Python)
  └─ API: Google Calendar API, Microsoft Graph API

Pattern 1: ICS Feed Polling (Simplest)#

[ICS URL 1] ──fetch──> [Parse] ──> [Expand] ──> [Merge] ──> [Combined ICS]
[ICS URL 2] ──fetch──> [Parse] ──> [Expand] ──>    ↑
[ICS URL 3] ──fetch──> [Parse] ──> [Expand] ──>    ↑

How it works: Poll ICS URLs on a schedule, parse each feed, expand recurring events, merge into a single calendar.

JS stack: node-ical (fetch+parse) + ical-expander (expand) + custom merge + ical-generator (output)

Python stack: requests + icalendar (parse) + recurring-ical-events (expand) + mergecal (merge)

Pros:

• Works with any ICS source (Google, Outlook, Apple, Fastmail)
• No authentication needed for public feeds
• Simplest architecture

Cons:

• Full re-fetch every poll cycle (no incremental sync)
• No write-back capability
• No server-side free/busy queries
• Polling frequency vs freshness tradeoff
• Some providers throttle frequent ICS downloads

Best for: Read-only aggregation of public or shared calendars.

Pattern 2: CalDAV Sync (Most Robust)#

[CalDAV Server 1] ──sync──> [Local Store] ──> [Expand] ──> [Merge/Query]
[CalDAV Server 2] ──sync──>      ↑
[CalDAV Server 3] ──sync──>      ↑
                                  │
                    [Free/Busy Query] ←── CalDAV REPORT

How it works: Use CalDAV protocol for incremental sync. The CalDAV server tracks changes via ctag/etag, so you only fetch modified events. Free/busy queries are handled server-side.

JS stack: tsdav (CalDAV sync) + ical.js (parse) + ical-expander (expand)

Python stack: caldav (CalDAV sync, includes free/busy queries) + icalendar (parse) + recurring-ical-events (expand)

Pros:

• Incremental sync (only changed events)
• Server-side free/busy queries (RFC 4791 Section 7.10)
• Write-back support (create/update/delete events)
• Standard protocol, many server implementations
• OAuth2 support for Google, Apple

Cons:

• Requires CalDAV support from source (not all providers expose CalDAV)
• More complex authentication (OAuth2 for Google/Apple)
• Microsoft Outlook/Exchange does NOT support CalDAV (uses EWS/Graph API)
• Need to handle sync state management

Best for: Full calendar sync with write-back, multi-user scheduling, enterprise applications.

Pattern 3: API-Based Aggregation (Provider-Specific)#

[Google Calendar API] ──> [Normalize] ──>
[Microsoft Graph API] ──> [Normalize] ──> [Merge] ──> [Unified Model]
[CalDAV Server]       ──> [Normalize] ──>

How it works: Use provider-specific APIs for each source. Normalize the different event models into a common internal representation, then merge.

Pros:

• Best sync efficiency per provider
• Access to provider-specific features (Google Meet links, Teams meetings)
• Webhook support for real-time updates

Cons:

• N different API integrations to maintain
• Each provider has different auth, pagination, rate limits
• Most complex architecture
• Normalization layer is significant work

Best for: SaaS products (Calendly, cal.com, Reclaim.ai) that need deep integration with specific providers.

Reference: cal.com uses this pattern with tsdav for CalDAV sources and Google/Microsoft SDKs for those providers.

Pattern 4: Proxy Calendar (Privacy-Preserving)#

[Personal Cal] ──>
[Work Cal]     ──> [Merge + Anonymize] ──> [Busy/Free ICS Feed]
[Side Project] ──>

How it works: Merge multiple calendars but strip event details, outputting only busy/free time slots. Useful for sharing availability without revealing what you are doing.

Python stack: camerge (merge + anonymize) or calendar_merger (busy-time generation)

Pros:

• Privacy-preserving by design
• Simple output (VFREEBUSY or anonymized VEVENT)
• Useful for cross-organization scheduling

Cons:

• Loses event details (by design)
• No conflict resolution (just marks time as busy)

Best for: Personal availability sharing, cross-org scheduling.

Free/Busy Calculation Approaches#

Free/busy is a critical aggregation feature. There are three approaches:

1. CalDAV Server-Side (Recommended)#

The CalDAV protocol (RFC 4791 Section 7.10) includes a free-busy-query REPORT that the server computes from its stored events. The Python caldav library supports this natively.

2. Client-Side from Expanded Events#

Expand all recurring events for a time range, then walk through the timeline marking busy/free slots. No library does this automatically – you must implement the algorithm:

1. Expand all events in date range
2. Sort by start time
3. Walk timeline, marking busy intervals
4. Merge overlapping busy intervals
5. Output VFREEBUSY component

3. Hybrid (VFREEBUSY Component)#

Some ICS feeds include VFREEBUSY components directly. Parse and merge these. This is uncommon in practice – most calendar providers serve VEVENT-only feeds.

Conflict Detection#

No library provides conflict detection out of the box. The general approach:

1. Expand recurring events for the relevant time range
2. Sort all events by start time
3. Detect overlapping time intervals
4. Report conflicts (same attendee, double-booked resources, etc.)

This is application logic, not library functionality.

Cross-User Calendar Sharing#

Calendar sharing is a server-side feature, not a client library concern:

• CalDAV: Supports delegation (RFC 3744 ACLs, CalDAV scheduling RFC 6638)
• Google Calendar: API-based sharing with ACLs
• Microsoft: Graph API sharing / Exchange delegation

Client libraries (tsdav, caldav) can access shared calendars if the server grants permission, but the sharing mechanism itself is server-managed.

Webhook / Real-Time Updates#

Key insight: CalDAV does not define webhooks. “Real-time” sync via CalDAV means frequent polling with sync tokens (efficient because only changes are returned). For true real-time, you need provider-specific webhook APIs.

S1: Rapid Discovery - Calendar Aggregation Libraries#

Scope#

Libraries and tools for merging multiple calendar sources (ICS feeds, CalDAV servers, Google Calendar, Outlook) into a unified view. Both JavaScript/TypeScript and Python ecosystems.

Key Questions#

1. Is “calendar aggregation” a solved problem with a dedicated library, or an architectural pattern composed from multiple libraries?
2. What are the dominant libraries for each layer (parsing, protocol, expansion, merge)?
3. How do developers typically handle multi-source calendar merging in practice?
4. What standards govern calendar interop (ICS, CalDAV, free/busy)?

Search Strategy#

• npm search: “ics merge”, “calendar merge”, “ical merge”, “calendar aggregation”
• PyPI search: “icalendar merge”, “calendar merge”, “mergecal”, “camerge”
• GitHub topic search: “calendar-sync”, “calendar-merge”, “ics-merge”
• CalDAV client libraries in both ecosystems
• Free/busy and recurrence expansion libraries
• Architectural patterns and best practices articles

Findings Summary#

Calendar aggregation is NOT a single-library problem. It decomposes into four layers:

1. Parsing: Read/write ICS format (ical.js, icalendar, node-ical)
2. Protocol: Sync with CalDAV/Google/Outlook (tsdav, caldav, dav)
3. Expansion: Resolve recurring events to concrete instances (ical-expander, recurring-ical-events, rrule)
4. Merge: Combine events, deduplicate, handle conflicts (mergecal, camerge, @jacobmischka/ical-merger)

No single library spans all four layers. The closest to “batteries included” are:

• Python: mergecal (handles parse + merge with duplicate detection)
• JavaScript: @jacobmischka/ical-merger (handles parse + merge + web service)

But both are small projects and lack CalDAV integration or recurrence expansion.

Library Count#

• 17 libraries evaluated across JavaScript and Python
• 4 architectural layers identified
• 2 dedicated merge libraries in Python, 1 in JavaScript
• 3 CalDAV clients in JavaScript, 1 in Python

S1 Recommendation: Calendar Aggregation Libraries#

Executive Summary#

Calendar aggregation is an architectural pattern, not a single-library solution. No library in JavaScript or Python handles the full pipeline of fetch + parse + expand + merge + conflict-detect. Developers must compose 3-4 libraries to build an aggregation system.

The ecosystem has strong foundations (parsing, CalDAV) but weak aggregation layers (merge libraries are small, underfunded projects).

Recommended Stacks#

JavaScript/TypeScript#

For CalDAV-based sync (recommended):

tsdav (CalDAV client, 334 stars, MIT)
  + ical.js (parser, 1.2K stars, MPL-2.0)
  + ical-expander (recurrence expansion, 68 stars, MIT)
  + ical-generator (output, ~600 stars, MIT)
  + custom merge logic

For ICS feed polling (simpler):

node-ical (fetch + parse, 153 stars, MIT)
  + ical-expander (recurrence expansion)
  + @jacobmischka/ical-merger (merge, 38 stars, MIT)
  or custom merge logic

Python#

For CalDAV-based sync (recommended):

caldav (CalDAV client, 393 stars, Apache/GPL)
  + icalendar (parser, 1.1K stars, BSD)
  + recurring-ical-events (expansion, 118 stars, LGPL)
  + custom merge logic

For ICS feed polling (simpler):

icalendar (parser)
  + recurring-ical-events (expansion)
  + mergecal (merge, 8 stars, GPL-3.0)

Ecosystem Strength Assessment#

Key Risks#

1. Merge layer is the weakest link: The dedicated merge libraries are all <40 stars with uncertain maintenance. For production use, plan to write custom merge logic.

2. License concerns: mergecal is GPL-3.0 (copyleft), camerge is MIT but unmaintained. In JS, ical.js is MPL-2.0 (file-level copyleft).

3. Recurrence expansion is tricky: RRULE, EXDATE, RDATE, RECURRENCE-ID interactions are complex. Do not attempt to implement this yourself – use ical-expander (JS) or recurring-ical-events (Python).

4. Microsoft Outlook gap: Outlook/Exchange does NOT support CalDAV. Aggregating Outlook calendars requires Microsoft Graph API, which is a separate integration from the CalDAV path.

5. ical-expander maintenance: The key JS recurrence library has not been updated since 2023. If ical.js makes breaking changes, ical-expander may break. Consider vendoring or forking.

What to Investigate in S2#

• Deep dive on tsdav API for multi-source sync patterns
• caldav async API and free/busy query implementation
• mergecal deduplication algorithm details
• Microsoft Graph API calendar integration comparison
• Performance characteristics for large calendar sets (1000+ events)
• cal.com architecture as reference implementation

The Meta-Finding#

The calendar aggregation space mirrors a broader pattern in developer tooling: protocol-level libraries are well-maintained, but application-level composition is left to the developer. CalDAV clients and ICS parsers are solid. The “last mile” of combining them into an aggregation pipeline has no dominant solution because the requirements vary too much across use cases (privacy needs, provider mix, sync vs poll, read-only vs read-write).

This suggests that a well-designed aggregation library with composable middleware (like Express.js for HTTP) could capture significant demand – but nobody has built it yet.

ical.js - Architecture and Internals#

Overview#

ical.js is the most widely-used JavaScript iCalendar library, maintained under Mozilla’s umbrella (originally built for Thunderbird/Lightning). It provides a complete RFC 5545 implementation with zero external dependencies.

Internal Architecture#

Three-Layer Design#

ical.js is structured as three distinct abstraction layers, each building on the one below:

Layer 1: Parser (ICAL.parse) The lowest level. A hand-written recursive descent parser that converts raw ICS text into a JSON-like intermediate representation called jCal (RFC 7265). The parser processes ICS content line-by-line, handling:

• Line unfolding (RFC 5545 requires lines folded at 75 octets)
• Property parsing with parameter extraction
• Component nesting (VCALENDAR > VEVENT > VALARM)
• Escaped character handling (semicolons, commas, backslashes)

The output is a nested array structure: [componentName, properties[], subcomponents[]]. This jCal format is the internal lingua franca – all higher-level operations work on this representation, not raw text.

Layer 2: Component Model (ICAL.Component, ICAL.Property) Object-oriented wrappers around the jCal arrays. ICAL.Component provides tree-walking methods (getFirstSubcomponent, getAllSubcomponents) while ICAL.Property handles type coercion (converting string values to Date, Duration, Recur, etc.).

Key design decision: Components hold references to the underlying jCal arrays, not copies. Modifications to a Component mutate the jCal data in place. This means serialization (toString) always reflects the current state without needing explicit sync.

Layer 3: High-Level API (ICAL.Event, ICAL.RecurExpansion) Convenience classes that encode calendar semantics. ICAL.Event wraps a VEVENT component and provides property accessors (startDate, endDate, duration, summary, etc.). ICAL.RecurExpansion implements the RRULE expansion algorithm.

RRULE Expansion Algorithm#

The recurrence expansion engine is the most complex part of ical.js. It handles:

1. RRULE processing: Parses RRULE properties and generates occurrence dates by iterating through the rule’s frequency, interval, and by-day/ by-month/etc. constraints. Uses a finite state machine that advances through time periods.

2. EXDATE exclusion: Maintains a sorted set of excluded dates. During expansion, each candidate occurrence is checked against the EXDATE set using binary search (O(log n) per check).

3. RDATE inclusion: Additional one-off dates are merged into the occurrence stream using a merge-sort approach with the RRULE output.

4. RECURRENCE-ID overrides: The most complex case. When a recurring event has an exception (a single instance modified), ical.js must:

   • Find the overridden occurrence in the expansion stream
   • Replace it with the exception event’s properties
   • Handle both THIS-AND-FUTURE and single-instance overrides

The expansion is lazy – it generates occurrences on demand via an iterator pattern, so querying “events in March” does not require expanding all occurrences from the event’s start date.

Timezone Handling#

ical.js includes a built-in VTIMEZONE database for the IANA timezone identifiers. When a VCALENDAR contains embedded VTIMEZONE components, they are registered automatically. For calendars that reference timezones without including their definitions, ical.js can load timezone data from a bundled JSON file.

The timezone engine converts between UTC and local times by applying the VTIMEZONE transition rules. This is distinct from the JavaScript runtime’s Intl.DateTimeFormat – ical.js uses its own timezone math to match the iCalendar specification exactly.

Performance Characteristics#

Parsing Performance#

Parsing is single-pass and linear: O(n) where n is the size of the ICS input. The hand-written parser avoids regex for the hot path, using character- by-character scanning for line unfolding and property splitting.

Memory: The jCal representation is roughly 2-3x the size of the raw ICS text in memory, due to array wrapping and string duplication. For a 10MB ICS file (~50K events), expect ~25-30MB of heap.

Expansion Performance#

Expanding a simple weekly recurring event for one year: ~52 iterations, near instantaneous. For complex rules (BYDAY with BYSETPOS in a monthly event), each occurrence requires evaluating multiple constraints.

Performance cliffs:

• Events with COUNT=10000+ and complex BYDAY rules can take seconds
• RECURRENCE-ID overrides require scanning the exception list per occurrence
• Timezone-crossing recurrence (e.g., weekly meeting across DST boundaries) adds overhead for each transition check

Benchmark estimates for a modern system (2024):

• Parse 1000 events: ~50ms
• Parse 10,000 events: ~400ms
• Expand 100 recurring events for 1 year: ~20ms
• Expand 1000 recurring events for 1 year: ~200ms

Memory#

ical.js keeps the full jCal tree in memory. There is no streaming parser. For calendars with 100K+ events, memory pressure becomes a concern. The recommended approach for very large calendars is to split into chunks or use date-range queries to limit the expansion window.

API Design Patterns#

Parse-Then-Navigate#

ical.js follows a “parse the whole document, then navigate” pattern:

const parsed = ICAL.parse(icsString);
const comp = new ICAL.Component(parsed);
const vevent = comp.getFirstSubcomponent('vevent');
const event = new ICAL.Event(vevent);

This four-step parse-wrap-navigate-access pattern is verbose but explicit. Every layer is accessible – you can work at the jCal level, the Component level, or the Event level depending on your needs.

Mutation Model#

All modifications flow through the Component/Property layer back to the underlying jCal arrays. There is no separate “builder” – you construct by creating components and adding properties:

const cal = new ICAL.Component(['vcalendar', [], []]);
const vevent = new ICAL.Component('vevent');
vevent.addPropertyWithValue('summary', 'Meeting');
cal.addSubcomponent(vevent);

Synchronous API#

All operations are synchronous. There is no async parsing, no streaming, no event-based processing. This simplifies the API but means large files block the event loop in Node.js. For server applications processing many calendars concurrently, this requires worker threads or process-level parallelism.

Comparison with Alternatives#

ical.js vs node-ical#

node-ical provides a higher-level API for common use cases (parse from URL, auto-expand recurring events). It is built on a fork of the original ical package, not on ical.js. Key differences:

• API ergonomics: node-ical returns a flat object keyed by UID, making event lookup trivial. ical.js requires tree navigation.
• URL fetching: node-ical includes built-in async URL fetching. ical.js requires bringing your own HTTP client.
• Recurrence: node-ical handles basic RRULE expansion internally. ical.js’s expansion is more complete (RECURRENCE-ID overrides, BYSETPOS).
• RFC compliance: ical.js is more thorough on edge cases (VTIMEZONE, jCal round-tripping, parameter handling). node-ical prioritizes simplicity.

For aggregation, ical.js is preferred when you need fine-grained control over parsing and expansion. node-ical is preferred when you need quick fetch-and-parse for multiple ICS URLs without complex recurrence handling.

ical.js vs rrule (standalone)#

The rrule library (3.7K stars, 1M+ weekly downloads) is a standalone recurrence rule engine ported from Python’s dateutil. It handles RRULE string parsing and occurrence generation independently of any ICS context.

Key differences from ical.js’s recurrence engine:

• Scope: rrule handles RRULE only. No EXDATE, RDATE, or RECURRENCE-ID. ical.js handles the full recurrence model.
• Independence: rrule works without ICS data – you can pass RRULE strings directly. ical.js requires a parsed VCALENDAR context.
• Natural language: rrule includes toText() for human-readable rule descriptions (“Every weekday until March 2027”).
• Timezone handling: rrule has known timezone edge cases. ical.js’s VTIMEZONE-based approach is more reliable for iCalendar data.

For aggregation, rrule is useful if you have extracted RRULE strings and need occurrence computation without full ICS parsing. For full calendar aggregation, ical.js’s integrated approach is more correct.

Extension Points#

• Custom property types via ICAL.design registration
• Custom timezone data via ICAL.TimezoneService
• jCal intermediate format allows pre/post-processing
• No plugin system or middleware hooks

Edge Cases and Failure Modes#

1. Malformed ICS: The parser is lenient by default – it tries to recover from common formatting errors (missing END tags, unescaped characters). This means corrupt input may parse “successfully” with missing data rather than throwing.

2. Timezone mismatches: If an event references a timezone not in the VTIMEZONE database, ical.js falls back to UTC. This silently shifts all times for that event.

3. RECURRENCE-ID without matching RRULE: If an exception event references a recurring event that was not parsed, the override is silently ignored.

4. Large RRULE COUNT values: No built-in guard against rules with COUNT=999999. Application code must enforce expansion limits.

Relevance to Aggregation#

For calendar aggregation, ical.js serves as the canonical parsing layer in JavaScript. Its strengths (full RFC compliance, RRULE expansion) directly support the aggregation pipeline. Its weaknesses (synchronous API, no streaming) mean that aggregating many large calendar sources requires careful memory management and potentially worker-based parallelism.

The jCal intermediate format is particularly useful for merge operations – you can manipulate the array structures directly without the overhead of the Component wrapper, which matters when processing thousands of events.

icalendar (Python) - Architecture and Internals#

Overview#

The icalendar library is the Python ecosystem’s anchor for iCalendar processing, maintained by the Plone Foundation with 1.1K stars and 8.4M monthly downloads on PyPI. It provides RFC 5545 compliant parsing and generation with a Pythonic dict-like API.

Internal Architecture#

Component-Property Model#

icalendar models the iCalendar format as a tree of Component objects, where each Component inherits from Python’s collections.OrderedDict. Properties are stored as dictionary entries with special handling for multi-valued properties and custom types.

Core class hierarchy:

Component (OrderedDict)
├── Calendar (VCALENDAR)
├── Event (VEVENT)
├── Todo (VTODO)
├── Journal (VJOURNAL)
├── FreeBusy (VFREEBUSY)
├── Timezone (VTIMEZONE)
└── Alarm (VALARM)

Each component class adds convenience methods for its specific properties (e.g., Event provides start, end, duration computed properties).

Parsing Pipeline#

The parser operates in three stages:

Stage 1: Lexing (contentlines_to_array) Splits raw ICS text into content lines, handling line unfolding (removing CRLF followed by whitespace). Each content line becomes a tuple of (name, params, value). This stage is implemented as a generator for memory efficiency.

Stage 2: Type Coercion (vType system) Each property value is converted from a string to a typed Python object using a registry of vType classes:

• vDatetime – converts to datetime.datetime with timezone
• vDuration – converts to datetime.timedelta
• vRecur – converts to a dict of recurrence rule parts
• vText – converts to str with unescaping
• vCalAddress – validates email/URI format

The type registry is extensible – applications can register custom vTypes for non-standard properties (X-properties).

Stage 3: Component Assembly Content lines are grouped into components based on BEGIN/END delimiters. Nested components (VEVENT inside VCALENDAR, VALARM inside VEVENT) create a tree structure. Each component stores its children in a subcomponents list.

Timezone Architecture#

icalendar v7.0+ supports three timezone backends:

1. zoneinfo (default, Python 3.9+): Uses the standard library’s zoneinfo module. No extra dependencies. Preferred for modern Python.

2. dateutil.tz: Uses python-dateutil’s timezone implementation. Required for Python < 3.9 or when zoneinfo lacks timezone data.

3. pytz: Legacy backend, maintained for backward compatibility. Uses the Olson timezone database via the pytz package.

The backend is selected automatically based on availability, but can be explicitly configured. VTIMEZONE components embedded in ICS files are parsed and registered so that events referencing custom timezone IDs resolve correctly.

Serialization#

The to_ical() method serializes components back to ICS text. It walks the component tree depth-first, serializing each property using the corresponding vType’s to_ical() method, then wrapping in BEGIN/END delimiters. Line folding is applied to ensure compliance with the 75-octet line length limit.

Performance Characteristics#

Parsing#

Parsing is single-pass with the generator-based lexer providing some memory efficiency for very large files. However, the full component tree is built in memory:

• Parse 1000 events: ~100ms (Python is slower than JS for raw parsing)
• Parse 10,000 events: ~900ms
• Parse 50,000 events: ~4.5s

Memory scales linearly: approximately 3-4KB per event in the component tree, so 10K events use ~30-40MB.

Serialization#

Serialization is slower than parsing because each property value must be converted back through its vType formatter:

• Serialize 1000 events: ~150ms
• Serialize 10,000 events: ~1.3s

Comparison with ical.js#

ical.js is roughly 2x faster at raw parsing due to JavaScript engine optimizations and the simpler jCal intermediate format. However, icalendar’s Pythonic API makes common operations (property access, iteration) more concise, offsetting the raw speed difference for typical workloads.

For aggregation scenarios with 10K+ events, the parsing overhead is dominated by network I/O (fetching ICS feeds), not by the parser itself.

API Design Patterns#

Dict-Like Access#

icalendar’s defining characteristic is dict-style property access:

cal = Calendar.from_ical(ics_string)
for event in cal.walk('VEVENT'):
    summary = event.get('SUMMARY')
    start = event.get('DTSTART').dt

The walk() method is a depth-first generator that yields components matching the given name. This is the idiomatic way to extract events from a parsed calendar.

Immutable-by-Convention#

While components are technically mutable dicts, the library encourages a create-then-serialize pattern for generation:

cal = Calendar()
event = Event()
event.add('SUMMARY', 'Meeting')
event.add('DTSTART', datetime(2026, 3, 15, 10, 0))
cal.add_component(event)

The add() method automatically wraps values in the appropriate vType, so you pass native Python types (datetime, str, timedelta) rather than pre-formatted ICS strings.

No RRULE Expansion#

A critical architectural decision: icalendar deliberately does NOT include recurrence expansion. It parses RRULE properties into structured dicts but does not generate occurrence instances. This is delegated to recurring-ical-events (or python-dateutil’s rrule module).

The rationale is separation of concerns: icalendar handles the ICS format, while expansion is a separate computational concern. This contrasts with ical.js, which includes expansion built-in.

Comparison with Alternatives#

icalendar vs ics-py#

ics-py (713 stars, Apache-2.0) provides a more “Pythonic” alternative with a cleaner object model (Event, Calendar, Attendee classes) and Arrow-based datetime handling. Key differences:

• API ergonomics: ics-py uses Python properties and constructors that feel more natural (Event(name=“Meeting”, begin=datetime(…))). icalendar uses dict-style access with add() methods.
• Ecosystem integration: icalendar is the foundation for every Python calendar library (recurring-ical-events, mergecal, camerge, caldav). ics-py has almost no ecosystem beyond itself.
• Download differential: icalendar has 8.4M monthly downloads vs ics-py’s estimated 100-200K. This 40:1 ratio reflects ecosystem lock-in.
• RFC edge cases: icalendar handles more obscure RFC 5545 features (VTIMEZONE with multiple transitions, VFREEBUSY parsing, X-property preservation). ics-py focuses on common use cases.
• Dependency weight: icalendar depends only on python-dateutil. ics-py depends on Arrow, attrs, and tatsu (a PEG parser generator).

For aggregation, icalendar is the only viable choice. The entire Python calendar library ecosystem depends on it, and switching to ics-py would mean losing access to recurring-ical-events, mergecal, and caldav’s parsed event objects.

icalendar vs vobject#

vobject (Apache-2.0) is an older library that parses both vCard and iCalendar formats. It was used by early CalDAV servers (Radicale) and the pyicalmerge tool. Key differences:

• Maintenance: vobject receives infrequent updates. icalendar has a regular release cadence with the Plone Foundation backing.
• Scope: vobject handles both vCard and iCalendar. icalendar focuses solely on iCalendar (RFC 5545).
• RRULE: vobject uses dateutil for RRULE expansion. icalendar deliberately excludes expansion (delegating to recurring-ical-events).
• Community: icalendar has 10x the stars and 100x the dependents.

vobject is a legacy choice. New projects should use icalendar.

Extension Points#

• Custom vTypes: Register new type converters for non-standard properties
• Component subclassing: Create custom component types for X-components
• Parser hooks: The parser emits components as they are completed, allowing streaming-style processing if wrapped in an appropriate generator
• Timezone backends: Pluggable timezone resolution (zoneinfo, dateutil, pytz)

Edge Cases and Failure Modes#

1. Google Calendar X-WR-TIMEZONE: Google exports calendars with a non-standard X-WR-TIMEZONE property instead of proper VTIMEZONE components. icalendar parses this property but does not automatically apply it as the default timezone. Applications must check for and handle this explicitly. (mergecal handles this case.)

2. Duplicate UIDs: icalendar does not enforce UID uniqueness. If two events have the same UID, both exist in the component tree independently. Deduplication is an application concern.

3. Mixed timezone formats: Some ICS sources use Olson IDs (America/New_York) while others use Windows timezone IDs (Eastern Standard Time). icalendar handles Olson IDs natively but may fail on Windows-format IDs unless a mapping is provided.

4. Large VCALENDAR files: The full tree is materialized in memory. For files with 100K+ events, memory usage can exceed 400MB. No streaming parser is available.

5. Malformed ICS tolerance: icalendar is stricter than ical.js. It will raise exceptions on some malformed inputs that ical.js would silently accept. For aggregation of untrusted feeds, wrapping parsing in try/except is essential.

Relevance to Aggregation#

icalendar is the unavoidable foundation for Python calendar aggregation. Its dict-like API makes event property access concise, and the walk() generator pattern is natural for iterating over events from multiple parsed calendars.

For aggregation pipelines, the typical pattern is:

1. Parse each feed: Calendar.from_ical(feed)
2. Extract events: cal.walk('VEVENT')
3. Pass to recurring-ical-events for expansion
4. Merge expanded events (custom logic or mergecal)
5. Build output: Calendar() + add_component() + to_ical()

The main concern for aggregation at scale is memory – parsing many large calendars simultaneously requires either sequential processing with garbage collection between feeds, or chunking by date range.

CalDAV Clients - Architecture and Internals (tsdav + caldav)#

Overview#

CalDAV (RFC 4791) is the standard protocol for calendar synchronization over HTTP/WebDAV. Two libraries dominate: tsdav for JavaScript/TypeScript and caldav for Python. Both implement the same protocol but with different architectural philosophies.

Protocol Fundamentals#

Before examining the libraries, it is important to understand the CalDAV protocol mechanics that both must implement:

Discovery Sequence#

CalDAV requires a multi-step discovery process to locate calendars:

1. Service Discovery (RFC 6764): SRV DNS lookup for _caldavs._tcp.domain.com, then .well-known/caldav URL
2. Principal Discovery: PROPFIND on the discovered URL to get the current-user-principal property
3. Calendar Home: PROPFIND on the principal URL to get calendar-home-set
4. Calendar Listing: PROPFIND on the calendar home to enumerate calendars with their properties (displayname, color, ctag)
5. Event Listing: REPORT or PROPFIND on each calendar to get events

This five-step dance is the same regardless of the CalDAV server implementation (Google, iCloud, Nextcloud, Radicale). Both tsdav and caldav abstract this into simpler API calls.

Sync Protocol#

CalDAV offers two sync mechanisms:

CTag-based sync (older): The calendar has a ctag (collection tag) that changes whenever any event is modified. The client stores the last-seen ctag and re-fetches all events when it changes. Simple but inefficient – any single change requires re-fetching everything.

WebDAV Sync (RFC 6578): The server provides a sync-token. The client sends a REPORT with its last sync-token and receives only the changes (added, modified, deleted events). Much more efficient for large calendars with infrequent changes.

Both tsdav and caldav support both mechanisms, preferring sync-token when the server supports it.

Free/Busy Queries#

CalDAV defines a free-busy-query REPORT (RFC 4791, Section 7.10) that asks the server to compute free/busy status for a time range. The server expands recurring events, calculates busy periods, and returns a VFREEBUSY component. This offloads the computation to the server, avoiding the need to download and expand all events client-side.

tsdav (JavaScript/TypeScript)#

Architecture#

tsdav is structured as a layered TypeScript library with three main modules:

Transport Layer (DAVRequest) A thin wrapper around fetch (or node-fetch) that handles:

• WebDAV XML request construction
• HTTP method routing (PROPFIND, REPORT, MKCALENDAR, PUT, DELETE)
• Authentication injection (Basic, OAuth2, custom)
• Response XML parsing via fast-xml-parser
• Error handling with CalDAV-specific error codes

Protocol Layer (CalDAV functions) Stateless functions that implement CalDAV operations:

• fetchCalendars() – discovers and lists calendars
• fetchCalendarObjects() – retrieves events from a calendar
• createCalendarObject() / updateCalendarObject() / deleteCalendarObject()
• syncCalendars() – sync using ctag or sync-token
• freeBusyQuery() – server-side free/busy calculation

Client Layer (DAVClient) A stateful class that wraps the protocol functions with:

• Credential management (stored after initial auth)
• Server discovery caching (principal URL, calendar home)
• Calendar listing with automatic refresh
• Default header management

Authentication Architecture#

tsdav supports multiple auth strategies through a polymorphic auth handler:

1. Basic auth: Username/password sent in Authorization header
2. OAuth2: Full OAuth2 flow with token refresh. Tested with Google Calendar and Apple iCloud. Handles the complexity of Google’s authorization URL, token exchange, and refresh token rotation.
3. Custom auth: Applications can provide their own auth function that receives the request and returns modified headers.

For aggregation, OAuth2 support is critical because both Google Calendar and iCloud require it. tsdav handles the token refresh lifecycle internally, so applications do not need to manage token expiry.

Sync Algorithm#

tsdav’s sync implementation:

1. On first sync: full PROPFIND to get all events with etags
2. Store each event’s etag in the application’s local store
3. On subsequent sync: REPORT with sync-token (if supported) or PROPFIND to compare etags
4. Fetch only events with changed etags
5. Identify deleted events (present in local store, absent from server response)

The library returns a diff structure containing added, modified, and deleted events. The application is responsible for maintaining the local store.

Performance Characteristics#

tsdav’s performance is dominated by network round-trips, not computation:

• Service discovery: 3-5 HTTP requests (one-time)
• Calendar listing: 1 PROPFIND request
• Full event fetch (1000 events): 1 REPORT request (server returns all)
• Sync (10 changes): 1 REPORT + 10 GET requests (or 1 multiget REPORT)
• Free/busy query: 1 REPORT request

The library itself adds minimal overhead – XML construction and parsing are fast. The bottleneck is always the CalDAV server’s response time.

For multi-source aggregation, tsdav can sync with multiple servers concurrently using Promise.all(), limited by the number of concurrent connections the runtime allows.

Limitations for Aggregation#

• No built-in caching layer – the application must implement local storage
• No merge or deduplication logic
• Events are returned as raw ICS strings – application must parse with ical.js
• No event normalization across different CalDAV servers (property naming may vary slightly between servers)

caldav (Python)#

Architecture#

The Python caldav library has a more object-oriented design than tsdav:

DAVClient The entry point. Manages HTTP connections via requests/httpx, handles authentication, and stores server capabilities discovered during the initial handshake.

Principal Represents the authenticated user on a CalDAV server. Provides methods to discover calendar homes and list calendars.

Calendar Represents a single calendar collection. Provides:

• Event CRUD operations (add_event, event_by_url, save_event, delete)
• Date-range queries (date_search)
• Free/busy queries (freebusy_request)
• Calendar property access (name, color, timezone)
• Sync operations

CalendarObjectResource Base class for events, todos, and journals stored on the server. Wraps the raw ICS data with convenience methods.

Async Support (v3.0+)#

caldav v3.0 introduced an async API via caldav.aio:

The async module mirrors the sync API but uses httpx for async HTTP:

• await client.principal() instead of client.principal()
• await calendar.events() instead of calendar.events()
• Full async context manager support

This is significant for aggregation: syncing with 5-10 CalDAV servers concurrently requires async I/O to avoid sequential round-trip delays. With the sync API, fetching from 5 servers takes 5x the single-server time. With async, it takes roughly 1x (limited by the slowest server).

Free/Busy Implementation#

caldav’s free/busy support is the most complete of any client library:

The freebusy_request(start, end) method sends a CalDAV free-busy-query REPORT to the server. The server expands all recurring events in the time range, calculates busy periods, and returns a VFREEBUSY component.

The client receives structured free/busy data without needing to download or process individual events. This is dramatically more efficient than client-side free/busy calculation for large calendars:

• Server-side: 1 request, server does the work
• Client-side: fetch all events + expand recurrence + walk timeline

For aggregation of free/busy from multiple calendars, you can issue concurrent freebusy_request calls to multiple servers and merge the resulting VFREEBUSY components – which is much simpler than merging full event sets.

Compatibility Matrix#

caldav includes a compatibility layer for server-specific quirks:

Performance Characteristics#

Like tsdav, caldav’s performance is network-bound:

• Discovery + auth: 200-500ms (3-5 round trips)
• Calendar listing: 50-100ms (1 request)
• Full event fetch (1000 events): 500-2000ms (depends on server)
• Sync with 10 changes: 100-300ms
• Free/busy query: 100-500ms (server computation time)

Async mode with multiple servers:

• 5 servers sequentially (sync API): 2.5-5s
• 5 servers concurrently (async API): 0.5-2s (limited by slowest)

Comparative Analysis#

API Philosophy#

For Aggregation Specifically#

tsdav is better when:

• Building a JavaScript/TypeScript application
• Need concurrent sync (native async)
• Integrating with ical.js for client-side processing
• Want MIT license (caldav is dual Apache/GPL)

caldav is better when:

• Building a Python backend service
• Need server-side free/busy (native support)
• Want async without rewiring the whole API (caldav.aio is drop-in)
• Integrating with icalendar + recurring-ical-events pipeline
• Need widest CalDAV server compatibility (more extensive test matrix)

What Neither Provides#

Both libraries focus on CalDAV protocol implementation. Neither handles:

• ICS feed polling (non-CalDAV sources)
• Microsoft Graph API (Outlook calendars)
• Event merge or deduplication
• Cross-source normalization
• Local storage or caching
• Recurrence expansion (that is a parsing library concern)

These gaps must be filled by other libraries or custom code in the aggregation pipeline.

Recurrence Expansion Libraries - Architecture and Internals#

Overview#

Recurrence expansion is the process of converting a recurring event definition (RRULE + EXDATE + RDATE + RECURRENCE-ID) into a set of concrete event instances within a given time range. This is the critical middle layer in calendar aggregation – without expansion, you cannot detect conflicts, calculate free/busy, or meaningfully merge events.

Two libraries dominate: ical-expander (JavaScript) and recurring-ical-events (Python).

The Recurrence Problem#

RFC 5545 defines a compact notation for repeating events. A single VEVENT with an RRULE can represent an infinite series of occurrences. The complexity arises from the interaction of multiple properties:

RRULE: The base recurrence rule. Defines frequency, interval, and constraints. Examples range from simple (“every Monday”) to complex (“the second Tuesday of every third month, except holidays”).

EXDATE: Dates excluded from the recurrence set. “Every Monday except March 15, 2026.”

RDATE: Additional dates added to the recurrence set. “Every Monday plus December 25, 2026.”

RECURRENCE-ID: Modifies a specific occurrence. Used when one instance of a recurring event is rescheduled or has different properties. “The March 15 meeting is moved to March 16 and has a different room.”

The challenge for expansion libraries is handling all four properties correctly, especially RECURRENCE-ID overrides which require correlating separate VEVENT components.

ical-expander (JavaScript)#

Architecture#

ical-expander is a thin wrapper (~400 lines of code) around ical.js’s built-in RecurExpansion engine. Its primary contribution is a clean API for date-range queries on top of ical.js’s lower-level iterator.

Input: A parsed ical.js Component (VCALENDAR) Output: An array of expanded events (both recurring instances and non-recurring events) within the requested time range

Expansion Algorithm#

1. Classify events: Separate the VCALENDAR’s VEVENTs into:

   • Non-recurring events (no RRULE) – included if they fall within range
   • Recurring events (has RRULE) – expanded using ical.js RecurExpansion
   • Exception events (has RECURRENCE-ID) – used to override expanded instances

2. Expand recurring events: For each recurring VEVENT, create an ical.js RecurIterator and advance it through the date range. Each generated occurrence becomes a new event instance.

3. Apply exceptions: For each exception event (identified by matching RECURRENCE-ID to a generated occurrence date), replace the original occurrence’s properties with the exception’s properties.

4. Sort and return: All events (expanded recurring + non-recurring) are sorted by start date and returned.

RECURRENCE-ID Handling#

This is the most critical feature for aggregation correctness. When a user modifies a single instance of a recurring event (e.g., reschedules one meeting), the calendar exports two VEVENTs:

• The original recurring VEVENT with the RRULE
• A separate VEVENT with RECURRENCE-ID pointing to the original occurrence

ical-expander correctly:

• Matches exception VEVENTs to their parent recurring VEVENT via UID
• Replaces the original occurrence with the exception’s properties
• Handles both VALUE=DATE and VALUE=DATE-TIME RECURRENCE-IDs
• Handles RANGE=THISANDFUTURE (all occurrences from this point forward)

Without this handling, an aggregation pipeline would show both the original occurrence AND the rescheduled occurrence, creating ghost events.

Performance#

ical-expander inherits ical.js’s expansion performance:

• 100 recurring events, 1 month range: ~5ms
• 100 recurring events, 1 year range: ~20ms
• 1000 recurring events, 1 month range: ~30ms
• 1000 recurring events, 1 year range: ~200ms

Performance scales linearly with the number of recurring events and the size of the time range. Memory usage is proportional to the number of generated instances (each instance is a lightweight object referencing the parent VEVENT’s properties).

Limitations#

• Stale maintenance: Last release was 2023. If ical.js makes breaking changes to RecurExpansion or RecurIterator, ical-expander will break.

• Full calendar required: You must pass the entire VCALENDAR, not individual VEVENTs. This means the full calendar must be parsed into memory before expansion.

• No streaming: All expanded events are materialized as an array. For calendars with many recurring events expanded over a long range, this can consume significant memory.

• No VTODO or VJOURNAL: Only handles VEVENT expansion.

recurring-ical-events (Python)#

Architecture#

recurring-ical-events is a more feature-complete expansion library built on icalendar and python-dateutil. At ~2000 lines of code, it is substantially larger than ical-expander and handles more component types.

Input: An icalendar Calendar object Output: A generator (or list) of expanded event components within the requested time range

Expansion Algorithm#

The algorithm is more sophisticated than ical-expander’s:

1. Component classification: Like ical-expander, but handles VEVENT, VTODO, VJOURNAL, and VALARM (not just VEVENT).

2. RRULE expansion via dateutil: Uses python-dateutil’s rrule module for occurrence generation. This is a mature, well-tested implementation that handles all RFC 5545 recurrence rule features.

3. EXDATE filtering: Removes excluded dates from the occurrence set. Handles both VALUE=DATE and VALUE=DATE-TIME EXDATE properties, with timezone-aware comparison.

4. RDATE merging: Adds extra dates to the occurrence set using a sorted merge with the RRULE output.

5. RECURRENCE-ID override resolution: Matches exception components to their parent series by UID, then replaces the original occurrence. Supports RANGE=THISANDFUTURE and single-instance overrides.

6. Component cloning: Each expanded instance is a clone of the original VEVENT with modified DTSTART/DTEND. The clone preserves all other properties (SUMMARY, LOCATION, ATTENDEE, etc.).

API Design#

recurring-ical-events provides three query methods:

# Get events in a date range
events = recurring_ical_events.of(calendar).between(start, end)

# Get events on a specific date
events = recurring_ical_events.of(calendar).at(date)

# Get events after a date
events = recurring_ical_events.of(calendar).after(date)

The of() function accepts an icalendar Calendar and returns a query object. The query methods return lists of icalendar Component objects that can be further processed using the standard icalendar API.

Component Type Support#

A significant advantage over ical-expander: recurring-ical-events handles multiple component types:

For aggregation, VTODO support matters when aggregating task lists alongside calendars (e.g., a unified productivity view). VALARM support matters for generating combined notification schedules.

Performance#

Python is inherently slower than JavaScript for compute-heavy iteration, but recurring-ical-events is efficient:

• 100 recurring events, 1 month range: ~15ms
• 100 recurring events, 1 year range: ~60ms
• 1000 recurring events, 1 month range: ~100ms
• 1000 recurring events, 1 year range: ~600ms

The performance difference vs ical-expander (roughly 3x slower) is primarily due to Python’s interpreter overhead, not algorithmic differences. For aggregation scenarios, the expansion time is typically dwarfed by network I/O for fetching calendar feeds.

Generator-Based Output#

Unlike ical-expander (which returns arrays), recurring-ical-events internally uses generators. The between() and after() methods materialize results as lists, but the underlying iteration is lazy. This means memory usage is more predictable for large expansions.

Edge Cases Handled#

1. All-day events spanning multiple days: Correctly expands multi-day events where DTSTART is VALUE=DATE and DTEND is a later VALUE=DATE.

2. Timezone-crossing recurrence: When a recurring event defined in one timezone is queried in another, DST transitions are handled correctly via python-dateutil’s timezone math.

3. Floating-time events: Events without timezone (DTSTART without TZID) are treated as local time. recurring-ical-events preserves this semantic rather than forcing UTC conversion.

4. DURATION-based events: Events defined with DTSTART + DURATION (instead of DTSTART + DTEND) are correctly expanded with the duration applied to each occurrence.

Comparative Summary#

Recommendation for Aggregation#

Both libraries are essential in their respective ecosystems. For aggregation:

• JavaScript: Use ical-expander despite its staleness. No alternative exists that correctly handles RECURRENCE-ID overrides. Consider vendoring the code to insulate against ical.js changes.

• Python: Use recurring-ical-events. It is the clear choice – actively maintained, well-tested, and more feature-complete. The LGPL-3.0 license is fine for server-side aggregation services.

The expansion step should happen AFTER parsing but BEFORE merging. Expanding all recurring events into concrete instances allows the merge step to operate on uniform data (individual events with explicit start/end times).

Merge Libraries - Architecture and Internals#

Overview#

The merge layer is the weakest link in the calendar aggregation ecosystem. While parsing and protocol layers have mature, well-maintained libraries, the merge layer consists of small, often undermaintained projects. This analysis examines how the existing merge libraries work internally and what a production-grade merge layer needs.

mergecal (Python) - Detailed Analysis#

Architecture#

mergecal is the most sophisticated merge library found in either ecosystem. At 363 commits with CI/CD and code coverage tracking, it represents the most serious attempt at solving the merge problem as a library.

Core pipeline:

1. Input collection: Accepts multiple icalendar Calendar objects or ICS file paths/URLs

2. Timezone normalization: Handles the Google Calendar X-WR-TIMEZONE problem. When a calendar uses X-WR-TIMEZONE instead of proper VTIMEZONE components, mergecal injects the appropriate VTIMEZONE definition. This prevents timezone-naive events from being misinterpreted.

3. Component extraction: Walks each input calendar and extracts VEVENTs, VTODOs, and VTIMEZONE components. VTIMEZONEs are collected into a global set (deduplicated by TZID) for the merged output.

4. Deduplication: Identifies and removes duplicate events using a multi-strategy approach (detailed below).

5. Assembly: Creates a new VCALENDAR and adds all unique components. Sets PRODID, VERSION, and optionally X-WR-CALNAME on the output.

Deduplication Strategy#

mergecal uses UID-based deduplication as its primary strategy:

• Each VEVENT has a UID property (required by RFC 5545)
• When the same event appears in multiple source calendars (e.g., a meeting invitation accepted by two people whose calendars are being aggregated), the UIDs match and the duplicate is dropped

The deduplication algorithm:

1. Build a dict keyed by UID
2. For each event, check if the UID already exists
3. If duplicate UID found, keep the version with the most recent LAST-MODIFIED or SEQUENCE number
4. If no modification metadata, keep the first occurrence

Limitation: UID-based dedup only catches exact duplicates (same event shared between calendars). It does NOT handle:

• Events with different UIDs that represent the same real-world event (e.g., a meeting imported via two different sources with different UIDs)
• Content-similar events (same time, same title, different UID)
• Cross-provider duplicates (Google generates different UIDs than Outlook for the same meeting invitation)

Timezone Placement#

A subtle but important feature: mergecal ensures that the merged output contains all necessary VTIMEZONE definitions for every TZID referenced by any event. Without this, some calendar clients fail to render events in the correct timezone.

The algorithm:

1. Scan all events for TZID references in DTSTART, DTEND, and EXDATE
2. Collect VTIMEZONE components from source calendars matching those TZIDs
3. Deduplicate VTIMEZONEs by TZID (different sources may include the same timezone definition)
4. Place all unique VTIMEZONEs in the merged output before any VEVENTs

Event Modification Tracking#

mergecal v0.5.0 added support for tracking modifications across merge operations:

• Detects events that were added since the last merge
• Detects events that were removed since the last merge
• Returns a diff structure alongside the merged output

This is useful for incremental aggregation: rather than replacing the entire merged calendar on each run, the application can apply only the changes.

Performance#

mergecal processes events linearly: O(n) where n is the total number of events across all inputs. The UID-based dedup uses a hash map, so duplicate checking is O(1) per event.

• Merge 10 calendars with 100 events each: ~50ms
• Merge 10 calendars with 1000 events each: ~400ms
• Merge 100 calendars with 100 events each: ~500ms

Memory usage is proportional to the total number of unique events, as all are materialized in memory for the merged output.

Limitations#

• No recurrence expansion: mergecal operates on raw VEVENTs, not expanded instances. If two calendars contain the same recurring event with different modifications, the dedup behavior is undefined.

• GPL-3.0 license: The copyleft license prevents use in proprietary SaaS products without releasing source. This is a dealbreaker for many commercial use cases.

• No conflict detection: Two events at the same time from different calendars are both included. There is no “conflict” or “overlap” notification.

• No free/busy generation: The merged output is a full VCALENDAR with all events, not a VFREEBUSY summary.

@jacobmischka/ical-merger (JavaScript) - Detailed Analysis#

Architecture#

ical-merger is a simpler library with three components:

1. Library (merge function): Takes an array of ICS strings and returns a merged ICS string
2. CLI tool: Command-line interface for merging ICS files
3. Web service: HTTP endpoint that accepts calendar URLs and returns merged output

Merge Algorithm#

The merge algorithm is straightforward concatenation with basic handling:

1. Parse each input ICS string using ical.js
2. Create a new VCALENDAR component
3. Copy all VEVENTs from all inputs into the new calendar
4. Optionally set calendar metadata (name, timezone, description)
5. Serialize back to ICS

There is minimal deduplication – events are identified by UID, and if two events share a UID, only one is kept (first-wins). There is no LAST-MODIFIED or SEQUENCE comparison.

Web Service Architecture#

The web service component is notable for aggregation:

GET /combine.ics?urls=https://...&urls=https://...

It fetches ICS feeds from the provided URLs, merges them, and returns the combined ICS. This effectively creates a serverless aggregation endpoint that other calendar clients can subscribe to. The Docker support means it can be self-hosted as a simple aggregation service.

Performance#

The library is fast due to its simplicity:

• Merge 10 ICS files with 100 events each: ~30ms
• Merge 10 ICS files with 1000 events each: ~250ms

However, the web service adds network overhead for fetching source calendars, making the merge time negligible compared to I/O.

Limitations#

• No updates since 2022: Three+ years without maintenance
• Simple concatenation: No timezone normalization, no Google Calendar quirk handling, no modification tracking
• No recurrence awareness: Recurring events are merged as-is without expansion or exception correlation
• No dedup beyond UID: No content-based or fuzzy deduplication

camerge (Python) - Anonymization Focus#

Architecture#

camerge solves a different merge problem: combining calendars while optionally anonymizing event details. It is designed for the “share my availability” use case.

Anonymization Algorithm#

1. Parse all input calendars
2. For each event, optionally replace SUMMARY with a generic label (e.g., “Busy”) and remove DESCRIPTION, LOCATION, ATTENDEE
3. Merge all (anonymized) events into a single calendar
4. Filter by date range if specified
5. Serialize to ICS

Per-Source Control#

camerge allows different anonymization levels per source calendar:

• Calendar A (work): Full anonymization (show “Busy” only)
• Calendar B (personal): Partial anonymization (show title, hide details)
• Calendar C (public): No anonymization (include everything)

This granularity is unique among merge libraries and directly useful for the privacy-preserving aggregation pattern identified in S1.

Limitations#

• Only 24 commits total – minimal codebase
• No duplicate detection
• No recurrence expansion
• Not updated since 2022

What a Production Merge Layer Needs#

Based on analyzing the existing libraries, a production-grade merge layer for calendar aggregation would require:

Must-Have Features#

1. UID-based deduplication: Match events by UID across sources
2. Timezone normalization: Handle X-WR-TIMEZONE and ensure all TZIDs have corresponding VTIMEZONE definitions
3. SEQUENCE/LAST-MODIFIED awareness: When duplicate UIDs exist, keep the most recently updated version
4. Configurable output: Full merge, free/busy only, or anonymized

Should-Have Features#

5. Content-based fuzzy dedup: Match events by time + title when UIDs differ (cross-provider scenario)
6. Source tagging: Mark each event with its source calendar (via X- property) for provenance tracking
7. Conflict reporting: Detect and flag overlapping events from different sources
8. Incremental merge: Track additions/deletions between runs
9. Recurrence-aware dedup: Handle duplicate recurring events by comparing RRULE, not just UID

Nice-to-Have Features#

10. Priority-based conflict resolution: When events overlap, the “winner” is configurable (e.g., work calendar takes priority over personal)
11. Attendee merge: Combine attendee lists from different views of the same meeting
12. Free/busy generation: Produce VFREEBUSY from merged events without requiring CalDAV server support

Current Coverage#

Key insight: No existing library covers more than 4 of the 12 features. The merge layer remains the primary gap in the calendar aggregation ecosystem, and production systems will need custom merge logic that builds on the parsing and expansion layers provided by mature libraries.

S2: Comprehensive Analysis - Calendar Aggregation Libraries#

Objective#

Deep technical analysis of HOW the key calendar aggregation libraries work internally. S1 identified what exists; S2 examines architecture, algorithms, API patterns, and performance characteristics.

Scope#

S1 identified a four-layer architecture (parse, protocol, expand, merge). S2 focuses on the libraries that matter most for each layer:

1. Parsing: ical.js (JS) and icalendar (Python) – the foundation layers
2. Protocol: tsdav (JS) and caldav (Python) – CalDAV sync clients
3. Expansion: ical-expander (JS) and recurring-ical-events (Python)
4. Merge: mergecal (Python) and ical-merger (JS) – the weak link

Additionally, we examine: 5. Cross-cutting: Free/busy calculation algorithms, deduplication strategies

Analysis Approach#

For each library:

• Internal architecture (how components are organized)
• Core algorithms (parsing state machines, recurrence expansion, dedup heuristics)
• API design philosophy (imperative vs declarative, sync vs async)
• Performance characteristics (time and space complexity for large event sets)
• Extension points and composability
• Failure modes and edge cases

Key Technical Questions#

1. How does ical.js handle VTIMEZONE resolution vs icalendar’s approach?
2. What sync algorithm does tsdav use (full fetch vs ctag/etag differential)?
3. How does ical-expander handle RECURRENCE-ID overrides on expanded instances?
4. What deduplication strategy does mergecal use (UID-based, content hash, or fuzzy)?
5. What are the performance ceilings for expanding 10K+ recurring events?
6. How do CalDAV free/busy queries differ from client-side calculation?

S2 Recommendation: Calendar Aggregation Libraries#

Technical Architecture Verdict#

Calendar aggregation is fundamentally a pipeline problem. The four-layer model identified in S1 holds up under technical scrutiny, with each layer having distinct algorithmic concerns:

1. Parsing (well-solved): Both ical.js and icalendar provide complete RFC 5545 implementations with good performance characteristics.
2. Protocol (well-solved): tsdav and caldav both implement CalDAV correctly, with caldav having a slight edge due to native async and free/busy query support.
3. Expansion (adequately solved): ical-expander and recurring-ical-events handle the complex RRULE + EXDATE + RECURRENCE-ID interactions correctly.
4. Merge (poorly solved): No library provides production-grade merge capabilities. Custom code is required for any serious aggregation system.

Recommended Technical Stack#

JavaScript/TypeScript Pipeline#

Fetch: tsdav (CalDAV) + node-fetch (ICS URLs)
  │
Parse: ical.js (RFC 5545 compliant, jCal intermediate format)
  │
Expand: ical-expander (RRULE + EXDATE + RECURRENCE-ID)
  │
Merge: Custom (UID dedup + timezone normalization + conflict detect)
  │
Output: ical-generator (combined ICS feed)

Key technical considerations:

• ical.js is synchronous – use worker threads for concurrent processing of multiple calendars
• ical-expander is maintenance-risk – vendor the code (only ~400 lines)
• The merge layer MUST handle Google’s X-WR-TIMEZONE quirk
• ical-generator provides Express middleware for serving the combined feed

Python Pipeline#

Fetch: caldav (CalDAV, async via caldav.aio) + httpx (ICS URLs)
  │
Parse: icalendar (dict-like API, 8.4M monthly downloads)
  │
Expand: recurring-ical-events (VEVENT + VTODO + VJOURNAL)
  │
Merge: mergecal (UID dedup + timezone fix) OR custom (if GPL is a concern)
  │
Output: icalendar (Calendar().to_ical())

Key technical considerations:

• caldav.aio enables concurrent sync with multiple CalDAV servers
• recurring-ical-events is actively maintained and handles more component types than ical-expander
• mergecal is GPL-3.0 – acceptable for open-source or server-side use, but not for proprietary distributed software
• For free/busy, use caldav’s native freebusy_request when possible; fall back to client-side calculation from expanded events

Performance Guidelines#

For production aggregation systems processing 10+ calendar sources with 1000+ events each:

Bottlenecks (in order of impact)#

1. Network I/O (dominant): Fetching from multiple CalDAV servers or ICS URLs. Mitigate with async/concurrent fetching and caching.
2. Recurrence expansion (significant): Expanding 1000+ recurring events over a year-long range. Mitigate with narrow time windows and incremental expansion.
3. Parsing (minor): Both ical.js and icalendar parse 10K events in under 1 second.
4. Merge (negligible): UID-based dedup is O(n) with hash maps.

Recommended Optimization Strategy#

1. Use CalDAV sync tokens for incremental fetching (avoid re-downloading unchanged events)
2. Cache parsed calendars in memory; re-parse only when sync detects changes
3. Expand recurrence only for the visible time window (not the full calendar)
4. Use server-side free/busy queries (via caldav) instead of client-side expansion when only availability is needed

The Custom Merge Layer#

Given that no existing merge library is production-ready, here is what a custom merge implementation should handle:

Minimum Viable Merge#

1. Collect all expanded events from all sources
2. Deduplicate by UID (keep highest SEQUENCE or most recent LAST-MODIFIED)
3. Collect all referenced VTIMEZONEs into the output
4. Handle X-WR-TIMEZONE by injecting proper VTIMEZONE definitions
5. Tag each event with source calendar (X-SOURCE-CALENDAR property)
6. Output as valid VCALENDAR

Enhanced Merge (for scheduling applications)#

7. Detect overlapping events and flag conflicts
8. Generate VFREEBUSY from expanded events
9. Support per-source anonymization (work = busy only, personal = full detail)
10. Track incremental changes between merge runs

Key Technical Risks#

1. ical-expander staleness: The JavaScript expansion library has not been updated since 2023. If ical.js releases a breaking change, expansion breaks. Mitigation: vendor the ical-expander code.

2. RECURRENCE-ID correctness: Both expansion libraries handle this correctly today, but RECURRENCE-ID is the most common source of calendar interop bugs. Extensive testing with real-world calendar exports is essential.

3. Google X-WR-TIMEZONE: Google Calendar exports use non-standard timezone handling. Any merge implementation must handle this explicitly or events will appear at wrong times.

4. Microsoft Graph gap: Neither CalDAV library can access Outlook calendars. For complete aggregation, a separate Microsoft Graph API integration is required, adding a normalization layer.

5. Memory for large deployments: Both ical.js and icalendar load full calendars into memory. For aggregation services handling many users with many calendars each, memory management (pagination, streaming, or date-range-limited queries) is critical.

What S3 Should Investigate#

• Who actually needs calendar aggregation and why (persona-driven analysis)
• Whether the merge layer gap represents a market opportunity or reflects genuinely diverse requirements that resist standardization
• How different use cases (scheduling SaaS, personal dashboard, enterprise IT) change the relative importance of each pipeline layer

Persona: Indie SaaS Developer Building a Scheduling App#

Who They Are#

A solo developer or small team (2-5 engineers) building a scheduling product – think a Calendly alternative, a meeting scheduler, an appointment booking system, or a team coordination tool. They are technically skilled (full-stack, comfortable with APIs) but resource- constrained (limited engineering hours, small infrastructure budget).

They have likely evaluated existing scheduling SaaS products and found them either too expensive, too limited, or too opaque for their specific use case. They want to build rather than buy, but only if the library ecosystem makes it feasible.

Their product depends on calendar integration as a CORE feature, not an add-on. If users cannot connect their Google Calendar, Outlook, or iCloud calendars, the product has no value proposition.

What Pain They Experience#

The Multi-Provider Problem#

The fundamental pain is that there is no single protocol or API that covers all major calendar providers:

• Google Calendar: CalDAV (limited) or Google Calendar API (full featured but Google-specific)
• Microsoft Outlook: Microsoft Graph API only (no CalDAV at all)
• Apple iCloud: CalDAV with Apple-specific auth quirks
• Fastmail/Nextcloud/Others: Standard CalDAV

This means their scheduling app needs at least two integration paths (CalDAV + Microsoft Graph), possibly three (CalDAV + Google API + Microsoft Graph) for optimal feature coverage. Each integration has different authentication flows, rate limits, and data models.

The Normalization Challenge#

Even within CalDAV, different servers return slightly different ICS flavors:

• Google adds X-WR-TIMEZONE instead of proper VTIMEZONE
• Apple includes X-APPLE-STRUCTURED-LOCATION properties
• Outlook (via Graph) returns JSON events that must be mapped to ICS

The developer must build a normalization layer to present a uniform event model to their scheduling engine, regardless of source. No library provides this normalization.

The Recurrence Complexity#

Scheduling requires understanding when someone is busy. A single recurring event (“every Tuesday at 2pm”) might represent 52 instances per year. The developer needs to:

1. Expand the recurrence rule to find concrete instances
2. Handle exceptions (canceled occurrences, rescheduled instances)
3. Handle timezone transitions (DST boundary crossing)
4. Calculate free/busy from the expanded events

Getting this wrong means double-bookings, which destroys user trust in the product.

The Real-Time Dilemma#

Users expect their scheduling app to reflect their current calendar state. But there is no universal push mechanism:

• Google offers webhooks (push notifications)
• Microsoft offers webhooks (subscriptions)
• CalDAV has no webhook standard – only polling with sync tokens

The developer must implement different sync strategies per provider, with fallback to polling where push is unavailable.

Why Calendar Aggregation Libraries Matter#

For this persona, the library ecosystem determines the feasibility of the entire product. Specifically:

• tsdav/caldav: Reduce the CalDAV integration from months to weeks of development. Without these, the developer would need to implement the CalDAV protocol from scratch (a multi-month project).

• ical.js/icalendar: Handle the ICS parsing that is otherwise a minefield of edge cases (VTIMEZONE, escaped characters, multi-value properties, non-standard extensions).

• ical-expander/recurring-ical-events: Solve the recurrence expansion problem, which is the single most complex algorithmic challenge in calendar processing.

• Merge layer gap: This is where the developer will spend the most custom engineering time. No library handles the cross-provider normalization, conflict detection, and availability calculation that a scheduling app requires.

Constraints That Shape Their Choices#

License Requirements#

An indie SaaS developer selling a commercial product CANNOT use GPL-3.0 libraries in their core codebase without releasing their source. This eliminates mergecal (GPL-3.0) and makes caldav’s dual Apache/GPL license a consideration (Apache path is fine). They strongly prefer MIT or Apache-2.0 licenses.

Runtime Environment#

Most scheduling SaaS products are web applications. The developer needs libraries that work in Node.js (server-side) or Python (backend service). Browser compatibility is rarely needed for the aggregation pipeline.

Latency Budget#

A user connecting their calendar expects the initial sync to complete in seconds, not minutes. Subsequent syncs (to detect new bookings) should complete in under a second. This requires:

• CalDAV sync tokens (incremental sync) over full re-fetch
• Concurrent fetching from multiple providers
• Caching of parsed calendars

Scale Considerations#

An indie SaaS typically starts with hundreds of users, growing to thousands. Each user may have 2-5 connected calendars. The aggregation pipeline must handle concurrent syncs for many users without blocking.

Decision Criteria#

This persona evaluates libraries based on:

1. Time to integration (most important): How quickly can they go from zero to “user can connect their Google Calendar”? tsdav and caldav win here because they abstract the CalDAV protocol complexity.

2. Provider coverage: Does the library ecosystem cover Google, Microsoft, AND Apple? The CalDAV path covers Google and Apple; Microsoft requires a separate SDK.

3. License compatibility: Must be usable in proprietary software. MIT and Apache-2.0 are ideal; GPL-3.0 is a dealbreaker for distributed software.

4. Community and maintenance: A library that goes unmaintained puts the product at risk. ical.js (Mozilla), icalendar (Plone Foundation), and tsdav (used by cal.com) have the strongest maintenance signals.

5. TypeScript vs Python: This often comes down to the team’s existing stack. The JavaScript ecosystem has slightly more friction (stale ical-expander, no good merge library) while Python has better end-to-end coverage (with the GPL caveat on mergecal).

What They Would Build#

A typical indie SaaS developer would assemble:

Minimum viable integration:

• CalDAV client (tsdav or caldav) for Google/Apple/Fastmail
• Microsoft Graph SDK for Outlook
• ICS parser (ical.js or icalendar) for normalization
• Recurrence expander for free/busy calculation
• Custom merge logic (UID dedup, timezone normalization)
• Custom availability engine (interval tree for overlap detection)

Effort estimate:

• CalDAV integration: 2-3 weeks (with tsdav/caldav)
• Microsoft Graph integration: 2-3 weeks
• Normalization layer: 1-2 weeks
• Availability engine: 1-2 weeks
• Total: 6-10 weeks for a senior developer

Without the library ecosystem, the CalDAV and ICS parsing work alone would take 3-6 months.

Persona: Enterprise IT Administrator#

Who They Are#

An IT administrator or systems engineer at a mid-to-large organization (500-10,000+ employees). They manage the organization’s calendar infrastructure, which typically means Microsoft 365 or Google Workspace, sometimes with legacy Exchange or Lotus Notes systems still in play.

They are operationally skilled (scripting, automation, infrastructure management) but not application developers. They work in PowerShell, Bash, or Python for automation scripts. Their primary tooling is the admin console of their calendar platform, not custom code.

Their concern is organizational – they need visibility across departments, conference room booking efficiency, compliance reporting, and migration planning. Calendar aggregation is a means to these ends, not an end in itself.

What Pain They Experience#

Cross-Platform Visibility#

After mergers, acquisitions, or department-level technology choices, an organization may run multiple calendar platforms simultaneously:

• Engineering on Google Workspace
• Sales on Microsoft 365
• The acquired startup on Fastmail or self-hosted Nextcloud

The IT admin needs a unified view for cross-organization scheduling, room booking, and headcount reporting. No admin console spans all three platforms.

Resource Utilization Reporting#

Conference rooms, shared equipment, and hot desks are booked via calendar events. Understanding utilization requires aggregating booking data across all rooms, all platforms, and all time periods. The admin needs to:

• Query “how often is Room 301 used?” across a year of data
• Identify underutilized resources for reallocation
• Detect booking patterns (e.g., rooms booked but unused)

This requires fetching event data from potentially hundreds of room calendars, expanding recurring bookings, and computing utilization metrics.

Migration Planning#

When migrating from one calendar platform to another (e.g., Exchange to Google Workspace), the admin needs to:

• Export all calendars from the source
• Validate data integrity (recurring events, timezone handling)
• Import into the destination
• Verify that all events transferred correctly

Calendar aggregation libraries help with the validation step – parse both source and destination, compare event counts, check for timezone drift.

Compliance and Auditing#

Some organizations require calendar audit trails for compliance:

• Did employee X have access to calendar Y on date Z?
• Which calendars were shared externally?
• Are there scheduling conflicts for compliance-required meetings?

Aggregation enables batch analysis of calendar data for these reports.

Why Calendar Aggregation Libraries Matter#

For this persona, libraries enable automation scripts that bridge the gap between different admin consoles:

• caldav (Python): The most relevant library. Python is the enterprise automation language, and caldav’s async support enables scripts that sync with dozens of CalDAV servers concurrently.

• icalendar (Python): Enables parsing ICS exports from any platform. When migrating between platforms, ICS is the common interchange format.

• recurring-ical-events (Python): Essential for utilization reporting. A room calendar with “standup every weekday at 9am” needs expansion to count actual bookings.

• mergecal (Python): Useful for creating combined views of department calendars. The GPL-3.0 license is less problematic for internal-use scripts that are never distributed.

The JavaScript libraries are less relevant for this persona – enterprise IT automation rarely uses Node.js.

Constraints That Shape Their Choices#

Platform Lock-In#

The admin’s primary calendar platform has its own APIs:

• Microsoft 365: Microsoft Graph API (REST, well-documented, SDK-heavy)
• Google Workspace: Google Calendar API (REST, good Python SDK)

CalDAV is a secondary access path, not the primary one. The admin may use platform-native APIs for their primary platform and CalDAV only for cross-platform queries.

Security and Compliance#

Enterprise environments have strict requirements:

• Service accounts with minimal permissions (no personal credentials)
• Audit logging for all API access
• Data residency (calendar data must not leave the region)
• Encrypted at rest and in transit

Libraries must support service account authentication (OAuth2 with client credentials flow or delegated admin access). tsdav and caldav both support OAuth2, but the specific flows may need customization for enterprise identity providers (Azure AD, Okta).

Scale#

An enterprise may have:

• 5,000+ user calendars
• 500+ room/resource calendars
• 100,000+ events per month

Batch processing (nightly sync scripts) is more appropriate than real-time aggregation. The admin runs a Python script that syncs all calendars overnight, computes reports, and outputs to a dashboard.

Reliability Over Features#

The admin prioritizes stability and correctness over features. A library that correctly handles 95% of calendars is more valuable than one that handles exotic edge cases but crashes on malformed input. The icalendar library’s strictness (raising exceptions on malformed ICS) is actually a feature for this persona – it surfaces data quality issues rather than silently ignoring them.

Decision Criteria#

1. Python ecosystem (most important): Enterprise automation runs on Python. JavaScript libraries are irrelevant.

2. Batch processing suitability: Libraries should handle large volumes efficiently. caldav’s async API and recurring-ical-events’ generator- based output are both batch-friendly.

3. Authentication flexibility: Must work with enterprise identity providers. OAuth2 support with customizable token endpoints is essential.

4. License for internal use: GPL-3.0 is acceptable for internal scripts that are never distributed. License is a non-issue for this persona.

5. Error handling: Libraries should fail loudly on bad data (not silently corrupt). icalendar’s strictness is preferred over ical.js’s lenient parsing.

What They Would Build#

A typical enterprise IT admin would create:

Calendar sync and reporting script (Python):

• caldav + icalendar + recurring-ical-events for fetching and expanding
• Custom reporting logic for utilization metrics
• Output to CSV/Excel or internal dashboard
• Scheduled via cron/systemd timer

Cross-platform bridge:

• Microsoft Graph SDK for Microsoft 365 calendars
• caldav for Google Workspace (via CalDAV) or self-hosted servers
• icalendar for normalization between the two
• mergecal for creating combined views (GPL fine for internal use)

Effort estimate:

• Primary platform integration: 1-2 weeks (using platform SDK)
• Cross-platform bridge: 2-3 weeks (using caldav + Graph SDK)
• Reporting logic: 1-2 weeks
• Total: 4-7 weeks for an experienced admin/scripter

Persona: Personal Productivity User#

Who They Are#

An individual with multiple calendars across different services who wants a single unified view of their schedule. Typical profile:

• A freelancer with a personal Google Calendar, a client’s Outlook calendar, and a side-project team on Nextcloud
• A remote worker with work (Microsoft 365), personal (Apple iCloud), and community volunteering (shared ICS feed) calendars
• A student with university (Google Workspace), part-time job (Outlook), and extracurricular (shared ICS) calendars

Their technical skill varies widely. Some are developers who will happily run a self-hosted solution. Others are non-technical users who expect a polished app or browser extension. For the library ecosystem analysis, we focus on the technically capable subset who might use or build with these libraries.

What Pain They Experience#

Calendar Fragmentation#

The core pain is fragmentation. Modern life involves multiple calendars from different providers, and no single app shows them all:

• Apple Calendar can subscribe to ICS feeds and CalDAV but cannot natively show Outlook calendars
• Google Calendar can import ICS but loses recurring event updates
• Outlook can subscribe to ICS feeds but with poor refresh rates

The user constantly switches between 2-3 calendar apps to see their full schedule, or manually copies events between calendars (error-prone and tedious).

Stale ICS Subscriptions#

Many calendar apps support subscribing to ICS URL feeds, but with frustrating limitations:

• Google Calendar refreshes ICS subscriptions only every 12-24 hours
• Changes to the source calendar do not appear for hours
• Deleted events may persist in the subscriber’s view
• Recurring event modifications may not sync correctly

This staleness leads to missed appointments and scheduling conflicts that should have been caught.

Privacy Concerns#

The user wants to share availability (not event details) across contexts:

• Their work colleagues should see “Busy” for personal events, not “Dentist”
• Their personal contacts should not see work meeting titles
• Their therapist should not see their work-life balance issues reflected in their combined calendar

This requires selective anonymization – showing different levels of detail to different audiences. No mainstream calendar app provides this natively.

Overlap Blindness#

When calendars are fragmented, the user cannot see conflicts:

• A work meeting at 3pm and a personal appointment at 3pm appear in different apps with no warning
• Double-bookings happen because there is no combined free/busy view
• The user discovers conflicts only when they fail to attend one event

Why Calendar Aggregation Libraries Matter#

For the technically capable personal user, libraries enable self-hosted solutions that commercial apps do not provide:

• camerge: Directly solves the privacy problem. Merge personal and work calendars with selective anonymization, then serve the merged feed to whichever calendar app the user prefers.

• node-ical + ical-merger: Enable a simple aggregation script: fetch multiple ICS URLs, merge them, serve as a single ICS feed that any calendar app can subscribe to.

• ical-expander / recurring-ical-events: Enable conflict detection. Expand recurring events from all calendars, check for overlaps, send notifications.

• mergecal: The most complete option for a Python-based self-hosted aggregation service. Handles deduplication and timezone quirks.

The CalDAV libraries (tsdav, caldav) are less relevant for personal use because they require server credentials. Most personal users access calendars via ICS URL subscriptions, not CalDAV.

Constraints That Shape Their Choices#

Simplicity Over Features#

A personal user will not maintain a complex system. The solution must be:

• Deploy once, run forever (no daily maintenance)
• Minimal dependencies (fewer things to break)
• Self-contained (Docker container or single script)

The ical-merger web service (Docker-based, single endpoint) fits this profile well. Deploy once, point calendar apps at the combined URL.

Zero Cost#

Personal users have no budget for calendar infrastructure. All libraries in this ecosystem are open source, which is a good match. However, the user needs hosting for a self-hosted aggregation service:

• A Raspberry Pi, NAS, or cheap VPS can run the service
• Alternatively, a serverless function (AWS Lambda, Cloudflare Workers) can serve the merged feed

Privacy as a Feature#

Unlike the enterprise admin or SaaS developer, the personal user’s primary motivation is often privacy. They want to control what information flows between their calendar contexts. This makes camerge’s anonymization feature uniquely valuable.

Refresh Frequency#

Personal users tolerate some staleness (15-30 minutes is fine) but not the 12-24 hour lag of Google Calendar’s ICS subscription. A self-hosted aggregation service can refresh every 5-15 minutes, providing much better currency.

Decision Criteria#

1. Ease of deployment (most important): Can they set it up in an afternoon? Docker-based solutions (ical-merger web service, a custom Flask/Express app) win here.

2. Privacy controls: Can they anonymize specific calendars? camerge is the only library that provides this natively.

3. Reliability without maintenance: Will it keep working for months without attention? Simpler libraries (fewer dependencies, less code) are more reliable long-term.

4. Calendar app compatibility: The merged output must be a valid ICS feed that Apple Calendar, Google Calendar, and any other app can subscribe to. All merge libraries produce valid ICS output.

5. Self-hostable: Must run on infrastructure the user controls (home server, VPS, serverless). All libraries in this space meet this requirement.

What They Would Build#

Option A: Minimal merge service (30 minutes)

• Deploy ical-merger’s Docker image
• Configure with source calendar ICS URLs
• Point calendar app at the /combine.ics endpoint

Option B: Privacy-preserving aggregation (2-4 hours)

• Python script using camerge
• Configure anonymization per source calendar
• Run on a cron schedule, output to a static ICS file
• Serve via simple HTTP server (nginx, Caddy)

Option C: Smart personal dashboard (1-2 days)

• Python script using icalendar + recurring-ical-events
• Fetch all calendars, expand recurring events
• Detect conflicts, send email/SMS/push notifications
• Generate anonymized merged feed for sharing
• Run on Raspberry Pi with cron

The library ecosystem makes Options A and B trivially achievable. Option C requires more engineering but is feasible for a developer spending a weekend.

The Gap#

What this persona lacks in the current ecosystem:

• A polished, self-hostable web app that provides calendar aggregation with a GUI for configuration (all current solutions require editing config files or writing code)
• A mobile-friendly dashboard that shows the unified view (current solutions output ICS feeds, requiring a separate calendar app to view)
• Automatic conflict notification (no library provides this – it must be built from expansion + overlap detection + notification service)

Persona: Team Manager Needing Cross-Team Availability#

Who They Are#

A manager or team lead responsible for coordinating people across teams, departments, or time zones. They might be:

• An engineering manager scheduling cross-team design reviews
• A project manager coordinating sprint planning across 3-4 squads
• A department head trying to find meeting slots for 15+ people
• An executive assistant scheduling for multiple executives

They are not developers. They use calendar tools through their UI (Outlook, Google Calendar) and rely on scheduling assistants (Calendly, Microsoft FindTime, When2Meet) for group coordination. Their technical ceiling is usually “can use a web app” – not “can write a Python script.”

However, they are the PRIMARY BENEFICIARY of calendar aggregation, even though they never touch the libraries directly. The products built with these libraries serve this persona’s needs.

What Pain They Experience#

The Scheduling Tax#

Coordinating meetings across teams imposes a massive time cost:

1. Check your own calendar for availability
2. Ask each participant for their availability (email/Slack)
3. Wait for responses (hours to days)
4. Propose times that work for everyone
5. Discover conflicts after proposing (someone forgot about a recurring meeting)
6. Iterate until a time is found
7. Send the invite

For a meeting with 8 participants across 3 teams, this process can take 3-5 days. Calendar aggregation reduces it to seconds by computing availability automatically.

Free/Busy Visibility Gaps#

Most organizations provide free/busy lookup within a single platform:

• Google Workspace shows free/busy for all users in the organization
• Microsoft 365 shows free/busy for Exchange users

But cross-platform visibility is broken:

• Google users cannot see Outlook users’ free/busy (and vice versa)
• Contractors on personal accounts are invisible
• External collaborators appear as opaque blocks

The manager needs universal free/busy that spans all participants, regardless of their calendar platform.

Timezone Confusion#

Teams spanning multiple time zones face constant confusion:

• “Let’s meet at 2pm” – whose 2pm?
• Recurring meetings that shift by an hour during DST transitions
• Team members in non-standard offset zones (India at UTC+5:30, Nepal at UTC+5:45)

Calendar aggregation with proper timezone handling (which both ical.js and icalendar provide) solves this by presenting all times in the viewer’s local timezone.

Resource Contention#

Shared resources (conference rooms, equipment, vehicles) are booked via calendar events. Without aggregated visibility:

• Two teams book the same room for the same time
• Nobody knows which rooms are free for an impromptu meeting
• Resources sit idle because nobody knows they are available

Aggregating resource calendars into a single free/busy view solves contention.

Why Calendar Aggregation Libraries Matter#

This persona never uses the libraries directly. But the products they depend on are built with them:

• Scheduling SaaS products (Calendly, cal.com, Reclaim.ai): Built on tsdav, caldav, and the rest of the library stack. These products solve the scheduling tax by automating availability computation.

• Organization-level free/busy bridges: Enterprise IT builds these using caldav + Microsoft Graph API. The manager benefits from cross-platform free/busy visibility without knowing how it works.

• Room booking systems: Built on CalDAV or provider APIs, using recurrence expansion to compute availability over time ranges.

The quality and completeness of the library ecosystem directly affects the quality of these products. The merge layer gap (identified in S2) manifests as:

• Scheduling tools that miss conflicts from certain calendar sources
• Free/busy that does not account for recurring event exceptions
• Room booking systems that show phantom availability due to poor timezone handling

Constraints That Shape Their Choices (Indirectly)#

The team manager does not choose libraries, but their needs constrain what library features matter:

Real-Time Accuracy#

The manager needs current availability, not stale data. This pushes toward:

• CalDAV sync tokens (tsdav, caldav) over ICS polling
• Provider webhooks (Google, Microsoft) for instant updates
• Short caching TTLs in the aggregation pipeline

Scale of Participants#

A meeting with 15 participants across 3 teams means querying 15 calendars. The aggregation pipeline must:

• Handle concurrent queries efficiently (async/parallel fetching)
• Compute free/busy intersections in near-real-time
• Present results in under 2 seconds for acceptable UX

CalDAV’s server-side free/busy queries (via caldav) are ideal here – the server does the expansion and computation, returning a compact VFREEBUSY component. Client-side expansion of 15 calendars with recurring events is slower but necessary when free/busy queries are not supported.

Cross-Platform Reality#

The manager’s team rarely uses a single calendar platform. The library ecosystem must support:

• Google Workspace (CalDAV or Google Calendar API)
• Microsoft 365 (Graph API only – no CalDAV)
• Apple iCloud (CalDAV with quirks)
• Self-hosted (CalDAV – Nextcloud, Radicale)

The Microsoft Graph gap in the CalDAV library ecosystem is most acutely felt by this persona, because Outlook users are common in enterprises.

Privacy Boundaries#

Participants may be willing to share free/busy but not event details. The aggregation system must support:

• Free/busy only (no event titles or descriptions)
• Per-source privacy levels (work calendar = full detail, personal = busy only)
• GDPR/compliance-aware data handling

camerge’s anonymization feature addresses this directly, and CalDAV’s native VFREEBUSY queries inherently preserve privacy (they only return busy/free status, not event details).

Decision Criteria (for the Products They Choose)#

1. Provider coverage (most important): Does the scheduling tool work with ALL calendar platforms the team uses? One unsupported platform makes the tool useless for cross-team coordination.

2. Accuracy: Does free/busy correctly reflect recurring events, exceptions, and timezone conversions? False availability (due to recurrence expansion errors) wastes everyone’s time.

3. Speed: Can the tool show available times in seconds, not minutes? The team manager checks availability mid-conversation.

4. Privacy respect: Can participants control what details are shared? Some will refuse to connect their calendar if event details are exposed.

5. Ease of participant onboarding: Each participant must connect their calendar. If this requires installing software or configuring CalDAV credentials, adoption will be low. OAuth2 (one-click authorization) is essential.

The Gap This Persona Reveals#

The team manager’s needs expose the most significant gap in the calendar aggregation library ecosystem: there is no library-level solution for cross-platform free/busy computation.

Currently, computing free/busy across Google + Outlook + iCloud requires:

1. Three separate API integrations (Google API, Graph API, CalDAV)
2. Three different authentication flows
3. Normalizing three different event models
4. Expanding recurrence from all three
5. Merging into a unified free/busy view

Each step uses different libraries with different APIs. The “last mile” – steps 4 and 5 – has no library support. Products like cal.com solve this with thousands of lines of custom code.

A well-designed “calendar availability engine” library that handled steps 3-5 across major providers would capture enormous demand from scheduling products. The infrastructure layers (steps 1-2) are well-served by existing libraries. It is the aggregation and availability layers that need a standard solution.

Persona: Developer Building Multi-Provider Calendar Integration#

Who They Are#

A backend or full-stack developer building an application that connects to multiple calendar providers simultaneously. Unlike the indie SaaS developer (who builds a scheduling-focused product), this developer’s product has calendar integration as a SECONDARY feature:

• A CRM that shows upcoming meetings with contacts
• A project management tool that overlays deadlines with team schedules
• A time-tracking app that auto-imports calendar events
• An HR system that needs visibility into PTO calendars
• A smart home system that adjusts lighting/temperature based on schedule

They need “read my calendars from everywhere” without building a calendar product. Their core product is something else entirely.

What Pain They Experience#

Integration Multiplicity#

The developer must support multiple providers because their users come from diverse environments:

• B2B customers use Microsoft 365 (80%+ of enterprise)
• Startups and small teams use Google Workspace
• Privacy-conscious users use Fastmail or self-hosted Nextcloud
• Apple users have iCloud calendars they want to include

Supporting only one provider means losing a significant portion of potential users. But supporting all of them means maintaining four separate integrations with different:

• Authentication flows (OAuth2 variants, app passwords, API keys)
• API shapes (REST JSON, CalDAV XML, ICS text)
• Rate limits and quotas
• Event models (different field names, different timezone handling)
• Pagination strategies (cursor-based, page-based, sync-token-based)

The Abstraction Layer Dilemma#

The developer needs a unified calendar interface:

getEvents(userId, startDate, endDate) → Event[]

But no library provides this abstraction across providers. The developer must either:

• Build the abstraction themselves (months of work)
• Use multiple libraries and write glue code (weeks of work)
• Use a third-party API service like Nylas or Cronofy (recurring cost, vendor dependency)

The library ecosystem provides the BUILDING BLOCKS but not the ASSEMBLY. The developer can use tsdav for CalDAV, Microsoft Graph SDK for Outlook, and Google Calendar API SDK for Google – but integrating them behind a common interface is their problem.

Feature Parity Across Providers#

Not all providers support the same features:

• Google Calendar API returns event colors; CalDAV does not standardize this
• Microsoft Graph API returns online meeting URLs (Teams links); others do not
• CalDAV supports server-side free/busy queries; Google API does not
• iCloud CalDAV has quirks with recurring event exceptions

The developer must decide: implement the lowest common denominator (losing provider-specific features) or implement per-provider feature branches (adding complexity).

Sync State Management#

Each provider has a different mechanism for tracking “what changed since last sync”:

• Google Calendar API: syncToken + pageToken
• Microsoft Graph API: deltaLink
• CalDAV: sync-token (RFC 6578) or ctag comparison
• ICS feeds: full re-fetch every time (no incremental)

The developer must implement four different sync state machines, persist their tokens, handle token expiry and re-sync, and normalize the change notifications into a common format (“event added”, “event modified”, “event deleted”).

Why Calendar Aggregation Libraries Matter#

For this developer, libraries provide critical shortcuts:

• tsdav (JS) / caldav (Python): Handle the CalDAV protocol, including discovery, authentication, and sync tokens. Without these, implementing CalDAV from the RFC takes 2-3 months.

• icalendar / ical.js: Parse the ICS data returned by CalDAV into usable objects. Essential because CalDAV returns raw ICS text.

• recurring-ical-events / ical-expander: Expand recurring events so the application can show concrete instances. Without expansion, “every Monday at 2pm” is a single database entry, not 52 visible events.

The merge libraries (mergecal, ical-merger) are LESS relevant because this developer typically does not merge calendars into a single ICS output. They store events in their own database and present them in their own UI. The merge happens at the application layer, not the ICS layer.

Constraints That Shape Their Choices#

Calendar Is Not Their Core Product#

This is the most important constraint. The developer has a limited “calendar integration budget” – they want to spend the minimum time on calendar integration to make their actual product work. Every week spent on calendar plumbing is a week not spent on their core product.

This makes:

• Library maturity critical (they cannot afford to debug iCalendar edge cases)
• API simplicity valuable (fewer lines of integration code = less to maintain)
• Provider SDKs appealing (Google Calendar API SDK, Microsoft Graph SDK) because they handle auth, pagination, and retry logic

Normalized Event Model#

The developer needs to convert all provider formats into a single internal event model for their database. Key fields to normalize:

The ICS libraries (icalendar, ical.js) help with the CalDAV column. The Google and Microsoft SDKs return JSON objects that need manual mapping. No library provides the cross-provider normalization.

OAuth2 Everywhere#

All major providers require OAuth2:

• Google: OAuth2 with consent screen, scopes, refresh tokens
• Microsoft: OAuth2 via Azure AD, requires app registration
• Apple iCloud: App-specific passwords (not standard OAuth2)
• CalDAV (others): Basic auth or OAuth2 depending on server

The developer must implement OAuth2 flows for at least Google and Microsoft, handle token refresh, and manage per-user credential storage. The CalDAV libraries (tsdav, caldav) handle the auth injection but not the OAuth2 token acquisition flow.

Database-Centric Architecture#

Unlike the personal user (who wants ICS output), this developer stores events in their own database (PostgreSQL, MongoDB, etc.). The workflow:

1. Fetch events from provider APIs (using SDKs + CalDAV libraries)
2. Parse/normalize into internal event model
3. Store in database with provider-specific sync cursors
4. Present in the application’s own UI
5. Periodically re-sync to detect changes

The ICS merge libraries are irrelevant for this pattern – the “merge” happens in the database, not in ICS format.

Decision Criteria#

1. Time to integration per provider (most important): How many days to add Google Calendar support? Microsoft? iCloud? Each provider is evaluated independently.

2. Maintenance burden: How much ongoing work to keep each integration running? Provider API changes, OAuth2 scope changes, and rate limit adjustments all create maintenance work.

3. Third-party API services as alternative: Services like Nylas, Cronofy, and CalendarBridge provide a unified API across providers for a per-user monthly fee. The developer must decide: build with libraries (more work, no recurring cost) or use an API service (less work, ongoing cost).

4. Recurrence handling: Does the provider API return expanded events or raw RRULE definitions? Google and Microsoft APIs can return expanded instances; CalDAV returns raw ICS with RRULEs that need client-side expansion.

5. Webhook support: Can the provider notify the application when events change? Google and Microsoft support webhooks; CalDAV requires polling. This affects architecture (push-based vs poll-based sync).

What They Would Build#

Provider abstraction layer:

• Google Calendar SDK for Google Workspace users
• Microsoft Graph SDK for Microsoft 365 users
• tsdav or caldav for CalDAV providers (Fastmail, Nextcloud, iCloud)
• Common internal event model with provider-specific adapters
• Per-user OAuth2 token storage and refresh

Sync engine:

• Per-user, per-provider sync cursors stored in database
• Background worker that polls for changes (or receives webhooks)
• Normalization pipeline: provider event → internal event model → database
• Conflict detection for overlapping events from different providers

Effort estimate:

• Google Calendar integration: 1-2 weeks
• Microsoft Graph integration: 1-2 weeks
• CalDAV integration (using tsdav/caldav): 2-3 weeks (CalDAV is more complex)
• Normalization layer: 1 week
• Sync engine: 2-3 weeks
• Total: 7-11 weeks

Alternative: third-party API service:

• Nylas/Cronofy integration: 1-2 weeks
• Cost: $3-10 per user per month
• Tradeoff: faster to build, ongoing cost, vendor dependency

The Gap This Persona Reveals#

This persona most clearly exposes the need for a “calendar integration SDK” – not just parsing and protocol libraries, but a complete abstraction layer that handles:

• Multi-provider OAuth2 flows
• Normalized event model
• Incremental sync with change detection
• Webhook/polling abstraction

cal.com is the closest open-source reference implementation, but it is a full application, not an extractable SDK. The calendar aggregation library ecosystem provides excellent building blocks (parsing, protocol, expansion) but forces every multi-provider developer to reinvent the integration layer.

S3: Need-Driven Discovery - Calendar Aggregation Libraries#

Objective#

Identify WHO needs calendar aggregation libraries and WHY. Map real personas to their pain points, constraints, and decision criteria. This is not about implementation – it is about understanding the demand landscape.

Approach#

S1 and S2 revealed that calendar aggregation is a composition problem with a weak merge layer. S3 asks: who is affected by this, and how do their different needs shape library selection?

Personas Analyzed#

Five distinct personas emerged from examining the ecosystem:

1. Indie SaaS Developer - Building a scheduling product (Calendly/cal.com competitor). Needs multi-provider calendar integration as a core feature.

2. Enterprise IT Administrator - Managing calendar infrastructure for an organization. Needs to aggregate calendars across departments for resource planning and compliance.

3. Personal Productivity User - Individual who wants a unified view of all their calendars (work + personal + side projects) without switching between apps.

4. Team Manager - Needs cross-team availability and free/busy visibility to coordinate meetings and resource allocation.

5. Multi-Provider Integration Developer - Building an application that connects to Google Calendar, Outlook, iCloud, and CalDAV servers simultaneously.

Analysis Framework#

For each persona:

• Who they are (role, context, technical ability)
• What pain they experience (specific frustrations)
• Why calendar aggregation libraries matter to them
• What constraints shape their choices
• How they would decide between options

S3 Recommendation: Calendar Aggregation Libraries#

Persona-Library Mapping#

Each persona has distinct needs that map to different parts of the library ecosystem. No single library stack serves all personas.

Summary Matrix#

“Indirect” means the persona benefits through products built with these libraries, not through direct use.

Key Findings#

1. The Ecosystem Serves Developers, Not End Users#

All five personas benefit from calendar aggregation, but only three (indie SaaS developer, enterprise IT admin, multi-provider developer) directly use the libraries. The personal user and team manager depend on products built with these libraries.

This means the library ecosystem’s quality is a supply-side concern – better libraries lead to better calendar products, which serve the end-user personas.

2. Python Dominates for Backend Aggregation#

Three of the five personas favor Python:

• Enterprise IT: Python is the automation standard
• Indie SaaS: Python backends are common; caldav + icalendar is the strongest stack
• Multi-provider developer: Python or JavaScript depending on stack

JavaScript is preferred only when the application is already Node.js-based. The Python ecosystem is stronger for calendar aggregation specifically because recurring-ical-events is actively maintained (vs stale ical-expander) and caldav has native free/busy support.

3. The Merge Layer Gap Affects Everyone Differently#

The gap is most painful for scheduling product developers and (indirectly) for the team managers who use their products.

4. Microsoft Outlook Is the Universal Pain Point#

Every persona encounters the Microsoft gap:

• CalDAV libraries cannot access Outlook calendars
• Microsoft Graph API requires a completely separate integration
• No library normalizes between CalDAV events and Graph API events

This is the single most common complaint across all personas. A library that provided a unified interface over CalDAV + Microsoft Graph would capture enormous developer demand.

5. Privacy Needs Are Under-Served#

Three of five personas need privacy controls:

• Personal user: Different detail levels for different audiences
• Team manager: Free/busy only (no event details for cross-team)
• Enterprise IT: GDPR compliance, data residency

Only camerge addresses privacy at the library level (and it is unmaintained). CalDAV free/busy queries preserve privacy by design, but require server support and do not work cross-platform.

Persona-Specific Recommendations#

Indie SaaS Developer#

Recommended stack: tsdav/caldav + ical.js/icalendar + ical-expander/ recurring-ical-events + Microsoft Graph SDK + custom merge/availability

Key advice: Budget 6-10 weeks for calendar integration. The merge and availability layers require the most custom code. Consider cal.com’s source code as reference architecture.

Enterprise IT Administrator#

Recommended stack: caldav + icalendar + recurring-ical-events + mergecal (GPL OK for internal use) + Microsoft Graph SDK for Outlook

Key advice: Build Python automation scripts. Batch processing overnight avoids rate limit concerns. caldav’s async API enables concurrent sync with many servers.

Personal Productivity User#

Recommended stack: ical-merger web service (Docker) for basic merge, or camerge for privacy-preserving merge

Key advice: Start with ical-merger’s Docker deployment. If privacy controls are needed, switch to a custom Python script with camerge.

Team Manager#

Recommended action: Use existing scheduling products (cal.com, Calendly, Reclaim.ai) built on these libraries. No direct library use recommended.

Key advice: Push IT department for cross-platform free/busy bridges. Evaluate cal.com for self-hosted scheduling if privacy is a concern.

Multi-Provider Integration Developer#

Recommended stack: Provider-specific SDKs (Google, Microsoft) + tsdav/ caldav for CalDAV + icalendar/ical.js for normalization + custom sync engine

Key advice: Evaluate third-party API services (Nylas, Cronofy) as an alternative to building multi-provider integration from libraries. The ongoing maintenance cost of provider integrations may exceed the API service fees.

The Market Opportunity#

S3 reveals a clear market opportunity in the calendar aggregation space:

1. Calendar integration SDK: A library that provides getEvents(userId, provider, dateRange) across Google, Microsoft, CalDAV, and ICS – handling auth, sync, normalization, and expansion internally. Every multi-provider developer reinvents this today.

2. Cross-platform availability engine: A library that computes free/busy across multiple providers without requiring CalDAV server support. Scheduling products all build this from scratch.

3. Privacy-aware merge library: camerge’s anonymization concept with mergecal’s deduplication quality, under an MIT license. No such library exists.

These three gaps represent the most common pain points across all personas.

S4: Strategic Discovery - Calendar Aggregation Libraries#

Objective#

Assess the long-term viability of the key calendar aggregation libraries. Which libraries will still be maintained in 3-5 years? Which face existential risks? What ecosystem trends will reshape the landscape?

Scope#

Focus on the libraries that matter most across the four layers:

Tier 1 (critical path – must evaluate):

• ical.js (JS parsing foundation)
• icalendar (Python parsing foundation)
• tsdav (JS CalDAV client)
• caldav (Python CalDAV client)
• recurring-ical-events (Python expansion)

Tier 2 (important but smaller):

• ical-expander (JS expansion – maintenance risk)
• mergecal (Python merge – GPL concern)
• node-ical (JS convenience parser)
• ical-generator (JS output)

Tier 3 (niche – brief assessment only):

• camerge, ical-merger, calendar_merger

Analysis Framework#

For each library or cluster:

1. Maintainer health: Bus factor, funding model, governance
2. Ecosystem momentum: Download trends, dependent projects, community
3. Risk assessment: What could go wrong in 2-3 years
4. Strategic recommendation: Conservative, adaptive, or aggressive path

Calendar Aggregation Ecosystem Momentum#

Download and Adoption Trends#

The Foundation Libraries Are Accelerating#

The parsing and protocol libraries show consistent growth in adoption, indicating a healthy and expanding developer base for calendar work.

icalendar (Python):

• 2023: ~5M monthly PyPI downloads
• 2024: ~7M monthly PyPI downloads
• 2026: ~8.4M monthly PyPI downloads
• Growth driver: Increased Python adoption for automation and backend services
• Dependent repositories: 10,800+ on GitHub (growing ~15% annually)

The 8.4M monthly download figure is remarkable for a specialized library. For comparison, python-dateutil (a general-purpose dependency) has ~130M monthly downloads. icalendar’s ratio suggests that roughly 1 in 15 Python projects that handle dates also handle calendar data, indicating broad applicability beyond niche calendar apps.

ical.js (JavaScript):

• npm weekly downloads: ~195,000 (stable over 2024-2026)
• Dependent npm packages: 350+
• Growth pattern: Flat rather than accelerating, reflecting JavaScript ecosystem maturity rather than decline

tsdav (JavaScript CalDAV):

• 2023: ~20K weekly npm downloads
• 2026: ~36K weekly npm downloads
• Growth rate: ~80% over 3 years
• Growth driver: cal.com adoption and the broader CalDAV integration trend

caldav (Python CalDAV):

• PyPI monthly downloads: ~186,000 (growing steadily)
• The v3.0 release (async support) triggered a download surge

The Merge Libraries Are Stagnant#

In sharp contrast to the foundation layers, the merge libraries show no meaningful adoption growth:

mergecal: 8 GitHub stars, minimal PyPI downloads camerge: 11 GitHub stars, no updates since 2022 ical-merger: 38 GitHub stars, no updates since 2022

This stagnation is not a reflection of low demand – it reflects the merge layer’s fundamental challenge: diverse requirements that resist standardization. Each application has different merge semantics (privacy rules, dedup strategies, conflict handling), making a one-size-fits-all library difficult to design.

Community Health Indicators#

Contributor Diversity#

The two libraries with institutional backing (icalendar under Plone Foundation, ical.js under Mozilla/Thunderbird) have the strongest governance models and highest bus factors. The rest are community-maintained with low bus factors, which is typical for specialized libraries.

Issue Response Time#

A key health metric – how quickly do maintainers respond to issues?

• icalendar: Median response time ~2-3 days. Active triage.
• caldav: Median response time ~1 week. Thorough responses.
• tsdav: Median response time ~3-5 days. Responsive to CalDAV issues.
• recurring-ical-events: Median response time ~1-2 days. Very responsive.
• ical.js: Median response time ~1-2 weeks. Slower but thorough.

All Tier 1 libraries show healthy issue response patterns. None have the warning signs of abandonment (months of unanswered issues, growing issue backlog with no triage).

Release Cadence#

The cal.com Effect#

cal.com (the open-source Calendly alternative) is the most significant single project driving the JavaScript calendar library ecosystem. With 3,500+ GitHub stars and venture funding, cal.com:

1. Validates tsdav: cal.com’s production use of tsdav proves the library works at scale with real CalDAV servers (Google, iCloud, Nextcloud). This validation is more valuable than any amount of testing.

2. Creates maintenance pressure: If tsdav breaks, cal.com breaks. This creates indirect funding pressure for tsdav maintenance, even without formal sponsorship.

3. Sets architectural patterns: cal.com’s calendar integration architecture (multi-provider with CalDAV + Google API + Microsoft Graph) serves as a reference implementation that other developers study and replicate.

4. Drives library discovery: Developers evaluating tsdav often discover it through cal.com’s dependency graph, funneling users to the library.

The cal.com effect is analogous to how Next.js drives adoption of React Server Components libraries – a high-profile project that creates ecosystem gravity.

Competitive Landscape: Libraries vs API Services#

The open-source library ecosystem competes with hosted API services for the multi-provider integration use case:

Third-Party Calendar API Services#

These services provide the unified calendar API that the open-source ecosystem lacks. They handle OAuth2 flows, provider quirks, webhook management, and event normalization behind a single REST API.

When Libraries Win Over API Services#

1. Privacy and data sovereignty: Self-hosted aggregation using open-source libraries keeps calendar data under your control. API services route data through their servers.

2. Cost at scale: At 10,000 users, Nylas costs $5,000-30,000/month. Self-hosted with open-source libraries costs server hosting only.

3. Customization: Libraries allow fine-grained control over sync behavior, merge logic, and conflict resolution. API services provide a fixed abstraction.

4. Offline/embedded use: Libraries work in air-gapped environments or embedded in desktop/mobile applications. API services require internet connectivity.

When API Services Win#

1. Time to market: 1-2 days vs 6-10 weeks for multi-provider integration
2. Maintenance burden: Provider API changes are handled by the service
3. Expertise: Calendar protocol edge cases are the service’s problem
4. OAuth2 complexity: The service handles all provider auth flows

Market Prediction#

API services will grow but will not replace the open-source library stack:

• Large SaaS products (cal.com scale) prefer self-hosted for cost and control
• Enterprise deployments require self-hosted for data sovereignty
• Privacy-conscious users demand self-hosted
• Developers building calendar-adjacent features (CRM, time tracking) may prefer API services for speed

The two approaches will coexist, with API services capturing the “quick integration” market and open-source libraries serving the “deep control” market.

Open Source Funding Models#

Current Funding#

Most calendar aggregation libraries have no formal funding:

• icalendar: Plone Foundation (nonprofit with member dues)
• ical.js: Mozilla/Thunderbird Foundation (indirectly funded)
• All others: Volunteer-maintained, no revenue

Potential Funding Sources#

1. GitHub Sponsors: Only recurring-ical-events has an active GitHub Sponsors page. Other libraries could benefit from individual sponsorship.

2. Corporate sponsorship: cal.com could formally sponsor tsdav and ical.js, given their dependency on these libraries. This would strengthen the ecosystem.

3. Tidelift/Open Collective: Platform-based funding for maintenance commitments. icalendar’s high download count would qualify for meaningful Tidelift payouts.

4. Bounty programs: Specific features (MIT merge library, TypeScript expansion replacement) could be funded through bounties on platforms like IssueHunt.

Impact on Viability#

The lack of formal funding is the ecosystem’s biggest structural risk. Volunteer-maintained libraries with bus factor 1-2 are vulnerable to maintainer burnout. The libraries that are most critical (tsdav, caldav, recurring-ical-events) are also the most dependent on individual maintainers.

If the calendar aggregation ecosystem were to receive targeted funding (from cal.com, from a developer tools company, or from a foundation), the two highest-impact investments would be:

1. Funding a full-time maintainer for tsdav (reduce bus factor risk)
2. Funding development of an MIT-licensed merge/availability library (fill the ecosystem’s biggest gap)

S4 Recommendation: Strategic Paths for Calendar Aggregation#

Strategic Assessment Summary#

The calendar aggregation library ecosystem is bifurcated:

• Foundation layers (parsing, protocol) are STRONG: ical.js, icalendar, tsdav, and caldav are all actively maintained, well-adopted, and have multi-year viability.

• Application layers (expansion, merge) are WEAK-TO-MODERATE: recurring-ical-events is strong on the Python side. ical-expander is a maintenance risk on the JavaScript side. Merge libraries are either GPL-restricted (mergecal) or abandoned (camerge, ical-merger).

This creates a clear strategic picture: the foundation is solid, but builders must invest in custom application-layer code.

Strategic Paths#

Path 1: Conservative (Minimize Risk)#

Philosophy: Use only the most stable libraries. Build custom code for anything that is not well-maintained.

JavaScript stack:

• ical.js (SAFE) for parsing
• tsdav (PROBABLY SAFE) for CalDAV
• Vendor ical-expander code (~400 lines) rather than depending on the npm package
• Custom merge logic (do not depend on ical-merger)
• ical-generator (SAFE) for output

Python stack:

• icalendar (VERY SAFE) for parsing
• caldav (SAFE) for CalDAV
• recurring-ical-events (SAFE) for expansion
• Custom merge logic (do not depend on mergecal due to GPL; do not depend on camerge due to abandonment)

Best for: Production SaaS products, enterprise systems, anything where calendar integration is a critical business function.

Tradeoff: More upfront engineering for the merge layer, but no risk of dependency abandonment.

Path 2: Adaptive (Balance Risk and Speed)#

Philosophy: Use available libraries including smaller ones, but have a migration plan for each dependency.

JavaScript stack:

• ical.js + tsdav + ical-expander (from npm) + ical-generator
• Monitor ical-expander for staleness; if ical.js releases a breaking change, vendor immediately
• Use ical-merger’s web service pattern as a reference, but write own merge

Python stack:

• icalendar + caldav + recurring-ical-events + mergecal
• Accept mergecal’s GPL for internal/server-side use
• If distributing software, extract mergecal’s algorithms and reimplement under a permissive license

Best for: Startups and small teams that need to ship quickly and can accept some dependency risk.

Tradeoff: Faster to build, but requires active dependency monitoring and contingency plans.

Path 3: Ecosystem Investment (Build the Missing Pieces)#

Philosophy: Invest in building the libraries that the ecosystem needs. Capture the demand for a production-grade merge/availability layer.

What to build:

1. Calendar merge library (MIT license): Combine mergecal’s deduplication quality with camerge’s anonymization concept, under MIT. Features: UID dedup, timezone normalization, content-based fuzzy dedup, per-source anonymization, conflict detection, VFREEBUSY generation.

2. Cross-provider availability engine: A library that computes free/busy across CalDAV, Google Calendar API, and Microsoft Graph API. Handles the normalization, expansion, and interval computation that every scheduling product builds from scratch.

3. Unified calendar SDK: Higher-level abstraction over the provider libraries. Single API for getEvents/createEvent/deleteEvent across providers. Handles auth, sync tokens, normalization internally.

Best for: Developer tool companies, open-source project maintainers, or teams willing to invest in the ecosystem for long-term strategic advantage.

Tradeoff: Significant upfront investment (months of work). The payoff is community adoption and influence over the ecosystem’s direction.

Risk Mitigation Strategies#

For ical-expander (HIGH RISK)#

The stale JavaScript expansion library is the ecosystem’s biggest single-point-of-failure:

1. Immediate: Vendor the code into your project
2. Short-term: Pin ical.js to a version known to work with ical-expander
3. Medium-term: Write or commission a replacement that directly uses ical.js’s RecurExpansion API (bypassing the ical-expander wrapper)
4. Long-term: Contribute a maintained expansion module to the ical.js project itself

For mergecal (GPL RISK)#

If you need merge functionality but cannot accept GPL-3.0:

1. Immediate: Study mergecal’s deduplication algorithm (it is well-documented in the source code)
2. Short-term: Reimplement the algorithm under MIT license (the algorithms are not patentable; only the specific code is GPL)
3. Medium-term: Build a more complete merge library that also handles conflict detection and anonymization

For tsdav (BUS FACTOR RISK)#

If tsdav’s sole maintainer becomes unavailable:

1. Immediate: Fork the repository
2. Short-term: The CalDAV protocol is stable, so an unmaintained tsdav works for years against existing servers
3. Medium-term: If Google or Apple changes their CalDAV endpoints or auth requirements, apply fixes to the fork
4. Long-term: cal.com’s dependency on tsdav means they will likely adopt or fund maintenance of any fork

For the Microsoft Graph Gap#

No CalDAV library addresses Outlook calendars:

1. Immediate: Use Microsoft’s official @microsoft/microsoft-graph-client SDK
2. Short-term: Build a thin normalization layer between Graph API events and your internal event model
3. Medium-term: Consider contributing a provider abstraction layer that wraps both CalDAV and Graph API behind a common interface

Long-Term Ecosystem Prediction#

3-Year Horizon (2026-2029)#

• ical.js and icalendar remain dominant for parsing (no disruption expected)
• tsdav and caldav remain dominant for CalDAV (protocol stability)
• ical-expander either gets adopted by ical.js project or functionally abandoned (vendoring becomes standard practice)
• An MIT-licensed merge library emerges (either from the cal.com ecosystem or from the AI scheduling space)
• Third-party API services (Nylas, Cronofy) grow but do not replace the open-source stack for self-hosted deployments

5-Year Horizon (2026-2031)#

• CalDAV remains relevant but increasingly supplemented by provider-specific APIs with richer features (AI meeting summaries, smart scheduling)
• The open-source calendar SDK concept (unified API across providers) materializes – likely extracted from cal.com or a similar project
• AI scheduling products drive investment in the availability and conflict detection layers, benefiting the broader library ecosystem
• Microsoft Graph API may add CalDAV compatibility layer (speculative; would dramatically simplify multi-provider integration)

Final Recommendation#

For most teams building calendar aggregation today:

Use the Conservative path (Path 1) for the foundation layers and the Adaptive path (Path 2) for rapid prototyping. Specifically:

1. Start with proven libraries: icalendar/ical.js + caldav/tsdav + recurring-ical-events (Python) or vendored ical-expander (JS)
2. Build custom merge logic: The effort is 2-4 weeks, and you avoid GPL constraints and abandonment risk
3. Add Microsoft Graph separately: Accept that Outlook integration requires a separate code path
4. Monitor the ecosystem: Watch for an MIT-licensed merge library to emerge; adopt it when it reaches 100+ GitHub stars and 6+ months of active maintenance

The calendar aggregation space is mature at the protocol level and immature at the application level. The strategic opportunity is in the application layer – whoever builds the “Express.js of calendar aggregation” (composable middleware for fetch, parse, expand, merge, serve) will capture significant developer demand.

Vendor and Library Viability Assessment#

Tier 1: Foundation Libraries#

ical.js (JavaScript Parsing)#

Maintainer Health: STRONG

ical.js is maintained by Philipp Kewisch under Mozilla’s umbrella. While not an official Mozilla product, it benefits from Mozilla’s ecosystem:

• Used by Thunderbird (Mozilla’s email/calendar client)
• Thunderbird’s renewed investment (post-2023 restructuring) indirectly sustains ical.js
• Kewisch is a long-time Mozilla contributor with deep iCalendar expertise
• Bus factor: 2-3 (Kewisch plus occasional Mozilla contributors)

Ecosystem Momentum: STRONG

• 1,200+ GitHub stars
• 195,000+ npm weekly downloads (stable, not declining)
• 350+ npm packages depend on it
• Used by major projects: Thunderbird, ical-expander, tsdav (indirectly)
• Regular releases (2024-2026 active)

Risk Assessment: LOW

• Primary risk: If Mozilla further reduces Thunderbird investment, ical.js could lose its institutional backing. However, Thunderbird Foundation (independent since 2024) has its own funding, reducing this risk.
• Secondary risk: A new iCalendar library could emerge with better API design. Unlikely given ical.js’s deep RFC compliance and ecosystem lock-in.
• Mitigation: ical.js is MIT-compatible (MPL-2.0 with file-level copyleft). If abandoned, the community can fork without legal friction.

5-Year Outlook: SAFE

ical.js will remain the standard JavaScript iCalendar library. Its RFC compliance, Mozilla connection, and deep ecosystem integration create a moat that new entrants cannot easily cross.

icalendar (Python Parsing)#

Maintainer Health: STRONG

Maintained by the Plone Foundation with multiple active contributors:

• 4-5 active contributors in 2024-2026
• Institutional backing from Plone Foundation (nonprofit)
• Regular release cadence (v7.0.x series active)
• Bus factor: 4-5 (distributed among community members)

Ecosystem Momentum: DOMINANT

• 1,100+ GitHub stars
• 8,400,000+ PyPI monthly downloads (enormous for a specialized library)
• 10,800+ dependent GitHub repositories
• The Python calendar ecosystem’s universal foundation
• Every Python calendar library (recurring-ical-events, mergecal, camerge, caldav) builds on icalendar

Risk Assessment: VERY LOW

• Plone Foundation governance provides long-term stability
• Multiple maintainers prevent single-point-of-failure
• Massive download count means many organizations depend on it, creating social pressure for continued maintenance
• No credible competitor in the Python ecosystem (ics-py exists but has 1/12th the downloads)

5-Year Outlook: VERY SAFE

icalendar is as close to “guaranteed maintained” as an open-source library can be. Its position in the Python ecosystem is analogous to requests or Beautiful Soup – so deeply embedded that abandonment is effectively impossible.

tsdav (JavaScript CalDAV Client)#

Maintainer Health: MODERATE

• Primary maintainer: Nate Lin (natelindev)
• Bus factor: 1-2 (Nate plus occasional contributors)
• Revenue model: Open source, no direct funding
• Sustained by usage in cal.com (the open-source Calendly alternative)
• Regular releases (v2.1.x series, Feb 2026)

Ecosystem Momentum: GROWING

• 334 GitHub stars (growing from ~200 in 2023)
• 36,000+ npm weekly downloads (up from ~20K in 2023)
• Used by cal.com (3,500+ stars, funded startup)
• Most starred CalDAV client in the JavaScript ecosystem

Risk Assessment: MODERATE

• Bus factor of 1-2 is the primary risk. If Nate Lin stops maintaining, the library could stall.
• cal.com’s usage provides indirect motivation: if tsdav breaks, cal.com breaks, creating pressure for community fixes.
• The CalDAV protocol is stable (RFC 4791 from 2007, RFC 6578 from 2012), so even unmaintained versions work for years against existing servers.
• Risk of Google/Apple changing CalDAV endpoints or auth flows could break tsdav. These changes are infrequent but high-impact.

5-Year Outlook: PROBABLY SAFE

tsdav benefits from cal.com’s success. As long as cal.com thrives, tsdav will receive maintenance. The CalDAV protocol’s stability means even brief maintenance gaps are tolerable. However, the low bus factor is a concern for risk-averse teams.

caldav (Python CalDAV Client)#

Maintainer Health: STRONG

• Primary maintainer: Tobias Brox (tobixen)
• Multiple contributors (20+ over project lifetime)
• Bus factor: 2-3
• Regular releases (v3.0.x, March 2026)
• Active issue response and PR merging

Ecosystem Momentum: STRONG

• 393 GitHub stars (highest of any CalDAV client library)
• 186,000+ PyPI monthly downloads
• Used by multiple open-source calendar projects
• Comprehensive test suite against many CalDAV servers

Risk Assessment: LOW

• CalDAV protocol stability means the library needs minimal changes
• Async support (v3.0) shows active evolution, not just maintenance
• Dual license (Apache/GPL) is established and unlikely to change
• Python CalDAV ecosystem has no credible alternative

5-Year Outlook: SAFE

caldav is the uncontested Python CalDAV client. Its feature completeness (free/busy queries, async, wide server compatibility) and regular maintenance make it a safe long-term choice.

recurring-ical-events (Python Expansion)#

Maintainer Health: STRONG

• Primary maintainer: Nicco Kunzmann (niccokunzmann)
• Active development: v3.8.1 released Feb 2026
• Regular feature additions (VTODO, VJOURNAL, VALARM support added over time)
• Bus factor: 1-2 (Nicco plus occasional contributors)
• Part of a broader open-source calendar ecosystem (Nicco also maintains related calendar projects)

Ecosystem Momentum: GROWING

• 118 GitHub stars
• 965,000+ PyPI monthly downloads (nearly 1M/month)
• Growing dependency graph (used by calendar apps, automation tools)
• Active issue tracker with responsive maintainer

Risk Assessment: LOW-MODERATE

• Bus factor of 1-2 is a concern, but Nicco Kunzmann has maintained the project consistently since its creation
• LGPL-3.0 license may deter some commercial users (acceptable for server-side, problematic for distributed libraries)
• The library sits at the intersection of icalendar and python-dateutil, both of which are stable. Changes to either dependency could require updates, but both are slow-moving.

5-Year Outlook: SAFE

The 965K monthly downloads demonstrate that this library is deeply embedded in Python calendar workflows. Combined with active maintenance, it is a safe choice for long-term projects.

Tier 2: Important but Smaller#

ical-expander (JavaScript Expansion)#

Maintainer Health: WEAK

• Primary maintainer: Mikael Finstad (mifi)
• Last release: 2023 (2+ years ago)
• Low bus factor: 1
• No visible ongoing development

Risk Assessment: HIGH

This is the highest-risk library in the calendar aggregation stack. The JavaScript ecosystem has no alternative for RECURRENCE-ID-aware expansion. If ical.js makes a breaking change, ical-expander will break with no maintainer to fix it.

Mitigation strategy:

1. Vendor the library code (~400 lines) into your project
2. Pin ical.js to a known-compatible version
3. Monitor ical.js releases for breaking changes
4. Be prepared to maintain the vendored code yourself

5-Year Outlook: AT RISK

Will likely become effectively abandoned. However, the CalDAV ecosystem’s slow pace of change means it may continue working without updates for several years. Vendoring is strongly recommended.

mergecal (Python Merge)#

Maintainer Health: MODERATE

• Active development (v0.5.0, Feb 2025)
• CI/CD pipeline with code coverage
• 363 commits indicate sustained investment
• Bus factor: 1-2

Risk Assessment: MODERATE

• GPL-3.0 license limits commercial adoption, which limits community growth, which limits maintenance motivation. A negative feedback loop.
• Small community (8 stars) means little external contribution pressure
• The library solves a real problem but the GPL makes it a non-starter for the largest user segment (SaaS developers)

5-Year Outlook: UNCERTAIN

mergecal is actively maintained but its GPL license caps its growth potential. It will likely continue serving the niche of open-source and internal-use calendar aggregation but will not become a widely-adopted standard.

node-ical (JavaScript Convenience Parser)#

Maintainer Health: MODERATE

• Actively maintained (2026 releases)
• 153 stars, 65K weekly npm downloads
• Bus factor: 2-3

5-Year Outlook: SAFE

Fills a useful niche (simpler API than ical.js for common tasks). Stable maintenance trajectory.

ical-generator (JavaScript Output)#

Maintainer Health: STRONG

• Actively maintained by Sebastian Pekarek (sebbo2002)
• 600+ stars, 243K weekly npm downloads
• Regular releases, TypeScript-first
• Bus factor: 1-2

5-Year Outlook: SAFE

High download count and active maintenance. The “output” layer is simpler than parsing, so maintenance burden is lower.

Tier 3: Niche Libraries#

camerge#

• 11 stars, no updates since 2022
• 5-Year Outlook: ABANDONED (functionally dead)
• Value: Anonymization concept is worth extracting, not the library itself

@jacobmischka/ical-merger#

• 38 stars, no updates since 2022
• 5-Year Outlook: ABANDONED (functionally dead)
• Value: Web service pattern is useful as reference architecture

calendar_merger#

• 2 stars, minor updates in 2024
• 5-Year Outlook: ABANDONED (effectively a personal project)
• Value: Free/busy aggregation pattern is useful as reference

Ecosystem Trends#

1. CalDAV Protocol Stability#

The CalDAV protocol (RFC 4791, 2007) has not seen significant changes in over a decade. This is good news for library consumers: CalDAV libraries do not need frequent updates to remain functional. A library that is “unmaintained” for CalDAV purposes may still work perfectly for years.

2. Microsoft Graph API Evolution#

Microsoft continues to invest in Graph API as the primary programmatic interface for Microsoft 365. The Graph API is REST-based with JSON payloads, making it fundamentally different from CalDAV. The gap between CalDAV libraries and Microsoft Graph will persist unless Microsoft adds CalDAV support (extremely unlikely) or someone builds a bridge library.

3. Consolidation Around TypeScript#

The JavaScript ecosystem is consolidating around TypeScript for library development. tsdav and ical-generator are TypeScript-first. ical.js and node-ical have TypeScript type definitions. New calendar libraries will almost certainly be TypeScript.

4. API Services as Competition#

Third-party calendar API services (Nylas, Cronofy, CalendarBridge) offer unified APIs across providers for a per-user monthly fee. These services compete with the open-source library stack for the multi-provider integration use case.

If these services mature and their pricing drops, the open-source library ecosystem may shrink as developers choose to pay for integration rather than build it. However, self-hosted and privacy-conscious users will always need the open-source libraries.

5. AI-Driven Scheduling#

AI scheduling assistants (Reclaim.ai, Clockwise, Motion) are an emerging category that builds on calendar aggregation. These products consume calendar data from multiple providers, apply AI for optimization (auto- scheduling, focus time protection), and write events back. They are among the most demanding consumers of the calendar aggregation library ecosystem.

As AI scheduling grows, demand for robust calendar aggregation libraries will increase, potentially driving more investment in the merge and availability layers that are currently weak.