@chipmobilesdk/rn-notification 0.4.0 → 0.5.0

package/src/repeat/expiry.ts

@@ -1,55 +1,53 @@
-/**
- * Repeat expiry.
- *
- * When a stop marker is delivered, the alert it guards has run its declared
- * course. This handler ends the sound and leaves the notification exactly where
- * it is, then removes the marker.
- *
- * Nothing here imports the engine. It talks to the port, which is what lets the
- * whole mechanism be proven on a virtual clock with no device.
- */
-
-import type { DeliveryEvent, NotificationEngineAdapter } from '../engine/adapter';
-
-export interface RepeatExpiryDependencies {
-	readonly engine: NotificationEngineAdapter;
-	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
-}
-
-export interface RepeatExpiryHandler {
-	/** Reacts to one delivery. Ignores anything that is not a stop marker. */
-	handle(event: DeliveryEvent): Promise<void>;
-	/** Removes the marker guarding a target, when the target is cancelled or replaced. */
-	release(targetId: string): Promise<void>;
-}
-
-export function createRepeatExpiryHandler(
-	deps: RepeatExpiryDependencies,
-): RepeatExpiryHandler {
-	return {
-		async handle(event: DeliveryEvent): Promise<void> {
-			const stop = event.repeatStop;
-			if (stop === undefined) return;
-
-			// Order matters. Silence first, remove the marker second: if the
-			// process dies between the two, a marker left behind is harmless
-			// noise, whereas a device left sounding is the failure this exists to
-			// prevent.
-			//
-			// `silenceDelivered` returning false is the ordinary case, not an
-			// error — it means the user already handled the notification. Checking
-			// the tray rather than racing to cancel the marker on interaction is
-			// what makes early handling correct by construction: even if the marker
-			// fires, there is nothing left to act on.
-			await deps.engine.silenceDelivered(stop.targetId);
-			await deps.engine.cancel(stop.markerId);
-		},
-
-		async release(targetId: string): Promise<void> {
-			const outstanding = await deps.engine.listRepeatStops();
-			const marker = outstanding.find(stop => stop.targetId === targetId);
-			if (marker === undefined) return;
-			await deps.engine.cancel(marker.markerId);
-		},
-	};
-}
+/**
+ * Repeat expiry.
+ *
+ * When a stop marker is delivered, the alert it guards has run its declared
+ * course. This handler ends the sound and leaves the notification exactly where
+ * it is, then removes the marker.
+ *
+ * Nothing here imports the engine. It talks to the port, which is what lets the
+ * whole mechanism be proven on a virtual clock with no device.
+ */
+
+import type { DeliveryEvent, NotificationEngineAdapter } from '../engine/adapter';
+
+export interface RepeatExpiryDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+export interface RepeatExpiryHandler {
+	/** Reacts to one delivery. Ignores anything that is not a stop marker. */
+	handle(event: DeliveryEvent): Promise<void>;
+	/** Removes the marker guarding a target, when the target is cancelled or replaced. */
+	release(targetId: string): Promise<void>;
+}
+
+export function createRepeatExpiryHandler(deps: RepeatExpiryDependencies): RepeatExpiryHandler {
+	return {
+		async handle(event: DeliveryEvent): Promise<void> {
+			const stop = event.repeatStop;
+			if (stop === undefined) return;
+
+			// Order matters. Silence first, remove the marker second: if the
+			// process dies between the two, a marker left behind is harmless
+			// noise, whereas a device left sounding is the failure this exists to
+			// prevent.
+			//
+			// `silenceDelivered` returning false is the ordinary case, not an
+			// error — it means the user already handled the notification. Checking
+			// the tray rather than racing to cancel the marker on interaction is
+			// what makes early handling correct by construction: even if the marker
+			// fires, there is nothing left to act on.
+			await deps.engine.silenceDelivered(stop.targetId);
+			await deps.engine.cancel(stop.markerId);
+		},
+
+		async release(targetId: string): Promise<void> {
+			const outstanding = await deps.engine.listRepeatStops();
+			const marker = outstanding.find(stop => stop.targetId === targetId);
+			if (marker === undefined) return;
+			await deps.engine.cancel(marker.markerId);
+		},
+	};
+}

