@craftguild/jscalendar 0.2.0 → 0.3.0

package/dist/jscal/datetime.js

@@ -0,0 +1,42 @@
+import { normalizeUtcDateTime } from "../utils.js";
+import { isStringValue } from "../utils.js";
+/**
+ * Pad a number to two digits.
+ * @param value Number to pad.
+ * @return Zero-padded string.
+ */
+function pad2(value) {
+    return value.toString().padStart(2, "0");
+}
+/**
+ * Convert a Date input to a LocalDateTime string.
+ * @param value Date or LocalDateTime string.
+ * @return LocalDateTime string.
+ */
+export function toLocalDateTime(value) {
+    if (isStringValue(value))
+        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("");
+}
+/**
+ * Convert a Date input to a UTCDateTime string.
+ * @param value Date or UTCDateTime string.
+ * @return UTCDateTime string.
+ */
+export function toUtcDateTime(value) {
+    if (isStringValue(value))
+        return value;
+    return normalizeUtcDateTime(value.toISOString());
+}

package/dist/jscal/defaults.d.ts

@@ -0,0 +1,31 @@
+import type { Alert, Event, JSCalendarObject, Participant, Task } from "../types.js";
+/**
+ * Apply common defaults to the target.
+ * @param data JSCalendar object to mutate.
+ * @return The same object with defaults applied.
+ */
+export declare function applyCommonDefaults<T extends JSCalendarObject>(data: T): T;
+/**
+ * Apply event defaults to the target.
+ * @param data Event to mutate.
+ * @return The same event with defaults applied.
+ */
+export declare function applyEventDefaults(data: Event): Event;
+/**
+ * Apply task defaults to the target.
+ * @param data Task to mutate.
+ * @return The same task with defaults applied.
+ */
+export declare function applyTaskDefaults(data: Task): Task;
+/**
+ * Apply participant defaults to the target.
+ * @param participant Participant to mutate.
+ * @return The same participant with defaults applied.
+ */
+export declare function applyParticipantDefaults(participant: Participant): Participant;
+/**
+ * Apply alert defaults to the target.
+ * @param alert Alert to mutate.
+ * @return The same alert with defaults applied.
+ */
+export declare function applyAlertDefaults(alert: Alert): Alert;

package/dist/jscal/defaults.js

@@ -0,0 +1,102 @@
+import { STATUS_COMPLETED, STATUS_FAILED, STATUS_IN_PROCESS, STATUS_NEEDS_ACTION, TRIGGER_OFFSET } from "./constants.js";
+/**
+ * Apply common defaults to the target.
+ * @param data JSCalendar object to mutate.
+ * @return The same object with defaults applied.
+ */
+export 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;
+}
+/**
+ * Apply event defaults to the target.
+ * @param data Event to mutate.
+ * @return The same event with defaults applied.
+ */
+export function applyEventDefaults(data) {
+    if (data.duration === undefined)
+        data.duration = "PT0S";
+    if (data.status === undefined)
+        data.status = "confirmed";
+    return data;
+}
+/**
+ * Apply task defaults to the target.
+ * @param data Task to mutate.
+ * @return The same task with defaults applied.
+ */
+export function applyTaskDefaults(data) {
+    if (data.progress === undefined) {
+        const participants = data.participants ? Object.values(data.participants) : [];
+        if (participants.length === 0) {
+            data.progress = STATUS_NEEDS_ACTION;
+        }
+        else if (participants.every((p) => p.progress === STATUS_COMPLETED)) {
+            data.progress = STATUS_COMPLETED;
+        }
+        else if (participants.some((p) => p.progress === STATUS_FAILED)) {
+            data.progress = STATUS_FAILED;
+        }
+        else if (participants.some((p) => p.progress === STATUS_IN_PROCESS)) {
+            data.progress = STATUS_IN_PROCESS;
+        }
+        else {
+            data.progress = STATUS_NEEDS_ACTION;
+        }
+    }
+    return data;
+}
+/**
+ * Apply participant defaults to the target.
+ * @param participant Participant to mutate.
+ * @return The same participant with defaults applied.
+ */
+export 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;
+}
+/**
+ * Apply alert defaults to the target.
+ * @param alert Alert to mutate.
+ * @return The same alert with defaults applied.
+ */
+export function applyAlertDefaults(alert) {
+    if (alert.action === undefined)
+        alert.action = "display";
+    if (alert.trigger["@type"] === TRIGGER_OFFSET) {
+        if (alert.trigger.relativeTo === undefined) {
+            alert.trigger.relativeTo = "start";
+        }
+    }
+    return alert;
+}

