@craftguild/jscalendar 0.1.0 → 0.3.0

package/dist/ical.js

@@ -1,5 +1,14 @@
 import { normalizeUtcDateTime } from "./utils.js";
+const TYPE_EVENT = "Event";
+const TYPE_GROUP = "Group";
+const TYPE_TASK = "Task";
 const DEFAULT_PRODID = "-//craftguild//EN";
+/**
+ * Convert JSCalendar objects into an iCalendar string.
+ * @param objects JSCalendar objects to export.
+ * @param options Export options.
+ * @return iCalendar text.
+ */
 export function toICal(objects, options = {}) {
     const lines = [];
     const includeX = options.includeXJSCalendar !== false;
@@ -10,7 +19,7 @@ export function toICal(objects, options = {}) {
     if (method)
         lines.push(`METHOD:${method.toUpperCase()}`);
     for (const object of objects) {
-        if (object["@type"] === "Group") {
+        if (object["@type"] === TYPE_GROUP) {
             const group = object;
             if (includeX) {
                 lines.push(`X-JSCALENDAR-GROUP:${escapeText(JSON.stringify(stripEntries(group)))}`);
@@ -26,6 +35,11 @@ export function toICal(objects, options = {}) {
     lines.push("END:VCALENDAR");
     return foldLines(lines).join("\r\n");
 }
+/**
+ * Find the first METHOD value from objects.
+ * @param objects JSCalendar objects.
+ * @return METHOD value or undefined.
+ */
 function findMethod(objects) {
     for (const object of objects) {
         if (object.method)
@@ -33,13 +47,25 @@ function findMethod(objects) {
     }
     return undefined;
 }
+/**
+ * Build an iCalendar component from a JSCalendar object.
+ * @param object JSCalendar object.
+ * @param includeX Whether to include X-JSCALENDAR.
+ * @return iCalendar lines for the component.
+ */
 function buildComponent(object, includeX) {
-    if (object["@type"] === "Event")
+    if (object["@type"] === TYPE_EVENT)
         return buildEvent(object, includeX);
-    if (object["@type"] === "Task")
+    if (object["@type"] === TYPE_TASK)
         return buildTask(object, includeX);
     return [];
 }
+/**
+ * Build a VEVENT component.
+ * @param event Event object.
+ * @param includeX Whether to include X-JSCALENDAR.
+ * @return VEVENT lines.
+ */
 function buildEvent(event, includeX) {
     const lines = [];
     lines.push("BEGIN:VEVENT");
@@ -69,6 +95,12 @@ function buildEvent(event, includeX) {
     lines.push("END:VEVENT");
     return lines;
 }
+/**
+ * Build a VTODO component.
+ * @param task Task object.
+ * @param includeX Whether to include X-JSCALENDAR.
+ * @return VTODO lines.
+ */
 function buildTask(task, includeX) {
     const lines = [];
     lines.push("BEGIN:VTODO");
@@ -111,6 +143,12 @@ function buildTask(task, includeX) {
     lines.push("END:VTODO");
     return lines;
 }
+/**
+ * Append RRULE lines for recurrence rules.
+ * @param lines Lines to append to.
+ * @param rules Recurrence rules.
+ * @return Nothing.
+ */
 function appendRecurrence(lines, rules) {
     if (!rules)
         return;
@@ -120,6 +158,11 @@ function appendRecurrence(lines, rules) {
             lines.push(`RRULE:${rrule}`);
     }
 }
+/**
+ * Convert a RecurrenceRule to an RRULE string.
+ * @param rule Recurrence rule.
+ * @return RRULE value or null.
+ */
 function recurrenceRuleToRRule(rule) {
     const parts = [];
     parts.push(`FREQ=${rule.frequency.toUpperCase()}`);
@@ -159,6 +202,11 @@ function recurrenceRuleToRRule(rule) {
         parts.push(`SKIP=${rule.skip.toUpperCase()}`);
     return parts.join(";");
 }
+/**
+ * Format a UTCDateTime for iCalendar.
+ * @param value UTCDateTime string.
+ * @return iCalendar-formatted UTCDateTime.
+ */
 function formatUtcDateTime(value) {
     const normalized = normalizeUtcDateTime(value);
     return normalized
@@ -166,12 +214,22 @@ function formatUtcDateTime(value) {
         .replace(/\.\d+Z$/, "Z")
         .replace(/Z$/, "Z");
 }
+/**
+ * Format a LocalDateTime for iCalendar.
+ * @param value LocalDateTime string.
+ * @return iCalendar-formatted LocalDateTime.
+ */
 function formatLocalDateTime(value) {
     return value
         .replace(/[-:]/g, "")
         .replace(/\.\d+$/, "")
         .replace(/Z$/, "");
 }
+/**
+ * Escape text for iCalendar content lines.
+ * @param value Raw text.
+ * @return Escaped text.
+ */
 function escapeText(value) {
     return value
         .replace(/\\/g, "\\\\")
@@ -179,6 +237,11 @@ function escapeText(value) {
         .replace(/;/g, "\\;")
         .replace(/,/g, "\\,");
 }
+/**
+ * Fold iCalendar lines to 75 octets per RFC.
+ * @param lines Lines to fold.
+ * @return Folded lines.
+ */
 function foldLines(lines) {
     const result = [];
     for (const line of lines) {
@@ -196,6 +259,11 @@ function foldLines(lines) {
     }
     return result;
 }
+/**
+ * Strip group entries for X-JSCALENDAR-GROUP payload.
+ * @param group Group object.
+ * @return Group without entries.
+ */
 function stripEntries(group) {
     const { entries: _entries, ...rest } = group;
     return rest;

package/dist/jscal/base.d.ts

@@ -0,0 +1,90 @@
+import type { Alert, Id, JSCalendarObject, Location, Participant, PatchObject, VirtualLocation } from "../types.js";
+import type { UpdateOptions } from "./types.js";
+export declare class Base<T extends JSCalendarObject> {
+    data: T;
+    /**
+     * Create a new base instance that wraps a JSCalendar object.
+     * @param data Underlying JSCalendar data.
+     * @return Result.
+     */
+    constructor(data: T);
+    /**
+     * Return a deep-cloned plain object for safe serialization.
+     * @return Cloned JSCalendar data.
+     */
+    eject(): T;
+    /**
+     * Clone the current instance with a deep-cloned payload.
+     * @return New instance with cloned data.
+     */
+    clone(): Base<T>;
+    /**
+     * Read a field value from the underlying data.
+     * @param key Field key.
+     * @return Field value.
+     */
+    get<K extends keyof T>(key: K): T[K];
+    /**
+     * Set a field value and update metadata as needed.
+     * @param key Field key.
+     * @param value Field value.
+     * @return Updated instance.
+     */
+    set<K extends keyof T>(key: K, value: T[K]): this;
+    /**
+     * Apply shallow updates and touch updated/sequence metadata.
+     * @param values Partial values to merge.
+     * @param options Update options.
+     * @return Updated instance.
+     */
+    update(values: Partial<T>, options?: UpdateOptions): this;
+    /**
+     * Apply a PatchObject and touch updated/sequence metadata.
+     * @param patch Patch to apply.
+     * @param options Update options.
+     * @return Updated instance.
+     */
+    patch(patch: PatchObject, options?: UpdateOptions): this;
+    /**
+     * Add a physical location and return its generated ID.
+     * @param location Location data (without @type).
+     * @param id Optional location ID.
+     * @return Location ID.
+     */
+    addLocation(location: Omit<Location, "@type"> & Partial<Pick<Location, "@type">>, id?: Id): Id;
+    /**
+     * Add a virtual location and return its generated ID.
+     * @param location Virtual location data (without @type).
+     * @param id Optional virtual location ID.
+     * @return Virtual location ID.
+     */
+    addVirtualLocation(location: Omit<VirtualLocation, "@type"> & Partial<Pick<VirtualLocation, "@type">>, id?: Id): Id;
+    /**
+     * Add a participant and return its generated ID.
+     * @param participant Participant data (without @type).
+     * @param id Optional participant ID.
+     * @return Participant ID.
+     */
+    addParticipant(participant: Omit<Participant, "@type"> & Partial<Pick<Participant, "@type">>, id?: Id): Id;
+    /**
+     * Add an alert and return its generated ID.
+     * @param alert Alert data (without @type).
+     * @param id Optional alert ID.
+     * @return Alert ID.
+     */
+    addAlert(alert: Omit<Alert, "@type"> & Partial<Pick<Alert, "@type">>, id?: Id): Id;
+    /**
+     * Update updated/sequence metadata for modified keys.
+     * @param keys Modified keys.
+     * @param options Update options.
+     * @return Updated instance.
+     */
+    protected touchKeys(keys: string[], options?: UpdateOptions): this;
+    /**
+     * Update updated/sequence metadata for PatchObject changes.
+     * @param patch Patch applied to the object.
+     * @param options Update options.
+     * @return Updated instance.
+     */
+    protected touchFromPatch(patch: PatchObject, options?: UpdateOptions): this;
+}

package/dist/jscal/base.js

@@ -0,0 +1,181 @@
+import { applyPatch } from "../patch.js";
+import { deepClone, isNumberValue, nowUtc } from "../utils.js";
+import { validateJsCalendarObject } from "../validate.js";
+import { KEY_PARTICIPANTS } from "./constants.js";
+import { applyAlertDefaults, applyParticipantDefaults } from "./defaults.js";
+import { createId } from "./ids.js";
+export class Base {
+    data;
+    /**
+     * Create a new base instance that wraps a JSCalendar object.
+     * @param data Underlying JSCalendar data.
+     * @return Result.
+     */
+    constructor(data) {
+        this.data = data;
+    }
+    /**
+     * Return a deep-cloned plain object for safe serialization.
+     * @return Cloned JSCalendar data.
+     */
+    eject() {
+        return deepClone(this.data);
+    }
+    /**
+     * Clone the current instance with a deep-cloned payload.
+     * @return New instance with cloned data.
+     */
+    clone() {
+        return new Base(deepClone(this.data));
+    }
+    /**
+     * Read a field value from the underlying data.
+     * @param key Field key.
+     * @return Field value.
+     */
+    get(key) {
+        return this.data[key];
+    }
+    /**
+     * Set a field value and update metadata as needed.
+     * @param key Field key.
+     * @param value Field value.
+     * @return Updated instance.
+     */
+    set(key, value) {
+        this.data[key] = value;
+        return this.touchKeys([String(key)]);
+    }
+    /**
+     * Apply shallow updates and touch updated/sequence metadata.
+     * @param values Partial values to merge.
+     * @param options Update options.
+     * @return Updated instance.
+     */
+    update(values, options = {}) {
+        const next = { ...this.data, ...values };
+        if (options.validate !== false) {
+            validateJsCalendarObject(next);
+        }
+        this.data = next;
+        return this.touchKeys(Object.keys(values), options);
+    }
+    /**
+     * Apply a PatchObject and touch updated/sequence metadata.
+     * @param patch Patch to apply.
+     * @param options Update options.
+     * @return Updated instance.
+     */
+    patch(patch, options = {}) {
+        const next = applyPatch(this.data, patch);
+        if (options.validate !== false) {
+            validateJsCalendarObject(next);
+        }
+        this.data = next;
+        return this.touchFromPatch(patch, options);
+    }
+    /**
+     * Add a physical location and return its generated ID.
+     * @param location Location data (without @type).
+     * @param id Optional location ID.
+     * @return Location ID.
+     */
+    addLocation(location, id) {
+        const actualId = id ?? createId();
+        if (!this.data.locations)
+            this.data.locations = {};
+        this.data.locations[actualId] = { ...location, "@type": "Location" };
+        this.touchKeys(["locations"]);
+        return actualId;
+    }
+    /**
+     * Add a virtual location and return its generated ID.
+     * @param location Virtual location data (without @type).
+     * @param id Optional virtual location ID.
+     * @return Virtual location ID.
+     */
+    addVirtualLocation(location, id) {
+        const actualId = id ?? createId();
+        if (!this.data.virtualLocations)
+            this.data.virtualLocations = {};
+        const name = location.name ?? "";
+        this.data.virtualLocations[actualId] = { ...location, name, "@type": "VirtualLocation" };
+        this.touchKeys(["virtualLocations"]);
+        return actualId;
+    }
+    /**
+     * Add a participant and return its generated ID.
+     * @param participant Participant data (without @type).
+     * @param id Optional participant ID.
+     * @return Participant ID.
+     */
+    addParticipant(participant, id) {
+        const actualId = id ?? createId();
+        if (!this.data.participants)
+            this.data.participants = {};
+        const filled = applyParticipantDefaults({ ...participant, "@type": "Participant" });
+        this.data.participants[actualId] = filled;
+        this.touchKeys(["participants"], { sequence: false });
+        return actualId;
+    }
+    /**
+     * Add an alert and return its generated ID.
+     * @param alert Alert data (without @type).
+     * @param id Optional alert ID.
+     * @return Alert ID.
+     */
+    addAlert(alert, id) {
+        const actualId = id ?? createId();
+        if (!this.data.alerts)
+            this.data.alerts = {};
+        const filled = applyAlertDefaults({ ...alert, "@type": "Alert" });
+        this.data.alerts[actualId] = filled;
+        this.touchKeys(["alerts"]);
+        return actualId;
+    }
+    /**
+     * Update updated/sequence metadata for modified keys.
+     * @param keys Modified keys.
+     * @param options Update options.
+     * @return Updated instance.
+     */
+    touchKeys(keys, options = {}) {
+        if (options.touch === false)
+            return this;
+        const now = options.now ?? nowUtc;
+        this.data.updated = now();
+        if (options.sequence === false)
+            return this;
+        const onlyParticipants = keys.length > 0 && keys.every((key) => key === KEY_PARTICIPANTS);
+        if (!onlyParticipants) {
+            const current = isNumberValue(this.data.sequence) ? this.data.sequence : 0;
+            this.data.sequence = current + 1;
+        }
+        return this;
+    }
+    /**
+     * Update updated/sequence metadata for PatchObject changes.
+     * @param patch Patch applied to the object.
+     * @param options Update options.
+     * @return Updated instance.
+     */
+    touchFromPatch(patch, options = {}) {
+        if (options.touch === false)
+            return this;
+        const now = options.now ?? nowUtc;
+        this.data.updated = now();
+        if (options.sequence === false)
+            return this;
+        const pointers = Object.keys(patch);
+        const onlyParticipants = pointers.length > 0 &&
+            pointers.every((pointer) => {
+                const normalized = pointer.startsWith("/") ? pointer.slice(1) : pointer;
+                return normalized.startsWith("participants");
+            });
+        if (!onlyParticipants) {
+            const current = isNumberValue(this.data.sequence) ? this.data.sequence : 0;
+            this.data.sequence = current + 1;
+        }
+        return this;
+    }
+}

package/dist/jscal/builders.d.ts

@@ -0,0 +1,135 @@
+import type { Alert, Link, Location, NDay, Participant, RecurrenceRule, Relation, TimeZone, TimeZoneRule, VirtualLocation, Id } from "../types.js";
+declare const TYPE_PARTICIPANT = "Participant";
+declare const TYPE_LOCATION = "Location";
+declare const TYPE_VIRTUAL_LOCATION = "VirtualLocation";
+declare const TYPE_ALERT = "Alert";
+declare const TYPE_RELATION = "Relation";
+declare const TYPE_LINK = "Link";
+declare const TYPE_TIME_ZONE = "TimeZone";
+declare const TYPE_TIME_ZONE_RULE = "TimeZoneRule";
+declare const TYPE_RECURRENCE_RULE = "RecurrenceRule";
+declare const TYPE_NDAY = "NDay";
+type WithOptionalType<T, TypeName extends string> = Omit<T, "@type"> & {
+    "@type"?: TypeName;
+};
+export type ParticipantInput = WithOptionalType<Participant, typeof TYPE_PARTICIPANT>;
+export type LocationInput = WithOptionalType<Location, typeof TYPE_LOCATION>;
+export type VirtualLocationInput = WithOptionalType<VirtualLocation, typeof TYPE_VIRTUAL_LOCATION>;
+export type AlertInput = WithOptionalType<Alert, typeof TYPE_ALERT>;
+export type RelationInput = WithOptionalType<Relation, typeof TYPE_RELATION>;
+export type LinkInput = WithOptionalType<Link, typeof TYPE_LINK>;
+export type TimeZoneInput = WithOptionalType<TimeZone, typeof TYPE_TIME_ZONE>;
+export type TimeZoneRuleInput = WithOptionalType<TimeZoneRule, typeof TYPE_TIME_ZONE_RULE>;
+export type RecurrenceRuleInput = WithOptionalType<RecurrenceRule, typeof TYPE_RECURRENCE_RULE>;
+export type NDayInput = WithOptionalType<NDay, typeof TYPE_NDAY>;
+/**
+ * Build a Participant object with @type set and validated.
+ * @param input Participant fields without @type.
+ * @return Validated Participant object.
+ */
+export declare function buildParticipant(input: ParticipantInput): Participant;
+/**
+ * Build a Location object with @type set and validated.
+ * @param input Location fields without @type.
+ * @return Validated Location object.
+ */
+export declare function buildLocation(input: LocationInput): Location;
+/**
+ * Build a VirtualLocation object with @type set and validated.
+ * @param input VirtualLocation fields without @type.
+ * @return Validated VirtualLocation object.
+ */
+export declare function buildVirtualLocation(input: VirtualLocationInput): VirtualLocation;
+/**
+ * Build an Alert object with @type set and validated.
+ * @param input Alert fields without @type.
+ * @return Validated Alert object.
+ */
+export declare function buildAlert(input: AlertInput): Alert;
+/**
+ * Build a Relation object with @type set and validated.
+ * @param input Relation fields without @type.
+ * @return Validated Relation object.
+ */
+export declare function buildRelation(input: RelationInput): Relation;
+/**
+ * Build a Link object with @type set and validated.
+ * @param input Link fields without @type.
+ * @return Validated Link object.
+ */
+export declare function buildLink(input: LinkInput): Link;
+/**
+ * Build a TimeZone object with @type set and validated.
+ * @param input TimeZone fields without @type.
+ * @return Validated TimeZone object.
+ */
+export declare function buildTimeZone(input: TimeZoneInput): TimeZone;
+/**
+ * Build a TimeZoneRule object with @type set and validated.
+ * @param input TimeZoneRule fields without @type.
+ * @return Validated TimeZoneRule object.
+ */
+export declare function buildTimeZoneRule(input: TimeZoneRuleInput): TimeZoneRule;
+/**
+ * Build a RecurrenceRule object with @type set and validated.
+ * @param input RecurrenceRule fields without @type.
+ * @return Validated RecurrenceRule object.
+ */
+export declare function buildRecurrenceRule(input: RecurrenceRuleInput): RecurrenceRule;
+/**
+ * Build an NDay object with @type set and validated.
+ * @param input NDay fields without @type.
+ * @return Validated NDay object.
+ */
+export declare function buildNDay(input: NDayInput): NDay;
+/**
+ * Build a record keyed by generated Ids.
+ * @param items Items to store.
+ * @param builder Builder function to validate each item.
+ * @param idFn Optional ID generator.
+ * @return Record keyed by generated Ids.
+ */
+export declare function buildIdMap<TInput, TOutput>(items: TInput[], builder: (input: TInput) => TOutput, idFn?: (input: TInput, index: number) => Id): Record<Id, TOutput>;
+/**
+ * Build a record of Participant objects keyed by generated Ids.
+ * @param items Participant inputs.
+ * @return Participant record keyed by Id.
+ */
+export declare function buildParticipants(items: ParticipantInput[]): Record<Id, Participant>;
+/**
+ * Build a record of Location objects keyed by generated Ids.
+ * @param items Location inputs.
+ * @return Location record keyed by Id.
+ */
+export declare function buildLocations(items: LocationInput[]): Record<Id, Location>;
+/**
+ * Build a record of VirtualLocation objects keyed by generated Ids.
+ * @param items VirtualLocation inputs.
+ * @return VirtualLocation record keyed by Id.
+ */
+export declare function buildVirtualLocations(items: VirtualLocationInput[]): Record<Id, VirtualLocation>;
+/**
+ * Build a record of Alert objects keyed by generated Ids.
+ * @param items Alert inputs.
+ * @return Alert record keyed by Id.
+ */
+export declare function buildAlerts(items: AlertInput[]): Record<Id, Alert>;
+/**
+ * Build a record of Link objects keyed by generated Ids.
+ * @param items Link inputs.
+ * @return Link record keyed by Id.
+ */
+export declare function buildLinks(items: LinkInput[]): Record<Id, Link>;
+/**
+ * Build a record of Relation objects keyed by generated Ids.
+ * @param items Relation inputs.
+ * @return Relation record keyed by Id.
+ */
+export declare function buildRelatedTo(items: RelationInput[]): Record<Id, Relation>;
+/**
+ * Build a record of TimeZone objects keyed by tzId.
+ * @param items TimeZone inputs.
+ * @return TimeZone record keyed by tzId.
+ */
+export declare function buildTimeZoneMap(items: TimeZoneInput[]): Record<string, TimeZone>;
+export {};