@procedures/ics 0.2.3 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,73 @@
+# @procedures/ics
+
+## 0.4.0
+
+### Minor Changes
+
+- 0f1d06e: New iCalendar writer. The function `writeIcs(events, options)` and the pure procedure `ics.write` write a calendar from events. The reader `parseIcs` reads the text back to the same events.
+  
+  - The writer writes `UID`, `DTSTAMP`, `DTSTART`, `DTEND`, `SUMMARY`, `LOCATION`, `DESCRIPTION`, `URL`, `RRULE`, `EXDATE`, `STATUS` and `SEQUENCE`. Each time is in UTC. An all-day event gets `VALUE=DATE`.
+  - The options set `PRODID`, `METHOD`, `CALSCALE`, `X-WR-CALNAME` and the `DTSTAMP`. `VERSION` is always `2.0`.
+  - The writer escapes `\`, `;`, `,` and each line break in a text value. It folds each line at 75 octets of UTF-8 and does not divide a character. Each line ends with CRLF.
+  - The package also exports `escapeText`, `foldLine`, `formatUtc` and `formatDate`.
+  
+  Two corrections of the reader:
+  
+  - `unescapeText` reads each escape one time from left to right. Before, an escaped backslash before an `n` (`C:\\new`) became a line break.
+  - The reader decodes the escapes of a `UID`, because a `UID` is a TEXT value.
+
+### Patch Changes
+
+- Updated dependencies [d919678]
+- Updated dependencies [057d69a]
+- Updated dependencies [b2a1a1e]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [057d69a]
+- Updated dependencies [afd6a19]
+- Updated dependencies [057d69a]
+- Updated dependencies [4e751da]
+  - @procedures/client@0.4.0
+
+## 0.3.0
+
+### Minor Changes
+
+- 5e2ba76: New package: `ics.parse`, `ics.occurrences` and `ics.fetch` read an iCalendar calendar and give the occurrences of its events in a time window, recurrences included.
+
+### Patch Changes
+
+- Updated dependencies [ddea529]
+- Updated dependencies [b2a3e3a]
+- Updated dependencies [a8c47f1]
+- Updated dependencies [381ce3a]
+- Updated dependencies [0c627f8]
+- Updated dependencies [ae7f05f]
+- Updated dependencies [7873940]
+- Updated dependencies [a70d445]
+- Updated dependencies [bc70357]
+- Updated dependencies [07cc998]
+- Updated dependencies [a6b01a9]
+- Updated dependencies [c799cdd]
+- Updated dependencies [540f8d9]
+- Updated dependencies [b6daaec]
+- Updated dependencies [5b9264e]
+- Updated dependencies [956e88b]
+- Updated dependencies [ff62281]
+- Updated dependencies [d81d0ed]
+- Updated dependencies [aa67cc7]
+- Updated dependencies [061fa22]
+- Updated dependencies [cfb9d69]
+- Updated dependencies [43f7de5]
+- Updated dependencies [b07bb50]
+- Updated dependencies [4a3bfa1]
+- Updated dependencies [bd0b626]
+- Updated dependencies [a6be873]
+- Updated dependencies [fb30718]
+- Updated dependencies [c5528e4]
+- Updated dependencies [fee5d9c]
+- Updated dependencies [21f7743]
+- Updated dependencies [31a0b46]
+  - @procedures/client@0.3.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm](https://img.shields.io/npm/v/@procedures/ics?color=2346c4&label=npm)](https://www.npmjs.com/package/@procedures/ics)
 
-An iCalendar (RFC 5545) reader without dependencies. It gives the events of a calendar and the occurrences of each event in a time window, with the recurrence rules.
+An iCalendar (RFC 5545) reader and writer without dependencies. The reader gives the events of a calendar and the occurrences of each event in a time window, with the recurrence rules. The writer makes a calendar from events.
 
 ## Install
 
@@ -18,6 +18,7 @@ A host registers the procedures with `createRegistry(icsModule)`, or with `impor
 | --- | --- | --- |
 | `ics.parse` | none | Reads the events of an iCalendar text. |
 | `ics.occurrences` | none | Gives the occurrences of the events in a time window. An edited instance replaces its occurrence. |
+| `ics.write` | none | Writes an iCalendar text from events. `ics.parse` reads the text back to the same events. |
 | `ics.fetch` | reads `network` | Gets a calendar feed and reads its events. No error repeats the feed address. |
 
 ## Example
@@ -30,6 +31,33 @@ const { occurrences } = await client.exec(["ics", "occurrences"], {
 });
 ```
 
+## Write a calendar
+
+The function `writeIcs(events, options)` and the procedure `ics.write` make the same text:
+
+```ts
+import { writeIcs } from "@procedures/ics";
+
+const text = writeIcs(
+  [
+    { uid: "dinner-1@example.org", summary: "Dinner", start: "2026-11-01T23:00:00Z", end: "2026-11-02T01:00:00Z", sequence: 4 },
+    { uid: "trip@example.org", summary: "Trip", start: "2026-12-24", end: "2026-12-27", allDay: true },
+    { uid: "old-time@example.org", start: "2026-11-01T22:00:00Z", status: "CANCELLED", sequence: 4 },
+  ],
+  { prodId: "-//Example//Plans//EN", method: "PUBLISH", calendarName: "Plans" }
+);
+```
+
+- An event has `uid` and `start`. The other fields are optional: `end`, `allDay`, `summary`, `location`, `description`, `url`, `sequence`, `status`, `rrule` and `exdates`.
+- The writer writes each time in UTC (`20261101T230000Z`). An all-day event gets `VALUE=DATE`, and its end date is exclusive.
+- The writer escapes `\`, `;`, `,` and each line break in a text value. It removes the other control characters.
+- The writer folds each line at 75 octets of UTF-8. A fold does not divide a character. Each line ends with CRLF.
+- The options set the calendar properties: `prodId`, `method`, `calscale` and `calendarName` (`X-WR-CALNAME`). `VERSION` is always `2.0`.
+- `stamp` sets the `DTSTAMP` of each event. The default is the current time.
+- The writer throws a `RangeError` for a value that the format cannot hold. Examples are a time that is not ISO 8601 and a line break in `rrule`.
+- The caller keeps `sequence` and `status`. To remove an event from a calendar, write its `uid` with `status: "CANCELLED"` and a higher `sequence`.
+- The reader skips an event with `STATUS:CANCELLED`, and it does not read `DESCRIPTION`, `URL` or `STATUS`. The writer writes no `TZID` and no `RECURRENCE-ID`.
+
 ## Recurrences
 
 `ics.occurrences` knows `FREQ` `DAILY`, `WEEKLY` (with `BYDAY`), `MONTHLY` and `YEARLY`, with `INTERVAL`, `COUNT`, `UNTIL` and `EXDATE`. An event with a `TZID` keeps its local time across a change of daylight saving time. A month without the day of a monthly event (a 31st in April) has no occurrence. An all-day event starts at noon UTC of its date, so each time zone reads the same date.