@chipmobilesdk/rn-notification 0.4.0 → 0.4.1

package/src/recurrence/expand.ts

@@ -1,319 +1,326 @@
-/**
- * Recurrence expansion.
- *
- * Written first-party rather than delegated to an RFC 5545 library, because the
- * daylight-saving rules here are specified behaviour (FR-008) rather than a
- * dependency's opinion, and because expansion must be provable with no device.
- *
- * Determinism is the hard requirement: the same rule, anchoring mode, zone, and
- * evaluation moment must produce exactly the same occurrences in the same order
- * on every run and on both platforms. Without that, reconciliation could not be
- * idempotent over a recurring series.
- */
-
-import type {
-	RecurrenceRule,
-	RecurrencePattern,
-	DailyPattern,
-	WeeklyPattern,
-	MonthlyByDayPattern,
-	LookaheadConfig,
-	Weekday,
-} from '../contract/recurrence';
-import type { AnchoringMode } from '../contract/notification';
-import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
-import { instantForParts, partsInZone, type WallClockParts } from '../schedule/anchor';
-
-export interface Occurrence {
-	/** Derived from the series id and the occurrence's calendar slot — never random. */
-	readonly id: string;
-	/** The calendar slot, `YYYYMMDDTHHmm`. Orders occurrences and survives a zone change. */
-	readonly key: string;
-	readonly seriesId: string;
-	readonly at: number;
-	readonly anchoring: AnchoringMode;
-	/** True when an earlier expansion already counted this occurrence. */
-	readonly previouslyEmitted: boolean;
-}
-
-const pad = (value: number, width: number) => String(value).padStart(width, '0');
-
-/**
- * The calendar slot of an occurrence: the date and clock time the rule asked
- * for, in the frame the series is anchored in. Fixed-width, so comparing two
- * keys as strings compares them in time.
- */
-export function occurrenceKey(parts: WallClockParts): string {
-	return `${pad(parts.year, 4)}${pad(parts.month, 2)}${pad(parts.day, 2)}T${pad(parts.hour, 2)}${pad(parts.minute, 2)}`;
-}
-
-/**
- * Occurrence identity.
- *
- * Derived from the series and the calendar slot, not the instant. Re-expanding
- * the same series produces the same identifiers, which is what lets a refresh
- * recognize an occurrence it already scheduled. Until 0.4.0 the instant was
- * used, so after a time-zone change re-anchoring kept the old identifier while
- * the window refresh derived a new one, and the occurrence was scheduled twice.
- */
-export function occurrenceId(seriesId: string, slot: WallClockParts | string): string {
-	return `${seriesId}#${typeof slot === 'string' ? slot : occurrenceKey(slot)}`;
-}
-
-const MS_PER_DAY = 24 * 60 * 60 * 1000;
-
-function validatePattern(pattern: RecurrencePattern): void {
-	const { hour, minute } = pattern;
-
-	if (!Number.isInteger(hour) || hour < 0 || hour > 23) {
-		throw new NotificationError(
-			DIAGNOSTIC_CODES.INVALID_RECURRENCE,
-			'Recurrence hour must be an integer from 0 to 23.',
-			{ hour },
-		);
-	}
-	if (!Number.isInteger(minute) || minute < 0 || minute > 59) {
-		throw new NotificationError(
-			DIAGNOSTIC_CODES.INVALID_RECURRENCE,
-			'Recurrence minute must be an integer from 0 to 59.',
-			{ minute },
-		);
-	}
-
-	const interval = pattern.interval ?? 1;
-	if (!Number.isInteger(interval) || interval < 1) {
-		throw new NotificationError(
-			DIAGNOSTIC_CODES.INVALID_RECURRENCE,
-			'Recurrence interval must be a positive integer.',
-			{ interval },
-		);
-	}
-
-	if (pattern.kind === 'weekly') {
-		if (pattern.weekdays.length === 0) {
-			throw new NotificationError(
-				DIAGNOSTIC_CODES.INVALID_RECURRENCE,
-				'A weekly recurrence must name at least one weekday.',
-			);
-		}
-		for (const day of pattern.weekdays) {
-			if (!Number.isInteger(day) || day < 0 || day > 6) {
-				throw new NotificationError(
-					DIAGNOSTIC_CODES.INVALID_RECURRENCE,
-					'Weekdays must be integers from 0 (Sunday) to 6 (Saturday).',
-					{ day },
-				);
-			}
-		}
-	}
-
-	if (pattern.kind === 'monthlyByDay') {
-		if (!Number.isInteger(pattern.dayOfMonth) || pattern.dayOfMonth < 1 || pattern.dayOfMonth > 31) {
-			throw new NotificationError(
-				DIAGNOSTIC_CODES.INVALID_RECURRENCE,
-				'Day of month must be an integer from 1 to 31.',
-				{ dayOfMonth: pattern.dayOfMonth },
-			);
-		}
-	}
-}
-
-/** Calendar date in the anchoring zone, carrying the pattern's clock time. */
-function partsFor(date: { year: number; month: number; day: number }, pattern: RecurrencePattern): WallClockParts {
-	return {
-		year: date.year,
-		month: date.month,
-		day: date.day,
-		hour: pattern.hour,
-		minute: pattern.minute,
-		second: 0,
-	};
-}
-
-function addDays(parts: WallClockParts, days: number): WallClockParts {
-	const shifted = new Date(Date.UTC(parts.year, parts.month - 1, parts.day) + days * MS_PER_DAY);
-	return {
-		year: shifted.getUTCFullYear(),
-		month: shifted.getUTCMonth() + 1,
-		day: shifted.getUTCDate(),
-		hour: parts.hour,
-		minute: parts.minute,
-		second: 0,
-	};
-}
-
-function weekdayOf(parts: WallClockParts): Weekday {
-	return new Date(Date.UTC(parts.year, parts.month - 1, parts.day)).getUTCDay() as Weekday;
-}
-
-function daysInMonth(year: number, month: number): number {
-	return new Date(Date.UTC(year, month, 0)).getUTCDate();
-}
-
-export interface ExpandInput {
-	readonly rule: RecurrenceRule;
-	/** Occurrences strictly after this instant are produced. */
-	readonly from: number;
-	readonly lookahead: LookaheadConfig;
-	/** Zone the series is anchored against. Ignored for absolute anchoring. */
-	readonly timeZone: string;
-	/** How many occurrences the series has already emitted, for count-limited rules. */
-	readonly alreadyEmitted?: number;
-	/**
-	 * Key of the latest occurrence an earlier expansion emitted. Occurrences at or
-	 * before it are produced again — they are still in the window — but are not
-	 * counted again. Counting them on every refresh is what ended count-limited
-	 * series early.
-	 */
-	readonly lastEmittedKey?: string;
-}
-
-export interface ExpandResult {
-	readonly occurrences: readonly Occurrence[];
-	/** The horizon expansion reached. */
-	readonly expandedThrough: number;
-	/** True when the series produced its final occurrence. */
-	readonly exhausted: boolean;
-}
-
-/**
- * Expands a rule inside the lookahead window.
- *
- * Bounded by both a duration and a count, because either alone fails: a
- * duration alone lets a frequent series exhaust the platform ceiling, and a
- * count alone leaves an annual series scheduled a decade out.
- */
-export function expand(input: ExpandInput): ExpandResult {
-	const { rule, from, lookahead, timeZone } = input;
-	validatePattern(rule.pattern);
-
-	const anchoring = rule.anchoring ?? 'wallClock';
-	const horizon = from + lookahead.days * MS_PER_DAY;
-	const start = Math.max(rule.startAt ?? from, from);
-	const { lastEmittedKey } = input;
-
-	const occurrences: Occurrence[] = [];
-	let cursor = partsFor(partsInZone(start, timeZone), rule.pattern);
-	// Position of the next not-yet-counted occurrence, for count-limited rules.
-	let index = input.alreadyEmitted ?? 0;
-	let exhausted = false;
-
-	// Bounded independently of the emit conditions so a pattern that matches
-	// nothing (e.g. day 31 in February) can never spin forever.
-	const maxIterations = lookahead.days * 2 + 400;
-
-	for (let iteration = 0; iteration < maxIterations; iteration += 1) {
-		if (occurrences.length >= lookahead.occurrencesPerSeries) break;
-
-		const candidate = nextCandidate(cursor, rule.pattern, iteration === 0);
-		if (candidate === undefined) break;
-		cursor = candidate;
-
-		const at =
-			anchoring === 'absolute'
-				? Date.UTC(cursor.year, cursor.month - 1, cursor.day, cursor.hour, cursor.minute, 0)
-				: instantForParts(cursor, timeZone);
-
-		if (at > horizon) break;
-
-		if (at > start) {
-			if (rule.end.kind === 'untilDate' && at > rule.end.until) {
-				exhausted = true;
-				break;
-			}
-			const key = occurrenceKey(cursor);
-			const previouslyEmitted = lastEmittedKey !== undefined && key <= lastEmittedKey;
-			if (!previouslyEmitted && rule.end.kind === 'count' && index >= rule.end.count) {
-				exhausted = true;
-				break;
-			}
-
-			occurrences.push({
-				id: occurrenceId(rule.id, key),
-				key,
-				seriesId: rule.id,
-				at,
-				anchoring,
-				previouslyEmitted,
-			});
-			if (!previouslyEmitted) index += 1;
-		}
-
-		cursor = advance(cursor, rule.pattern);
-	}
-
-	return {
-		occurrences,
-		expandedThrough: horizon,
-		exhausted,
-	};
-}
-
-/** Moves the cursor onto the first date the pattern actually matches. */
-function nextCandidate(
-	cursor: WallClockParts,
-	pattern: RecurrencePattern,
-	isFirst: boolean,
-): WallClockParts | undefined {
-	if (pattern.kind === 'daily') return cursor;
-
-	if (pattern.kind === 'weekly') {
-		const wanted = new Set((pattern as WeeklyPattern).weekdays);
-		let candidate = cursor;
-		for (let step = 0; step < 14; step += 1) {
-			if (wanted.has(weekdayOf(candidate))) return candidate;
-			candidate = addDays(candidate, 1);
-		}
-		return undefined;
-	}
-
-	const monthly = pattern as MonthlyByDayPattern;
-	let candidate = cursor;
-	// Months shorter than the requested day are skipped rather than clamped: a
-	// caller asking for the 31st means the 31st, and inventing the 28th would be
-	// the package deciding something it was not asked to decide.
-	for (let step = 0; step < 48; step += 1) {
-		if (daysInMonth(candidate.year, candidate.month) >= monthly.dayOfMonth) {
-			const onDay = { ...candidate, day: monthly.dayOfMonth };
-			if (isFirst || onDay.day >= candidate.day || step > 0) return onDay;
-		}
-		candidate = firstOfNextMonth(candidate);
-	}
-	return undefined;
-}
-
-function firstOfNextMonth(parts: WallClockParts): WallClockParts {
-	const month = parts.month === 12 ? 1 : parts.month + 1;
-	const year = parts.month === 12 ? parts.year + 1 : parts.year;
-	return { ...parts, year, month, day: 1 };
-}
-
-/** Steps the cursor past the occurrence just produced. */
-function advance(cursor: WallClockParts, pattern: RecurrencePattern): WallClockParts {
-	const interval = pattern.interval ?? 1;
-
-	if (pattern.kind === 'daily') {
-		return addDays(cursor, (pattern as DailyPattern).interval ?? 1);
-	}
-
-	if (pattern.kind === 'weekly') {
-		const wanted = [...new Set((pattern as WeeklyPattern).weekdays)].sort((a, b) => a - b);
-		const current = weekdayOf(cursor);
-		const next = wanted.find(day => day > current);
-
-		// Wrapping into a new week is where the interval applies — stepping day by
-		// day within the week would multiply the interval by the weekday count.
-		return next === undefined
-			? addDays(cursor, 7 * interval - current + wanted[0])
-			: addDays(cursor, next - current);
-	}
-
-	const monthly = pattern as MonthlyByDayPattern;
-	let year = cursor.year;
-	let month = cursor.month + interval;
-	while (month > 12) {
-		month -= 12;
-		year += 1;
-	}
-	return { ...cursor, year, month, day: Math.min(monthly.dayOfMonth, daysInMonth(year, month)) };
-}
+/**
+ * Recurrence expansion.
+ *
+ * Written first-party rather than delegated to an RFC 5545 library, because the
+ * daylight-saving rules here are specified behaviour (FR-008) rather than a
+ * dependency's opinion, and because expansion must be provable with no device.
+ *
+ * Determinism is the hard requirement: the same rule, anchoring mode, zone, and
+ * evaluation moment must produce exactly the same occurrences in the same order
+ * on every run and on both platforms. Without that, reconciliation could not be
+ * idempotent over a recurring series.
+ */
+
+import type {
+	RecurrenceRule,
+	RecurrencePattern,
+	DailyPattern,
+	WeeklyPattern,
+	MonthlyByDayPattern,
+	LookaheadConfig,
+	Weekday,
+} from '../contract/recurrence';
+import type { AnchoringMode } from '../contract/notification';
+import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
+import { instantForParts, partsInZone, type WallClockParts } from '../schedule/anchor';
+
+export interface Occurrence {
+	/** Derived from the series id and the occurrence's calendar slot — never random. */
+	readonly id: string;
+	/** The calendar slot, `YYYYMMDDTHHmm`. Orders occurrences and survives a zone change. */
+	readonly key: string;
+	readonly seriesId: string;
+	readonly at: number;
+	readonly anchoring: AnchoringMode;
+	/** True when an earlier expansion already counted this occurrence. */
+	readonly previouslyEmitted: boolean;
+}
+
+const pad = (value: number, width: number) => String(value).padStart(width, '0');
+
+/**
+ * The calendar slot of an occurrence: the date and clock time the rule asked
+ * for, in the frame the series is anchored in. Fixed-width, so comparing two
+ * keys as strings compares them in time.
+ */
+export function occurrenceKey(parts: WallClockParts): string {
+	return `${pad(parts.year, 4)}${pad(parts.month, 2)}${pad(parts.day, 2)}T${pad(parts.hour, 2)}${pad(parts.minute, 2)}`;
+}
+
+/**
+ * Occurrence identity.
+ *
+ * Derived from the series and the calendar slot, not the instant. Re-expanding
+ * the same series produces the same identifiers, which is what lets a refresh
+ * recognize an occurrence it already scheduled. Until 0.4.0 the instant was
+ * used, so after a time-zone change re-anchoring kept the old identifier while
+ * the window refresh derived a new one, and the occurrence was scheduled twice.
+ */
+export function occurrenceId(seriesId: string, slot: WallClockParts | string): string {
+	return `${seriesId}#${typeof slot === 'string' ? slot : occurrenceKey(slot)}`;
+}
+
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+function validatePattern(pattern: RecurrencePattern): void {
+	const { hour, minute } = pattern;
+
+	if (!Number.isInteger(hour) || hour < 0 || hour > 23) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.INVALID_RECURRENCE,
+			'Recurrence hour must be an integer from 0 to 23.',
+			{ hour },
+		);
+	}
+	if (!Number.isInteger(minute) || minute < 0 || minute > 59) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.INVALID_RECURRENCE,
+			'Recurrence minute must be an integer from 0 to 59.',
+			{ minute },
+		);
+	}
+
+	const interval = pattern.interval ?? 1;
+	if (!Number.isInteger(interval) || interval < 1) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.INVALID_RECURRENCE,
+			'Recurrence interval must be a positive integer.',
+			{ interval },
+		);
+	}
+
+	if (pattern.kind === 'weekly') {
+		if (pattern.weekdays.length === 0) {
+			throw new NotificationError(
+				DIAGNOSTIC_CODES.INVALID_RECURRENCE,
+				'A weekly recurrence must name at least one weekday.',
+			);
+		}
+		for (const day of pattern.weekdays) {
+			if (!Number.isInteger(day) || day < 0 || day > 6) {
+				throw new NotificationError(
+					DIAGNOSTIC_CODES.INVALID_RECURRENCE,
+					'Weekdays must be integers from 0 (Sunday) to 6 (Saturday).',
+					{ day },
+				);
+			}
+		}
+	}
+
+	if (pattern.kind === 'monthlyByDay') {
+		if (
+			!Number.isInteger(pattern.dayOfMonth) ||
+			pattern.dayOfMonth < 1 ||
+			pattern.dayOfMonth > 31
+		) {
+			throw new NotificationError(
+				DIAGNOSTIC_CODES.INVALID_RECURRENCE,
+				'Day of month must be an integer from 1 to 31.',
+				{ dayOfMonth: pattern.dayOfMonth },
+			);
+		}
+	}
+}
+
+/** Calendar date in the anchoring zone, carrying the pattern's clock time. */
+function partsFor(
+	date: { year: number; month: number; day: number },
+	pattern: RecurrencePattern,
+): WallClockParts {
+	return {
+		year: date.year,
+		month: date.month,
+		day: date.day,
+		hour: pattern.hour,
+		minute: pattern.minute,
+		second: 0,
+	};
+}
+
+function addDays(parts: WallClockParts, days: number): WallClockParts {
+	const shifted = new Date(Date.UTC(parts.year, parts.month - 1, parts.day) + days * MS_PER_DAY);
+	return {
+		year: shifted.getUTCFullYear(),
+		month: shifted.getUTCMonth() + 1,
+		day: shifted.getUTCDate(),
+		hour: parts.hour,
+		minute: parts.minute,
+		second: 0,
+	};
+}
+
+function weekdayOf(parts: WallClockParts): Weekday {
+	return new Date(Date.UTC(parts.year, parts.month - 1, parts.day)).getUTCDay() as Weekday;
+}
+
+function daysInMonth(year: number, month: number): number {
+	return new Date(Date.UTC(year, month, 0)).getUTCDate();
+}
+
+export interface ExpandInput {
+	readonly rule: RecurrenceRule;
+	/** Occurrences strictly after this instant are produced. */
+	readonly from: number;
+	readonly lookahead: LookaheadConfig;
+	/** Zone the series is anchored against. Ignored for absolute anchoring. */
+	readonly timeZone: string;
+	/** How many occurrences the series has already emitted, for count-limited rules. */
+	readonly alreadyEmitted?: number;
+	/**
+	 * Key of the latest occurrence an earlier expansion emitted. Occurrences at or
+	 * before it are produced again — they are still in the window — but are not
+	 * counted again. Counting them on every refresh is what ended count-limited
+	 * series early.
+	 */
+	readonly lastEmittedKey?: string;
+}
+
+export interface ExpandResult {
+	readonly occurrences: readonly Occurrence[];
+	/** The horizon expansion reached. */
+	readonly expandedThrough: number;
+	/** True when the series produced its final occurrence. */
+	readonly exhausted: boolean;
+}
+
+/**
+ * Expands a rule inside the lookahead window.
+ *
+ * Bounded by both a duration and a count, because either alone fails: a
+ * duration alone lets a frequent series exhaust the platform ceiling, and a
+ * count alone leaves an annual series scheduled a decade out.
+ */
+export function expand(input: ExpandInput): ExpandResult {
+	const { rule, from, lookahead, timeZone } = input;
+	validatePattern(rule.pattern);
+
+	const anchoring = rule.anchoring ?? 'wallClock';
+	const horizon = from + lookahead.days * MS_PER_DAY;
+	const start = Math.max(rule.startAt ?? from, from);
+	const { lastEmittedKey } = input;
+
+	const occurrences: Occurrence[] = [];
+	let cursor = partsFor(partsInZone(start, timeZone), rule.pattern);
+	// Position of the next not-yet-counted occurrence, for count-limited rules.
+	let index = input.alreadyEmitted ?? 0;
+	let exhausted = false;
+
+	// Bounded independently of the emit conditions so a pattern that matches
+	// nothing (e.g. day 31 in February) can never spin forever.
+	const maxIterations = lookahead.days * 2 + 400;
+
+	for (let iteration = 0; iteration < maxIterations; iteration += 1) {
+		if (occurrences.length >= lookahead.occurrencesPerSeries) break;
+
+		const candidate = nextCandidate(cursor, rule.pattern, iteration === 0);
+		if (candidate === undefined) break;
+		cursor = candidate;
+
+		const at =
+			anchoring === 'absolute'
+				? Date.UTC(cursor.year, cursor.month - 1, cursor.day, cursor.hour, cursor.minute, 0)
+				: instantForParts(cursor, timeZone);
+
+		if (at > horizon) break;
+
+		if (at > start) {
+			if (rule.end.kind === 'untilDate' && at > rule.end.until) {
+				exhausted = true;
+				break;
+			}
+			const key = occurrenceKey(cursor);
+			const previouslyEmitted = lastEmittedKey !== undefined && key <= lastEmittedKey;
+			if (!previouslyEmitted && rule.end.kind === 'count' && index >= rule.end.count) {
+				exhausted = true;
+				break;
+			}
+
+			occurrences.push({
+				id: occurrenceId(rule.id, key),
+				key,
+				seriesId: rule.id,
+				at,
+				anchoring,
+				previouslyEmitted,
+			});
+			if (!previouslyEmitted) index += 1;
+		}
+
+		cursor = advance(cursor, rule.pattern);
+	}
+
+	return {
+		occurrences,
+		expandedThrough: horizon,
+		exhausted,
+	};
+}
+
+/** Moves the cursor onto the first date the pattern actually matches. */
+function nextCandidate(
+	cursor: WallClockParts,
+	pattern: RecurrencePattern,
+	isFirst: boolean,
+): WallClockParts | undefined {
+	if (pattern.kind === 'daily') return cursor;
+
+	if (pattern.kind === 'weekly') {
+		const wanted = new Set((pattern as WeeklyPattern).weekdays);
+		let candidate = cursor;
+		for (let step = 0; step < 14; step += 1) {
+			if (wanted.has(weekdayOf(candidate))) return candidate;
+			candidate = addDays(candidate, 1);
+		}
+		return undefined;
+	}
+
+	const monthly = pattern as MonthlyByDayPattern;
+	let candidate = cursor;
+	// Months shorter than the requested day are skipped rather than clamped: a
+	// caller asking for the 31st means the 31st, and inventing the 28th would be
+	// the package deciding something it was not asked to decide.
+	for (let step = 0; step < 48; step += 1) {
+		if (daysInMonth(candidate.year, candidate.month) >= monthly.dayOfMonth) {
+			const onDay = { ...candidate, day: monthly.dayOfMonth };
+			if (isFirst || onDay.day >= candidate.day || step > 0) return onDay;
+		}
+		candidate = firstOfNextMonth(candidate);
+	}
+	return undefined;
+}
+
+function firstOfNextMonth(parts: WallClockParts): WallClockParts {
+	const month = parts.month === 12 ? 1 : parts.month + 1;
+	const year = parts.month === 12 ? parts.year + 1 : parts.year;
+	return { ...parts, year, month, day: 1 };
+}
+
+/** Steps the cursor past the occurrence just produced. */
+function advance(cursor: WallClockParts, pattern: RecurrencePattern): WallClockParts {
+	const interval = pattern.interval ?? 1;
+
+	if (pattern.kind === 'daily') {
+		return addDays(cursor, (pattern as DailyPattern).interval ?? 1);
+	}
+
+	if (pattern.kind === 'weekly') {
+		const wanted = [...new Set((pattern as WeeklyPattern).weekdays)].sort((a, b) => a - b);
+		const current = weekdayOf(cursor);
+		const next = wanted.find(day => day > current);
+
+		// Wrapping into a new week is where the interval applies — stepping day by
+		// day within the week would multiply the interval by the weekday count.
+		return next === undefined
+			? addDays(cursor, 7 * interval - current + wanted[0])
+			: addDays(cursor, next - current);
+	}
+
+	const monthly = pattern as MonthlyByDayPattern;
+	let year = cursor.year;
+	let month = cursor.month + interval;
+	while (month > 12) {
+		month -= 12;
+		year += 1;
+	}
+	return { ...cursor, year, month, day: Math.min(monthly.dayOfMonth, daysInMonth(year, month)) };
+}