@tuturuuu/utils 0.33.3 → 0.35.0

package/src/calendar-recurrence-edit.ts

@@ -0,0 +1,148 @@
+import { Temporal } from '@js-temporal/polyfill';
+import type {
+  CalendarRecurrenceAnchor,
+  CalendarRecurrenceRule,
+} from '@tuturuuu/types/primitives/calendar-recurrence';
+import { matchesCalendarRecurrenceDate } from './calendar-recurrence-pattern';
+import {
+  CalendarLocalDateTimeSchema,
+  validateCalendarRecurrence,
+} from './calendar-recurrence-validation';
+
+/** Validates immutable occurrence identity and counts slots before exceptions.
+ * Never trust a caller-provided instance index for COUNT or future splits. */
+export function inspectCalendarRecurrenceSlot(input: {
+  rule: CalendarRecurrenceRule;
+  anchor: CalendarRecurrenceAnchor;
+  originalStartLocal: string;
+}): {
+  precedingCount: number;
+  previousRule: CalendarRecurrenceRule | null;
+  remainingRule: CalendarRecurrenceRule;
+} {
+  const { rule, anchor } = validateCalendarRecurrence(input.rule, input.anchor);
+  const slot = Temporal.PlainDateTime.from(
+    CalendarLocalDateTimeSchema.parse(input.originalStartLocal)
+  );
+  const first = Temporal.PlainDateTime.from(anchor.startLocal);
+  if (
+    Temporal.PlainDateTime.compare(slot, first) < 0 ||
+    !slot.toPlainTime().equals(first.toPlainTime())
+  )
+    throw new RangeError('Not a series occurrence');
+  let precedingCount = 0;
+  let scanned = 0;
+  for (
+    let date = first.toPlainDate();
+    Temporal.PlainDate.compare(date, slot.toPlainDate()) <= 0;
+    date = date.add({ days: 1 })
+  ) {
+    if (++scanned > 36600)
+      throw new RangeError('Recurrence scan exceeds 100 years');
+    if (
+      rule.end.type === 'until' &&
+      Temporal.PlainDate.compare(date, rule.end.date) > 0
+    )
+      break;
+    if (!matchesCalendarRecurrenceDate(date, first.toPlainDate(), rule))
+      continue;
+    const local = date.toPlainDateTime(first.toPlainTime());
+    if (
+      !local
+        .toZonedDateTime(rule.timeZone, { disambiguation: 'compatible' })
+        .toPlainDateTime()
+        .equals(local)
+    )
+      continue;
+    if (rule.end.type === 'count' && precedingCount >= rule.end.count) break;
+    if (local.equals(slot)) {
+      return {
+        precedingCount,
+        previousRule:
+          precedingCount === 0
+            ? null
+            : {
+                ...rule,
+                end: {
+                  type: 'until',
+                  date: slot.toPlainDate().subtract({ days: 1 }).toString(),
+                },
+              },
+        remainingRule: {
+          ...rule,
+          ...(rule.end.type === 'count'
+            ? { end: { type: 'count', count: rule.end.count - precedingCount } }
+            : {}),
+        },
+      };
+    }
+    precedingCount++;
+  }
+  throw new RangeError('Not a series occurrence');
+}
+
+export function calendarAnchorAtSlot(
+  anchor: CalendarRecurrenceAnchor,
+  originalStartLocal: string
+): CalendarRecurrenceAnchor {
+  const start = Temporal.PlainDateTime.from(anchor.startLocal);
+  const duration = start.until(anchor.endLocal, { largestUnit: 'days' });
+  const slot = Temporal.PlainDateTime.from(
+    CalendarLocalDateTimeSchema.parse(originalStartLocal)
+  );
+  return {
+    ...anchor,
+    startLocal: slot.toString({ smallestUnit: 'second' }),
+    endLocal: slot.add(duration).toString({ smallestUnit: 'second' }),
+  };
+}
+
+/** Immutable original slot as a UTC instant for provider occurrence lookup. */
+export function calendarRecurrenceSlotInstant(input: {
+  rule: CalendarRecurrenceRule;
+  anchor: CalendarRecurrenceAnchor;
+  originalStartLocal: string;
+}) {
+  inspectCalendarRecurrenceSlot(input);
+  return Temporal.PlainDateTime.from(input.originalStartLocal)
+    .toZonedDateTime(input.rule.timeZone, { disambiguation: 'compatible' })
+    .toInstant()
+    .toString();
+}
+
+/** Normalize a provider date-time without falling back to the machine timezone. */
+export function calendarProviderDateTimeLocal(
+  input: { dateTime: string; timeZone?: string },
+  timeZone: string
+) {
+  const instant = /(?:Z|[+-]\d{2}:\d{2})$/i.test(input.dateTime)
+    ? Temporal.Instant.from(input.dateTime)
+    : Temporal.PlainDateTime.from(input.dateTime)
+        .toZonedDateTime(input.timeZone ?? timeZone, {
+          disambiguation: 'compatible',
+        })
+        .toInstant();
+  if (instant.epochNanoseconds % 1_000_000_000n !== 0n)
+    throw new RangeError(
+      'Provider occurrence has unsupported fractional precision'
+    );
+  return instant
+    .toZonedDateTimeISO(timeZone)
+    .toPlainDateTime()
+    .toString({ smallestUnit: 'second' });
+}
+
+/** Original slot interval, before moves/cancellations, for coverage fencing. */
+export function calendarRecurrenceSlotBounds(input: {
+  rule: CalendarRecurrenceRule;
+  anchor: CalendarRecurrenceAnchor;
+  originalStartLocal: string;
+}) {
+  const start = calendarRecurrenceSlotInstant(input);
+  const slot = calendarAnchorAtSlot(input.anchor, input.originalStartLocal);
+  const end = Temporal.PlainDateTime.from(slot.endLocal)
+    .toZonedDateTime(input.rule.timeZone, { disambiguation: 'compatible' })
+    .toInstant()
+    .toString();
+  return { start, end };
+}

