@craftguild/jscalendar 0.2.0 → 0.3.0

package/dist/jscal/task.d.ts

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

package/dist/jscal/task.js

@@ -0,0 +1,60 @@
+import { resolveTimeZone } from "../timezones.js";
+import { deepClone, nowUtc } from "../utils.js";
+import { validateJsCalendarObject } from "../validate.js";
+import { applyCommonDefaults, applyTaskDefaults } from "./defaults.js";
+import { createUid } from "./ids.js";
+import { toLocalDateTime, toUtcDateTime } from "./datetime.js";
+import { Base } from "./base.js";
+export class TaskObject extends Base {
+    /**
+     * Create a task with normalized date fields and RFC defaults applied.
+     * @param input Task input values to normalize.
+     * @param options Creation options (validation, clock).
+     * @return TaskObject instance.
+     */
+    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 the task as a new TaskObject instance.
+     * @return Cloned TaskObject.
+     */
+    clone() {
+        const cloneData = deepClone(this.data);
+        const { "@type": _type, ...rest } = cloneData;
+        return new TaskObject(rest);
+    }
+}

package/dist/jscal/types.d.ts

@@ -0,0 +1,38 @@
+import type { Event, Group, Task, TimeZoneInput, UTCDateTime } from "../types.js";
+export type CreateOptions = {
+    now?: () => UTCDateTime;
+    validate?: boolean;
+};
+export type UpdateOptions = {
+    touch?: boolean;
+    sequence?: boolean;
+    now?: () => UTCDateTime;
+    validate?: boolean;
+};
+export type DateInput = string | Date;
+export type DurationInput = string | number;
+export type EntryInput = Event | Task | {
+    data: Event | Task;
+};
+export type EventInput = Omit<Event, "@type" | "uid" | "updated" | "created" | "start" | "duration" | "timeZone"> & {
+    start: DateInput;
+    duration?: DurationInput;
+    timeZone?: TimeZoneInput | null;
+    uid?: string;
+    updated?: DateInput;
+    created?: DateInput;
+};
+export type TaskInput = Omit<Task, "@type" | "uid" | "updated" | "created" | "start" | "due" | "timeZone"> & {
+    uid?: string;
+    updated?: DateInput;
+    created?: DateInput;
+    start?: DateInput;
+    due?: DateInput;
+    timeZone?: TimeZoneInput | null;
+};
+export type GroupInput = Omit<Group, "@type" | "uid" | "updated" | "created" | "entries"> & {
+    entries: EntryInput[];
+    uid?: string;
+    updated?: DateInput;
+    created?: DateInput;
+};

package/dist/jscal/types.js

@@ -0,0 +1 @@
+export {};

package/dist/jscal.d.ts

@@ -1,73 +1,15 @@
-import type { Alert, Event, Group, Id, JSCalendarObject, Location, Participant, PatchObject, Task, TimeZoneInput, UTCDateTime, VirtualLocation } from "./types.js";
-import { applyPatch } from "./patch.js";
+import type { JSCalendarObject } from "./types.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;
-}
+import { applyPatch } from "./patch.js";
+import { EventObject } from "./jscal/event.js";
+import { TaskObject } from "./jscal/task.js";
+import { GroupObject } from "./jscal/group.js";
+import { createId, createUid } from "./jscal/ids.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 type { CreateOptions, UpdateOptions } from "./jscal/types.js";
+export type { AlertInput, LinkInput, LocationInput, NDayInput, ParticipantInput, RecurrenceRuleInput, RelationInput, TimeZoneInput, TimeZoneRuleInput, VirtualLocationInput, } from "./jscal/builders.js";
+export { createId, createUid, isEvent, isGroup, isTask };
 export declare const JsCal: {
     Event: typeof EventObject;
     Task: typeof TaskObject;
@@ -89,27 +31,87 @@ export declare const JsCal: {
     timeZone: typeof resolveTimeZone;
     timeZones: import("./timezones.js").TimeZoneId[];
     applyPatch: typeof applyPatch;
+    Participant: typeof buildParticipant;
+    Location: typeof buildLocation;
+    VirtualLocation: typeof buildVirtualLocation;
+    Alert: typeof buildAlert;
+    Relation: typeof buildRelation;
+    Link: typeof buildLink;
+    TimeZone: typeof buildTimeZone;
+    TimeZoneRule: typeof buildTimeZoneRule;
+    RecurrenceRule: typeof buildRecurrenceRule;
+    NDay: typeof buildNDay;
+    participants: typeof buildParticipants;
+    locations: typeof buildLocations;
+    virtualLocations: typeof buildVirtualLocations;
+    alerts: typeof buildAlerts;
+    links: typeof buildLinks;
+    relatedTo: typeof buildRelatedTo;
+    timeZonesMap: typeof 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: Array<JSCalendarObject | {
         data: JSCalendarObject;
     }>, uid: string): JSCalendarObject | undefined;
+    /**
+     * Filter JSCalendar objects by @type.
+     * @param items JSCalendar objects or JsCal instances.
+     * @param type JSCalendar @type to match.
+     * @return Matching objects.
+     */
     filterByType(items: Array<JSCalendarObject | {
         data: JSCalendarObject;
     }>, type: JSCalendarObject["@type"]): JSCalendarObject[];
+    /**
+     * Group JSCalendar objects by @type.
+     * @param items JSCalendar objects or JsCal instances.
+     * @return Record keyed by @type.
+     */
     groupByType(items: Array<JSCalendarObject | {
         data: JSCalendarObject;
     }>): Record<string, JSCalendarObject[]>;
+    /**
+     * 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: Array<JSCalendarObject | {
         data: JSCalendarObject;
     }>, query: string): JSCalendarObject[];
+    /**
+     * 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: Array<JSCalendarObject | {
         data: JSCalendarObject;
     }>, range: import("./search.js").DateRange, options?: import("./search.js").DateRangeOptions): JSCalendarObject[];
+    /**
+     * 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: Array<JSCalendarObject | {
         data: JSCalendarObject;
     }>, range: {
         from: Date;
         to: Date;
     }): Generator<JSCalendarObject>;
+    /**
+     * 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: Array<JSCalendarObject | {
         data: JSCalendarObject;
     }>, range: {
@@ -122,8 +124,13 @@ export declare const JsCal: {
         items: JSCalendarObject[];
         nextCursor?: string;
     };
+    /**
+     * Convert JSCalendar objects to iCalendar text.
+     * @param value JSCalendar objects or JsCal instances.
+     * @param options iCalendar export options.
+     * @return iCalendar text.
+     */
     toICal(value: Array<JSCalendarObject | {
         data: JSCalendarObject;
     }>, options?: import("./ical.js").ICalOptions): string;
 };
-export {};