@chipmobilesdk/rn-notification 0.1.1 → 0.2.0

package/src/recurrence/expand.ts

@@ -1,292 +1,292 @@
-/**
- * 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 instant — never random. */
-	readonly id: string;
-	readonly seriesId: string;
-	readonly at: number;
-	readonly anchoring: AnchoringMode;
-	readonly index: number;
-}
-
-/**
- * Occurrence identity.
- *
- * Derived from the series and the instant so re-expanding the same series
- * produces the same identifiers — which is what lets reconciliation recognize
- * an occurrence it already scheduled instead of creating a duplicate.
- */
-export function occurrenceId(seriesId: string, at: number): string {
-	return `${seriesId}#${at}`;
-}
-
-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;
-}
-
-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 alreadyEmitted = input.alreadyEmitted ?? 0;
-
-	const occurrences: Occurrence[] = [];
-	let cursor = partsFor(partsInZone(start, timeZone), rule.pattern);
-	let index = alreadyEmitted;
-	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;
-			}
-			if (rule.end.kind === 'count' && index >= rule.end.count) {
-				exhausted = true;
-				break;
-			}
-
-			occurrences.push({
-				id: occurrenceId(rule.id, at),
-				seriesId: rule.id,
-				at,
-				anchoring,
-				index,
-			});
-			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 instant — never random. */
+	readonly id: string;
+	readonly seriesId: string;
+	readonly at: number;
+	readonly anchoring: AnchoringMode;
+	readonly index: number;
+}
+
+/**
+ * Occurrence identity.
+ *
+ * Derived from the series and the instant so re-expanding the same series
+ * produces the same identifiers — which is what lets reconciliation recognize
+ * an occurrence it already scheduled instead of creating a duplicate.
+ */
+export function occurrenceId(seriesId: string, at: number): string {
+	return `${seriesId}#${at}`;
+}
+
+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;
+}
+
+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 alreadyEmitted = input.alreadyEmitted ?? 0;
+
+	const occurrences: Occurrence[] = [];
+	let cursor = partsFor(partsInZone(start, timeZone), rule.pattern);
+	let index = alreadyEmitted;
+	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;
+			}
+			if (rule.end.kind === 'count' && index >= rule.end.count) {
+				exhausted = true;
+				break;
+			}
+
+			occurrences.push({
+				id: occurrenceId(rule.id, at),
+				seriesId: rule.id,
+				at,
+				anchoring,
+				index,
+			});
+			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)) };
+}

package/src/repeat/expiry.ts

@@ -0,0 +1,55 @@
+/**
+ * Repeat expiry.
+ *
+ * When a stop marker is delivered, the alert it guards has run its declared
+ * course. This handler ends the sound and leaves the notification exactly where
+ * it is, then removes the marker.
+ *
+ * Nothing here imports the engine. It talks to the port, which is what lets the
+ * whole mechanism be proven on a virtual clock with no device.
+ */
+
+import type { DeliveryEvent, NotificationEngineAdapter } from '../engine/adapter';
+
+export interface RepeatExpiryDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export interface RepeatExpiryHandler {
+	/** Reacts to one delivery. Ignores anything that is not a stop marker. */
+	handle(event: DeliveryEvent): Promise<void>;
+	/** Removes the marker guarding a target, when the target is cancelled or replaced. */
+	release(targetId: string): Promise<void>;
+}
+
+export function createRepeatExpiryHandler(
+	deps: RepeatExpiryDependencies,
+): RepeatExpiryHandler {
+	return {
+		async handle(event: DeliveryEvent): Promise<void> {
+			const stop = event.repeatStop;
+			if (stop === undefined) return;
+
+			// Order matters. Silence first, remove the marker second: if the
+			// process dies between the two, a marker left behind is harmless
+			// noise, whereas a device left sounding is the failure this exists to
+			// prevent.
+			//
+			// `silenceDelivered` returning false is the ordinary case, not an
+			// error — it means the user already handled the notification. Checking
+			// the tray rather than racing to cancel the marker on interaction is
+			// what makes early handling correct by construction: even if the marker
+			// fires, there is nothing left to act on.
+			await deps.engine.silenceDelivered(stop.targetId);
+			await deps.engine.cancel(stop.markerId);
+		},
+
+		async release(targetId: string): Promise<void> {
+			const outstanding = await deps.engine.listRepeatStops();
+			const marker = outstanding.find(stop => stop.targetId === targetId);
+			if (marker === undefined) return;
+			await deps.engine.cancel(marker.markerId);
+		},
+	};
+}