package/dist/jscal/duration.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Convert seconds to an ISO 8601 duration string.
+ * @param totalSeconds Total seconds to encode.
+ * @return ISO 8601 duration string.
+ */
+export declare function durationFromSeconds(totalSeconds: number): string;
+export declare const Duration: {
+    /**
+     * Convert seconds to a duration string.
+     * @param value Total seconds.
+     * @return ISO 8601 duration string.
+     */
+    seconds(value: number): string;
+    /**
+     * Convert minutes to a duration string.
+     * @param value Total minutes.
+     * @return ISO 8601 duration string.
+     */
+    minutes(value: number): string;
+    /**
+     * Convert hours to a duration string.
+     * @param value Total hours.
+     * @return ISO 8601 duration string.
+     */
+    hours(value: number): string;
+    /**
+     * Convert days to a duration string.
+     * @param value Total days.
+     * @return ISO 8601 duration string.
+     */
+    days(value: number): string;
+    /**
+     * Build a duration string from component parts.
+     * @param parts Day/hour/minute/second parts.
+     * @return ISO 8601 duration string.
+     */
+    from(parts: {
+        days?: number;
+        hours?: number;
+        minutes?: number;
+        seconds?: number;
+    }): string;
+};

package/dist/jscal/duration.js

@@ -0,0 +1,72 @@
+import { EMPTY_STRING } from "./constants.js";
+/**
+ * Convert seconds to an ISO 8601 duration string.
+ * @param totalSeconds Total seconds to encode.
+ * @return ISO 8601 duration string.
+ */
+export 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 === EMPTY_STRING && timeParts.length === 0)) {
+        timeParts.push(`${seconds}S`);
+    }
+    const timePart = timeParts.length > 0 ? `T${timeParts.join("")}` : "";
+    return `P${datePart}${timePart}`;
+}
+export const Duration = {
+    /**
+     * Convert seconds to a duration string.
+     * @param value Total seconds.
+     * @return ISO 8601 duration string.
+     */
+    seconds(value) {
+        return durationFromSeconds(value);
+    },
+    /**
+     * Convert minutes to a duration string.
+     * @param value Total minutes.
+     * @return ISO 8601 duration string.
+     */
+    minutes(value) {
+        return durationFromSeconds(value * 60);
+    },
+    /**
+     * Convert hours to a duration string.
+     * @param value Total hours.
+     * @return ISO 8601 duration string.
+     */
+    hours(value) {
+        return durationFromSeconds(value * 3600);
+    },
+    /**
+     * Convert days to a duration string.
+     * @param value Total days.
+     * @return ISO 8601 duration string.
+     */
+    days(value) {
+        return durationFromSeconds(value * 86400);
+    },
+    /**
+     * Build a duration string from component parts.
+     * @param parts Day/hour/minute/second parts.
+     * @return ISO 8601 duration string.
+     */
+    from(parts) {
+        const seconds = (parts.days ?? 0) * 86400 +
+            (parts.hours ?? 0) * 3600 +
+            (parts.minutes ?? 0) * 60 +
+            (parts.seconds ?? 0);
+        return durationFromSeconds(seconds);
+    },
+};

package/dist/jscal/event.d.ts

@@ -0,0 +1,17 @@
+import type { Event } from "../types.js";
+import type { CreateOptions, EventInput } from "./types.js";
+import { Base } from "./base.js";
+export declare class EventObject extends Base<Event> {
+    /**
+     * Create an event with normalized dates, duration, and RFC defaults.
+     * @param input Event input values to normalize.
+     * @param options Creation options (validation, clock).
+     * @return EventObject instance.
+     */
+    constructor(input: EventInput, options?: CreateOptions);
+    /**
+     * Clone the event as a new EventObject instance.
+     * @return Cloned EventObject.
+     */
+    clone(): EventObject;
+}

package/dist/jscal/event.js

