@craftguild/jscalendar 0.2.0 → 0.3.0

package/dist/patch.js

@@ -1,91 +1,216 @@
 import { deepClone } from "./utils.js";
+const POINTER_SEPARATOR = "/";
+const TYPE_OBJECT = "object";
+const PATCH_ERROR_NAME = "PatchError";
+/**
+ * Error thrown when a patch operation is invalid.
+ */
 export class PatchError extends Error {
+    /**
+     * Create a new PatchError.
+     * @param message Error message.
+     */
     constructor(message) {
         super(message);
-        this.name = "PatchError";
+        this.name = PATCH_ERROR_NAME;
     }
 }
+/**
+ * Unescape a JSON Pointer segment.
+ * @param segment Escaped pointer segment.
+ * @return Unescaped pointer segment.
+ */
 function unescapePointer(segment) {
     return segment.replace(/~1/g, "/").replace(/~0/g, "~");
 }
+/**
+ * Normalize a JSON Pointer string to ensure it is absolute.
+ * @param pointer Pointer to normalize.
+ * @return Normalized pointer.
+ */
 function normalizePointer(pointer) {
-    return pointer.startsWith("/") ? pointer : `/${pointer}`;
+    return pointer.startsWith(POINTER_SEPARATOR)
+        ? pointer
+        : `${POINTER_SEPARATOR}${pointer}`;
 }
+/**
+ * Split a JSON Pointer into unescaped segments.
+ * @param pointer Pointer to split.
+ * @return Unescaped pointer segments.
+ */
 function splitPointer(pointer) {
     const normalized = normalizePointer(pointer);
-    if (normalized === "/")
+    if (normalized === POINTER_SEPARATOR)
         return [];
     return normalized
-        .split("/")
+        .split(POINTER_SEPARATOR)
         .slice(1)
         .map(unescapePointer);
 }
