@craftguild/jscalendar 0.1.0

package/dist/index.js

@@ -0,0 +1,2 @@
+export { JsCal } from "./jscal.js";
+export { ValidationError } from "./validate.js";

package/dist/jscal.d.ts

@@ -0,0 +1,129 @@
+import type { Alert, Event, Group, Id, JSCalendarObject, Location, Participant, PatchObject, Task, TimeZoneInput, UTCDateTime, VirtualLocation } from "./types.js";
+import { applyPatch } from "./patch.js";
+import { resolveTimeZone } from "./timezones.js";
+export type CreateOptions = {
+    now?: () => UTCDateTime;
+    validate?: boolean;
+};
+export type UpdateOptions = {
+    touch?: boolean;
+    sequence?: boolean;
+    now?: () => UTCDateTime;
+    validate?: boolean;
+};
+type DateInput = string | Date;
+type DurationInput = string | number;
+type EventInput = Omit<Event, "@type" | "uid" | "updated" | "created" | "start" | "duration" | "timeZone"> & {
+    start: DateInput;
+    duration?: DurationInput;
+    timeZone?: TimeZoneInput | null;
+    uid?: string;
+    updated?: DateInput;
+    created?: DateInput;
+};
+type TaskInput = Omit<Task, "@type" | "uid" | "updated" | "created" | "start" | "due" | "timeZone"> & {
+    uid?: string;
+    updated?: DateInput;
+    created?: DateInput;
+    start?: DateInput;
+    due?: DateInput;
+    timeZone?: TimeZoneInput | null;
+};
+type GroupInput = Omit<Group, "@type" | "uid" | "updated" | "created"> & {
+    uid?: string;
+    updated?: DateInput;
+    created?: DateInput;
+};
+export declare function createUid(): string;
+export declare function createId(): Id;
+export declare function isEvent(obj: JSCalendarObject): obj is Event;
+export declare function isTask(obj: JSCalendarObject): obj is Task;
+export declare function isGroup(obj: JSCalendarObject): obj is Group;
+declare class Base<T extends JSCalendarObject> {
+    data: T;
+    constructor(data: T);
+    eject(): T;
+    clone(): Base<T>;
+    get<K extends keyof T>(key: K): T[K];
+    set<K extends keyof T>(key: K, value: T[K]): this;
+    update(values: Partial<T>, options?: UpdateOptions): this;
+    patch(patch: PatchObject, options?: UpdateOptions): this;
+    addLocation(location: Omit<Location, "@type"> & Partial<Pick<Location, "@type">>, id?: Id): Id;
+    addVirtualLocation(location: Omit<VirtualLocation, "@type"> & Partial<Pick<VirtualLocation, "@type">>, id?: Id): Id;
+    addParticipant(participant: Omit<Participant, "@type"> & Partial<Pick<Participant, "@type">>, id?: Id): Id;
+    addAlert(alert: Omit<Alert, "@type"> & Partial<Pick<Alert, "@type">>, id?: Id): Id;
+    protected touchKeys(keys: string[], options?: UpdateOptions): this;
+    protected touchFromPatch(patch: PatchObject, options?: UpdateOptions): this;
+}
+declare class EventObject extends Base<Event> {
+    constructor(input: EventInput, options?: CreateOptions);
+    clone(): EventObject;
+}
+declare class TaskObject extends Base<Task> {
+    constructor(input?: TaskInput, options?: CreateOptions);
+    clone(): TaskObject;
+}
+declare class GroupObject extends Base<Group> {
+    constructor(input: GroupInput, options?: CreateOptions);
+    addEntry(entry: Event | Task): this;
+    clone(): GroupObject;
+}
+export declare const JsCal: {
+    Event: typeof EventObject;
+    Task: typeof TaskObject;
+    Group: typeof GroupObject;
+    createUid: typeof createUid;
+    createId: typeof createId;
+    duration: {
+        seconds(value: number): string;
+        minutes(value: number): string;
+        hours(value: number): string;
+        days(value: number): string;
+        from(parts: {
+            days?: number;
+            hours?: number;
+            minutes?: number;
+            seconds?: number;
+        }): string;
+    };
+    timeZone: typeof resolveTimeZone;
+    timeZones: import("./timezones.js").TimeZoneId[];
+    applyPatch: typeof applyPatch;
+    findByUid(items: Array<JSCalendarObject | {
+        data: JSCalendarObject;
+    }>, uid: string): JSCalendarObject | undefined;
+    filterByType(items: Array<JSCalendarObject | {
+        data: JSCalendarObject;
+    }>, type: JSCalendarObject["@type"]): JSCalendarObject[];
+    groupByType(items: Array<JSCalendarObject | {
+        data: JSCalendarObject;
+    }>): Record<string, JSCalendarObject[]>;
+    filterByText(items: Array<JSCalendarObject | {
+        data: JSCalendarObject;
+    }>, query: string): JSCalendarObject[];
+    filterByDateRange(items: Array<JSCalendarObject | {
+        data: JSCalendarObject;
+    }>, range: import("./search.js").DateRange, options?: import("./search.js").DateRangeOptions): JSCalendarObject[];
+    expandRecurrence(items: Array<JSCalendarObject | {
+        data: JSCalendarObject;
+    }>, range: {
+        from: Date;
+        to: Date;
+    }): Generator<JSCalendarObject>;
+    expandRecurrencePaged(items: Array<JSCalendarObject | {
+        data: JSCalendarObject;
+    }>, range: {
+        from: Date;
+        to: Date;
+    }, options: {
+        limit: number;
+        cursor?: string;
+    }): {
+        items: JSCalendarObject[];
+        nextCursor?: string;
+    };
+    toICal(value: Array<JSCalendarObject | {
+        data: JSCalendarObject;
+    }>, options?: import("./ical.js").ICalOptions): string;
+};
+export {};

package/dist/jscal.js

@@ -0,0 +1,504 @@
+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 { 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);
+    }
+}
+export const JsCal = {
+    Event: EventObject,
+    Task: TaskObject,
+    Group: GroupObject,
+    createUid,
+    createId,
+    duration: Duration,
+    timeZone: resolveTimeZone,
+    timeZones: TimeZones,
+    applyPatch,
+    findByUid(items, uid) {
+        return findByUid(normalizeItems(items), uid);
+    },
+    filterByType(items, type) {
+        return filterByType(normalizeItems(items), type);
+    },
+    groupByType(items) {
+        return groupByType(normalizeItems(items));
+    },
+    filterByText(items, query) {
+        return filterByText(normalizeItems(items), query);
+    },
+    filterByDateRange(items, range, options) {
+        return filterByDateRange(normalizeItems(items), range, options);
+    },
+    expandRecurrence(items, range) {
+        return expandRecurrence(normalizeItems(items), range);
+    },
+    expandRecurrencePaged(items, range, options) {
+        return expandRecurrencePaged(normalizeItems(items), range, options);
+    },
+    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

@@ -0,0 +1,5 @@
+import type { PatchObject } from "./types.js";
+export declare class PatchError extends Error {
+    constructor(message: string);
+}
+export declare function applyPatch<T extends object>(input: T, patch: PatchObject): T;