package/src/repeat/index.ts

@@ -1,54 +1,54 @@
-/**
- * Repeat expiry — bounding an alert that repeats until it is handled.
- *
- * The one piece of this package a consumer has to wire up themselves. The
- * engine registers its background task at module scope, outside the React tree,
- * and no library can perform that registration on an app's behalf.
- *
- * An app that declares no repeating tone needs none of this.
- */
-
-import type { NotificationEngineAdapter } from '../engine/adapter';
-import { createRepeatExpiryHandler } from './expiry';
-
-export { createRepeatExpiryHandler } from './expiry';
-export type { RepeatExpiryHandler, RepeatExpiryDependencies } from './expiry';
-export { REPEAT_STOP_PREFIX, isRepeatStopId, markerIdFor, repeatStopFor } from './marker';
-
-export interface BackgroundHandlerRegistration {
-	readonly engine: NotificationEngineAdapter;
-	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
-}
-
-/**
- * Registers the handler that ends a repeating alert while the app is dead.
- *
- * Call this at module scope in `index.js`, beside the app registration — not
- * inside a component, and not inside an effect. By the time a component mounts,
- * the process that needed this handler has already been asked to run it.
- *
- * Without it a repeating alert still starts and still stops when the user
- * handles it, but nothing ends it on a device left face-down on a table. That
- * is the whole reason the feature exists, so `apply()` reports its absence
- * rather than letting anyone find out the hard way.
- */
-export function registerBackgroundNotificationHandler(
-	registration: BackgroundHandlerRegistration,
-): void {
-	const handler = createRepeatExpiryHandler(registration);
-
-	registration.engine.registerBackgroundDeliveryHandler(event => handler.handle(event));
-
-	// Both paths, not just the background one. The engine routes a delivery to
-	// the foreground listener while the app is alive and to the headless task
-	// only when it is not — so registering only the latter leaves the alert
-	// sounding for anyone holding the phone when the window runs out, which is
-	// the one case they would certainly notice.
-	registration.engine.subscribeToDeliveries(event => {
-		// Deliberately not awaited: the engine's foreground listener is
-		// synchronous, and a rejection here must not take the subscription down
-		// with it — a handler that stopped listening would leave every later
-		// alarm unbounded.
-		handler.handle(event).catch(() => {});
-	});
-}
+/**
+ * Repeat expiry — bounding an alert that repeats until it is handled.
+ *
+ * The one piece of this package a consumer has to wire up themselves. The
+ * engine registers its background task at module scope, outside the React tree,
+ * and no library can perform that registration on an app's behalf.
+ *
+ * An app that declares no repeating tone needs none of this.
+ */
+
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import { createRepeatExpiryHandler } from './expiry';
+
+export { createRepeatExpiryHandler } from './expiry';
+export type { RepeatExpiryHandler, RepeatExpiryDependencies } from './expiry';
+export { REPEAT_STOP_PREFIX, isRepeatStopId, markerIdFor, repeatStopFor } from './marker';
+
+export interface BackgroundHandlerRegistration {
+	readonly engine: NotificationEngineAdapter;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+}
+
+/**
+ * Registers the handler that ends a repeating alert while the app is dead.
+ *
+ * Call this at module scope in `index.js`, beside the app registration — not
+ * inside a component, and not inside an effect. By the time a component mounts,
+ * the process that needed this handler has already been asked to run it.
+ *
+ * Without it a repeating alert still starts and still stops when the user
+ * handles it, but nothing ends it on a device left face-down on a table. That
+ * is the whole reason the feature exists, so `apply()` reports its absence
+ * rather than letting anyone find out the hard way.
+ */
+export function registerBackgroundNotificationHandler(
+	registration: BackgroundHandlerRegistration,
+): void {
+	const handler = createRepeatExpiryHandler(registration);
+
+	registration.engine.registerBackgroundDeliveryHandler(event => handler.handle(event));
+
+	// Both paths, not just the background one. The engine routes a delivery to
+	// the foreground listener while the app is alive and to the headless task
+	// only when it is not — so registering only the latter leaves the alert
+	// sounding for anyone holding the phone when the window runs out, which is
+	// the one case they would certainly notice.
+	registration.engine.subscribeToDeliveries(event => {
+		// Deliberately not awaited: the engine's foreground listener is
+		// synchronous, and a rejection here must not take the subscription down
+		// with it — a handler that stopped listening would leave every later
+		// alarm unbounded.
+		handler.handle(event).catch(() => {});
+	});
+}