+/**
+ * Validate that no pointer is a prefix of another pointer.
+ * @param pointers Patch pointers to validate.
+ * @return Nothing.
+ */
 function validatePrefixConflicts(pointers) {
     const normalized = pointers.map(normalizePointer).sort();
     for (let i = 0; i < normalized.length; i += 1) {
         const current = normalized[i];
         for (let j = i + 1; j < normalized.length; j += 1) {
             const other = normalized[j];
-            if (other && other.startsWith(`${current}/`)) {
+            const prefix = `${current}${POINTER_SEPARATOR}`;
+            if (other && other.startsWith(prefix)) {
                 throw new PatchError(`Patch pointer conflict: ${current} is prefix of ${other}`);
             }
         }
     }
 }
+/**
+ * Ensure the value is not an array when traversing pointers.
+ * @param value Value to check.
+ * @param pointer Pointer for error context.
+ * @return Nothing.
+ */
 function assertNotArray(value, pointer) {
     if (Array.isArray(value)) {
         throw new PatchError(`Patch pointer references into array: ${pointer}`);
     }
 }
+/**
+ * Ensure a value is an object record for traversal.
+ * @param value Value to check.
+ * @param pointer Pointer for error context.
+ * @return Nothing.
+ */
 function assertObject(value, pointer) {
-    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    if (value === null || typeof value !== TYPE_OBJECT || Array.isArray(value)) {
         throw new PatchError(`Patch pointer references missing or non-object path: ${pointer}`);
     }
 }
+/**
+ * Ensure a value is a record at the current traversal position.
+ * @param value Value to check.
+ * @param pointer Pointer for error context.
+ * @return Nothing.
+ */
 function assertRecord(value, pointer) {
     if (value === null || Array.isArray(value)) {
         throw new PatchError(`Patch pointer references missing or non-object path: ${pointer}`);
     }
 }
-export function applyPatch(input, patch) {
-    const pointers = Object.keys(patch);
-    validatePrefixConflicts(pointers);
-    const target = deepClone(input);
-    assertRecord(target, "/");
+/**
+ * Apply a PatchObject to a target record.
+ * @param target Target record to mutate.
+ * @param patch Patch entries to apply.
+ * @return Nothing.
+ */
+function applyPatchEntries(target, patch) {
     for (const [rawPointer, value] of Object.entries(patch)) {
         const pointer = normalizePointer(rawPointer);
         const segments = splitPointer(pointer);
-        let current = target;
-        for (let i = 0; i < segments.length; i += 1) {
-            const segment = segments[i];
-            if (segment === undefined) {
-                throw new PatchError(`Patch pointer missing segment: ${pointer}`);
-            }
-            const isLast = i === segments.length - 1;
-            assertNotArray(current, pointer);
-            assertRecord(current, pointer);
-            if (isLast) {
-                if (value === null) {
-                    if (Object.prototype.hasOwnProperty.call(current, segment)) {
-                        delete current[segment];
-                    }
-                }
-                else {
-                    current[segment] = value;
-                }
-            }
-            else {
-                if (!Object.prototype.hasOwnProperty.call(current, segment)) {
-                    throw new PatchError(`Patch pointer missing path: ${pointer}`);
-                }
-                const next = current[segment];
-                if (next === undefined) {
-                    throw new PatchError(`Patch pointer missing path: ${pointer}`);
-                }
-                assertObject(next, pointer);
-                current = next;
-            }
+        applyPointerSegments(target, pointer, segments, value);
+    }
+}
+/**
+ * Apply patch segments to the target by walking each segment.
+ * @param target Target record to mutate.
+ * @param pointer Normalized pointer.
+ * @param segments Pointer segments.
+ * @param value Patch value for the pointer.
+ * @return Nothing.
+ */
+function applyPointerSegments(target, pointer, segments, value) {
+    let current = target;
+    for (let i = 0; i < segments.length; i += 1) {
+        const segment = ensureSegment(segments[i], pointer);
+        const isLast = isLastSegment(i, segments.length);
+        current = applySegment(current, segment, isLast, value, pointer);
+    }
+}
+/**
+ * Ensure the current segment is present.
+ * @param segment Segment to validate.
+ * @param pointer Pointer for error context.
+ * @return Validated segment.
+ */
+function ensureSegment(segment, pointer) {
+    if (segment === undefined) {
+        throw new PatchError(`Patch pointer missing segment: ${pointer}`);
+    }
+    return segment;
+}
+/**
+ * Determine if the index is the last segment.
+ * @param index Current index.
+ * @param length Total number of segments.
+ * @return True if this is the last segment.
+ */
+function isLastSegment(index, length) {
+    return index === length - 1;
+}
+/**
+ * Apply a single patch segment and return the next traversal record.
+ * @param current Current record.
+ * @param segment Current segment.
+ * @param isLast Whether this is the last segment.
+ * @param value Patch value.
+ * @param pointer Pointer for error context.
+ * @return Next record to traverse.
+ */
+function applySegment(current, segment, isLast, value, pointer) {
+    assertNotArray(current, pointer);
+    assertRecord(current, pointer);
+    if (isLast) {
+        applyValueAtSegment(current, segment, value);
+        return current;
+    }
+    return getNextRecord(current, segment, pointer);
+}
+/**
+ * Apply a value update or delete at the given segment.
+ * @param current Current record.
+ * @param segment Segment to update.
+ * @param value Patch value.
+ * @return Nothing.
+ */
+function applyValueAtSegment(current, segment, value) {
+    if (value === null) {
+        if (Object.prototype.hasOwnProperty.call(current, segment)) {
+            delete current[segment];
         }
+        return;
+    }
+    current[segment] = value;
+}
+/**
+ * Resolve the next record in the traversal, validating it exists and is an object.
+ * @param current Current record.
+ * @param segment Segment to traverse.
+ * @param pointer Pointer for error context.
+ * @return Next record to traverse.
+ */
+function getNextRecord(current, segment, pointer) {
+    if (!Object.prototype.hasOwnProperty.call(current, segment)) {
+        throw new PatchError(`Patch pointer missing path: ${pointer}`);
     }
+    const next = current[segment];
+    if (next === undefined) {
+        throw new PatchError(`Patch pointer missing path: ${pointer}`);
+    }
+    assertObject(next, pointer);
+    return next;
+}
+/**
+ * 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 function applyPatch(input, patch) {
+    const pointers = Object.keys(patch);
+    validatePrefixConflicts(pointers);
+    const target = deepClone(input);
+    assertRecord(target, POINTER_SEPARATOR);
+    applyPatchEntries(target, patch);
     return target;
 }

package/dist/recurrence/constants.d.ts

@@ -0,0 +1,13 @@
+export declare const TYPE_EVENT = "Event";
+export declare const TYPE_TASK = "Task";
+export declare const RSCALE_GREGORIAN = "gregorian";
+export declare const SKIP_OMIT = "omit";
+export declare const SKIP_FORWARD = "forward";
+export declare const SKIP_BACKWARD = "backward";
+export declare const FREQ_YEARLY = "yearly";
+export declare const FREQ_MONTHLY = "monthly";
+export declare const FREQ_WEEKLY = "weekly";
+export declare const FREQ_DAILY = "daily";
+export declare const FREQ_HOURLY = "hourly";
+export declare const FREQ_MINUTELY = "minutely";
+export declare const FREQ_SECONDLY = "secondly";

package/dist/recurrence/constants.js

@@ -0,0 +1,13 @@
+export const TYPE_EVENT = "Event";
+export const TYPE_TASK = "Task";
+export const RSCALE_GREGORIAN = "gregorian";
+export const SKIP_OMIT = "omit";
+export const SKIP_FORWARD = "forward";
+export const SKIP_BACKWARD = "backward";
+export const FREQ_YEARLY = "yearly";
+export const FREQ_MONTHLY = "monthly";
+export const FREQ_WEEKLY = "weekly";
+export const FREQ_DAILY = "daily";
+export const FREQ_HOURLY = "hourly";
+export const FREQ_MINUTELY = "minutely";
+export const FREQ_SECONDLY = "secondly";

package/dist/recurrence/date-utils.d.ts

@@ -0,0 +1,125 @@
+import type { DayOfWeek, DateTime } from "./types.js";
+import type { RecurrenceRule } from "../types.js";
+/**
+ * Advance a date-time by a recurrence interval.
+ * @param start Anchor date-time.
+ * @param frequency Recurrence frequency.
+ * @param amount Number of intervals to add.
+ * @param firstDay First day of week for weekly intervals.
+ * @return Date-time moved to the next interval boundary.
+ */
+export declare function addInterval(start: DateTime, frequency: RecurrenceRule["frequency"], amount: number, firstDay: DayOfWeek): DateTime;
+/**
+ * Parse local date time into structured data.
+ * @param value LocalDateTime string.
+ * @return Parsed date-time parts.
+ */
+export declare function parseLocalDateTime(value: string): DateTime;
+/**
+ * Format local date time as string.
+ * @param dt Date-time parts.
+ * @return LocalDateTime string.
+ */
+export declare function formatLocalDateTime(dt: DateTime): string;
+/**
+ * Pad a numeric value with leading zeros.
+ * @param value Number to pad.
+ * @param length Total length.
+ * @return Zero-padded string.
+ */
+export declare function pad(value: number, length: number): string;
+/**
+ * Add days to the target.
+ * @param dt Date-time parts.
+ * @param days Days to add.
+ * @return New date-time with days added.
+ */
+export declare function addDays(dt: DateTime, days: number): DateTime;
+/**
+ * Add hours to the target.
+ * @param dt Date-time parts.
+ * @param hours Hours to add.
+ * @return New date-time with hours added.
+ */
+export declare function addHours(dt: DateTime, hours: number): DateTime;
+/**
+ * Add minutes to the target.
+ * @param dt Date-time parts.
+ * @param minutes Minutes to add.
+ * @return New date-time with minutes added.
+ */
+export declare function addMinutes(dt: DateTime, minutes: number): DateTime;
+/**
+ * Add seconds to the target.
+ * @param dt Date-time parts.
+ * @param seconds Seconds to add.
+ * @return New date-time with seconds added.
+ */
+export declare function addSeconds(dt: DateTime, seconds: number): DateTime;
+/**
+ * Add months to the target.
+ * @param dt Date-time parts.
+ * @param months Months to add.
+ * @return New date-time with months added.
+ */
+export declare function addMonths(dt: DateTime, months: number): DateTime;
+/**
+ * Get day of week for a date-time.
+ * @param dt Date-time parts.
+ * @return Two-letter weekday code.
+ */
+export declare function dayOfWeek(dt: DateTime): DayOfWeek;
+/**
+ * Get day of year for a date-time.
+ * @param dt Date-time parts.
+ * @return Day of year (1-366).
+ */
+export declare function dayOfYear(dt: DateTime): number;
+/**
+ * Get number of days in a month.
+ * @param year Year number.
+ * @param month Month number (1-12).
+ * @return Days in the month.
+ */
+export declare function daysInMonth(year: number, month: number): number;
+/**
+ * Get number of days in a year.
+ * @param year Year number.
+ * @return Days in the year.
+ */
+export declare function daysInYear(year: number): number;
+/**
+ * Get the start of week for a date-time.
+ * @param dt Date-time parts.
+ * @param firstDay Weekday that starts the week.
+ * @return Date-time at the start of the week.
+ */
+export declare function startOfWeek(dt: DateTime, firstDay: DayOfWeek): DateTime;
+/**
+ * Get ISO-like week number for a date-time.
+ * @param dt Date-time parts.
+ * @param firstDay Weekday that starts the week.
+ * @return Week number for the given date.
+ */
+export declare function weekNumber(dt: DateTime, firstDay: DayOfWeek): number;
+/**
+ * Get total weeks in a year.
+ * @param year Year number.
+ * @param firstDay Weekday that starts the week.
+ * @return Total number of weeks in the year.
+ */
+export declare function totalWeeksInYear(year: number, firstDay: DayOfWeek): number;
+/**
+ * Get whole-day difference between two dates.
+ * @param a Start date.
+ * @param b End date.
+ * @return Whole-day difference (b - a).
+ */
+export declare function daysBetween(a: DateTime, b: DateTime): number;
+/**
+ * Compare two dates without time.
+ * @param a First date.
+ * @param b Second date.
+ * @return Negative/zero/positive comparison result.
+ */
+export declare function compareDate(a: DateTime, b: DateTime): number;

package/dist/recurrence/date-utils.js

@@ -0,0 +1,259 @@
+import { FREQ_DAILY, FREQ_HOURLY, FREQ_MINUTELY, FREQ_MONTHLY, FREQ_WEEKLY, FREQ_YEARLY } from "./constants.js";
+/**
+ * Advance a date-time by a recurrence interval.
+ * @param start Anchor date-time.
+ * @param frequency Recurrence frequency.
+ * @param amount Number of intervals to add.
+ * @param firstDay First day of week for weekly intervals.
+ * @return Date-time moved to the next interval boundary.
+ */
+export function addInterval(start, frequency, amount, firstDay) {
+    if (frequency === FREQ_YEARLY) {
+        return { year: start.year + amount, month: 1, day: 1, hour: 0, minute: 0, second: 0 };
+    }
+    if (frequency === FREQ_MONTHLY) {
+        const next = addMonths(start, amount);
+        return { year: next.year, month: next.month, day: 1, hour: 0, minute: 0, second: 0 };
+    }
+    if (frequency === FREQ_WEEKLY) {
+        const weekStart = startOfWeek(start, firstDay);
+        return addDays(weekStart, amount * 7);
+    }
+    if (frequency === FREQ_DAILY) {
+        return addDays(start, amount);
+    }
+    if (frequency === FREQ_HOURLY) {
+        return addHours(start, amount);
+    }
+    if (frequency === FREQ_MINUTELY) {
+        return addMinutes(start, amount);
+    }
+    return addSeconds(start, amount);
+}
+/**
+ * Parse local date time into structured data.
+ * @param value LocalDateTime string.
+ * @return Parsed date-time parts.
+ */
+export function parseLocalDateTime(value) {
+    const match = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})/.exec(value);
+    if (!match) {
+        throw new Error(`Invalid LocalDateTime: ${value}`);
+    }
+    return {
+        year: Number(match[1]),
+        month: Number(match[2]),
+        day: Number(match[3]),
+        hour: Number(match[4]),
+        minute: Number(match[5]),
+        second: Number(match[6]),
+    };
+}
+/**
+ * Format local date time as string.
+ * @param dt Date-time parts.
+ * @return LocalDateTime string.
+ */
+export function formatLocalDateTime(dt) {
+    return `${pad(dt.year, 4)}-${pad(dt.month, 2)}-${pad(dt.day, 2)}T${pad(dt.hour, 2)}:${pad(dt.minute, 2)}:${pad(dt.second, 2)}`;
+}
+/**
+ * Pad a numeric value with leading zeros.
+ * @param value Number to pad.
+ * @param length Total length.
+ * @return Zero-padded string.
+ */
+export function pad(value, length) {
+    return value.toString().padStart(length, "0");
+}
+/**
+ * Add days to the target.
+ * @param dt Date-time parts.
+ * @param days Days to add.
+ * @return New date-time with days added.
+ */
+export function addDays(dt, days) {
+    const ms = Date.UTC(dt.year, dt.month - 1, dt.day, dt.hour, dt.minute, dt.second) + days * 86400 * 1000;
+    const d = new Date(ms);
+    return {
+        year: d.getUTCFullYear(),
+        month: d.getUTCMonth() + 1,
+        day: d.getUTCDate(),
+        hour: dt.hour,
+        minute: dt.minute,
+        second: dt.second,
+    };
+}
+/**
+ * Add hours to the target.
+ * @param dt Date-time parts.
+ * @param hours Hours to add.
+ * @return New date-time with hours added.
+ */
+export function addHours(dt, hours) {
+    const ms = Date.UTC(dt.year, dt.month - 1, dt.day, dt.hour, dt.minute, dt.second) + hours * 3600 * 1000;
+    const d = new Date(ms);
+    return {
+        year: d.getUTCFullYear(),
+        month: d.getUTCMonth() + 1,
+        day: d.getUTCDate(),
+        hour: d.getUTCHours(),
+        minute: d.getUTCMinutes(),
+        second: d.getUTCSeconds(),
+    };
+}
+/**
+ * Add minutes to the target.
+ * @param dt Date-time parts.
+ * @param minutes Minutes to add.
+ * @return New date-time with minutes added.
+ */
+export function addMinutes(dt, minutes) {
+    return addSeconds(dt, minutes * 60);
+}
+/**
+ * Add seconds to the target.
+ * @param dt Date-time parts.
+ * @param seconds Seconds to add.
+ * @return New date-time with seconds added.
+ */
+export function addSeconds(dt, seconds) {
+    const ms = Date.UTC(dt.year, dt.month - 1, dt.day, dt.hour, dt.minute, dt.second) + seconds * 1000;
+    const d = new Date(ms);
+    return {
+        year: d.getUTCFullYear(),
+        month: d.getUTCMonth() + 1,
+        day: d.getUTCDate(),
+        hour: d.getUTCHours(),
+        minute: d.getUTCMinutes(),
+        second: d.getUTCSeconds(),
+    };
+}
+/**
+ * Add months to the target.
+ * @param dt Date-time parts.
+ * @param months Months to add.
+ * @return New date-time with months added.
+ */
+export function addMonths(dt, months) {
+    const total = (dt.year * 12 + (dt.month - 1)) + months;
+    const year = Math.floor(total / 12);
+    const month = (total % 12) + 1;
+    const day = Math.min(dt.day, daysInMonth(year, month));
+    return { year, month, day, hour: dt.hour, minute: dt.minute, second: dt.second };
+}
+/**
+ * Get day of week for a date-time.
+ * @param dt Date-time parts.
+ * @return Two-letter weekday code.
+ */
+export function dayOfWeek(dt) {
+    const d = new Date(Date.UTC(dt.year, dt.month - 1, dt.day));
+    const idx = d.getUTCDay();
+    if (idx === 0)
+        return "su";
+    if (idx === 1)
+        return "mo";
+    if (idx === 2)
+        return "tu";
+    if (idx === 3)
+        return "we";
+    if (idx === 4)
+        return "th";
+    if (idx === 5)
+        return "fr";
+    return "sa";
+}
+/**
+ * Get day of year for a date-time.
+ * @param dt Date-time parts.
+ * @return Day of year (1-366).
+ */
+export function dayOfYear(dt) {
+    const start = Date.UTC(dt.year, 0, 1);
+    const current = Date.UTC(dt.year, dt.month - 1, dt.day);
+    return Math.floor((current - start) / (24 * 3600 * 1000)) + 1;
+}
+/**
+ * Get number of days in a month.
+ * @param year Year number.
+ * @param month Month number (1-12).
+ * @return Days in the month.
+ */
+export function daysInMonth(year, month) {
+    return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+/**
+ * Get number of days in a year.
+ * @param year Year number.
+ * @return Days in the year.
+ */
+export function daysInYear(year) {
+    return new Date(Date.UTC(year + 1, 0, 0)).getUTCDate();
+}
+/**
+ * Get the start of week for a date-time.
+ * @param dt Date-time parts.
+ * @param firstDay Weekday that starts the week.
+ * @return Date-time at the start of the week.
+ */
+export function startOfWeek(dt, firstDay) {
+    const order = ["mo", "tu", "we", "th", "fr", "sa", "su"];
+    const dow = dayOfWeek(dt);
+    const offset = (order.indexOf(dow) - order.indexOf(firstDay) + 7) % 7;
+    return addDays(dt, -offset);
+}
+/**
+ * Get ISO-like week number for a date-time.
+ * @param dt Date-time parts.
+ * @param firstDay Weekday that starts the week.
+ * @return Week number for the given date.
+ */
+export function weekNumber(dt, firstDay) {
+    const yearStart = { year: dt.year, month: 1, day: 1, hour: 0, minute: 0, second: 0 };
+    const weekStart = startOfWeek(yearStart, firstDay);
+    const daysBeforeYear = daysBetween(weekStart, yearStart);
+    const daysInFirstWeek = 7 - daysBeforeYear;
+    const week1Start = daysInFirstWeek >= 4 ? weekStart : addDays(weekStart, 7);
+    if (compareDate(dt, week1Start) < 0) {
+        return totalWeeksInYear(dt.year - 1, firstDay);
+    }
+    const diff = daysBetween(week1Start, dt);
+    return Math.floor(diff / 7) + 1;
+}
+/**
+ * Get total weeks in a year.
+ * @param year Year number.
+ * @param firstDay Weekday that starts the week.
+ * @return Total number of weeks in the year.
+ */
+export function totalWeeksInYear(year, firstDay) {
+    const lastDay = { year, month: 12, day: 31, hour: 0, minute: 0, second: 0 };
+    return weekNumber(lastDay, firstDay);
+}
+/**
+ * Get whole-day difference between two dates.
+ * @param a Start date.
+ * @param b End date.
+ * @return Whole-day difference (b - a).
+ */
+export function daysBetween(a, b) {
+    const msA = Date.UTC(a.year, a.month - 1, a.day);
+    const msB = Date.UTC(b.year, b.month - 1, b.day);
+    return Math.floor((msB - msA) / (24 * 3600 * 1000));
+}
+/**
+ * Compare two dates without time.
+ * @param a First date.
+ * @param b Second date.
+ * @return Negative/zero/positive comparison result.
+ */
+export function compareDate(a, b) {
+    if (a.year !== b.year)
+        return a.year - b.year;
+    if (a.month !== b.month)
+        return a.month - b.month;
+    if (a.day !== b.day)
+        return a.day - b.day;
+    return 0;
+}

package/dist/recurrence/expand.d.ts

@@ -0,0 +1,23 @@
+import type { JSCalendarObject } from "../types.js";
+import type { RecurrenceRange } from "./types.js";
+/**
+ * Expand recurrence into occurrences.
+ * @param items JSCalendar objects to expand.
+ * @param range Date range bounds.
+ * @return Generator of expanded occurrences.
+ */
+export declare function expandRecurrence(items: JSCalendarObject[], range: RecurrenceRange): Generator<JSCalendarObject>;
+/**
+ * Expand recurrence paged into occurrences.
+ * @param items JSCalendar objects to expand.
+ * @param range Date range bounds.
+ * @param options Pagination options.
+ * @return Page of expanded items plus an optional next cursor.
+ */
+export declare function expandRecurrencePaged(items: JSCalendarObject[], range: RecurrenceRange, options: {
+    limit: number;
+    cursor?: string;
+}): {
+    items: JSCalendarObject[];
+    nextCursor?: string;
+};