package/src/calendar-recurrence-expansion.ts

@@ -0,0 +1,131 @@
+import { Temporal } from '@js-temporal/polyfill';
+import type {
+  CalendarRecurrenceAnchor,
+  CalendarRecurrenceException,
+  CalendarRecurrenceOccurrence,
+  CalendarRecurrenceRule,
+} from '@tuturuuu/types/primitives/calendar-recurrence';
+import { matchesCalendarRecurrenceDate } from './calendar-recurrence-pattern';
+import {
+  CalendarRecurrenceAnchorSchema,
+  CalendarRecurrenceExceptionSchema,
+  validateCalendarRecurrence,
+} from './calendar-recurrence-validation';
+
+const MAX_SCANNED_DAYS = 36600;
+
+/** A bounded recurrence expansion. Count is applied before cancellations/moves.
+ * Nonexistent DST wall-clock slots are skipped; folds use the earlier instant.
+ * Throws on a scan limit rather than presenting incomplete history as complete. */
+export function expandCalendarRecurrence(args: {
+  rule: CalendarRecurrenceRule;
+  anchor: CalendarRecurrenceAnchor;
+  from: string;
+  to: string;
+  exceptions?: CalendarRecurrenceException[];
+  limit?: number;
+}): { occurrences: CalendarRecurrenceOccurrence[]; truncated: boolean } {
+  const { rule, anchor } = validateCalendarRecurrence(args.rule, args.anchor);
+  const from = Temporal.Instant.from(args.from);
+  const to = Temporal.Instant.from(args.to);
+  if (Temporal.Instant.compare(from, to) >= 0)
+    throw new RangeError('Invalid recurrence range');
+  const limit = args.limit ?? 500;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 1000)
+    throw new RangeError('Occurrence limit must be 1–1000');
+  const start = Temporal.PlainDateTime.from(anchor.startLocal);
+  const duration = start.until(anchor.endLocal, { largestUnit: 'days' });
+  const first = start.toPlainDate();
+  const exceptionBySlot = new Map<string, CalendarRecurrenceException>();
+  let stop = to.toZonedDateTimeISO(rule.timeZone).toPlainDate();
+  if ((args.exceptions?.length ?? 0) > 1000)
+    throw new RangeError('Exception limit exceeds 1000');
+  for (const rawException of args.exceptions ?? []) {
+    const exception = CalendarRecurrenceExceptionSchema.parse(rawException);
+    const slot = Temporal.PlainDateTime.from(
+      exception.originalStartLocal
+    ).toString({ smallestUnit: 'second' });
+    if (exceptionBySlot.has(slot))
+      throw new RangeError('Duplicate recurrence exception slot');
+    if (exception.startLocal || exception.endLocal) {
+      CalendarRecurrenceAnchorSchema.parse({
+        startLocal: exception.startLocal,
+        endLocal: exception.endLocal,
+        allDay: anchor.allDay,
+      });
+    }
+    exceptionBySlot.set(slot, exception);
+    const date = Temporal.PlainDateTime.from(slot).toPlainDate();
+    if (Temporal.PlainDate.compare(date, stop) > 0) stop = date;
+  }
+  if (
+    rule.end.type === 'until' &&
+    Temporal.PlainDate.compare(stop, rule.end.date) > 0
+  )
+    stop = Temporal.PlainDate.from(rule.end.date);
+  // An uncounted rule necessarily visits every date through the effective stop.
+  // Reject oversized history before constructing thousands of zoned occurrences.
+  // COUNT can terminate earlier, so its existing incremental guard remains below.
+  if (
+    rule.end.type !== 'count' &&
+    first.until(stop, { largestUnit: 'days' }).days >= MAX_SCANNED_DAYS
+  )
+    throw new RangeError('Recurrence scan exceeds 100 years');
+  const occurrences: CalendarRecurrenceOccurrence[] = [];
+  let count = 0;
+  let scanned = 0;
+  for (
+    let date = first;
+    Temporal.PlainDate.compare(date, stop) <= 0;
+    date = date.add({ days: 1 })
+  ) {
+    if (++scanned > MAX_SCANNED_DAYS)
+      throw new RangeError('Recurrence scan exceeds 100 years');
+    if (!matchesCalendarRecurrenceDate(date, first, rule)) continue;
+    const local = date.toPlainDateTime(start.toPlainTime());
+    const zoned = local.toZonedDateTime(rule.timeZone, {
+      disambiguation: 'compatible',
+    });
+    // RFC 5545 invalid/nonexistent local times do not consume COUNT.
+    if (!zoned.toPlainDateTime().equals(local)) continue;
+    if (rule.end.type === 'count' && ++count > rule.end.count) break;
+    const slot = local.toString({ smallestUnit: 'second' });
+    const exception = exceptionBySlot.get(slot);
+    if (exception?.cancelled) continue;
+    const actualStart = exception?.startLocal
+      ? Temporal.PlainDateTime.from(exception.startLocal)
+      : local;
+    const actualEnd = exception?.endLocal
+      ? Temporal.PlainDateTime.from(exception.endLocal)
+      : local.add(duration);
+    const startInstant = actualStart
+      .toZonedDateTime(rule.timeZone, { disambiguation: 'compatible' })
+      .toInstant();
+    const endInstant = actualEnd
+      .toZonedDateTime(rule.timeZone, { disambiguation: 'compatible' })
+      .toInstant();
+    if (Temporal.Instant.compare(endInstant, startInstant) <= 0)
+      throw new RangeError('Occurrence end must follow start');
+    if (
+      Temporal.Instant.compare(startInstant, to) >= 0 ||
+      Temporal.Instant.compare(endInstant, from) <= 0
+    )
+      continue;
+    occurrences.push({
+      originalStartLocal: slot,
+      start_at: startInstant.toString(),
+      end_at: endInstant.toString(),
+      is_all_day: anchor.allDay,
+      isException: Boolean(exception),
+    });
+  }
+  occurrences.sort(
+    (a, b) =>
+      Temporal.Instant.compare(a.start_at, b.start_at) ||
+      a.originalStartLocal.localeCompare(b.originalStartLocal)
+  );
+  return {
+    occurrences: occurrences.slice(0, limit),
+    truncated: occurrences.length > limit,
+  };
+}