package/src/repeat/marker.ts

@@ -1,72 +1,72 @@
-/**
- * Stop-marker identity.
- *
- * A repeating alert has to end without the app being alive, and no platform
- * offers "stop the sound at time T but keep the notification". So the package
- * schedules its own notification at T and reacts to its delivery. That
- * notification is a *marker*: it exists to be delivered and immediately
- * removed, never to be read.
- *
- * The marker's identifier is derived from the target's by hashing rather than by
- * concatenation. Concatenation would overflow the package's 128-character
- * identifier limit for any target already near it, and would make the marker's
- * identity a function of a value the consumer controls — which is how a
- * consumer identifier ends up colliding with an internal one.
- */
-
-import type { RepeatStop } from '../engine/adapter';
-
-/**
- * Reserved identifier namespace.
- *
- * Rejected as a consumer identifier prefix. A consumer id colliding with a
- * marker would not merely confuse a listing: the expiry handler cancels
- * markers, so the collision would delete a real notification.
- */
-export const REPEAT_STOP_PREFIX = 'cms.stop:';
-
-/**
- * FNV-1a, 32-bit. Deterministic, dependency-free, and stable across releases.
- *
- * Bitwise operators are the algorithm, not a micro-optimisation: arithmetic
- * equivalents would not wrap to 32 bits, and a marker id that changed between
- * releases would orphan every marker already scheduled on a device.
- */
-/* eslint-disable no-bitwise */
-function fnv1a(value: string, basis: number): number {
-	let hash = basis;
-	for (let index = 0; index < value.length; index += 1) {
-		hash ^= value.codePointAt(index) ?? 0;
-		hash = Math.imul(hash, 0x01000193) >>> 0;
-	}
-	return hash >>> 0;
-}
-/* eslint-enable no-bitwise */
-
-function hex8(value: number): string {
-	return value.toString(16).padStart(8, '0');
-}
-
-/**
- * The marker identifier for a target notification.
- *
- * Two independent hashes rather than one: a single 32-bit hash collides often
- * enough to matter once a device holds a handful of alarms, and a collision here
- * means one alarm's marker silences the other alarm and never silences its own.
- */
-export function markerIdFor(targetId: string): string {
-	return `${REPEAT_STOP_PREFIX}${hex8(fnv1a(targetId, 0x811c9dc5))}${hex8(fnv1a(targetId, 0x9e3779b9))}`;
-}
-
-export function isRepeatStopId(id: string): boolean {
-	return id.startsWith(REPEAT_STOP_PREFIX);
-}
-
-/** Describes the stop for a target whose alert must end at a known instant. */
-export function repeatStopFor(targetId: string, deliveredAt: number, forMs: number): RepeatStop {
-	return {
-		markerId: markerIdFor(targetId),
-		targetId,
-		dueAt: deliveredAt + forMs,
-	};
-}
+/**
+ * Stop-marker identity.
+ *
+ * A repeating alert has to end without the app being alive, and no platform
+ * offers "stop the sound at time T but keep the notification". So the package
+ * schedules its own notification at T and reacts to its delivery. That
+ * notification is a *marker*: it exists to be delivered and immediately
+ * removed, never to be read.
+ *
+ * The marker's identifier is derived from the target's by hashing rather than by
+ * concatenation. Concatenation would overflow the package's 128-character
+ * identifier limit for any target already near it, and would make the marker's
+ * identity a function of a value the consumer controls — which is how a
+ * consumer identifier ends up colliding with an internal one.
+ */
+
+import type { RepeatStop } from '../engine/adapter';
+
+/**
+ * Reserved identifier namespace.
+ *
+ * Rejected as a consumer identifier prefix. A consumer id colliding with a
+ * marker would not merely confuse a listing: the expiry handler cancels
+ * markers, so the collision would delete a real notification.
+ */
+export const REPEAT_STOP_PREFIX = 'cms.stop:';
+
+/**
+ * FNV-1a, 32-bit. Deterministic, dependency-free, and stable across releases.
+ *
+ * Bitwise operators are the algorithm, not a micro-optimisation: arithmetic
+ * equivalents would not wrap to 32 bits, and a marker id that changed between
+ * releases would orphan every marker already scheduled on a device.
+ */
+/* eslint-disable no-bitwise */
+function fnv1a(value: string, basis: number): number {
+	let hash = basis;
+	for (let index = 0; index < value.length; index += 1) {
+		hash ^= value.codePointAt(index) ?? 0;
+		hash = Math.imul(hash, 0x01000193) >>> 0;
+	}
+	return hash >>> 0;
+}
+/* eslint-enable no-bitwise */
+
+function hex8(value: number): string {
+	return value.toString(16).padStart(8, '0');
+}
+
+/**
+ * The marker identifier for a target notification.
+ *
+ * Two independent hashes rather than one: a single 32-bit hash collides often
+ * enough to matter once a device holds a handful of alarms, and a collision here
+ * means one alarm's marker silences the other alarm and never silences its own.
+ */
+export function markerIdFor(targetId: string): string {
+	return `${REPEAT_STOP_PREFIX}${hex8(fnv1a(targetId, 0x811c9dc5))}${hex8(fnv1a(targetId, 0x9e3779b9))}`;
+}
+
+export function isRepeatStopId(id: string): boolean {
+	return id.startsWith(REPEAT_STOP_PREFIX);
+}
+
+/** Describes the stop for a target whose alert must end at a known instant. */
+export function repeatStopFor(targetId: string, deliveredAt: number, forMs: number): RepeatStop {
+	return {
+		markerId: markerIdFor(targetId),
+		targetId,
+		dueAt: deliveredAt + forMs,
+	};
+}

