@chipmobilesdk/rn-notification 0.4.0 → 0.5.0

package/src/initialize.ts

@@ -1,236 +1,247 @@
-/**
- * Package initialization.
- *
- * Composes the parts that must be in place before the first schedule call:
- * validate configuration, load persisted state, apply tone declarations, run
- * any pending channel migration, and start the maintenance registry.
- *
- * Budgeted at 100 ms of app startup, which is why state loading is synchronous
- * and tone declaration is the only platform round-trip.
- *
- * Automatic maintenance is started here too: whatever steps are registered on
- * `runtime.registry` run when the app returns to the foreground, with the
- * trigger reported as `timeZoneChange` when the device zone moved meanwhile.
- * Until 0.4.0 nothing ever called `runAutomatic`, so "automatic" maintenance
- * only ran when the app invoked it by hand.
- */
-
-import { AppState } from 'react-native';
-import type { InitializeResult, NotificationConfig } from './contract/diagnostics';
-import { DEFAULT_LOOKAHEAD, LOOKAHEAD_BOUNDS, type LookaheadConfig } from './contract/recurrence';
-import type { MaintenanceResult } from './contract/reconcile';
-import { DIAGNOSTIC_CODES, NotificationError, type DiagnosticCode } from './contract/errors';
-import { DiagnosticEmitter } from './diagnostics/events';
-import { MaintenanceRegistry } from './maintenance/cycle';
-import { MaintenanceController } from './maintenance/toggle';
-import { StateManager } from './state/record';
-import { ownedIdentifiers } from './state/series-ledger';
-import type { StateStore } from './state/store';
-import type { NotificationEngineAdapter } from './engine/adapter';
-import { createChannels, type Channels } from './channel/migrate';
-import { createPlatformTimeZoneReader, type TimeZoneReader } from './schedule/anchor';
-
-/** The slice of React Native's `AppState` the lifecycle observer uses. */
-export interface AppStateSource {
-	addEventListener(type: 'change', listener: (state: string) => void): { remove(): void };
-}
-
-export interface RuntimeDependencies {
-	readonly engine: NotificationEngineAdapter;
-	readonly store: StateStore;
-	readonly now?: () => number;
-	/** Injected in tests; defaults to React Native's `AppState`. */
-	readonly appState?: AppStateSource;
-	/** Injected in tests; defaults to the platform zone reader. */
-	readonly timeZone?: TimeZoneReader;
-}
-
-/** Everything assembled at initialization, shared by the operation modules. */
-export interface NotificationRuntime {
-	readonly engine: NotificationEngineAdapter;
-	readonly state: StateManager;
-	readonly emitter: DiagnosticEmitter;
-	readonly registry: MaintenanceRegistry;
-	readonly maintenance: MaintenanceController;
-	/** The channel module that applied `config.tones`. Added in 0.4.0. */
-	readonly channels: Channels;
-	readonly lookahead: LookaheadConfig;
-	readonly config: NotificationConfig;
-	readonly now: () => number;
-	/** The result of the latest automatic cycle, if one has run. Added in 0.4.0. */
-	readonly lastAutomaticMaintenance: () => MaintenanceResult | undefined;
-	/** Stops the lifecycle observer. Added in 0.4.0. */
-	dispose(): void;
-}
-
-/**
- * Clamps the lookahead into its documented bounds.
- *
- * Bounded on adjustment because the platform ceiling is not negotiable: a
- * consumer asking for a five-year window would silently exhaust the 64-entry
- * iOS ceiling on the first frequent series.
- */
-export function resolveLookahead(partial: Partial<LookaheadConfig> | undefined): LookaheadConfig {
-	const days = partial?.days ?? DEFAULT_LOOKAHEAD.days;
-	const occurrencesPerSeries = partial?.occurrencesPerSeries ?? DEFAULT_LOOKAHEAD.occurrencesPerSeries;
-
-	return {
-		days: Math.min(Math.max(days, LOOKAHEAD_BOUNDS.minDays), LOOKAHEAD_BOUNDS.maxDays),
-		occurrencesPerSeries: Math.min(
-			Math.max(occurrencesPerSeries, LOOKAHEAD_BOUNDS.minOccurrences),
-			LOOKAHEAD_BOUNDS.maxOccurrences,
-		),
-	};
-}
-
-/** Fails before any platform call, so a bad configuration never half-applies. */
-export function validateConfig(config: NotificationConfig): void {
-	if (config.tones.length === 0) {
-		throw new NotificationError(
-			DIAGNOSTIC_CODES.UNDECLARED_TONE,
-			'At least one tone must be declared before notifications can be scheduled.',
-		);
-	}
-
-	const seen = new Set<string>();
-	for (const tone of config.tones) {
-		if (seen.has(tone.id)) {
-			throw new NotificationError(
-				DIAGNOSTIC_CODES.UNDECLARED_TONE,
-				`Tone "${tone.id}" is declared more than once.`,
-				{ toneId: tone.id },
-			);
-		}
-		seen.add(tone.id);
-
-		if (!Number.isInteger(tone.version) || tone.version < 1) {
-			throw new NotificationError(
-				DIAGNOSTIC_CODES.CHANNEL_MIGRATION_REQUIRED,
-				`Tone "${tone.id}" must carry an integer version of 1 or greater, because a channel configuration change is a migration rather than an assignment.`,
-				{ toneId: tone.id, version: tone.version },
-			);
-		}
-	}
-
-	const groupIds = new Set((config.channelGroups ?? []).map(group => group.id));
-	for (const tone of config.tones) {
-		if (tone.groupId !== undefined && !groupIds.has(tone.groupId)) {
-			throw new NotificationError(
-				DIAGNOSTIC_CODES.UNDECLARED_TONE,
-				`Tone "${tone.id}" references undeclared channel group "${tone.groupId}".`,
-				{ toneId: tone.id, groupId: tone.groupId },
-			);
-		}
-	}
-}
-
-export async function initialize(
-	config: NotificationConfig,
-	deps: RuntimeDependencies,
-): Promise<{ runtime: NotificationRuntime; result: InitializeResult }> {
-	const now = deps.now ?? (() => Date.now());
-	const startedAt = now();
-
-	validateConfig(config);
-
-	const emitter = new DiagnosticEmitter({
-		sink: config.eventSink,
-		verbose: config.verboseDiagnostics,
-		now,
-	});
-
-	const state = new StateManager({
-		store: deps.store,
-		now,
-		emit: event => emitter.emit(event.code, describeStateEvent(event.code), event.context),
-	});
-
-	const channels = createChannels({
-		engine: deps.engine,
-		state,
-		now,
-		// The channel module emits only DIAGNOSTIC_CODES values; its port types the
-		// code as a string so it stays usable without the emitter.
-		emit: (code, message, context) => emitter.emit(code as DiagnosticCode, message, context),
-	});
-	// Declares groups and tones, and runs any version migration. An unchanged
-	// configuration costs no platform work, so doing this on every launch is free.
-	const applied = await channels.apply(config.tones, config.channelGroups ?? []);
-
-	const registry = new MaintenanceRegistry({ clock: now });
-	const maintenance = new MaintenanceController({
-		registry,
-		now,
-		// Occurrence identifiers, not series identifiers. Maintenance cancels
-		// occurrences, so a set of series ids made every legitimate cancel look
-		// like a scope violation.
-		ownedIds: async () =>
-			ownedIdentifiers(state, (await deps.engine.getPending()).map(entry => entry.id)),
-		enabled: config.automaticMaintenance ?? true,
-	});
-
-	const timeZone = deps.timeZone ?? createPlatformTimeZoneReader();
-	let lastZone = timeZone();
-	let lastAutomatic: MaintenanceResult | undefined;
-	const onAppState = (next: string) => {
-		if (next !== 'active') return;
-		const zone = timeZone();
-		const trigger = zone !== lastZone ? 'timeZoneChange' : 'foreground';
-		lastZone = zone;
-		maintenance.runAutomatic(trigger).then(
-			result => {
-				if (result !== undefined) lastAutomatic = result;
-			},
-			error => {
-				// Nothing awaits an automatic cycle, so a failure is reported here or
-				// not at all.
-				emitter.emit(
-					DIAGNOSTIC_CODES.MAINTENANCE_FAILED,
-					`Automatic maintenance (${trigger}) failed: ${error instanceof Error ? error.name : 'unknown error'}.`,
-					{ trigger },
-				);
-			},
-		);
-	};
-	const subscription = (deps.appState ?? AppState).addEventListener('change', onAppState);
-
-	const runtime: NotificationRuntime = {
-		engine: deps.engine,
-		state,
-		emitter,
-		registry,
-		maintenance,
-		channels,
-		lookahead: resolveLookahead(config.lookahead),
-		config,
-		now,
-		lastAutomaticMaintenance: () => lastAutomatic,
-		dispose: () => subscription.remove(),
-	};
-
-	return {
-		runtime,
-		result: {
-			tonesApplied: config.tones.length,
-			migrationsRun: applied.migrated.length,
-			stateRebuilt: state.health().rebuilt,
-			automaticMaintenance: maintenance.isEnabled,
-			durationMs: now() - startedAt,
-		},
-	};
-}
-
-function describeStateEvent(code: string): string {
-	switch (code) {
-		case DIAGNOSTIC_CODES.STATE_CORRUPT_REBUILT:
-			return 'Persisted state was unreadable and has been rebuilt. Deduplication history and buffered interactions from before the loss are gone; scheduled notifications are unaffected.';
-		case DIAGNOSTIC_CODES.STATE_WRITE_FAILED:
-			return 'Persisted state could not be written. The affected guarantee degrades to this session only.';
-		case DIAGNOSTIC_CODES.STATE_CAP_EVICTED:
-			return 'A persisted collection reached its cap and the oldest entries were evicted.';
-		case DIAGNOSTIC_CODES.INTERACTION_BUFFER_EVICTED:
-			return 'Buffered interactions were evicted at the cap or retention limit.';
-		default:
-			return 'Persisted state event.';
-	}
-}
+/**
+ * Package initialization.
+ *
+ * Composes the parts that must be in place before the first schedule call:
+ * validate configuration, load persisted state, apply tone declarations, run
+ * any pending channel migration, and start the maintenance registry.
+ *
+ * Budgeted at 100 ms of app startup, which is why state loading is synchronous
+ * and tone declaration is the only platform round-trip.
+ *
+ * Automatic maintenance is started here too: whatever steps are registered on
+ * `runtime.registry` run when the app returns to the foreground, with the
+ * trigger reported as `timeZoneChange` when the device zone moved meanwhile.
+ * Until 0.4.0 nothing ever called `runAutomatic`, so "automatic" maintenance
+ * only ran when the app invoked it by hand.
+ */
+
+import { appLifecycle } from '@chipmobilesdk/rn-core';
+import type { InitializeResult, NotificationConfig } from './contract/diagnostics';
+import { DEFAULT_LOOKAHEAD, LOOKAHEAD_BOUNDS, type LookaheadConfig } from './contract/recurrence';
+import type { MaintenanceResult } from './contract/reconcile';
+import { DIAGNOSTIC_CODES, NotificationError, type DiagnosticCode } from './contract/errors';
+import { DiagnosticEmitter } from './diagnostics/events';
+import { MaintenanceRegistry } from './maintenance/cycle';
+import { MaintenanceController } from './maintenance/toggle';
+import { StateManager } from './state/record';
+import { ownedIdentifiers } from './state/series-ledger';
+import type { StateStore } from './state/store';
+import type { NotificationEngineAdapter } from './engine/adapter';
+import { createChannels, type Channels } from './channel/migrate';
+import { createPlatformTimeZoneReader, type TimeZoneReader } from './schedule/anchor';
+
+/** The slice of React Native's `AppState` the lifecycle observer uses. */
+export interface AppStateSource {
+	addEventListener(type: 'change', listener: (state: string) => void): { remove(): void };
+}
+
+/** rn-core's shared lifecycle port in the observer's shape: one native subscription for every package (PERF-07). */
+const sharedLifecycle: AppStateSource = {
+	addEventListener: (_type, listener) => ({
+		remove: appLifecycle().subscribe(state => listener(state)),
+	}),
+};
+
+export interface RuntimeDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly store: StateStore;
+	readonly now?: () => number;
+	/** Injected in tests; defaults to rn-core's shared `appLifecycle()`. */
+	readonly appState?: AppStateSource;
+	/** Injected in tests; defaults to the platform zone reader. */
+	readonly timeZone?: TimeZoneReader;
+}
+
+/** Everything assembled at initialization, shared by the operation modules. */
+export interface NotificationRuntime {
+	readonly engine: NotificationEngineAdapter;
+	readonly state: StateManager;
+	readonly emitter: DiagnosticEmitter;
+	readonly registry: MaintenanceRegistry;
+	readonly maintenance: MaintenanceController;
+	/** The channel module that applied `config.tones`. Added in 0.4.0. */
+	readonly channels: Channels;
+	readonly lookahead: LookaheadConfig;
+	readonly config: NotificationConfig;
+	readonly now: () => number;
+	/** The result of the latest automatic cycle, if one has run. Added in 0.4.0. */
+	readonly lastAutomaticMaintenance: () => MaintenanceResult | undefined;
+	/** Stops the lifecycle observer. Added in 0.4.0. */
+	dispose(): void;
+}
+
+/**
+ * Clamps the lookahead into its documented bounds.
+ *
+ * Bounded on adjustment because the platform ceiling is not negotiable: a
+ * consumer asking for a five-year window would silently exhaust the 64-entry
+ * iOS ceiling on the first frequent series.
+ */
+export function resolveLookahead(partial: Partial<LookaheadConfig> | undefined): LookaheadConfig {
+	const days = partial?.days ?? DEFAULT_LOOKAHEAD.days;
+	const occurrencesPerSeries =
+		partial?.occurrencesPerSeries ?? DEFAULT_LOOKAHEAD.occurrencesPerSeries;
+
+	return {
+		days: Math.min(Math.max(days, LOOKAHEAD_BOUNDS.minDays), LOOKAHEAD_BOUNDS.maxDays),
+		occurrencesPerSeries: Math.min(
+			Math.max(occurrencesPerSeries, LOOKAHEAD_BOUNDS.minOccurrences),
+			LOOKAHEAD_BOUNDS.maxOccurrences,
+		),
+	};
+}
+
+/** Fails before any platform call, so a bad configuration never half-applies. */
+export function validateConfig(config: NotificationConfig): void {
+	if (config.tones.length === 0) {
+		throw new NotificationError(
+			DIAGNOSTIC_CODES.UNDECLARED_TONE,
+			'At least one tone must be declared before notifications can be scheduled.',
+		);
+	}
+
+	const seen = new Set<string>();
+	for (const tone of config.tones) {
+		if (seen.has(tone.id)) {
+			throw new NotificationError(
+				DIAGNOSTIC_CODES.UNDECLARED_TONE,
+				`Tone "${tone.id}" is declared more than once.`,
+				{ toneId: tone.id },
+			);
+		}
+		seen.add(tone.id);
+
+		if (!Number.isInteger(tone.version) || tone.version < 1) {
+			throw new NotificationError(
+				DIAGNOSTIC_CODES.CHANNEL_MIGRATION_REQUIRED,
+				`Tone "${tone.id}" must carry an integer version of 1 or greater, because a channel configuration change is a migration rather than an assignment.`,
+				{ toneId: tone.id, version: tone.version },
+			);
+		}
+	}
+
+	const groupIds = new Set((config.channelGroups ?? []).map(group => group.id));
+	for (const tone of config.tones) {
+		if (tone.groupId !== undefined && !groupIds.has(tone.groupId)) {
+			throw new NotificationError(
+				DIAGNOSTIC_CODES.UNDECLARED_TONE,
+				`Tone "${tone.id}" references undeclared channel group "${tone.groupId}".`,
+				{ toneId: tone.id, groupId: tone.groupId },
+			);
+		}
+	}
+}
+
+export async function initialize(
+	config: NotificationConfig,
+	deps: RuntimeDependencies,
+): Promise<{ runtime: NotificationRuntime; result: InitializeResult }> {
+	const now = deps.now ?? (() => Date.now());
+	const startedAt = now();
+
+	validateConfig(config);
+
+	const emitter = new DiagnosticEmitter({
+		sink: config.eventSink,
+		verbose: config.verboseDiagnostics,
+		now,
+	});
+
+	const state = new StateManager({
+		store: deps.store,
+		now,
+		emit: event => emitter.emit(event.code, describeStateEvent(event.code), event.context),
+	});
+
+	const channels = createChannels({
+		engine: deps.engine,
+		state,
+		now,
+		// The channel module emits only DIAGNOSTIC_CODES values; its port types the
+		// code as a string so it stays usable without the emitter.
+		emit: (code, message, context) => emitter.emit(code as DiagnosticCode, message, context),
+	});
+	// Declares groups and tones, and runs any version migration. An unchanged
+	// configuration costs no platform work, so doing this on every launch is free.
+	const applied = await channels.apply(config.tones, config.channelGroups ?? []);
+
+	const registry = new MaintenanceRegistry({ clock: now });
+	const maintenance = new MaintenanceController({
+		registry,
+		now,
+		// Occurrence identifiers, not series identifiers. Maintenance cancels
+		// occurrences, so a set of series ids made every legitimate cancel look
+		// like a scope violation.
+		ownedIds: async () =>
+			ownedIdentifiers(
+				state,
+				(await deps.engine.getPending()).map(entry => entry.id),
+			),
+		enabled: config.automaticMaintenance ?? true,
+	});
+
+	const timeZone = deps.timeZone ?? createPlatformTimeZoneReader();
+	let lastZone = timeZone();
+	let lastAutomatic: MaintenanceResult | undefined;
+	const onAppState = (next: string) => {
+		if (next !== 'active') return;
+		const zone = timeZone();
+		const trigger = zone !== lastZone ? 'timeZoneChange' : 'foreground';
+		lastZone = zone;
+		maintenance.runAutomatic(trigger).then(
+			result => {
+				if (result !== undefined) lastAutomatic = result;
+			},
+			error => {
+				// Nothing awaits an automatic cycle, so a failure is reported here or
+				// not at all.
+				emitter.emit(
+					DIAGNOSTIC_CODES.MAINTENANCE_FAILED,
+					`Automatic maintenance (${trigger}) failed: ${error instanceof Error ? error.name : 'unknown error'}.`,
+					{ trigger },
+				);
+			},
+		);
+	};
+	const subscription = (deps.appState ?? sharedLifecycle).addEventListener('change', onAppState);
+
+	const runtime: NotificationRuntime = {
+		engine: deps.engine,
+		state,
+		emitter,
+		registry,
+		maintenance,
+		channels,
+		lookahead: resolveLookahead(config.lookahead),
+		config,
+		now,
+		lastAutomaticMaintenance: () => lastAutomatic,
+		dispose: () => subscription.remove(),
+	};
+
+	return {
+		runtime,
+		result: {
+			tonesApplied: config.tones.length,
+			migrationsRun: applied.migrated.length,
+			stateRebuilt: state.health().rebuilt,
+			automaticMaintenance: maintenance.isEnabled,
+			durationMs: now() - startedAt,
+		},
+	};
+}
+
+function describeStateEvent(code: string): string {
+	switch (code) {
+		case DIAGNOSTIC_CODES.STATE_CORRUPT_REBUILT:
+			return 'Persisted state was unreadable and has been rebuilt. Deduplication history and buffered interactions from before the loss are gone; scheduled notifications are unaffected.';
+		case DIAGNOSTIC_CODES.STATE_WRITE_FAILED:
+			return 'Persisted state could not be written. The affected guarantee degrades to this session only.';
+		case DIAGNOSTIC_CODES.STATE_CAP_EVICTED:
+			return 'A persisted collection reached its cap and the oldest entries were evicted.';
+		case DIAGNOSTIC_CODES.INTERACTION_BUFFER_EVICTED:
+			return 'Buffered interactions were evicted at the cap or retention limit.';
+		default:
+			return 'Persisted state event.';
+	}
+}