@chipmobilesdk/rn-notification 0.1.2 → 0.2.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,147 +1,147 @@
-/**
- * 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 class MaintenanceRegistry {
-	private steps: MaintenanceStep[] = [];
-	private running = false;
-
-	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 collapsed rather than queued: a second foreground
-	 * event arriving mid-cycle wants the same work the running cycle is already
-	 * doing.
-	 */
-	async run(context: MaintenanceContext): Promise<MaintenanceResult> {
-		const started = context.now;
-
-		if (this.running) {
-			return {
-				ranAt: started,
-				windowRefreshed: false,
-				occurrencesScheduled: 0,
-				reAnchored: 0,
-				timeZoneChanged: false,
-				permissionChanged: false,
-				operationCount: 0,
-				durationMs: 0,
-			};
-		}
-
-		this.running = true;
-		const aggregate = {
-			windowRefreshed: false,
-			occurrencesScheduled: 0,
-			reAnchored: 0,
-			timeZoneChanged: false,
-			permissionChanged: false,
-			operationCount: 0,
-		};
-		let discrepancy: PendingDiscrepancy | undefined;
-
-		try {
-			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;
-			}
-		} finally {
-			this.running = false;
-		}
-
-		return { ranAt: started, ...aggregate, discrepancy, durationMs: 0 };
-	}
-}
+/**
+ * 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 class MaintenanceRegistry {
+	private steps: MaintenanceStep[] = [];
+	private running = false;
+
+	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 collapsed rather than queued: a second foreground
+	 * event arriving mid-cycle wants the same work the running cycle is already
+	 * doing.
+	 */
+	async run(context: MaintenanceContext): Promise<MaintenanceResult> {
+		const started = context.now;
+
+		if (this.running) {
+			return {
+				ranAt: started,
+				windowRefreshed: false,
+				occurrencesScheduled: 0,
+				reAnchored: 0,
+				timeZoneChanged: false,
+				permissionChanged: false,
+				operationCount: 0,
+				durationMs: 0,
+			};
+		}
+
+		this.running = true;
+		const aggregate = {
+			windowRefreshed: false,
+			occurrencesScheduled: 0,
+			reAnchored: 0,
+			timeZoneChanged: false,
+			permissionChanged: false,
+			operationCount: 0,
+		};
+		let discrepancy: PendingDiscrepancy | undefined;
+
+		try {
+			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;
+			}
+		} finally {
+			this.running = false;
+		}
+
+		return { ranAt: started, ...aggregate, discrepancy, durationMs: 0 };
+	}
+}

package/src/maintenance/permission-refresh.ts

@@ -1,41 +1,41 @@
-/**
- * The permission re-read maintenance step.
- *
- * The user can change permission in system settings while the app is
- * backgrounded, and the platform does not tell anyone. Re-reading on foreground
- * is the only way a consumer's interface avoids showing a stale answer.
- *
- * Runs last (order 30): permission state does not affect what the earlier steps
- * expand or re-anchor, and reading it after they have run means the report
- * reflects the device as the cycle leaves it.
- */
-
-import type { MaintenanceStep, MaintenanceContext, StepOutcome } from './cycle';
-import type { Permissions } from '../permission';
-
-export const PERMISSION_REFRESH_ORDER = 30;
-
-export interface PermissionRefreshDependencies {
-	readonly permissions: Permissions;
-}
-
-export function createPermissionRefreshStep(
-	deps: PermissionRefreshDependencies,
-): MaintenanceStep {
-	return {
-		name: 'permission-refresh',
-		order: PERMISSION_REFRESH_ORDER,
-
-		async run(_context: MaintenanceContext): Promise<StepOutcome> {
-			const { changed } = await deps.permissions.refresh();
-
-			return {
-				// Reading permission is not a platform mutation, so it never counts
-				// toward the zero-operation guarantee.
-				operationCount: 0,
-				permissionChanged: changed,
-				cancelledIds: [],
-			};
-		},
-	};
-}
+/**
+ * The permission re-read maintenance step.
+ *
+ * The user can change permission in system settings while the app is
+ * backgrounded, and the platform does not tell anyone. Re-reading on foreground
+ * is the only way a consumer's interface avoids showing a stale answer.
+ *
+ * Runs last (order 30): permission state does not affect what the earlier steps
+ * expand or re-anchor, and reading it after they have run means the report
+ * reflects the device as the cycle leaves it.
+ */
+
+import type { MaintenanceStep, MaintenanceContext, StepOutcome } from './cycle';
+import type { Permissions } from '../permission';
+
+export const PERMISSION_REFRESH_ORDER = 30;
+
+export interface PermissionRefreshDependencies {
+	readonly permissions: Permissions;
+}
+
+export function createPermissionRefreshStep(
+	deps: PermissionRefreshDependencies,
+): MaintenanceStep {
+	return {
+		name: 'permission-refresh',
+		order: PERMISSION_REFRESH_ORDER,
+
+		async run(_context: MaintenanceContext): Promise<StepOutcome> {
+			const { changed } = await deps.permissions.refresh();
+
+			return {
+				// Reading permission is not a platform mutation, so it never counts
+				// toward the zero-operation guarantee.
+				operationCount: 0,
+				permissionChanged: changed,
+				cancelledIds: [],
+			};
+		},
+	};
+}