@@ -0,0 +1,71 @@
+import { resolveTimeZone } from "../timezones.js";
+import { deepClone, nowUtc } from "../utils.js";
+import { validateJsCalendarObject } from "../validate.js";
+import { applyCommonDefaults, applyEventDefaults } from "./defaults.js";
+import { durationFromSeconds } from "./duration.js";
+import { createUid } from "./ids.js";
+import { toLocalDateTime, toUtcDateTime } from "./datetime.js";
+import { Base } from "./base.js";
+import { isStringValue, isNumberValue } from "../utils.js";
+export class EventObject extends Base {
+    /**
+     * Create an event with normalized dates, duration, and RFC defaults.
+     * @param input Event input values to normalize.
+     * @param options Creation options (validation, clock).
+     * @return EventObject instance.
+     */
+    constructor(input, options = {}) {
+        if (!isStringValue(input.start) && !(input.start instanceof Date)) {
+            throw new Error("Event.start is required");
+        }
+        if (isStringValue(input.start) && 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 = isNumberValue(rawDuration)
+                ? 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 the event as a new EventObject instance.
+     * @return Cloned EventObject.
+     */
+    clone() {
+        const cloneData = deepClone(this.data);
+        const { "@type": _type, ...rest } = cloneData;
+        return new EventObject(rest);
+    }
+}

package/dist/jscal/group.d.ts

@@ -0,0 +1,25 @@
+import type { Event, Group, Task } from "../types.js";
+import type { CreateOptions, GroupInput } from "./types.js";
+import { Base } from "./base.js";
+export declare class GroupObject extends Base<Group> {
+    /**
+     * Create a group with normalized entries and RFC defaults.
+     * @param input Group input values to normalize.
+     * @param options Creation options (validation, clock).
+     * @return GroupObject instance.
+     */
+    constructor(input: GroupInput, options?: CreateOptions);
+    /**
+     * Append a normalized entry to the group.
+     * @param entry Event or task entry to add.
+     * @return Updated GroupObject instance.
+     */
+    addEntry(entry: Event | Task | {
+        data: Event | Task;
+    }): this;
+    /**
+     * Clone the group as a new GroupObject instance.
+     * @return Cloned GroupObject.
+     */
+    clone(): GroupObject;
+}

package/dist/jscal/group.js

@@ -0,0 +1,62 @@
+import { deepClone, nowUtc } from "../utils.js";
+import { validateJsCalendarObject } from "../validate.js";
+import { applyCommonDefaults } from "./defaults.js";
+import { createUid } from "./ids.js";
+import { Base } from "./base.js";
+import { normalizeEntry } from "./normalize.js";
+import { toUtcDateTime } from "./datetime.js";
+export class GroupObject extends Base {
+    /**
+     * Create a group with normalized entries and RFC defaults.
+     * @param input Group input values to normalize.
+     * @param options Creation options (validation, clock).
+     * @return GroupObject instance.
+     */
+    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.map((entry) => normalizeEntry(entry));
+        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);
+    }
+    /**
+     * Append a normalized entry to the group.
+     * @param entry Event or task entry to add.
+     * @return Updated GroupObject instance.
+     */
+    addEntry(entry) {
+        const entries = [...this.data.entries, normalizeEntry(entry)];
+        this.data.entries = entries;
+        this.touchKeys(["entries"]);
+        return this;
+    }
+    /**
+     * Clone the group as a new GroupObject instance.
+     * @return Cloned GroupObject.
+     */
+    clone() {
+        const cloneData = deepClone(this.data);
+        const { "@type": _type, ...rest } = cloneData;
+        return new GroupObject(rest);
+    }
+}

package/dist/jscal/guards.d.ts

@@ -0,0 +1,19 @@
+import type { Event, Group, JSCalendarObject, Task } from "../types.js";
+/**
+ * Type guard for JSCalendar Event objects.
+ * @param obj JSCalendar object to check.
+ * @return True when the object is an Event.
+ */
+export declare function isEvent(obj: JSCalendarObject): obj is Event;
+/**
+ * Type guard for JSCalendar Task objects.
+ * @param obj JSCalendar object to check.
+ * @return True when the object is a Task.
+ */
+export declare function isTask(obj: JSCalendarObject): obj is Task;
+/**
+ * Type guard for JSCalendar Group objects.
+ * @param obj JSCalendar object to check.
+ * @return True when the object is a Group.
+ */
+export declare function isGroup(obj: JSCalendarObject): obj is Group;

package/dist/jscal/guards.js

@@ -0,0 +1,25 @@
+import { TYPE_EVENT, TYPE_GROUP, TYPE_TASK } from "./constants.js";
+/**
+ * Type guard for JSCalendar Event objects.
+ * @param obj JSCalendar object to check.
+ * @return True when the object is an Event.
+ */
+export function isEvent(obj) {
+    return obj["@type"] === TYPE_EVENT;
+}
+/**
+ * Type guard for JSCalendar Task objects.
+ * @param obj JSCalendar object to check.
+ * @return True when the object is a Task.
+ */
+export function isTask(obj) {
+    return obj["@type"] === TYPE_TASK;
+}
+/**
+ * Type guard for JSCalendar Group objects.
+ * @param obj JSCalendar object to check.
+ * @return True when the object is a Group.
+ */
+export function isGroup(obj) {
+    return obj["@type"] === TYPE_GROUP;
+}

