@procedures/ics 0.3.0 → 0.4.0

package/dist/write.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.js","sourceRoot":"","sources":["../src/write.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,14 +1,15 @@
 {
   "$schema": "https://json.schemastore.org/package",
   "name": "@procedures/ics",
-  "version": "0.3.0",
-  "description": "An iCalendar (RFC 5545) reader without dependencies: the events of a calendar and their occurrences in a time window, recurrences included.",
+  "version": "0.4.0",
+  "description": "An iCalendar (RFC 5545) reader and writer without dependencies: the events of a calendar, their occurrences in a time window with the recurrences, and a calendar from events.",
   "keywords": [
     "ics",
     "icalendar",
     "calendar",
     "rrule",
     "recurrence",
+    "writer",
     "procedures"
   ],
   "homepage": "https://mark1russell7.github.io/client/",
@@ -58,7 +59,7 @@
     "provenance": true
   },
   "dependencies": {
-    "@procedures/client": "0.3.0",
+    "@procedures/client": "0.4.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/src/ics.ts

@@ -66,15 +66,10 @@ const unfold = (text: string): string[] =>
 
 /**
  * This function decodes an RFC 5545 TEXT value. Exporters write both `\n` and `\N` for a new
- * line.
+ * line. It reads each escape one time from left to right, so `\\n` is a backslash and an `n`.
  */
 export const unescapeText = (value: string): string =>
-  value
-    .replaceAll("\\n", "\n")
-    .replaceAll("\\N", "\n")
-    .replaceAll("\\,", ",")
-    .replaceAll("\\;", ";")
-    .replaceAll("\\\\", "\\");
+  value.replace(/\\([\\;,nN])/g, (_escape: string, char: string) => (char === "n" || char === "N" ? "\n" : char));
 
 const parseProp = (line: string): IcsProp | undefined => {
   const colon = line.indexOf(":");
@@ -222,7 +217,9 @@ export const parseIcs = (text: string): IcsEvent[] => {
 };
 
 const eventOf = (props: ReadonlyMap<string, IcsProp>, exdates: readonly string[]): IcsEvent | undefined => {
-  const uid = props.get("UID")?.value;
+  // UID is a TEXT value (RFC 5545 3.8.4.7), so it can have escapes
+  const uidValue = props.get("UID")?.value;
+  const uid = uidValue === undefined ? undefined : unescapeText(uidValue);
   const startProp = props.get("DTSTART");
   const start = startProp === undefined ? undefined : parseIcsDate(startProp);
   if (uid === undefined || start === undefined || props.get("STATUS")?.value === "CANCELLED") return undefined;

package/src/index.ts

@@ -2,3 +2,5 @@
 export * from "./module.js";
 export * from "./procedures.js";
 export * from "./ics.js";
+export * from "./write.js";
+export * from "./types.js";

package/src/procedures/ics/index.ts

@@ -0,0 +1 @@
+export { icsWrite } from "./write.js";

package/src/procedures/ics/write.ts

@@ -0,0 +1,16 @@
+/**
+ * ics.write procedure
+ *
+ * Write an iCalendar text from events
+ */
+
+import type { IcsWriteInput, IcsWriteOutput } from "../../types.js";
+import { writeIcs } from "../../write.js";
+
+/**
+ * This function writes the iCalendar text of the events. It changes nothing.
+ */
+export async function icsWrite(input: IcsWriteInput): Promise<IcsWriteOutput> {
+  const { events, ...options } = input;
+  return { text: writeIcs(events, options) };
+}

package/src/procedures.ts

@@ -1,10 +1,12 @@
 /**
- * The procedures of `@procedures/ics`: `ics.parse`, `ics.occurrences` and `ics.fetch`.
+ * The procedures of `@procedures/ics`: `ics.parse`, `ics.occurrences`, `ics.write` and `ics.fetch`.
  */
 
 import { createProcedure, zodAdapter, type AnyProcedure, type ProcedureContext } from "@procedures/client";
 import { z } from "zod";
 import { calendarOccurrences, isCalendar, parseIcs, type IcsEvent, type Occurrence } from "./ics.js";
+import { icsWrite } from "./procedures/ics/write.js";
+import { IcsWriteInputSchema, IcsWriteOutputSchema, type IcsWriteInput, type IcsWriteOutput } from "./types.js";
 
 const PURE = { reads: [], writes: [] };
 
@@ -90,6 +92,22 @@ export const icsOccurrencesProcedure: AnyProcedure = createProcedure()
   )
   .build() as AnyProcedure;
 
+// =============================================================================
+// ics.write
+// =============================================================================
+
+export const icsWriteProcedure: AnyProcedure = createProcedure()
+  .path(["ics", "write"])
+  .input(zodAdapter<IcsWriteInput>(IcsWriteInputSchema))
+  .output(zodAdapter<IcsWriteOutput>(IcsWriteOutputSchema))
+  .meta({
+    description: "Write an iCalendar text from events: escaped text, folded lines and CRLF line ends",
+    output: "json",
+    effects: PURE,
+  })
+  .handler(async (input: IcsWriteInput): Promise<IcsWriteOutput> => icsWrite(input))
+  .build() as AnyProcedure;
+
 // =============================================================================
 // ics.fetch
 // =============================================================================
@@ -136,4 +154,4 @@ export const icsFetchProcedure: AnyProcedure = createProcedure()
   })
   .build() as AnyProcedure;
 
