@craftguild/jscalendar 0.2.0 → 0.3.0

package/dist/jscal.js

@@ -1,453 +1,17 @@
-import { applyPatch } from "./patch.js";
-import { deepClone, normalizeUtcDateTime, nowUtc } from "./utils.js";
 import { toICal } from "./ical.js";
 import { expandRecurrence, expandRecurrencePaged } from "./recurrence.js";
-import { validateJsCalendarObject } from "./validate.js";
-import { filterByDateRange, filterByText, filterByType, findByUid, groupByType, } from "./search.js";
+import { filterByDateRange, filterByText, filterByType, findByUid, groupByType } from "./search.js";
 import { resolveTimeZone, TimeZones } from "./timezones.js";
-function getCrypto() {
-    const cryptoObj = globalThis.crypto;
-    if (cryptoObj && typeof cryptoObj.getRandomValues === "function") {
-        return cryptoObj;
-    }
-    return undefined;
-}
-function getRandomBytes(length) {
-    const bytes = new Uint8Array(length);
-    const cryptoObj = getCrypto();
-    if (cryptoObj) {
-        cryptoObj.getRandomValues(bytes);
-        return bytes;
-    }
-    for (let i = 0; i < length; i += 1) {
-        bytes[i] = Math.floor(Math.random() * 256);
-    }
-    return bytes;
-}
-function base64UrlEncode(bytes) {
-    const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
-    let output = "";
-    for (let i = 0; i < bytes.length; i += 3) {
-        const b0 = bytes[i] ?? 0;
-        const b1 = bytes[i + 1] ?? 0;
-        const b2 = bytes[i + 2] ?? 0;
-        const triplet = ((b0 ?? 0) << 16) | ((b1 ?? 0) << 8) | (b2 ?? 0);
-        output += alphabet[(triplet >> 18) & 0x3f] ?? "";
-        output += alphabet[(triplet >> 12) & 0x3f] ?? "";
-        output += i + 1 < bytes.length ? alphabet[(triplet >> 6) & 0x3f] ?? "" : "=";
-        output += i + 2 < bytes.length ? alphabet[triplet & 0x3f] ?? "" : "=";
-    }
-    return output.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-export function createUid() {
-    const cryptoObj = getCrypto();
-    if (cryptoObj?.randomUUID) {
-        return cryptoObj.randomUUID();
-    }
-    const bytes = getRandomBytes(16);
-    if (bytes.length > 6) {
-        const b6 = bytes[6] ?? 0;
-        bytes[6] = (b6 & 0x0f) | 0x40;
-    }
-    if (bytes.length > 8) {
-        const b8 = bytes[8] ?? 0;
-        bytes[8] = (b8 & 0x3f) | 0x80;
-    }
-    const hex = Array.from(bytes).map((b) => b.toString(16).padStart(2, "0")).join("");
-    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
-}
-export function createId() {
-    return base64UrlEncode(getRandomBytes(16));
-}
-function pad2(value) {
-    return value.toString().padStart(2, "0");
-}
-function toLocalDateTime(value) {
-    if (typeof value === "string")
-        return value;
-    return [
-        value.getFullYear().toString().padStart(4, "0"),
-        "-",
-        pad2(value.getMonth() + 1),
-        "-",
-        pad2(value.getDate()),
-        "T",
-        pad2(value.getHours()),
-        ":",
-        pad2(value.getMinutes()),
-        ":",
-        pad2(value.getSeconds()),
-    ].join("");
-}
-function toUtcDateTime(value) {
-    if (typeof value === "string")
-        return value;
-    return normalizeUtcDateTime(value.toISOString());
-}
-function durationFromSeconds(totalSeconds) {
-    const clamped = Math.max(0, Math.floor(totalSeconds));
-    const days = Math.floor(clamped / 86400);
-    let remaining = clamped % 86400;
-    const hours = Math.floor(remaining / 3600);
-    remaining %= 3600;
-    const minutes = Math.floor(remaining / 60);
-    const seconds = remaining % 60;
-    const datePart = days > 0 ? `${days}D` : "";
-    const timeParts = [];
-    if (hours > 0)
-        timeParts.push(`${hours}H`);
-    if (minutes > 0)
-        timeParts.push(`${minutes}M`);
-    if (seconds > 0 || (datePart === "" && timeParts.length === 0)) {
-        timeParts.push(`${seconds}S`);
-    }
-    const timePart = timeParts.length > 0 ? `T${timeParts.join("")}` : "";
-    return `P${datePart}${timePart}`;
-}
-const Duration = {
-    seconds(value) {
-        return durationFromSeconds(value);
-    },
-    minutes(value) {
-        return durationFromSeconds(value * 60);
-    },
-    hours(value) {
-        return durationFromSeconds(value * 3600);
-    },
-    days(value) {
-        return durationFromSeconds(value * 86400);
-    },
-    from(parts) {
-        const seconds = (parts.days ?? 0) * 86400 +
-            (parts.hours ?? 0) * 3600 +
-            (parts.minutes ?? 0) * 60 +
-            (parts.seconds ?? 0);
-        return durationFromSeconds(seconds);
-    },
-};
-function applyCommonDefaults(data) {
-    if (data.sequence === undefined)
-        data.sequence = 0;
-    if (data.title === undefined)
-        data.title = "";
-    if (data.description === undefined)
-        data.description = "";
-    if (data.descriptionContentType === undefined)
-        data.descriptionContentType = "text/plain";
-    if (data.showWithoutTime === undefined)
-        data.showWithoutTime = false;
-    if (data.recurrenceIdTimeZone === undefined)
-        data.recurrenceIdTimeZone = null;
-    if (data.excluded === undefined)
-        data.excluded = false;
-    if (data.priority === undefined)
-        data.priority = 0;
-    if (data.freeBusyStatus === undefined)
-        data.freeBusyStatus = "busy";
-    if (data.privacy === undefined)
-        data.privacy = "public";
-    if (data.useDefaultAlerts === undefined)
-        data.useDefaultAlerts = false;
-    return data;
-}
-function applyEventDefaults(data) {
-    if (data.duration === undefined)
-        data.duration = "PT0S";
-    if (data.status === undefined)
-        data.status = "confirmed";
-    return data;
-}
-function applyTaskDefaults(data) {
-    if (data.progress === undefined) {
-        const participants = data.participants ? Object.values(data.participants) : [];
-        if (participants.length === 0) {
-            data.progress = "needs-action";
-        }
-        else if (participants.every((p) => p.progress === "completed")) {
-            data.progress = "completed";
-        }
-        else if (participants.some((p) => p.progress === "failed")) {
-            data.progress = "failed";
-        }
-        else if (participants.some((p) => p.progress === "in-process")) {
-            data.progress = "in-process";
-        }
-        else {
-            data.progress = "needs-action";
-        }
-    }
-    return data;
-}
-function applyParticipantDefaults(participant) {
-    if (participant.participationStatus === undefined)
-        participant.participationStatus = "needs-action";
-    if (participant.expectReply === undefined)
-        participant.expectReply = false;
-    if (participant.scheduleAgent === undefined)
-        participant.scheduleAgent = "server";
-    if (participant.scheduleForceSend === undefined)
-        participant.scheduleForceSend = false;
-    if (participant.scheduleSequence === undefined)
-        participant.scheduleSequence = 0;
-    return participant;
-}
-function applyAlertDefaults(alert) {
-    if (alert.action === undefined)
-        alert.action = "display";
-    if (alert.trigger["@type"] === "OffsetTrigger") {
-        if (alert.trigger.relativeTo === undefined) {
-            alert.trigger.relativeTo = "start";
-        }
-    }
-    return alert;
-}
-export function isEvent(obj) {
-    return obj["@type"] === "Event";
-}
-export function isTask(obj) {
-    return obj["@type"] === "Task";
-}
-export function isGroup(obj) {
-    return obj["@type"] === "Group";
-}
-class Base {
-    data;
-    constructor(data) {
-        this.data = data;
-    }
-    eject() {
-        return deepClone(this.data);
-    }
-    clone() {
-        return new Base(deepClone(this.data));
-    }
-    get(key) {
-        return this.data[key];
-    }
-    set(key, value) {
-        this.data[key] = value;
-        return this.touchKeys([String(key)]);
-    }
-    update(values, options = {}) {
-        const next = { ...this.data, ...values };
-        if (options.validate !== false) {
-            validateJsCalendarObject(next);
-        }
-        this.data = next;
-        return this.touchKeys(Object.keys(values), options);
-    }
-    patch(patch, options = {}) {
-        const next = applyPatch(this.data, patch);
-        if (options.validate !== false) {
-            validateJsCalendarObject(next);
-        }
-        this.data = next;
-        return this.touchFromPatch(patch, options);
-    }
-    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;
-    }
-    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;
-    }
-    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;
-    }
-    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;
-    }
-    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 === "participants");
-        if (!onlyParticipants) {
-            const current = typeof this.data.sequence === "number" ? this.data.sequence : 0;
-            this.data.sequence = current + 1;
-        }
-        return this;
-    }
-    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 = typeof this.data.sequence === "number" ? this.data.sequence : 0;
-            this.data.sequence = current + 1;
-        }
-        return this;
-    }
-}
-class EventObject extends Base {
-    constructor(input, options = {}) {
-        if (typeof input.start !== "string" && !(input.start instanceof Date)) {
-            throw new Error("Event.start is required");
-        }
-        if (typeof input.start === "string" && input.start.length === 0) {
-            throw new Error("Event.start is required");
-        }
-        const now = options.now ?? nowUtc;
-        const { start: rawStart, duration: rawDuration, updated: rawUpdated, created: rawCreated, timeZone: rawTimeZone, ...rest } = input;
-        const start = toLocalDateTime(rawStart);
-        const updated = rawUpdated ? toUtcDateTime(rawUpdated) : now();
-        let timeZone;
-        if (rawTimeZone === null) {
-            timeZone = null;
-        }
-        else if (rawTimeZone) {
-            timeZone = resolveTimeZone(rawTimeZone);
-        }
-        const data = {
-            ...rest,
-            "@type": "Event",
-            start,
-            uid: input.uid ?? createUid(),
-            updated,
-        };
-        if (timeZone !== undefined)
-            data.timeZone = timeZone;
-        if (rawDuration !== undefined) {
-            data.duration = typeof rawDuration === "number"
-                ? durationFromSeconds(rawDuration)
-                : rawDuration;
-        }
-        if (rawCreated) {
-            data.created = toUtcDateTime(rawCreated);
-        }
-        else {
-            data.created = updated;
-        }
-        applyCommonDefaults(data);
-        applyEventDefaults(data);
-        if (options.validate !== false) {
-            validateJsCalendarObject(data);
-        }
-        super(data);
-    }
-    clone() {
-        const cloneData = deepClone(this.data);
-        const { "@type": _type, ...rest } = cloneData;
-        return new EventObject(rest);
-    }
-}
-class TaskObject extends Base {
-    constructor(input = {}, options = {}) {
-        const now = options.now ?? nowUtc;
-        const { start: rawStart, due: rawDue, updated: rawUpdated, created: rawCreated, timeZone: rawTimeZone, ...rest } = input;
-        const updated = rawUpdated ? toUtcDateTime(rawUpdated) : now();
-        let timeZone;
-        if (rawTimeZone === null) {
-            timeZone = null;
-        }
-        else if (rawTimeZone) {
-            timeZone = resolveTimeZone(rawTimeZone);
-        }
-        const data = {
-            ...rest,
-            "@type": "Task",
-            uid: input.uid ?? createUid(),
-            updated,
-        };
-        if (rawStart)
-            data.start = toLocalDateTime(rawStart);
-        if (rawDue)
-            data.due = toLocalDateTime(rawDue);
-        if (timeZone !== undefined)
-            data.timeZone = timeZone;
-        if (rawCreated) {
-            data.created = toUtcDateTime(rawCreated);
-        }
-        else {
-            data.created = updated;
-        }
-        applyCommonDefaults(data);
-        applyTaskDefaults(data);
-        if (options.validate !== false) {
-            validateJsCalendarObject(data);
-        }
-        super(data);
-    }
-    clone() {
-        const cloneData = deepClone(this.data);
-        const { "@type": _type, ...rest } = cloneData;
-        return new TaskObject(rest);
-    }
-}
-class GroupObject extends Base {
-    constructor(input, options = {}) {
-        if (!Array.isArray(input.entries)) {
-            throw new Error("Group.entries is required");
-        }
-        const now = options.now ?? nowUtc;
-        const { updated: rawUpdated, created: rawCreated, ...rest } = input;
-        const entries = input.entries;
-        const updated = rawUpdated ? toUtcDateTime(rawUpdated) : now();
-        const data = {
-            ...rest,
-            "@type": "Group",
-            entries,
-            uid: input.uid ?? createUid(),
-            updated,
-        };
-        if (rawCreated) {
-            data.created = toUtcDateTime(rawCreated);
-        }
-        else {
-            data.created = updated;
-        }
-        applyCommonDefaults(data);
-        if (options.validate !== false) {
-            validateJsCalendarObject(data);
-        }
-        super(data);
-    }
-    addEntry(entry) {
-        const entries = [...this.data.entries, entry];
-        this.data.entries = entries;
-        this.touchKeys(["entries"]);
-        return this;
-    }
-    clone() {
-        const cloneData = deepClone(this.data);
-        const { "@type": _type, ...rest } = cloneData;
-        return new GroupObject(rest);
-    }
-}
+import { applyPatch } from "./patch.js";
+import { EventObject } from "./jscal/event.js";
+import { TaskObject } from "./jscal/task.js";
+import { GroupObject } from "./jscal/group.js";
+import { Duration } from "./jscal/duration.js";
+import { createId, createUid } from "./jscal/ids.js";
+import { normalizeItems, normalizeToObjects } from "./jscal/normalize.js";
+import { isEvent, isGroup, isTask } from "./jscal/guards.js";
+import { buildAlert, buildLink, buildLocation, buildNDay, buildParticipants, buildRecurrenceRule, buildRelation, buildRelatedTo, buildTimeZone, buildTimeZoneMap, buildTimeZoneRule, buildVirtualLocation, buildVirtualLocations, buildLocations, buildLinks, buildParticipant, buildAlerts, } from "./jscal/builders.js";
+export { createId, createUid, isEvent, isGroup, isTask };
 export const JsCal = {
     Event: EventObject,
     Task: TaskObject,
@@ -458,47 +22,95 @@ export const JsCal = {
     timeZone: resolveTimeZone,
     timeZones: TimeZones,
     applyPatch,
+    Participant: buildParticipant,
+    Location: buildLocation,
+    VirtualLocation: buildVirtualLocation,
+    Alert: buildAlert,
+    Relation: buildRelation,
+    Link: buildLink,
+    TimeZone: buildTimeZone,
+    TimeZoneRule: buildTimeZoneRule,
+    RecurrenceRule: buildRecurrenceRule,
+    NDay: buildNDay,
+    participants: buildParticipants,
+    locations: buildLocations,
+    virtualLocations: buildVirtualLocations,
+    alerts: buildAlerts,
+    links: buildLinks,
+    relatedTo: buildRelatedTo,
+    timeZonesMap: buildTimeZoneMap,
+    /**
+     * Find a JSCalendar object by UID.
+     * @param items JSCalendar objects or JsCal instances.
+     * @param uid UID to match.
+     * @return Matching object, if found.
+     */
     findByUid(items, uid) {
         return findByUid(normalizeItems(items), uid);
     },
+    /**
+     * Filter JSCalendar objects by @type.
+     * @param items JSCalendar objects or JsCal instances.
+     * @param type JSCalendar @type to match.
+     * @return Matching objects.
+     */
     filterByType(items, type) {
         return filterByType(normalizeItems(items), type);
     },
+    /**
+     * Group JSCalendar objects by @type.
+     * @param items JSCalendar objects or JsCal instances.
+     * @return Record keyed by @type.
+     */
     groupByType(items) {
         return groupByType(normalizeItems(items));
     },
+    /**
+     * Filter JSCalendar objects whose text fields match a query.
+     * @param items JSCalendar objects or JsCal instances.
+     * @param query Text query to match.
+     * @return Matching objects.
+     */
     filterByText(items, query) {
         return filterByText(normalizeItems(items), query);
     },
+    /**
+     * Filter JSCalendar objects that overlap a date range.
+     * @param items JSCalendar objects or JsCal instances.
+     * @param range Date range bounds.
+     * @param options Range comparison options.
+     * @return Matching objects.
+     */
     filterByDateRange(items, range, options) {
         return filterByDateRange(normalizeItems(items), range, options);
     },
+    /**
+     * Expand recurrence rules into concrete occurrences.
+     * @param items JSCalendar objects or JsCal instances.
+     * @param range Date range bounds.
+     * @return Generator of expanded JSCalendar objects.
+     */
     expandRecurrence(items, range) {
         return expandRecurrence(normalizeItems(items), range);
     },
+    /**
+     * Expand recurrence rules with pagination support.
+     * @param items JSCalendar objects or JsCal instances.
+     * @param range Date range bounds.
+     * @param options Pagination options.
+     * @return Page of expanded items plus an optional next cursor.
+     */
     expandRecurrencePaged(items, range, options) {
         return expandRecurrencePaged(normalizeItems(items), range, options);
     },
+    /**
+     * Convert JSCalendar objects to iCalendar text.
+     * @param value JSCalendar objects or JsCal instances.
+     * @param options iCalendar export options.
+     * @return iCalendar text.
+     */
     toICal(value, options) {
         const objects = normalizeToObjects(value);
         return toICal(objects, options);
     },
 };
-function isJsCalInstance(value) {
-    return "data" in value;
-}
-function normalizeItems(items) {
-    const mapped = [];
-    for (const entry of items) {
-        if (typeof entry === "object" && entry !== null && isJsCalInstance(entry)) {
-            mapped.push(entry.data);
-        }
-        else {
-            mapped.push(entry);
-        }
-    }
-    return mapped;
-}
-function normalizeToObjects(value) {
-    return normalizeItems(value);
-}

package/dist/patch.d.ts

@@ -1,5 +1,18 @@
 import type { PatchObject } from "./types.js";
+/**
+ * Error thrown when a patch operation is invalid.
+ */
 export declare class PatchError extends Error {
+    /**
+     * Create a new PatchError.
+     * @param message Error message.
+     */
     constructor(message: string);
 }
+/**
+ * Apply a JSCalendar PatchObject to an input object.
+ * @param input Input object.
+ * @param patch Patch object to apply.
+ * @return Patched clone of the input object.
+ */
 export declare function applyPatch<T extends object>(input: T, patch: PatchObject): T;