package/dist/jscal/ids.d.ts

@@ -0,0 +1,11 @@
+import type { Id } from "../types.js";
+/**
+ * Create a UUID-like identifier.
+ * @return UUID string.
+ */
+export declare function createUid(): string;
+/**
+ * Create a compact base64url identifier.
+ * @return Base64url ID string.
+ */
+export declare function createId(): Id;

package/dist/jscal/ids.js

@@ -0,0 +1,77 @@
+import { TYPEOF_FUNCTION } from "./constants.js";
+/**
+ * Get a Crypto instance if available.
+ * @return Crypto instance when available, otherwise undefined.
+ */
+function getCrypto() {
+    const cryptoObj = globalThis.crypto;
+    if (cryptoObj && typeof cryptoObj.getRandomValues === TYPEOF_FUNCTION) {
+        return cryptoObj;
+    }
+    return undefined;
+}
+/**
+ * Generate random bytes using Crypto or Math.random.
+ * @param length Number of bytes to generate.
+ * @return Random byte array.
+ */
+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;
+}
+/**
+ * Encode bytes as base64url.
+ * @param bytes Byte array to encode.
+ * @return Base64url string without padding.
+ */
+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(/=+$/, "");
+}
+/**
+ * Create a UUID-like identifier.
+ * @return UUID string.
+ */
+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)}`;
+}
+/**
+ * Create a compact base64url identifier.
+ * @return Base64url ID string.
+ */
+export function createId() {
+    return base64UrlEncode(getRandomBytes(16));
+}

package/dist/jscal/normalize.d.ts

@@ -0,0 +1,32 @@
+import type { Event, JSCalendarObject, Task } from "../types.js";
+import type { EntryInput } from "./types.js";
+/**
+ * Type guard for wrapper instances that expose a data field.
+ * @param value Value to check.
+ * @return True when value looks like a JsCal instance.
+ */
+export declare function isJsCalInstance(value: object): value is {
+    data: JSCalendarObject;
+};
+/**
+ * Normalize a list of mixed JSCalendar objects and JsCal instances.
+ * @param items Items to normalize.
+ * @return Plain JSCalendar objects.
+ */
+export declare function normalizeItems(items: Array<JSCalendarObject | {
+    data: JSCalendarObject;
+}>): JSCalendarObject[];
+/**
+ * Normalize a group entry into a plain Event or Task.
+ * @param entry Group entry input.
+ * @return Plain Event or Task object.
+ */
+export declare function normalizeEntry(entry: EntryInput): Event | Task;
+/**
+ * Normalize a list to plain JSCalendar objects.
+ * @param value List of JSCalendar objects or JsCal instances.
+ * @return Plain JSCalendar objects.
+ */
+export declare function normalizeToObjects(value: Array<JSCalendarObject | {
+    data: JSCalendarObject;
+}>): JSCalendarObject[];

package/dist/jscal/normalize.js

@@ -0,0 +1,45 @@
+import { isObjectValue } from "../utils.js";
+/**
+ * Type guard for wrapper instances that expose a data field.
+ * @param value Value to check.
+ * @return True when value looks like a JsCal instance.
+ */
+export function isJsCalInstance(value) {
+    return "data" in value;
+}
+/**
+ * Normalize a list of mixed JSCalendar objects and JsCal instances.
+ * @param items Items to normalize.
+ * @return Plain JSCalendar objects.
+ */
+export function normalizeItems(items) {
+    const mapped = [];
+    for (const entry of items) {
+        if (isObjectValue(entry) && isJsCalInstance(entry)) {
+            mapped.push(entry.data);
+        }
+        else {
+            mapped.push(entry);
+        }
+    }
+    return mapped;
+}
+/**
+ * Normalize a group entry into a plain Event or Task.
+ * @param entry Group entry input.
+ * @return Plain Event or Task object.
+ */
+export function normalizeEntry(entry) {
+    if (isObjectValue(entry) && isJsCalInstance(entry)) {
+        return entry.data;
+    }
+    return entry;
+}
+/**
+ * Normalize a list to plain JSCalendar objects.
+ * @param value List of JSCalendar objects or JsCal instances.
+ * @return Plain JSCalendar objects.
+ */
+export function normalizeToObjects(value) {
+    return normalizeItems(value);
+}