calendaryjs-plugin-ics 0.1.1 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +38 -73
  2. package/package.json +2 -2
package/README.md CHANGED
@@ -1,103 +1,68 @@
1
- # calendaryjs-plugin-ics
1
+ <p align="center">
2
+ <img src="https://cdn.jsdelivr.net/npm/calendaryjs/assets/logo.svg" alt="calendaryjs" width="380" />
3
+ </p>
2
4
 
3
- ICS (RFC 5545) export for [calendaryjs](https://www.npmjs.com/package/calendaryjs). Turn generated calendar occurrences into a standard `.ics` `VCALENDAR` that Apple Calendar, Google Calendar, Outlook and anything else can subscribe to.
5
+ # calendaryjs-plugin-ics
4
6
 
5
- It is an **edge integration**: calendaryjs owns the calendar core; this package only serializes its plain output. It adds **zero runtime dependency** to the core and works on any plain object shaped like a `CalendarEvent`.
7
+ > **New to calendaryjs?** Start with the [core README](https://www.npmjs.com/package/calendaryjs) — this plugin serializes its output.
6
8
 
7
- ## Features
9
+ Turn generated calendar occurrences into a standard `.ics` `VCALENDAR` that Apple
10
+ Calendar, Google Calendar, Outlook and anything else can subscribe to. An **edge
11
+ integration** — calendaryjs owns the calendar core; this only serializes its plain
12
+ output, with **zero runtime dependency**.
8
13
 
9
- - **📤 One VEVENT per occurrence** — events come in already expanded, so no `RRULE` is emitted. Lunar / hijri / formula dates and per-occurrence `exceptions` & `overrideDates` (already applied by the core) all export correctly.
10
- - **⏰ Reminders → `VALARM`** — each lead-time reminder becomes a relative-trigger alarm (`DISPLAY` or `EMAIL`).
11
- - **🔢 Priority → `PRIORITY`** — calendaryjs `priority` (CSS `z-index`: higher = on top) is inverted into ICS `PRIORITY` (1 = highest), with a pluggable mapper.
12
- - **🎨 Display fields** — `DESCRIPTION`, `LOCATION`, `URL`, `CATEGORIES`, `STATUS`, plus RFC 7986 `COLOR` / `IMAGE`.
13
- - **✅ Spec-correct output** — CRLF line endings, octet-aware line folding (75-octet, no multi-byte splits), RFC 5545 text escaping.
14
- - **🧪 Deterministic** — pass a fixed `dtstamp` for byte-stable, diff-friendly files.
14
+ <p align="center">
15
+ <a href="https://www.npmjs.com/package/calendaryjs-plugin-ics"><img alt="npm" src="https://img.shields.io/npm/v/calendaryjs-plugin-ics?style=for-the-badge&color=f59e0b&labelColor=16120F" /></a>
16
+ <a href="https://socket.dev/npm/package/calendaryjs-plugin-ics"><img alt="Socket" src="https://img.shields.io/badge/Socket-security-f59e0b?style=for-the-badge&labelColor=16120F" /></a>
17
+ <img alt="Zero dependencies" src="https://img.shields.io/badge/deps-zero-22c55e?style=for-the-badge&labelColor=16120F" />
18
+ </p>
15
19
 
16
- ## Installation
20
+ ## Install
17
21
 
18
22
  ```bash
19
- pnpm add calendaryjs calendaryjs-plugin-ics
23
+ npm i calendaryjs calendaryjs-plugin-ics
20
24
  ```
21
25
 
22
- ## Requirements
26
+ ## Use it
23
27
 
24
- - `calendaryjs` >= 0.1.0
28
+ Generate occurrences with calendaryjs, then pass them to `toICS()`:
25
29
 
26
- ## Quick Start
27
-
28
- ```typescript
30
+ ```ts
29
31
  import { calendary } from "calendaryjs";
32
+ import { every, date } from "calendaryjs/builder";
30
33
  import { toICS } from "calendaryjs-plugin-ics";
31
34
 
32
35
  const cal = calendary();
33
36
  cal.addGroup({
34
37
  id: "holidays",
35
- name: "Holidays",
36
- events: [
37
- { type: "const", id: "newyear", month: 1, day: 1, title: "New Year" },
38
- { type: "const", id: "christmas", month: 12, day: 25, title: "Christmas" },
39
- ],
38
+ events: [every("year").on(date(12, 25)).title("Christmas")],
40
39
  });
41
40
 
42
- const events = cal.getEventsInRange("2025-01-01", "2025-12-31");
41
+ const events = cal.getEventsInRange("2026-01-01", "2026-12-31");
43
42
  const ics = toICS(events, { calendarName: "Holidays" });
44
-
45
- // → write `ics` to a .ics file, or serve it from an endpoint
43
+ // → a VCALENDAR string: write to a .ics file or serve it from an endpoint
46
44
  ```
47
45
 
48
- ## API
46
+ One `VEVENT` per occurrence (events come pre-expanded, so no `RRULE`) — lunar / hijri /
47
+ formula dates and per-occurrence `exceptions` & `overrideDates` all export correctly.
48
+ Reminders → `VALARM`, `priority` → `PRIORITY`, plus `DESCRIPTION` / `LOCATION` / `URL` /
49
+ `CATEGORIES` / `COLOR`.
49
50
 
50
- ### `toICS(events, options?) → string`
51
+ ## Reference
51
52
 
52
- Serialize an array of occurrences into a full `VCALENDAR` document.
53
-
54
- ```typescript
55
- interface ICSOptions {
56
- prodId?: string; // PRODID. Default "-//calendaryjs//calendaryjs-plugin-ics//EN"
57
- calendarName?: string; // X-WR-CALNAME — the calendar's display name
58
- method?: string; // METHOD, e.g. "PUBLISH"
59
- dtstamp?: Date; // DTSTAMP for every event. Default: now (pass a fixed Date for stable output)
60
- priorityMap?: (priority: number) => number; // override priority → ICS PRIORITY (return 0 to omit)
61
- }
53
+ ```ts
54
+ toICS(events, options?) → string; // a full VCALENDAR document
62
55
  ```
63
56
 
64
- ### `eventToVEvent(event, options?) → string`
65
-
66
- Serialize a single occurrence to one folded `VEVENT` block (no `VCALENDAR` wrapper).
67
-
68
- Also exported: `veventLines` (unfolded lines), `defaultPriorityMap`, and the low-level `escapeText` / `foldLine` helpers.
69
-
70
- ## Field mapping
71
-
72
- | calendaryjs | ICS |
73
- | ---------------------------------- | ----------------------------------------- |
74
- | `date` + `startTime`/`endTime` | `DTSTART` / `DTEND` (floating local time) |
75
- | `date` (all-day / no time) | `DTSTART;VALUE=DATE` + exclusive `DTEND` |
76
- | `duration` (minutes) | `DURATION` (when `endTime` is absent) |
77
- | `title` | `SUMMARY` |
78
- | `description` / `location` / `url` | `DESCRIPTION` / `LOCATION` / `URL` |
79
- | `categories` / `status` | `CATEGORIES` / `STATUS` |
80
- | `priority` (z-index) | `PRIORITY` (inverted, 1 = highest) |
81
- | `color` / `icon` | `COLOR` / `IMAGE` (RFC 7986) |
82
- | `reminders[]` (minutes before) | `VALARM` with `TRIGGER:-PTnM` |
83
- | `source` / `groupId` / id + `date` | a stable, unique `UID` |
84
-
85
- ### Notes
86
-
87
- - **Timezones.** Timed events export as **floating local time** (no `Z`, no `TZID`) — the core stays timezone-neutral, so occurrences render in the viewer's local zone.
88
- - **Reminder & duration units** are **minutes**.
89
- - **`exceptions` / `overrideDates`** are resolved by the core before export (skipped occurrences are already gone, overrides already applied), so no `EXDATE` / `RECURRENCE-ID` is needed for the per-occurrence form.
90
-
91
- ## Roadmap
92
-
93
- - `RRULE` compaction for Gregorian-expressible recurrences (with `EXDATE` / `RECURRENCE-ID` for exceptions).
94
- - ICS **import** (`.ics` → event configs).
95
-
96
- ## Related Packages
57
+ | Option | Notes |
58
+ | -------------- | ----------------------------------------------------- |
59
+ | `prodId` | `PRODID` |
60
+ | `calendarName` | `X-WR-CALNAME` — the calendar's display name |
61
+ | `method` | `METHOD`, e.g. `"PUBLISH"` |
62
+ | `dtstamp` | fixed `Date` → byte-stable, diff-friendly output |
63
+ | `priorityMap` | override priority → ICS `PRIORITY` (return 0 to omit) |
97
64
 
98
- - [calendaryjs](https://www.npmjs.com/package/calendaryjs) — core engine
99
- - [calendaryjs-plugin-lunar](https://www.npmjs.com/package/calendaryjs-plugin-lunar) — lunar calendar
100
- - [calendaryjs-plugin-liturgical](https://www.npmjs.com/package/calendaryjs-plugin-liturgical) — liturgical calendar
65
+ Also exported: `eventToVEvent(event, options?)` — a single `VEVENT` block (no wrapper).
101
66
 
102
67
  ## License
103
68
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "calendaryjs-plugin-ics",
3
- "version": "0.1.1",
3
+ "version": "0.1.3",
4
4
  "description": "ICS (RFC 5545) export for calendaryjs — serialize generated calendar occurrences to a standard .ics VCALENDAR (VEVENT, VALARM reminders, PRIORITY, CATEGORIES, COLOR/IMAGE). The edge integration: calendaryjs owns the core, ICS rides at the boundary.",
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -39,7 +39,7 @@
39
39
  "devDependencies": {
40
40
  "typescript": "^5.3.2",
41
41
  "vitest": "^4.0.18",
42
- "calendaryjs": "0.2.1"
42
+ "calendaryjs": "0.2.4"
43
43
  },
44
44
  "files": [
45
45
  "dist"