package/src/calendar-recurrence-local.ts

@@ -0,0 +1,45 @@
+import { Temporal } from '@js-temporal/polyfill';
+import type { CalendarRecurrenceAnchor } from '@tuturuuu/types/primitives/calendar-recurrence';
+export function recurrenceLocalParts(value: string) {
+  const date = Temporal.PlainDateTime.from(value);
+  return { day: date.day, month: date.month, dayOfWeek: date.dayOfWeek };
+}
+export function recurrenceInitialTimes(timeZone: string, now: Date) {
+  const start = Temporal.Instant.from(now.toISOString())
+    .toZonedDateTimeISO(timeZone)
+    .toPlainDateTime()
+    .with({ second: 0, millisecond: 0 });
+  return {
+    startLocal: start.toString({ smallestUnit: 'minute' }),
+    endLocal: start.add({ hours: 1 }).toString({ smallestUnit: 'minute' }),
+    day: start.day,
+    dayOfWeek: start.dayOfWeek,
+  };
+}
+export function recurrenceInstantLocal(instant: string, timeZone: string) {
+  return Temporal.Instant.from(instant)
+    .toZonedDateTimeISO(timeZone)
+    .toPlainDateTime()
+    .toString({ smallestUnit: 'minute' });
+}
+export function recurrenceLocalAnchor(
+  start: string,
+  end: string,
+  allDay: boolean
+): CalendarRecurrenceAnchor {
+  return {
+    startLocal: Temporal.PlainDateTime.from(start).toString({
+      smallestUnit: 'second',
+    }),
+    endLocal: Temporal.PlainDateTime.from(end).toString({
+      smallestUnit: 'second',
+    }),
+    allDay,
+  };
+}
+export function recurrenceMidnightRange(startLocal: string, endLocal: string) {
+  const start = Temporal.PlainDateTime.from(startLocal).toPlainDate();
+  let end = Temporal.PlainDateTime.from(endLocal).toPlainDate();
+  if (Temporal.PlainDate.compare(end, start) <= 0) end = start.add({ days: 1 });
+  return { startLocal: `${start}T00:00`, endLocal: `${end}T00:00` };
+}

