{"id":15353601,"url":"https://github.com/mifi/ical-expander","last_synced_at":"2025-04-09T09:11:20.854Z","repository":{"id":45000276,"uuid":"86599126","full_name":"mifi/ical-expander","owner":"mifi","description":"ICS / iCal / iCalendar parser / expander","archived":false,"fork":false,"pushed_at":"2022-01-19T07:45:36.000Z","size":89,"stargazers_count":66,"open_issues_count":9,"forks_count":21,"subscribers_count":7,"default_branch":"master","last_synced_at":"2025-04-02T08:13:13.571Z","etag":null,"topics":["calendar","expand","ical","ics","parse","range","recurring","rrule","timezone"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mifi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"mifi","custom":"https://mifi.no/thanks"}},"created_at":"2017-03-29T15:29:28.000Z","updated_at":"2025-01-09T04:34:16.000Z","dependencies_parsed_at":"2022-09-06T21:52:44.816Z","dependency_job_id":null,"html_url":"https://github.com/mifi/ical-expander","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mifi%2Fical-expander","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mifi%2Fical-expander/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mifi%2Fical-expander/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mifi%2Fical-expander/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mifi","download_url":"https://codeload.github.com/mifi/ical-expander/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248008630,"owners_count":21032556,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["calendar","expand","ical","ics","parse","range","recurring","rrule","timezone"],"created_at":"2024-10-01T12:14:34.506Z","updated_at":"2025-04-09T09:11:20.832Z","avatar_url":"https://github.com/mifi.png","language":"JavaScript","funding_links":["https://github.com/sponsors/mifi","https://mifi.no/thanks"],"categories":[],"sub_categories":[],"readme":"# ical-expander 📅 [![npm version](https://badge.fury.io/js/ical-expander.svg)](https://badge.fury.io/js/ical-expander) ![Test local branches](https://github.com/mifi/ical-expander/workflows/Test%20local%20branches/badge.svg) [![](https://mifi.github.io/ical-expander-coverage/coverage-badge.svg)](https://mifi.github.io/ical-expander-coverage) [![Known Vulnerabilities](https://snyk.io/test/github/mifi/ical-expander/badge.svg)](https://snyk.io/test/github/mifi/ical-expander)\nICS / iCal / iCalendar parser / expander.\n\nWrapper around [ical.js](https://github.com/mozilla-comm/ical.js) that automatically handles `EXDATE` (excluded recursive occurrences), `RRULE` and recurring events overridden by `RECURRENCE-ID`.\n\nAlso handles timezones, and includes timezones from the [IANA Time Zone Database](https://www.iana.org/time-zones), so that it parses correctly when a timezone definition is not available in the ICS file itself. `zones.json` can be found [here](https://hg.mozilla.org/comm-central/file/tip/calendar/timezones/zones.json) and compiled by running `compile-zones.js`.\n\nBe careful as the processing done in this library is\nsynchronous and will block the JS event loop while processing. Especially when\nprocessing large ICS files and with high maxIterations values.\n\n## Install\n\n```\nnpm install ical-expander\n```\n\n⚠️ Warning: This package uses ES6 features, and might require transpiling if used in browsers\n\n## Example\n\nDownload .ics from google calendar for example.\n\n```\nconst IcalExpander = require('ical-expander');\nconst fs = require('fs');\n\nconst ics = fs.readFileSync('./basic.ics', 'utf-8');\n\nconst icalExpander = new IcalExpander({ ics, maxIterations: 100 });\nconst events = icalExpander.between(new Date('2017-01-24T00:00:00.000Z'), new Date('2017-03-30T00:00:00.000Z'));\n\nconst mappedEvents = events.events.map(e =\u003e ({ startDate: e.startDate, summary: e.summary }));\nconst mappedOccurrences = events.occurrences.map(o =\u003e ({ startDate: o.startDate, summary: o.item.summary }));\nconst allEvents = [].concat(mappedEvents, mappedOccurrences);\n\nconsole.log(allEvents.map(e =\u003e `${e.startDate.toJSDate().toISOString()} - ${e.summary}`).join('\\n'));\n```\n\n## Usage\n### Constructor\n```\nconst icalExpander = new IcalExpander({ ics, maxIterations })\n```\n- `ics`: String containing ICS data to parse\n- `maxIterations`: Max iterations on each RRULE. Defaults to 1000 (`undefined` or `null`). 0 means never stop (__be careful!__)\n\n### between()\n```\nicalExpander.between(after, before)\n```\nInclude all events occuring between `after` and `before`. i.e. with a start time before `before` `JS Date` __and__ an end time `after` `JS Date`.\n\n- `after` `JS Date`: Start of range. Default: No start limit.\n- `before` `JS Date`. End of range. Default: No end limit. __Do not run with no end limit and `maxIterations: 0`__\n\nExample of events included between a date range:\n```\nrange:    ---------- after |-----------------------| before -------------\nevent 1:                   |          start \u003c------|------------\u003e end\nevent 2:         start \u003c---|---------------\u003e end   |\nevent 3:      start \u003c------|-----------------------|--------------\u003e end\nevent 4:                   |    start \u003c---\u003e end    |                                                   \n```\n\nExample of events __not__ included between a date range:\n```\nrange:    -------------------- after |--------| before ------------------\nevent 5:  start \u003c------\u003e end         |        |\nevent 6:                             |        |          start \u003c---\u003e end\n```\n\n\n### before()\n`icalExpander.before(before)` is an alias for `icalExpander.between(undefined, before)`  \n\n### after()\n`icalExpander.after()` is an alias for `icalExpander.between(after)`  \n\n### all()\n`icalExpander.all()` is an alias for `icalExpander.between()`  \n__Do not run this with `maxIterations: 0`__\n\n### Return value\nAll methods return:\n```\n{\n  events: [],\n  occurrences: [],\n}\n```\n- `events` is a list of [ICAL.Event](http://mozilla-comm.github.io/ical.js/api/ICAL.Event.html) objects.\n- `occurrences` is a list of [ICAL.Event.occurrenceDetails](http://mozilla-comm.github.io/ical.js/api/ICAL.Event.html#.occurrenceDetails) objects.\n\n### icalExpander.component\nRoot [ICAL.Component](http://mozilla-comm.github.io/ical.js/api/ICAL.Component.html) from parsed data.\n\n## TODO\n- RECURRENCE-ID: check that within same day?\n- Get data from moment-timezone instead?\n\n## See also:\n- https://github.com/mozilla-comm/ical.js/issues/294\n- https://nylas.com/blog/rrules/\n- https://github.com/jakubroztocil/rrule\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmifi%2Fical-expander","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmifi%2Fical-expander","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmifi%2Fical-expander/lists"}