@chipmobilesdk/rn-notification 0.1.0

package/src/recurrence/expand.ts

@@ -0,0 +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)) };
+}

package/src/recurrence/index.ts

@@ -0,0 +1,177 @@
+/**
+ * Series registration and the lookahead window.
+ *
+ * A caller declares a rule once. The package expands it inside a finite window
+ * and refreshes that window on its own, because only it knows when the horizon
+ * has moved — that is the one piece of recurrence knowledge the consumer does
+ * not have.
+ *
+ * Occurrences carry derived identifiers, so re-expanding a series recognises
+ * what it already scheduled instead of creating duplicates. That is what makes
+ * a window refresh with nothing to do cost zero platform operations.
+ */
+
+import type {
+	RecurrenceRule,
+	SeriesResult,
+	SeriesSummary,
+	LookaheadConfig,
+} from '../contract/recurrence';
+import type { NotificationRequest } from '../contract/notification';
+import type { ResolvedTone } from '../contract/channel';
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import type { StateManager } from '../state/record';
+import type { TimeZoneReader } from '../schedule/anchor';
+import { validateIdentifier } from '../schedule/validate-identifier';
+import { validateContent } from '../schedule/validate-content';
+import { expand, type Occurrence } from './expand';
+import { guardAgainstClockChange } from './clock-guard';
+import { listSeries as readLedger, readSeries, removeSeries, upsertSeries } from '../state/series-ledger';
+
+export interface RecurrenceDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly state: StateManager;
+	readonly resolveTone: (toneId: string) => ResolvedTone | undefined;
+	readonly timeZone: TimeZoneReader;
+	readonly now: () => number;
+	readonly lookahead: LookaheadConfig;
+	readonly canScheduleExactly: () => boolean;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+/** Builds the request for one occurrence from the series template. */
+function toRequest(rule: RecurrenceRule, occurrence: Occurrence): NotificationRequest {
+	return {
+		id: occurrence.id,
+		content: rule.template.content,
+		tone: rule.template.tone,
+		moment: { at: occurrence.at, anchoring: occurrence.anchoring },
+		routing: rule.template.routing,
+		actions: rule.template.actions,
+		ownerTag: rule.template.ownerTag,
+		groupTag: rule.template.groupTag,
+	};
+}
+
+export function createRecurrence(deps: RecurrenceDependencies) {
+	const emit = deps.emit ?? (() => {});
+
+	/** Expands and registers, scheduling only occurrences the device lacks. */
+	const materialize = async (rule: RecurrenceRule): Promise<SeriesResult> => {
+		const now = deps.now();
+		const zone = deps.timeZone();
+		const previous = readSeries(deps.state, rule.id);
+
+		const expansion = expand({
+			rule,
+			from: now,
+			lookahead: deps.lookahead,
+			timeZone: zone,
+			alreadyEmitted: previous?.emittedCount ?? 0,
+		});
+
+		const guarded = guardAgainstClockChange({
+			occurrences: expansion.occurrences,
+			previousHorizon: previous?.expandedThrough,
+			now,
+			previousNow: previous?.at,
+		});
+
+		if (guarded.discontinuity !== 'none') {
+			emit(
+				'CLOCK_DISCONTINUITY',
+				`Device clock moved ${guarded.discontinuity}; ${guarded.suppressed} already-handled occurrence(s) were suppressed rather than re-delivered.`,
+				{ direction: guarded.discontinuity, suppressed: guarded.suppressed, seriesId: rule.id },
+			);
+		}
+
+		const tone = deps.resolveTone(rule.template.tone);
+		if (tone === undefined) {
+			throw new Error(`Tone "${rule.template.tone}" was never declared.`);
+		}
+
+		// Only what the device lacks — this is why a no-change refresh is free.
+		const existing = new Set((await deps.engine.getPending()).map(entry => entry.id));
+		const approximate = !deps.canScheduleExactly();
+		let scheduled = 0;
+
+		for (const occurrence of guarded.occurrences) {
+			if (existing.has(occurrence.id)) continue;
+
+			await deps.engine.schedule({
+				request: toRequest(rule, occurrence),
+				resolvedAt: occurrence.at,
+				tone,
+				// The zone the series was expanded against; absent for absolute series.
+				anchoringGeneration: occurrence.anchoring === 'absolute' ? undefined : zone,
+				approximate,
+				seriesId: rule.id,
+			});
+			scheduled += 1;
+		}
+
+		const emittedCount = (previous?.emittedCount ?? 0) + guarded.occurrences.length;
+		upsertSeries(
+			deps.state,
+			rule,
+			{
+				expandedThrough: expansion.expandedThrough,
+				emittedCount,
+				exhausted: expansion.exhausted,
+			},
+			now,
+		);
+
+		return {
+			seriesId: rule.id,
+			scheduled,
+			expandedThrough: expansion.expandedThrough,
+			exhausted: expansion.exhausted,
+		};
+	};
+
+	return {
+		async registerSeries(rule: RecurrenceRule): Promise<SeriesResult> {
+			validateIdentifier(rule.id, 'seriesId');
+			validateContent(rule.template.content);
+			return materialize(rule);
+		},
+
+		/** Re-expands a tracked series. Called by the window-refresh maintenance step. */
+		async refreshSeries(rule: RecurrenceRule): Promise<SeriesResult> {
+			return materialize(rule);
+		},
+
+		async cancelSeries(seriesId: string): Promise<readonly string[]> {
+			validateIdentifier(seriesId, 'seriesId');
+
+			// Every occurrence already scheduled from this series goes, identified by
+			// its derived prefix rather than by a list the ledger would have to keep
+			// in sync with the device.
+			const pending = await deps.engine.getPending();
+			const ids = pending
+				.filter(entry => entry.seriesId === seriesId || entry.id.startsWith(`${seriesId}#`))
+				.map(entry => entry.id);
+
+			await deps.engine.cancelMany(ids);
+			removeSeries(deps.state, seriesId);
+			return ids;
+		},
+
+		async listSeries(): Promise<readonly SeriesSummary[]> {
+			const pending = await deps.engine.getPending();
+
+			return readLedger(deps.state).map(entry => ({
+				seriesId: entry.seriesId,
+				anchoring: entry.anchoring,
+				expandedThrough: entry.expandedThrough,
+				pendingOccurrences: pending.filter(
+					p => p.seriesId === entry.seriesId || p.id.startsWith(`${entry.seriesId}#`),
+				).length,
+				exhausted: entry.exhausted,
+			}));
+		},
+	};
+}
+
+export type Recurrence = ReturnType<typeof createRecurrence>;