package/src/calendar-recurrence-pattern.ts

@@ -0,0 +1,54 @@
+import type { Temporal } from '@js-temporal/polyfill';
+import type { CalendarRecurrenceRule } from '@tuturuuu/types/primitives/calendar-recurrence';
+export const CALENDAR_WEEKDAYS = [
+  'MO',
+  'TU',
+  'WE',
+  'TH',
+  'FR',
+  'SA',
+  'SU',
+] as const;
+export function matchesCalendarRecurrenceDate(
+  date: Temporal.PlainDate,
+  first: Temporal.PlainDate,
+  rule: CalendarRecurrenceRule
+) {
+  const days = first.until(date, { largestUnit: 'days' }).days;
+  if (rule.frequency === 'daily') return days % rule.interval === 0;
+  const day = CALENDAR_WEEKDAYS[date.dayOfWeek - 1]!;
+  if (rule.frequency === 'weekly') {
+    const weekStart = CALENDAR_WEEKDAYS.indexOf(rule.weekStartsOn ?? 'MO') + 1;
+    const leading = (first.dayOfWeek - weekStart + 7) % 7;
+    return (
+      Math.floor((days + leading) / 7) % rule.interval === 0 &&
+      rule.weekdays!.includes(day)
+    );
+  }
+  const months = (date.year - first.year) * 12 + date.month - first.month;
+  if (
+    rule.frequency === 'monthly'
+      ? months % rule.interval !== 0
+      : (date.year - first.year) % rule.interval !== 0 ||
+        date.month !== rule.month
+  )
+    return false;
+  if (rule.monthDay !== undefined)
+    return (
+      date.day ===
+      (rule.monthDayOverflow === 'last-day'
+        ? Math.min(rule.monthDay, date.daysInMonth)
+        : rule.monthDay)
+    );
+  // Graph relative patterns select the earliest matching ordinal weekday.
+  const candidates = rule.weekdays!.map((weekday) => {
+    const index = CALENDAR_WEEKDAYS.indexOf(weekday) + 1;
+    if (rule.weekIndex === -1) {
+      const last = date.with({ day: date.daysInMonth });
+      return last.day - ((last.dayOfWeek - index + 7) % 7);
+    }
+    const start = date.with({ day: 1 });
+    return 1 + ((index - start.dayOfWeek + 7) % 7) + (rule.weekIndex! - 1) * 7;
+  });
+  return date.day === Math.min(...candidates);
+}