@chipmobilesdk/rn-notification 0.4.0 → 0.5.0

package/src/recurrence/index.ts

@@ -1,259 +1,270 @@
-/**
- * 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.
- *
- * Occurrences are written through the shared `ScheduleWriter`, like every other
- * consumer notification, so a repeating tone gets its stop marker and the
- * platform ceiling is respected here too.
- */
-
-import type {
-	RecurrenceRule,
-	SeriesResult,
-	SeriesSummary,
-	LookaheadConfig,
-} from '../contract/recurrence';
-import type { NotificationRequest, PendingEntry } from '../contract/notification';
-import type { ResolvedTone } from '../contract/channel';
-import type { NotificationEngineAdapter } from '../engine/adapter';
-import type { StateManager } from '../state/record';
-import { partsInZone, type TimeZoneReader } from '../schedule/anchor';
-import { validateIdentifier } from '../schedule/validate-identifier';
-import { validateRequest } from '../schedule';
-import { createScheduleWriter } from '../schedule/writer';
-import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
-import { expand, occurrenceKey, 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,
-	};
-}
-
-const belongsTo = (entry: PendingEntry, seriesId: string) =>
-	entry.seriesId === seriesId || entry.id.startsWith(`${seriesId}#`);
-
-/**
- * The latest occurrence a ledger entry written before 0.4.0 had emitted. Those
- * entries kept no key, so it is read back off the device: the last occurrence
- * still pending is the last one emitted.
- */
-function recoverLastEmittedKey(
-	pending: readonly PendingEntry[],
-	anchoring: RecurrenceRule['anchoring'],
-	zone: string,
-): string | undefined {
-	if (pending.length === 0) return undefined;
-	const latest = Math.max(...pending.map(entry => entry.resolvedAt));
-	return occurrenceKey(partsInZone(latest, anchoring === 'absolute' ? 'UTC' : zone));
-}
-
-export function createRecurrence(deps: RecurrenceDependencies) {
-	const emit = deps.emit ?? (() => {});
-	const writer = createScheduleWriter(deps.engine);
-
-	/**
-	 * Validates the template as the request every occurrence will be, once, so
-	 * a series is refused at registration for exactly what a direct schedule
-	 * would be refused for — an undeclared tone, too many actions, an oversized
-	 * routing payload — rather than failing later inside maintenance.
-	 */
-	const validateTemplate = (rule: RecurrenceRule): ResolvedTone =>
-		validateRequest(
-			{
-				id: rule.id,
-				content: rule.template.content,
-				tone: rule.template.tone,
-				moment: { at: deps.now(), anchoring: rule.anchoring ?? 'wallClock' },
-				routing: rule.template.routing,
-				actions: rule.template.actions,
-				ownerTag: rule.template.ownerTag,
-				groupTag: rule.template.groupTag,
-			},
-			deps.resolveTone,
-		);
-
-	const toneFor = (rule: RecurrenceRule): ResolvedTone => {
-		const tone = deps.resolveTone(rule.template.tone);
-		if (tone === undefined) {
-			throw new NotificationError(
-				DIAGNOSTIC_CODES.UNDECLARED_TONE,
-				`Tone "${rule.template.tone}" was never declared in the package configuration.`,
-				{ toneId: rule.template.tone, seriesId: rule.id },
-			);
-		}
-		return tone;
-	};
-
-	/** Expands and registers, scheduling only occurrences the device lacks. */
-	const materialize = async (rule: RecurrenceRule, tone: ResolvedTone): Promise<SeriesResult> => {
-		const now = deps.now();
-		const zone = deps.timeZone();
-		const previous = readSeries(deps.state, rule.id);
-
-		const pending = await deps.engine.getPending();
-		const ofSeries = pending.filter(entry => belongsTo(entry, rule.id));
-
-		const expansion = expand({
-			rule,
-			from: now,
-			lookahead: deps.lookahead,
-			timeZone: zone,
-			alreadyEmitted: previous?.emittedCount ?? 0,
-			lastEmittedKey:
-				previous?.lastEmittedKey ??
-				(previous !== undefined ? recoverLastEmittedKey(ofSeries, rule.anchoring, zone) : undefined),
-		});
-
-		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 wanted = new Set(guarded.occurrences.map(occurrence => occurrence.id));
-
-		// Upcoming entries of this series the expansion no longer produces: ones
-		// written under the instant-based identity before 0.4.0, or ones whose slot
-		// the rule no longer has. Left in place, each would fire beside its
-		// replacement. Entries already due are left alone — they may be firing now.
-		const stale = ofSeries.filter(entry => !wanted.has(entry.id) && entry.resolvedAt > now);
-		for (const entry of stale) {
-			await writer.cancel(entry.id);
-		}
-
-		const onDevice = new Set(ofSeries.filter(entry => !stale.includes(entry)).map(entry => entry.id));
-		const missing = guarded.occurrences.filter(occurrence => !onDevice.has(occurrence.id));
-
-		// The same ceiling reconciliation respects: soonest first, the rest
-		// registered by a later refresh once they move into range.
-		const room = Math.max(0, (await writer.capacity()) - (pending.length - stale.length));
-		const toSchedule = missing.slice(0, room);
-		if (toSchedule.length < missing.length) {
-			emit(
-				DIAGNOSTIC_CODES.TRUNCATED_OVER_CEILING,
-				`Series "${rule.id}" has ${missing.length - toSchedule.length} occurrence(s) beyond the platform ceiling; they are registered by a later window refresh.`,
-				{ seriesId: rule.id, dropped: missing.length - toSchedule.length },
-			);
-		}
-
-		const approximate = !deps.canScheduleExactly();
-		for (const occurrence of toSchedule) {
-			await writer.write({
-				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,
-			});
-		}
-
-		// Counted once, when first emitted — whether or not the ceiling let it on
-		// the device yet. Occurrences re-produced from an earlier expansion are not
-		// counted again.
-		const newlyEmitted = guarded.occurrences.filter(occurrence => !occurrence.previouslyEmitted);
-		const lastEmittedKey =
-			newlyEmitted.length > 0 ? newlyEmitted[newlyEmitted.length - 1].key : previous?.lastEmittedKey;
-
-		upsertSeries(
-			deps.state,
-			rule,
-			{
-				expandedThrough: expansion.expandedThrough,
-				emittedCount: (previous?.emittedCount ?? 0) + newlyEmitted.length,
-				exhausted: expansion.exhausted,
-				lastEmittedKey,
-			},
-			now,
-		);
-
-		return {
-			seriesId: rule.id,
-			scheduled: toSchedule.length,
-			expandedThrough: expansion.expandedThrough,
-			exhausted: expansion.exhausted,
-			cancelled: stale.map(entry => entry.id),
-		};
-	};
-
-	return {
-		async registerSeries(rule: RecurrenceRule): Promise<SeriesResult> {
-			validateIdentifier(rule.id, 'seriesId');
-			return materialize(rule, validateTemplate(rule));
-		},
-
-		/** Re-expands a tracked series. Called by the window-refresh maintenance step. */
-		async refreshSeries(rule: RecurrenceRule): Promise<SeriesResult> {
-			return materialize(rule, toneFor(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 => belongsTo(entry, seriesId)).map(entry => entry.id);
-
-			await deps.engine.cancelMany(ids);
-			for (const id of ids) await writer.releaseStop(id);
-			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 => belongsTo(p, entry.seriesId)).length,
-				exhausted: entry.exhausted,
-			}));
-		},
-	};
-}
-
-export type Recurrence = ReturnType<typeof createRecurrence>;
+/**
+ * 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.
+ *
+ * Occurrences are written through the shared `ScheduleWriter`, like every other
+ * consumer notification, so a repeating tone gets its stop marker and the
+ * platform ceiling is respected here too.
+ */
+
+import type {
+	RecurrenceRule,
+	SeriesResult,
+	SeriesSummary,
+	LookaheadConfig,
+} from '../contract/recurrence';
+import type { NotificationRequest, PendingEntry } from '../contract/notification';
+import type { ResolvedTone } from '../contract/channel';
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import type { StateManager } from '../state/record';
+import { partsInZone, type TimeZoneReader } from '../schedule/anchor';
+import { validateIdentifier } from '../schedule/validate-identifier';
+import { validateRequest } from '../schedule';
+import { createScheduleWriter } from '../schedule/writer';
+import { DIAGNOSTIC_CODES, NotificationError } from '../contract/errors';
+import { expand, occurrenceKey, 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,
+	};
+}
+
+const belongsTo = (entry: PendingEntry, seriesId: string) =>
+	entry.seriesId === seriesId || entry.id.startsWith(`${seriesId}#`);
+
+/**
+ * The latest occurrence a ledger entry written before 0.4.0 had emitted. Those
+ * entries kept no key, so it is read back off the device: the last occurrence
+ * still pending is the last one emitted.
+ */
+function recoverLastEmittedKey(
+	pending: readonly PendingEntry[],
+	anchoring: RecurrenceRule['anchoring'],
+	zone: string,
+): string | undefined {
+	if (pending.length === 0) return undefined;
+	const latest = Math.max(...pending.map(entry => entry.resolvedAt));
+	return occurrenceKey(partsInZone(latest, anchoring === 'absolute' ? 'UTC' : zone));
+}
+
+export function createRecurrence(deps: RecurrenceDependencies) {
+	const emit = deps.emit ?? (() => {});
+	const writer = createScheduleWriter(deps.engine);
+
+	/**
+	 * Validates the template as the request every occurrence will be, once, so
+	 * a series is refused at registration for exactly what a direct schedule
+	 * would be refused for — an undeclared tone, too many actions, an oversized
+	 * routing payload — rather than failing later inside maintenance.
+	 */
+	const validateTemplate = (rule: RecurrenceRule): ResolvedTone =>
+		validateRequest(
+			{
+				id: rule.id,
+				content: rule.template.content,
+				tone: rule.template.tone,
+				moment: { at: deps.now(), anchoring: rule.anchoring ?? 'wallClock' },
+				routing: rule.template.routing,
+				actions: rule.template.actions,
+				ownerTag: rule.template.ownerTag,
+				groupTag: rule.template.groupTag,
+			},
+			deps.resolveTone,
+		);
+
+	const toneFor = (rule: RecurrenceRule): ResolvedTone => {
+		const tone = deps.resolveTone(rule.template.tone);
+		if (tone === undefined) {
+			throw new NotificationError(
+				DIAGNOSTIC_CODES.UNDECLARED_TONE,
+				`Tone "${rule.template.tone}" was never declared in the package configuration.`,
+				{ toneId: rule.template.tone, seriesId: rule.id },
+			);
+		}
+		return tone;
+	};
+
+	/** Expands and registers, scheduling only occurrences the device lacks. */
+	const materialize = async (rule: RecurrenceRule, tone: ResolvedTone): Promise<SeriesResult> => {
+		const now = deps.now();
+		const zone = deps.timeZone();
+		const previous = readSeries(deps.state, rule.id);
+
+		const pending = await deps.engine.getPending();
+		const ofSeries = pending.filter(entry => belongsTo(entry, rule.id));
+
+		const expansion = expand({
+			rule,
+			from: now,
+			lookahead: deps.lookahead,
+			timeZone: zone,
+			alreadyEmitted: previous?.emittedCount ?? 0,
+			lastEmittedKey:
+				previous?.lastEmittedKey ??
+				(previous !== undefined
+					? recoverLastEmittedKey(ofSeries, rule.anchoring, zone)
+					: undefined),
+		});
+
+		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 wanted = new Set(guarded.occurrences.map(occurrence => occurrence.id));
+
+		// Upcoming entries of this series the expansion no longer produces: ones
+		// written under the instant-based identity before 0.4.0, or ones whose slot
+		// the rule no longer has. Left in place, each would fire beside its
+		// replacement. Entries already due are left alone — they may be firing now.
+		const stale = ofSeries.filter(entry => !wanted.has(entry.id) && entry.resolvedAt > now);
+		for (const entry of stale) {
+			await writer.cancel(entry.id);
+		}
+
+		const onDevice = new Set(
+			ofSeries.filter(entry => !stale.includes(entry)).map(entry => entry.id),
+		);
+		const missing = guarded.occurrences.filter(occurrence => !onDevice.has(occurrence.id));
+
+		// The same ceiling reconciliation respects: soonest first, the rest
+		// registered by a later refresh once they move into range.
+		const room = Math.max(0, (await writer.capacity()) - (pending.length - stale.length));
+		const toSchedule = missing.slice(0, room);
+		if (toSchedule.length < missing.length) {
+			emit(
+				DIAGNOSTIC_CODES.TRUNCATED_OVER_CEILING,
+				`Series "${rule.id}" has ${missing.length - toSchedule.length} occurrence(s) beyond the platform ceiling; they are registered by a later window refresh.`,
+				{ seriesId: rule.id, dropped: missing.length - toSchedule.length },
+			);
+		}
+
+		const approximate = !deps.canScheduleExactly();
+		for (const occurrence of toSchedule) {
+			await writer.write({
+				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,
+			});
+		}
+
+		// Counted once, when first emitted — whether or not the ceiling let it on
+		// the device yet. Occurrences re-produced from an earlier expansion are not
+		// counted again.
+		const newlyEmitted = guarded.occurrences.filter(occurrence => !occurrence.previouslyEmitted);
+		const lastEmittedKey =
+			newlyEmitted.length > 0
+				? newlyEmitted[newlyEmitted.length - 1].key
+				: previous?.lastEmittedKey;
+
+		upsertSeries(
+			deps.state,
+			rule,
+			{
+				expandedThrough: expansion.expandedThrough,
+				emittedCount: (previous?.emittedCount ?? 0) + newlyEmitted.length,
+				exhausted: expansion.exhausted,
+				lastEmittedKey,
+			},
+			now,
+		);
+
+		return {
+			seriesId: rule.id,
+			scheduled: toSchedule.length,
+			expandedThrough: expansion.expandedThrough,
+			exhausted: expansion.exhausted,
+			cancelled: stale.map(entry => entry.id),
+		};
+	};
+
+	return {
+		async registerSeries(rule: RecurrenceRule): Promise<SeriesResult> {
+			validateIdentifier(rule.id, 'seriesId');
+			return materialize(rule, validateTemplate(rule));
+		},
+
+		/** Re-expands a tracked series. Called by the window-refresh maintenance step. */
+		async refreshSeries(rule: RecurrenceRule): Promise<SeriesResult> {
+			return materialize(rule, toneFor(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 => belongsTo(entry, seriesId)).map(entry => entry.id);
+
+			await deps.engine.cancelMany(ids);
+			for (const id of ids) await writer.releaseStop(id);
+			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 => belongsTo(p, entry.seriesId)).length,
+				exhausted: entry.exhausted,
+			}));
+		},
+	};
+}
+
+export type Recurrence = ReturnType<typeof createRecurrence>;