@chipmobilesdk/rn-notification 0.4.0 → 0.4.1

package/src/interaction/index.ts

@@ -1,146 +1,146 @@
-/**
- * Interaction routing.
- *
- * One handler covers foreground, background, and cold start. The hard case is
- * the last one: the tap happens before any JavaScript exists to receive it, so
- * the event has to wait — durably — until a handler registers.
- *
- * Events are delivered in occurrence order and never dropped for want of a
- * listener. After delivery the notification leaves the tray, because a
- * notification the user has already acted on sitting there is noise.
- */
-
-import type {
-	InteractionEvent,
-	InteractionHandler,
-	TargetMissingSignal,
-	Unsubscribe,
-} from '../contract/interaction';
-import type { NotificationEngineAdapter } from '../engine/adapter';
-import type { StateManager } from '../state/record';
-import { DIAGNOSTIC_CODES } from '../contract/errors';
-import { buffer, bufferedCount, drain } from '../state/interaction-buffer';
-
-export interface InteractionDependencies {
-	readonly engine: NotificationEngineAdapter;
-	readonly state: StateManager;
-	readonly now: () => number;
-	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
-}
-
-export function createInteractions(deps: InteractionDependencies) {
-	const emit = deps.emit ?? (() => {});
-	let handlers: InteractionHandler[] = [];
-	let engineSubscription: Unsubscribe | undefined;
-	/** Serializes delivery so rapid interactions arrive in order, never interleaved. */
-	let deliveryChain: Promise<void> = Promise.resolve();
-
-	const deliver = (event: InteractionEvent): void => {
-		deliveryChain = deliveryChain.then(async () => {
-			for (const handler of handlers) {
-				try {
-					await handler(event);
-				} catch {
-					// A consumer's handler failing must not stop the next event, or one
-					// bad tap would silently swallow every tap after it.
-				}
-			}
-
-			// Acted on, so it leaves the tray and stops making noise.
-			if (event.kind !== 'dismiss') {
-				await deps.engine.cancel(event.notificationId).catch(() => undefined);
-			}
-		});
-	};
-
-	const route = (event: InteractionEvent): void => {
-		if (handlers.length === 0) {
-			buffer(deps.state, event);
-			return;
-		}
-		deliver(event);
-	};
-
-	const ensureSubscribed = (): void => {
-		engineSubscription ??= deps.engine.subscribeToInteractions(route);
-	};
-
-	// Subscribing immediately rather than on first handler registration: an
-	// interaction arriving in the gap would otherwise be lost entirely, which is
-	// the exact failure the buffer exists to prevent.
-	ensureSubscribed();
-
-	return {
-		/**
-		 * Registers a handler and immediately drains anything that was waiting.
-		 *
-		 * The drain is what makes a cold-start tap work: the event was persisted
-		 * before this handler existed, possibly before this process existed.
-		 */
-		onInteraction(handler: InteractionHandler): Unsubscribe {
-			handlers.push(handler);
-
-			for (const event of drain(deps.state)) {
-				deliver(event);
-			}
-
-			return () => {
-				handlers = handlers.filter(h => h !== handler);
-			};
-		},
-
-		/**
-		 * Collects the interaction that launched the app, if any.
-		 *
-		 * Called once during startup. If no handler exists yet the event is
-		 * buffered rather than discarded.
-		 */
-		async collectInitial(): Promise<void> {
-			const initial = await deps.engine.takeInitialInteraction();
-			if (initial === undefined) return;
-			route(initial);
-		},
-
-		/**
-		 * Signals that a routing target no longer exists.
-		 *
-		 * The consumer chooses its own fallback screen. No platform error is ever
-		 * shown to the user for this — a notification pointing at deleted data is
-		 * an ordinary condition, not a crash.
-		 */
-		reportTargetMissing(signal: TargetMissingSignal): void {
-			emit(
-				DIAGNOSTIC_CODES.TARGET_MISSING,
-				'The routing target no longer exists. The consumer chooses a fallback; no platform error is shown to the user.',
-				{ notificationId: signal.notificationId },
-			);
-		},
-
-		/** Reports that a background action exceeded the platform's execution window. */
-		reportBackgroundTimeout(notificationId: string, windowMs: number): void {
-			emit(
-				DIAGNOSTIC_CODES.BACKGROUND_WINDOW_EXCEEDED,
-				`A background action exceeded the platform's ${windowMs} ms execution window and was cut short.`,
-				{ notificationId, windowMs },
-			);
-		},
-
-		/** How many interactions are waiting for a handler. */
-		pendingCount(): number {
-			return bufferedCount(deps.state);
-		},
-
-		/** Settles outstanding deliveries. Exists for tests and orderly shutdown. */
-		async flush(): Promise<void> {
-			await deliveryChain;
-		},
-
-		dispose(): void {
-			engineSubscription?.();
-			engineSubscription = undefined;
-			handlers = [];
-		},
-	};
-}
-
-export type Interactions = ReturnType<typeof createInteractions>;
+/**
+ * Interaction routing.
+ *
+ * One handler covers foreground, background, and cold start. The hard case is
+ * the last one: the tap happens before any JavaScript exists to receive it, so
+ * the event has to wait — durably — until a handler registers.
+ *
+ * Events are delivered in occurrence order and never dropped for want of a
+ * listener. After delivery the notification leaves the tray, because a
+ * notification the user has already acted on sitting there is noise.
+ */
+
+import type {
+	InteractionEvent,
+	InteractionHandler,
+	TargetMissingSignal,
+	Unsubscribe,
+} from '../contract/interaction';
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import type { StateManager } from '../state/record';
+import { DIAGNOSTIC_CODES } from '../contract/errors';
+import { buffer, bufferedCount, drain } from '../state/interaction-buffer';
+
+export interface InteractionDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly state: StateManager;
+	readonly now: () => number;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export function createInteractions(deps: InteractionDependencies) {
+	const emit = deps.emit ?? (() => {});
+	let handlers: InteractionHandler[] = [];
+	let engineSubscription: Unsubscribe | undefined;
+	/** Serializes delivery so rapid interactions arrive in order, never interleaved. */
+	let deliveryChain: Promise<void> = Promise.resolve();
+
+	const deliver = (event: InteractionEvent): void => {
+		deliveryChain = deliveryChain.then(async () => {
+			for (const handler of handlers) {
+				try {
+					await handler(event);
+				} catch {
+					// A consumer's handler failing must not stop the next event, or one
+					// bad tap would silently swallow every tap after it.
+				}
+			}
+
+			// Acted on, so it leaves the tray and stops making noise.
+			if (event.kind !== 'dismiss') {
+				await deps.engine.cancel(event.notificationId).catch(() => undefined);
+			}
+		});
+	};
+
+	const route = (event: InteractionEvent): void => {
+		if (handlers.length === 0) {
+			buffer(deps.state, event);
+			return;
+		}
+		deliver(event);
+	};
+
+	const ensureSubscribed = (): void => {
+		engineSubscription ??= deps.engine.subscribeToInteractions(route);
+	};
+
+	// Subscribing immediately rather than on first handler registration: an
+	// interaction arriving in the gap would otherwise be lost entirely, which is
+	// the exact failure the buffer exists to prevent.
+	ensureSubscribed();
+
+	return {
+		/**
+		 * Registers a handler and immediately drains anything that was waiting.
+		 *
+		 * The drain is what makes a cold-start tap work: the event was persisted
+		 * before this handler existed, possibly before this process existed.
+		 */
+		onInteraction(handler: InteractionHandler): Unsubscribe {
+			handlers.push(handler);
+
+			for (const event of drain(deps.state)) {
+				deliver(event);
+			}
+
+			return () => {
+				handlers = handlers.filter(h => h !== handler);
+			};
+		},
+
+		/**
+		 * Collects the interaction that launched the app, if any.
+		 *
+		 * Called once during startup. If no handler exists yet the event is
+		 * buffered rather than discarded.
+		 */
+		async collectInitial(): Promise<void> {
+			const initial = await deps.engine.takeInitialInteraction();
+			if (initial === undefined) return;
+			route(initial);
+		},
+
+		/**
+		 * Signals that a routing target no longer exists.
+		 *
+		 * The consumer chooses its own fallback screen. No platform error is ever
+		 * shown to the user for this — a notification pointing at deleted data is
+		 * an ordinary condition, not a crash.
+		 */
+		reportTargetMissing(signal: TargetMissingSignal): void {
+			emit(
+				DIAGNOSTIC_CODES.TARGET_MISSING,
+				'The routing target no longer exists. The consumer chooses a fallback; no platform error is shown to the user.',
+				{ notificationId: signal.notificationId },
+			);
+		},
+
+		/** Reports that a background action exceeded the platform's execution window. */
+		reportBackgroundTimeout(notificationId: string, windowMs: number): void {
+			emit(
+				DIAGNOSTIC_CODES.BACKGROUND_WINDOW_EXCEEDED,
+				`A background action exceeded the platform's ${windowMs} ms execution window and was cut short.`,
+				{ notificationId, windowMs },
+			);
+		},
+
+		/** How many interactions are waiting for a handler. */
+		pendingCount(): number {
+			return bufferedCount(deps.state);
+		},
+
+		/** Settles outstanding deliveries. Exists for tests and orderly shutdown. */
+		async flush(): Promise<void> {
+			await deliveryChain;
+		},
+
+		dispose(): void {
+			engineSubscription?.();
+			engineSubscription = undefined;
+			handlers = [];
+		},
+	};
+}
+
+export type Interactions = ReturnType<typeof createInteractions>;