-export const icsProcedures: AnyProcedure[] = [icsParseProcedure, icsOccurrencesProcedure, icsFetchProcedure];
+export const icsProcedures: AnyProcedure[] = [icsParseProcedure, icsOccurrencesProcedure, icsWriteProcedure, icsFetchProcedure];

package/src/types.ts

@@ -0,0 +1,76 @@
+/**
+ * Type definitions of the procedures of this package
+ */
+
+import { z } from "zod";
+import type { IcsStatus } from "./write.js";
+
+// =============================================================================
+// ics.write Types - Write an iCalendar text from events
+// =============================================================================
+
+/** The input of `ics.write`: the events and the properties of the calendar. */
+export interface IcsWriteInput {
+  events: Array<{
+    uid: string;
+    start: string;
+    end?: string | undefined;
+    allDay?: boolean | undefined;
+    summary?: string | undefined;
+    location?: string | undefined;
+    description?: string | undefined;
+    url?: string | undefined;
+    sequence?: number | undefined;
+    status?: IcsStatus | undefined;
+    rrule?: string | undefined;
+    exdates?: string[] | undefined;
+  }>;
+  prodId?: string | undefined;
+  method?: string | undefined;
+  calscale?: string | undefined;
+  calendarName?: string | undefined;
+  stamp?: string | undefined;
+}
+
+/** The output of `ics.write`: the iCalendar text, which `ics.parse` reads. */
+export interface IcsWriteOutput {
+  text: string;
+}
+
+const isoTime = z.string().refine((value) => !Number.isNaN(Date.parse(value)), "Write an ISO 8601 time");
+const token = z.string().regex(/^[A-Za-z0-9-]+$/, "Write a token: letters, digits and -");
+
+const IcsWriteEventSchema = z.object({
+  uid: z.string().min(1).describe("The UID. Keep it stable across exports"),
+  start: isoTime.describe("The start (ISO 8601). For an all-day event, the date part is the date"),
+  end: isoTime.optional().describe("The end (ISO 8601). For an all-day event, the end date is exclusive"),
+  allDay: z.boolean().optional().describe("True for an all-day event (VALUE=DATE)"),
+  summary: z.string().optional().describe("The title"),
+  location: z.string().optional().describe("The place"),
+  description: z.string().optional().describe("The notes"),
+  url: z.url().optional().describe("A link"),
+  sequence: z.number().int().min(0).optional().describe("The SEQUENCE: it increases at each change of the event"),
+  status: z.enum(["TENTATIVE", "CONFIRMED", "CANCELLED"]).optional().describe("The STATUS. CANCELLED removes the event at the next import"),
+  rrule: z
+    .string()
+    .regex(/^[A-Za-z0-9=;,+-]+$/, "Write a recurrence rule, for example FREQ=WEEKLY;COUNT=4")
+    .optional()
+    .describe("The recurrence rule without RRULE:, for example FREQ=YEARLY"),
+  exdates: z
+    .array(z.string().regex(/^\d{4}-\d{2}-\d{2}$/, "Write a date (YYYY-MM-DD)"))
+    .optional()
+    .describe("The dates (YYYY-MM-DD) that the recurrence skips"),
+});
+
+export const IcsWriteInputSchema: z.ZodType<IcsWriteInput> = z.object({
+  events: z.array(IcsWriteEventSchema).describe("The events (VEVENT) of the calendar"),
+  prodId: z.string().min(1).optional().describe("The PRODID (default: -//procedures//ics//EN)"),
+  method: token.optional().describe("The METHOD, for example PUBLISH or CANCEL"),
+  calscale: token.optional().describe("The CALSCALE, for example GREGORIAN"),
+  calendarName: z.string().optional().describe("The name of the calendar (X-WR-CALNAME)"),
+  stamp: isoTime.optional().describe("The DTSTAMP of each event (ISO 8601). The default is the current time"),
+});
+
+export const IcsWriteOutputSchema: z.ZodType<IcsWriteOutput> = z.object({
+  text: z.string().describe("The iCalendar text, with CRLF line ends and folded lines"),
+});

