{"id":13318,"library":"ical","title":"ical: iCalendar Parser","description":"The `ical` (formerly `node-ical`) package, at version 0.8.0, is a JavaScript library designed for parsing iCalendar (ICS) files, primarily targeting Node.js environments. It adheres to RFC5545 and offers a tolerant and minimal API for extracting event data from ICS strings or local files. While providing straightforward parsing for basic calendar entries, the library explicitly notes that handling complex features like recurrence rules (RRULE), event recurrences, and exception dates (EXDATE) requires more in-depth developer implementation. This version, published 6 years ago, represents a stable but older state of the library. Newer, actively maintained forks like `node-ical` (by jens-maus) and `ical.js` (by kewisch) exist, offering more modern features like async APIs, robust recurrence expansion, and TypeScript support, indicating that `ical@0.8.0` is in a de facto maintenance state, superseded by these alternatives.","status":"maintenance","version":"0.8.0","language":"javascript","source_language":"en","source_url":"git://github.com/peterbraden/ical.js","tags":["javascript","ical","ics","calendar"],"install":[{"cmd":"npm install ical","lang":"bash","label":"npm"},{"cmd":"yarn add ical","lang":"bash","label":"yarn"},{"cmd":"pnpm add ical","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Version 0.8.0 of 'ical' is a CommonJS module and does not support native ES Modules import syntax. Use `require`.","wrong":"import ical from 'ical';","symbol":"ical","correct":"const ical = require('ical');"},{"note":"The `parseICS` function is a method of the default `ical` export. There are no named exports at this version.","symbol":"parseICS","correct":"const ical = require('ical');\nconst data = ical.parseICS(icsString);"},{"note":"The `parseFile` function is a synchronous method for reading ICS files from the local filesystem.","symbol":"parseFile","correct":"const ical = require('ical');\nconst data = ical.parseFile(filePath);"}],"quickstart":{"code":"const ical = require('ical');\nconst months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];\n\n// Example ICS content (in a real app, this would come from a file or network request)\nconst icsContent = `BEGIN:VCALENDAR\nVERSION:2.0\nPRODID:-//Example Corp//NONSGML Events//EN\nBEGIN:VEVENT\nUID:event1@example.com\nDTSTAMP:20260419T213000Z\nDTSTART:20260515T100000Z\nDTEND:20260515T110000Z\nSUMMARY:Node.js Conference Keynote\nLOCATION:Main Auditorium\nEND:VEVENT\nBEGIN:VEVENT\nUID:event2@example.com\nDTSTAMP:20260419T213000Z\nDTSTART:20260601T090000Z\nDTEND:20260601T170000Z\nSUMMARY:JavaScript Deep Dive Workshop\nLOCATION:Room 301\nEND:VEVENT\nEND:VCALENDAR`;\n\nconst data = ical.parseICS(icsContent);\n\nconsole.log('Upcoming Events:');\nfor (let k in data) {\n\tif (data.hasOwnProperty(k)) {\n\t\tconst ev = data[k];\n\t\tif (ev.type === 'VEVENT') {\n\t\t\tconst startDate = ev.start;\n\t\t\tconst endDate = ev.end;\n\t\t\t// Ensure start/end are valid Date objects before accessing methods\n\t\t\tif (startDate instanceof Date && endDate instanceof Date) {\n\t\t\t\tconsole.log(`- ${ev.summary || 'Untitled Event'} is in ${ev.location || 'Unknown location'} on the ${startDate.getDate()} of ${months[startDate.getMonth()]} at ${startDate.toLocaleTimeString('en-GB')}`);\n\t\t\t} else {\n\t\t\t\tconsole.log(`- ${ev.summary || 'Untitled Event'} has malformed date data.`);\n\t\t\t}\n\t\t}\n\t}\n}","lang":"javascript","description":"This quickstart demonstrates how to parse an iCalendar string using `ical.parseICS` and iterate through the resulting event data, logging key details like summary, location, and start time. It handles basic event types and provides a fallback for malformed date data."},"warnings":[{"fix":"Update `package.json` to depend on `ical` and change `require('node-ical')` to `require('ical')`.","message":"The package underwent a name change from `node-ical` to `ical.js` and is available on npm under `ical`. Older projects might need to update their `require` statements and `package.json` dependencies.","severity":"breaking","affected_versions":"<=0.7.x"},{"fix":"Refer to `example_rrule.js` (if available in the full package) or custom logic to correctly expand and filter recurring events based on `rrule`, `recurrences`, and `exdate` properties.","message":"Handling recurrence rules (RRULE), specific recurrences, and exception dates (EXDATE) for calendar events is significantly more complex than simple event parsing and requires careful implementation. The library provides the raw data but leaves the expansion logic to the developer.","severity":"gotcha","affected_versions":">=0.8.0"},{"fix":"Ensure you use `const ical = require('ical');` for importing the library. If working in an ESM-only project, a wrapper or a newer alternative (like `node-ical` or `ical.js` which support ESM) may be required.","message":"Version 0.8.0 is strictly a CommonJS module. Attempting to use ES Modules `import` syntax will result in errors.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Consider migrating to a more current iCalendar parsing library if advanced features, active development, or native ESM/TypeScript support are needed.","message":"The `ical` package (version 0.8.0) is effectively superseded by more actively maintained forks and related libraries, such as `node-ical` (by jens-maus) and `ical.js` (by kewisch), which offer modern features and better ongoing support, including async APIs and TypeScript definitions.","severity":"deprecated","affected_versions":"0.8.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure you are running in a Node.js environment. If parsing a string, use `ical.parseICS(icsString)`. Verify the `ical` object is correctly initialized: `const ical = require('ical');`","cause":"The `parseFile` function is not available in the browser environment, or the `ical` object was not correctly imported/required.","error":"TypeError: ical.parseFile is not a function"},{"fix":"Verify the file path provided to `ical.parseFile()` is correct and that the process has read permissions for the file.","cause":"The `ical.parseFile()` function could not find the specified ICS file at the given path.","error":"Error: ENOENT: no such file or directory, open 'calendar.ics'"},{"fix":"Always add defensive checks for `null` or `undefined` values on date properties (`ev.start`, `ev.end`) before attempting to access their methods. For example: `if (ev.start instanceof Date) { ev.start.getDate(); }`","cause":"An event object returned by `ical.parseICS` or `ical.parseFile` might have malformed or missing date properties, leading to attempts to call Date methods on `undefined`.","error":"TypeError: Cannot read properties of undefined (reading 'getDate')"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":"","cli_version":null}