package/src/maintenance/cycle.ts

@@ -1,154 +1,150 @@
-/**
- * The automatic maintenance cycle.
- *
- * Covers exactly what only the package can know — window refresh, recurrence
- * expansion, wall-clock re-anchoring, pending-set verification, permission
- * re-reads. Full desired-set reconciliation is never automatic, because only
- * the consumer knows what its data implies and a package that guessed would
- * cancel notifications it does not understand.
- *
- * Steps register themselves here rather than being wired in a fixed order. That
- * is what lets scheduling, reconciliation, recurrence, and permissions each
- * contribute a step without importing one another.
- *
- * The rule that makes automatic work safe: a step may act only on notifications
- * the package owns, and may never cancel anything else. It is enforced here
- * rather than trusted to each step.
- */
-
-import type { MaintenanceResult, PendingDiscrepancy } from '../contract/reconcile';
-
-export type MaintenanceTrigger =
-	| 'foreground'
-	| 'delivery'
-	| 'timeZoneChange'
-	| 'permissionChange'
-	| 'explicit';
-
-export interface MaintenanceContext {
-	readonly trigger: MaintenanceTrigger;
-	readonly now: number;
-	/**
-	 * Identifiers the package owns — series occurrences and entries it created.
-	 * A step may cancel only within this set.
-	 */
-	readonly ownedIds: ReadonlySet<string>;
-}
-
-export interface StepOutcome {
-	readonly occurrencesScheduled?: number;
-	readonly reAnchored?: number;
-	readonly windowRefreshed?: boolean;
-	readonly timeZoneChanged?: boolean;
-	readonly permissionChanged?: boolean;
-	readonly discrepancy?: PendingDiscrepancy;
-	/** Platform operations issued. Zero on a no-change pass. */
-	readonly operationCount?: number;
-	/** Identifiers this step cancelled, checked against `ownedIds`. */
-	readonly cancelledIds?: readonly string[];
-}
-
-export interface MaintenanceStep {
-	readonly name: string;
-	/** Lower runs first. Re-anchoring must precede verification, or verification sees stale instants. */
-	readonly order: number;
-	run(context: MaintenanceContext): Promise<StepOutcome>;
-}
-
-export class MaintenanceScopeViolation extends Error {
-	readonly step: string;
-	readonly offendingIds: readonly string[];
-
-	constructor(step: string, offendingIds: readonly string[]) {
-		super(
-			`Maintenance step "${step}" attempted to cancel ${offendingIds.length} notification(s) it does not own. ` +
-				'Automatic maintenance may never cancel a directly-scheduled notification.',
-		);
-		this.name = 'MaintenanceScopeViolation';
-		this.step = step;
-		this.offendingIds = offendingIds;
-		Object.setPrototypeOf(this, MaintenanceScopeViolation.prototype);
-	}
-}
-
-export interface MaintenanceRegistryOptions {
-	/** Measures `durationMs`. `context.now` is the cycle's logical time and does not move. */
-	readonly clock?: () => number;
-}
-
-export class MaintenanceRegistry {
-	private steps: MaintenanceStep[] = [];
-	private inFlight: Promise<MaintenanceResult> | null = null;
-	private readonly clock: () => number;
-
-	constructor(options: MaintenanceRegistryOptions = {}) {
-		this.clock = options.clock ?? (() => Date.now());
-	}
-
-	register(step: MaintenanceStep): () => void {
-		this.steps.push(step);
-		this.steps.sort((a, b) => a.order - b.order);
-		return () => {
-			this.steps = this.steps.filter(s => s !== step);
-		};
-	}
-
-	get registered(): readonly string[] {
-		return this.steps.map(s => s.name);
-	}
-
-	/**
-	 * Runs every registered step in order.
-	 *
-	 * Overlapping cycles are joined rather than queued or dropped: a second
-	 * caller arriving mid-cycle wants the work the running cycle is already
-	 * doing, so it waits for that cycle and gets its result. It used to get an
-	 * empty result at once. Since `initialize` started running a cycle on every
-	 * foreground, an app that ran maintenance and then reconciled on the same
-	 * event got that empty result and reconciled while the window refresh was
-	 * still writing: a reminder the reconcile cancelled could be scheduled again.
-	 */
-	run(context: MaintenanceContext): Promise<MaintenanceResult> {
-		if (this.inFlight) {
-			return this.inFlight;
-		}
-		const cycle = this.runSteps(context).finally(() => {
-			if (this.inFlight === cycle) this.inFlight = null;
-		});
-		this.inFlight = cycle;
-		return cycle;
-	}
-
-	private async runSteps(context: MaintenanceContext): Promise<MaintenanceResult> {
-		const started = context.now;
-		const clockStart = this.clock();
-		const aggregate = {
-			windowRefreshed: false,
-			occurrencesScheduled: 0,
-			reAnchored: 0,
-			timeZoneChanged: false,
-			permissionChanged: false,
-			operationCount: 0,
-		};
-		let discrepancy: PendingDiscrepancy | undefined;
-
-		for (const step of this.steps) {
-			const outcome = await step.run(context);
-
-			const offending = (outcome.cancelledIds ?? []).filter(id => !context.ownedIds.has(id));
-			if (offending.length > 0) {
-				throw new MaintenanceScopeViolation(step.name, offending);
-			}
-
-			aggregate.windowRefreshed ||= outcome.windowRefreshed ?? false;
-			aggregate.occurrencesScheduled += outcome.occurrencesScheduled ?? 0;
-			aggregate.reAnchored += outcome.reAnchored ?? 0;
-			aggregate.timeZoneChanged ||= outcome.timeZoneChanged ?? false;
-			aggregate.permissionChanged ||= outcome.permissionChanged ?? false;
-			aggregate.operationCount += outcome.operationCount ?? 0;
-			discrepancy ??= outcome.discrepancy;
-		}
-
-		return { ranAt: started, ...aggregate, discrepancy, durationMs: this.clock() - clockStart };
-	}
-}
+/**
+ * The automatic maintenance cycle.
+ *
+ * Covers exactly what only the package can know — window refresh, recurrence
+ * expansion, wall-clock re-anchoring, pending-set verification, permission
+ * re-reads. Full desired-set reconciliation is never automatic, because only
+ * the consumer knows what its data implies and a package that guessed would
+ * cancel notifications it does not understand.
+ *
+ * Steps register themselves here rather than being wired in a fixed order. That
+ * is what lets scheduling, reconciliation, recurrence, and permissions each
+ * contribute a step without importing one another.
+ *
+ * The rule that makes automatic work safe: a step may act only on notifications
+ * the package owns, and may never cancel anything else. It is enforced here
+ * rather than trusted to each step.
+ */
+
+import type { MaintenanceResult, PendingDiscrepancy } from '../contract/reconcile';
+
+export type MaintenanceTrigger =
+	'foreground' | 'delivery' | 'timeZoneChange' | 'permissionChange' | 'explicit';
+
+export interface MaintenanceContext {
+	readonly trigger: MaintenanceTrigger;
+	readonly now: number;
+	/**
+	 * Identifiers the package owns — series occurrences and entries it created.
+	 * A step may cancel only within this set.
+	 */
+	readonly ownedIds: ReadonlySet<string>;
+}
+
+export interface StepOutcome {
+	readonly occurrencesScheduled?: number;
+	readonly reAnchored?: number;
+	readonly windowRefreshed?: boolean;
+	readonly timeZoneChanged?: boolean;
+	readonly permissionChanged?: boolean;
+	readonly discrepancy?: PendingDiscrepancy;
+	/** Platform operations issued. Zero on a no-change pass. */
+	readonly operationCount?: number;
+	/** Identifiers this step cancelled, checked against `ownedIds`. */
+	readonly cancelledIds?: readonly string[];
+}
+
+export interface MaintenanceStep {
+	readonly name: string;
+	/** Lower runs first. Re-anchoring must precede verification, or verification sees stale instants. */
+	readonly order: number;
+	run(context: MaintenanceContext): Promise<StepOutcome>;
+}
+
+export class MaintenanceScopeViolation extends Error {
+	readonly step: string;
+	readonly offendingIds: readonly string[];
+
+	constructor(step: string, offendingIds: readonly string[]) {
+		super(
+			`Maintenance step "${step}" attempted to cancel ${offendingIds.length} notification(s) it does not own. ` +
+				'Automatic maintenance may never cancel a directly-scheduled notification.',
+		);
+		this.name = 'MaintenanceScopeViolation';
+		this.step = step;
+		this.offendingIds = offendingIds;
+		Object.setPrototypeOf(this, MaintenanceScopeViolation.prototype);
+	}
+}
+
+export interface MaintenanceRegistryOptions {
+	/** Measures `durationMs`. `context.now` is the cycle's logical time and does not move. */
+	readonly clock?: () => number;
+}
+
+export class MaintenanceRegistry {
+	private steps: MaintenanceStep[] = [];
+	private inFlight: Promise<MaintenanceResult> | null = null;
+	private readonly clock: () => number;
+
+	constructor(options: MaintenanceRegistryOptions = {}) {
+		this.clock = options.clock ?? (() => Date.now());
+	}
+
+	register(step: MaintenanceStep): () => void {
+		this.steps.push(step);
+		this.steps.sort((a, b) => a.order - b.order);
+		return () => {
+			this.steps = this.steps.filter(s => s !== step);
+		};
+	}
+
+	get registered(): readonly string[] {
+		return this.steps.map(s => s.name);
+	}
+
+	/**
+	 * Runs every registered step in order.
+	 *
+	 * Overlapping cycles are joined rather than queued or dropped: a second
+	 * caller arriving mid-cycle wants the work the running cycle is already
+	 * doing, so it waits for that cycle and gets its result. It used to get an
+	 * empty result at once. Since `initialize` started running a cycle on every
+	 * foreground, an app that ran maintenance and then reconciled on the same
+	 * event got that empty result and reconciled while the window refresh was
+	 * still writing: a reminder the reconcile cancelled could be scheduled again.
+	 */
+	run(context: MaintenanceContext): Promise<MaintenanceResult> {
+		if (this.inFlight) {
+			return this.inFlight;
+		}
+		const cycle = this.runSteps(context).finally(() => {
+			if (this.inFlight === cycle) this.inFlight = null;
+		});
+		this.inFlight = cycle;
+		return cycle;
+	}
+
+	private async runSteps(context: MaintenanceContext): Promise<MaintenanceResult> {
+		const started = context.now;
+		const clockStart = this.clock();
+		const aggregate = {
+			windowRefreshed: false,
+			occurrencesScheduled: 0,
+			reAnchored: 0,
+			timeZoneChanged: false,
+			permissionChanged: false,
+			operationCount: 0,
+		};
+		let discrepancy: PendingDiscrepancy | undefined;
+
+		for (const step of this.steps) {
+			const outcome = await step.run(context);
+
+			const offending = (outcome.cancelledIds ?? []).filter(id => !context.ownedIds.has(id));
+			if (offending.length > 0) {
+				throw new MaintenanceScopeViolation(step.name, offending);
+			}
+
+			aggregate.windowRefreshed ||= outcome.windowRefreshed ?? false;
+			aggregate.occurrencesScheduled += outcome.occurrencesScheduled ?? 0;
+			aggregate.reAnchored += outcome.reAnchored ?? 0;
+			aggregate.timeZoneChanged ||= outcome.timeZoneChanged ?? false;
+			aggregate.permissionChanged ||= outcome.permissionChanged ?? false;
+			aggregate.operationCount += outcome.operationCount ?? 0;
+			discrepancy ??= outcome.discrepancy;
+		}
+
+		return { ranAt: started, ...aggregate, discrepancy, durationMs: this.clock() - clockStart };
+	}
+}