package/src/write.ts

@@ -0,0 +1,194 @@
+/**
+ * An iCalendar (RFC 5545) writer: a VCALENDAR text from a list of events. It has no dependencies.
+ * The reader of this package (`parseIcs`) reads the text back to the same events.
+ *
+ * The writer obeys these rules of RFC 5545:
+ *
+ * - It escapes the backslash, the semicolon, the comma and the line break of a TEXT value (3.3.11).
+ * - It folds each content line at 75 octets of UTF-8, with CRLF and one space (3.1). A fold does
+ *   not divide a character of more than one octet.
+ * - Each line ends with CRLF.
+ */
+
+/** The STATUS of an event (RFC 5545 3.8.1.11). */
+export type IcsStatus = "TENTATIVE" | "CONFIRMED" | "CANCELLED";
+
+/** One event (one VEVENT) for `writeIcs`. An `IcsEvent` of `parseIcs` is also a correct value. */
+export interface IcsWriteEvent {
+  /** The UID. It identifies the event across exports, so keep it stable. */
+  readonly uid: string;
+  /**
+   * The start, as an ISO 8601 time. The writer writes it in UTC. For an all-day event, the writer
+   * uses the date part (`YYYY-MM-DD`) of the text, without a change of zone.
+   */
+  readonly start: string;
+  /** The end. Without it, the event has no DTEND. For an all-day event, the end date is exclusive. */
+  readonly end?: string | undefined;
+  /** True for an all-day event: DTSTART and DTEND get `VALUE=DATE`. */
+  readonly allDay?: boolean | undefined;
+  readonly summary?: string | undefined;
+  readonly location?: string | undefined;
+  readonly description?: string | undefined;
+  /** An absolute URL. The writer refuses a URL with a space or a control character. */
+  readonly url?: string | undefined;
+  /** The SEQUENCE: a number that increases at each change of the event. */
+  readonly sequence?: number | undefined;
+  /** The STATUS. A calendar removes an event with `CANCELLED` at the next import. */
+  readonly status?: IcsStatus | undefined;
+  /** The recurrence rule (`RRULE`) without the property name, for example `FREQ=WEEKLY;COUNT=4`. */
+  readonly rrule?: string | undefined;
+  /** The dates (`YYYY-MM-DD`) that the recurrence skips (`EXDATE`). */
+  readonly exdates?: readonly string[] | undefined;
+}
+
+/** The properties of the calendar (VCALENDAR). The writer always writes `VERSION:2.0`. */
+export interface IcsCalendarOptions {
+  /** The PRODID: the product that made the calendar. The default is `-//procedures//ics//EN`. */
+  readonly prodId?: string | undefined;
+  /** The METHOD, for example `PUBLISH` or `CANCEL`. Without it, the calendar has no METHOD. */
+  readonly method?: string | undefined;
+  /** The CALSCALE, for example `GREGORIAN`. Without it, the calendar has no CALSCALE. */
+  readonly calscale?: string | undefined;
+  /** The name of the calendar (`X-WR-CALNAME`). */
+  readonly calendarName?: string | undefined;
+  /** The DTSTAMP of each event, as an ISO 8601 time. The default is the current time. */
+  readonly stamp?: string | undefined;
+}
+
+/** The PRODID when the caller gives none. */
+export const DEFAULT_PRODID = "-//procedures//ics//EN";
+
+/** The maximum length of a content line, in octets, without the CRLF (RFC 5545 3.1). */
+export const MAX_LINE_OCTETS = 75;
+
+const STATUSES: ReadonlySet<string> = new Set(["TENTATIVE", "CONFIRMED", "CANCELLED"]);
+const TOKEN = /^[A-Za-z0-9-]+$/;
+const RRULE = /^[A-Za-z0-9=;,+-]+$/;
+// A URI has no space and no control character (RFC 3986)
+const UNSAFE_URI = /[\u0000- \u007f]/;
+
+/**
+ * This function encodes a TEXT value (RFC 5545 3.3.11). It escapes `\`, `;`, `,` and each line
+ * break (CRLF, CR or LF) as `\n`. It removes the other control characters, but not the tab.
+ */
+export const escapeText = (value: string): string =>
+  value
+    .replace(/\\/g, "\\\\")
+    .replace(/;/g, "\\;")
+    .replace(/,/g, "\\,")
+    .replace(/\r\n|\r|\n/g, "\\n")
+    .replace(/[\u0000-\u0008\u000b-\u001f\u007f]/g, "");
+
+/** The number of UTF-8 octets of one code point. A lone surrogate becomes U+FFFD (3 octets). */
+const octets = (char: string): number => {
+  const code = char.codePointAt(0) ?? 0;
+  if (code < 0x80) return 1;
+  if (code < 0x800) return 2;
+  if (code < 0x10000) return 3;
+  return 4;
+};
+
+/**
+ * This function folds one content line (RFC 5545 3.1). Each part has 75 octets of UTF-8 or
+ * fewer, and the parts join with CRLF and one space. The space counts in the 75 octets of its
+ * line. A fold does not divide a character.
+ */
+export const foldLine = (line: string): string => {
+  const parts: string[] = [];
+  let part = "";
+  let size = 0;
+  let limit = MAX_LINE_OCTETS;
+  for (const char of line) {
+    const length = octets(char);
+    if (size + length > limit) {
+      parts.push(part);
+      part = "";
+      size = 0;
+      // The space at the start of a continuation line is one of its 75 octets
+      limit = MAX_LINE_OCTETS - 1;
+    }
+    part += char;
+    size += length;
+  }
+  parts.push(part);
+  return parts.join("\r\n ");
+};
+
+/** This function gives a time in the UTC form of RFC 5545: `20261016T143000Z`. */
+export const formatUtc = (iso: string): string => {
+  const ms = Date.parse(iso);
+  if (Number.isNaN(ms)) throw new RangeError(`"${iso}" is not an ISO 8601 time`);
+  const text = new Date(ms).toISOString();
+  if (!/^\d{4}-/.test(text)) throw new RangeError(`"${iso}" is not in the years 0000 to 9999`);
+  // RFC 5545 has no fractions of a second
+  return text.replace(/[-:]/g, "").replace(/\.\d{3}Z$/, "Z");
+};
+
+/** This function gives the date part of a text (`YYYY-MM-DD...`) in the form of RFC 5545: `20261016`. */
+export const formatDate = (value: string): string => {
+  const m = /^(\d{4})-(\d{2})-(\d{2})/.exec(value);
+  const date = m === null ? undefined : new Date(`${m[1]}-${m[2]}-${m[3]}T00:00:00Z`);
+  if (m === null || date === undefined || Number.isNaN(date.getTime()) || date.toISOString().slice(0, 10) !== m[0]) {
+    throw new RangeError(`"${value}" does not start with a date (YYYY-MM-DD)`);
+  }
+  return `${m[1]}${m[2]}${m[3]}`;
+};
+
+const token = (name: string, value: string): string => {
+  if (!TOKEN.test(value)) throw new RangeError(`${name} "${value}" is not a token (letters, digits and "-")`);
+  return value.toUpperCase();
+};
+
+/** The lines of one VEVENT, before the fold. */
+const eventLines = (event: IcsWriteEvent, stamp: string): string[] => {
+  if (event.uid.length === 0) throw new RangeError("An event has no UID");
+  const allDay = event.allDay === true;
+  const time = (value: string): string => (allDay ? `;VALUE=DATE:${formatDate(value)}` : `:${formatUtc(value)}`);
+  const text = (name: string, value: string | undefined): string[] =>
+    value === undefined || value.length === 0 ? [] : [`${name}:${escapeText(value)}`];
+  const lines = ["BEGIN:VEVENT", `UID:${escapeText(event.uid)}`, `DTSTAMP:${stamp}`, `DTSTART${time(event.start)}`];
+  if (event.end !== undefined) lines.push(`DTEND${time(event.end)}`);
+  lines.push(...text("SUMMARY", event.summary));
+  if (event.rrule !== undefined) {
+    if (!RRULE.test(event.rrule)) throw new RangeError(`The RRULE of ${event.uid} has a character that a recurrence rule does not use`);
+    lines.push(`RRULE:${event.rrule}`);
+  }
+  if (event.exdates !== undefined && event.exdates.length > 0) {
+    // EXDATE has the value type of DTSTART: a date, or the start time of the skipped occurrence
+    const startTime = allDay ? "" : formatUtc(event.start).slice(8);
+    const values = event.exdates.map((date) => `${formatDate(date)}${startTime}`);
+    lines.push(allDay ? `EXDATE;VALUE=DATE:${values.join(",")}` : `EXDATE:${values.join(",")}`);
+  }
+  lines.push(...text("LOCATION", event.location), ...text("DESCRIPTION", event.description));
+  if (event.url !== undefined) {
+    if (event.url.length === 0 || UNSAFE_URI.test(event.url)) throw new RangeError(`The URL of ${event.uid} has a space or a control character`);
+    lines.push(`URL:${event.url}`);
+  }
+  if (event.status !== undefined) {
+    if (!STATUSES.has(event.status)) throw new RangeError(`The STATUS of ${event.uid} is not TENTATIVE, CONFIRMED or CANCELLED`);
+    lines.push(`STATUS:${event.status}`);
+  }
+  if (event.sequence !== undefined) {
+    if (!Number.isSafeInteger(event.sequence) || event.sequence < 0) {
+      throw new RangeError(`The SEQUENCE of ${event.uid} is not an integer of 0 or more`);
+    }
+    lines.push(`SEQUENCE:${event.sequence}`);
+  }
+  lines.push("END:VEVENT");
+  return lines;
+};
+
+/**
+ * This function writes a calendar (RFC 5545) from events. Each line ends with CRLF, and each
+ * long line is folded. It throws a `RangeError` for a value that the format cannot hold.
+ */
+export const writeIcs = (events: readonly IcsWriteEvent[], options: IcsCalendarOptions = {}): string => {
+  const stamp = formatUtc(options.stamp ?? new Date().toISOString());
+  const lines = ["BEGIN:VCALENDAR", "VERSION:2.0", `PRODID:${escapeText(options.prodId ?? DEFAULT_PRODID)}`];
+  if (options.calscale !== undefined) lines.push(`CALSCALE:${token("CALSCALE", options.calscale)}`);
+  if (options.method !== undefined) lines.push(`METHOD:${token("METHOD", options.method)}`);
+  if (options.calendarName !== undefined) lines.push(`X-WR-CALNAME:${escapeText(options.calendarName)}`);
+  for (const event of events) lines.push(...eventLines(event, stamp));
+  lines.push("END:VCALENDAR");
+  return `${lines.map(foldLine).join("\r\n")}\r\n`;
+};