package/src/repeat/place.ts

@@ -1,73 +1,73 @@
-/**
- * Keeping a notification's stop marker in step with the notification.
- *
- * Shared by the scheduler and the reconciler rather than written twice. They are
- * two doors into the same act — reconciliation is how most consumers schedule —
- * and a bound that only existed on one path would be a bound that mostly did not
- * exist.
- */
-
-import type { NotificationEngineAdapter } from '../engine/adapter';
-import type { ResolvedTone } from '../contract/channel';
-import { repeatStopFor } from './marker';
-
-export interface StopPlacement {
-	/**
-	 * Places the marker for a repeating notification, replacing any it already
-	 * had.
-	 *
-	 * Called on every schedule, replacements included: re-scheduling under an
-	 * identifier that already had one must leave exactly one entry and exactly
-	 * one marker, and the old marker's instant is no longer the right one.
-	 *
-	 * Nothing is placed when the tone does not repeat or the platform will not
-	 * honour repetition, so a non-repeating notification costs no extra platform
-	 * capacity at all.
-	 */
-	sync(targetId: string, tone: ResolvedTone, deliversAt: number): Promise<void>;
-	/** Drops any marker still guarding an identifier. */
-	release(targetId: string): Promise<void>;
-}
-
-export function createStopPlacement(engine: NotificationEngineAdapter): StopPlacement {
-	const release = async (targetId: string): Promise<void> => {
-		const outstanding = await engine.listRepeatStops();
-		const held = outstanding.find(stop => stop.targetId === targetId);
-		if (held !== undefined) {
-			await engine.cancel(held.markerId);
-		}
-	};
-
-	return {
-		release,
-
-		async sync(targetId, tone, deliversAt) {
-			await release(targetId);
-
-			const forMs = tone.android.repeatForMs;
-			if (!tone.android.loopSound || forMs === undefined) return;
-
-			const capabilities = await engine.getCapabilities();
-			if (!capabilities.supportsRepeatingAlert) return;
-
-			const stop = repeatStopFor(targetId, deliversAt, forMs);
-			await engine.schedule({
-				request: {
-					id: stop.markerId,
-					// Deliberately empty. A marker is delivered and removed within the
-					// same handler invocation; anything readable here would be text a
-					// user might glimpse and be confused by.
-					content: { title: '', body: '' },
-					tone: tone.toneId,
-					// Absolute: the bound is a duration from a known instant, not a
-					// wall-clock time that should follow the user across time zones.
-					moment: { at: stop.dueAt, anchoring: 'absolute' },
-				},
-				resolvedAt: stop.dueAt,
-				tone,
-				approximate: false,
-				repeatStop: stop,
-			});
-		},
-	};
-}
+/**
+ * Keeping a notification's stop marker in step with the notification.
+ *
+ * Shared by the scheduler and the reconciler rather than written twice. They are
+ * two doors into the same act — reconciliation is how most consumers schedule —
+ * and a bound that only existed on one path would be a bound that mostly did not
+ * exist.
+ */
+
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import type { ResolvedTone } from '../contract/channel';
+import { repeatStopFor } from './marker';
+
+export interface StopPlacement {
+	/**
+	 * Places the marker for a repeating notification, replacing any it already
+	 * had.
+	 *
+	 * Called on every schedule, replacements included: re-scheduling under an
+	 * identifier that already had one must leave exactly one entry and exactly
+	 * one marker, and the old marker's instant is no longer the right one.
+	 *
+	 * Nothing is placed when the tone does not repeat or the platform will not
+	 * honour repetition, so a non-repeating notification costs no extra platform
+	 * capacity at all.
+	 */
+	sync(targetId: string, tone: ResolvedTone, deliversAt: number): Promise<void>;
+	/** Drops any marker still guarding an identifier. */
+	release(targetId: string): Promise<void>;
+}
+
+export function createStopPlacement(engine: NotificationEngineAdapter): StopPlacement {
+	const release = async (targetId: string): Promise<void> => {
+		const outstanding = await engine.listRepeatStops();
+		const held = outstanding.find(stop => stop.targetId === targetId);
+		if (held !== undefined) {
+			await engine.cancel(held.markerId);
+		}
+	};
+
+	return {
+		release,
+
+		async sync(targetId, tone, deliversAt) {
+			await release(targetId);
+
+			const forMs = tone.android.repeatForMs;
+			if (!tone.android.loopSound || forMs === undefined) return;
+
+			const capabilities = await engine.getCapabilities();
+			if (!capabilities.supportsRepeatingAlert) return;
+
+			const stop = repeatStopFor(targetId, deliversAt, forMs);
+			await engine.schedule({
+				request: {
+					id: stop.markerId,
+					// Deliberately empty. A marker is delivered and removed within the
+					// same handler invocation; anything readable here would be text a
+					// user might glimpse and be confused by.
+					content: { title: '', body: '' },
+					tone: tone.toneId,
+					// Absolute: the bound is a duration from a known instant, not a
+					// wall-clock time that should follow the user across time zones.
+					moment: { at: stop.dueAt, anchoring: 'absolute' },
+				},
+				resolvedAt: stop.dueAt,
+				tone,
+				approximate: false,
+				repeatStop: stop,
+			});
+		},
+	};
+}