@chipmobilesdk/rn-notification 0.4.0 → 0.5.0

package/src/reconcile/index.ts

@@ -1,180 +1,180 @@
-/**
- * The reconciliation operation.
- *
- * A caller hands over the complete set its data implies; the package works out
- * what to add, replace, and remove. This is **never** run automatically — only
- * the caller knows what its data implies, and a package that guessed a desired
- * set would cancel notifications it does not understand.
- *
- * Overlapping calls are serialized rather than run concurrently, because two
- * passes interleaving their cancels and creates is exactly how duplicates
- * appear.
- */
-
-import type { NotificationRequest, PendingEntry } from '../contract/notification';
-import type { ReconcileInput, ReconcileResult } from '../contract/reconcile';
-import type { ResolvedTone } from '../contract/channel';
-import type { NotificationEngineAdapter } from '../engine/adapter';
-import { DIAGNOSTIC_CODES } from '../contract/errors';
-import { anchorMoment, type TimeZoneReader } from '../schedule/anchor';
-import { resolveMoment } from '../schedule/resolve-moment';
-import { validateRequest } from '../schedule';
-import { isNotificationError } from '../contract/errors';
-import type { RejectedEntry } from '../contract/reconcile';
-import { splitDuplicates } from './duplicates';
-import { truncateToCeiling } from './truncate';
-import { createScheduleWriter } from '../schedule/writer';
-import { diff } from './diff';
-import { applyInChunks } from './chunk';
-
-export interface ReconcileDependencies {
-	readonly engine: NotificationEngineAdapter;
-	readonly resolveTone: (toneId: string) => ResolvedTone | undefined;
-	readonly timeZone: TimeZoneReader;
-	readonly now: () => number;
-	readonly canScheduleExactly: () => boolean;
-	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
-	/** Overridable for tests that need to observe chunk boundaries. */
-	readonly chunkSize?: number;
-}
-
-/**
- * Narrows the device set to the caller's declared domain.
- *
- * Everything outside it is invisible to this pass, which is what makes it safe
- * to cancel strays: a notification from another domain or another library is
- * never a stray, it simply is not ours.
- */
-function inDomain(entry: PendingEntry, input: ReconcileInput): boolean {
-	if (entry.pushCreated && input.includePushCreated !== true) return false;
-	return entry.groupTag === input.domain;
-}
-
-export function createReconciler(deps: ReconcileDependencies) {
-	const emit = deps.emit ?? (() => {});
-	const writer = createScheduleWriter(deps.engine);
-	let inFlight: Promise<ReconcileResult> = Promise.resolve() as unknown as Promise<ReconcileResult>;
-
-	const run = async (input: ReconcileInput): Promise<ReconcileResult> => {
-		const startedAt = deps.now();
-		const zone = deps.timeZone();
-
-		const device = (await deps.engine.getPending()).filter(entry => inDomain(entry, input));
-		const existingIds = new Set(device.map(entry => entry.id));
-
-		// Duplicates first: a repeated identifier is refused before anything else
-		// looks at it, so no later stage has to decide which copy it meant.
-		const { unique, rejected: duplicateRejections } = splitDuplicates(input.desired, existingIds);
-		const rejected: RejectedEntry[] = [...duplicateRejections];
-
-		// Validate and anchor. A rejection here removes one entry; it never fails
-		// the pass, because 499 valid entries should not be lost to one bad one.
-		const valid: NotificationRequest[] = [];
-		const resolvedAt = new Map<string, number>();
-
-		for (const request of unique) {
-			try {
-				validateRequest(request, deps.resolveTone);
-				const anchored = anchorMoment(request.moment, zone);
-				const resolution = resolveMoment(anchored.resolvedAt, deps.now());
-				resolvedAt.set(request.id, resolution.at);
-				valid.push(request);
-			} catch (error) {
-				rejected.push({
-					id: request.id,
-					code: isNotificationError(error) ? error.code : 'UNKNOWN',
-					reason: error instanceof Error ? error.message : String(error),
-					occurrences: 1,
-					existingLeftInPlace: existingIds.has(request.id),
-				});
-			}
-		}
-
-		// Stop markers occupy real platform capacity, so the ceiling a consumer's
-		// notifications can actually use is smaller than the platform's own.
-		// Hiding that would let the package quietly reduce how many notifications
-		// fit and report a full set as registered when it was not.
-		const { kept, report: truncation } = truncateToCeiling(
-			valid,
-			resolvedAt,
-			await writer.capacity(),
-		);
-
-		if (truncation !== undefined) {
-			emit(
-				DIAGNOSTIC_CODES.TRUNCATED_OVER_CEILING,
-				`Desired set exceeded the platform ceiling of ${truncation.ceiling}; ${truncation.droppedCount} furthest-out entries were not registered. They are re-evaluated at the next window refresh.`,
-				{ ceiling: truncation.ceiling, dropped: truncation.droppedCount },
-			);
-		}
-
-		// Every rejected identifier is protected from cancellation. A rejection
-		// means the package could not tell what the caller intended, and
-		// destroying the existing notification on that basis would be the worst
-		// available answer (FR-028c).
-		const { operations, unchanged } = diff({
-			desired: kept,
-			resolvedAt,
-			device,
-			protectedIds: new Set(rejected.map(entry => entry.id)),
-		});
-
-		const created: string[] = [];
-		const replaced: string[] = [];
-		const cancelled: string[] = [];
-		const approximate = !deps.canScheduleExactly();
-
-		await applyInChunks(
-			operations,
-			async operation => {
-				if (operation.kind === 'cancel') {
-					await writer.cancel(operation.id);
-					cancelled.push(operation.id);
-					return;
-				}
-
-				const request = operation.request!;
-				const tone = deps.resolveTone(request.tone)!;
-				await writer.write({
-					request,
-					resolvedAt: operation.resolvedAt!,
-					tone,
-					anchoringGeneration:
-						(request.moment.anchoring ?? 'wallClock') === 'absolute' ? undefined : zone,
-					approximate,
-				});
-				(operation.kind === 'create' ? created : replaced).push(operation.id);
-			},
-			{ size: deps.chunkSize },
-		);
-
-		return {
-			domain: input.domain,
-			created,
-			replaced,
-			cancelled,
-			unchanged,
-			rejected,
-			truncated: truncation,
-			operationCount: operations.length,
-			durationMs: deps.now() - startedAt,
-		};
-	};
-
-	return {
-		/**
-		 * Serialized against itself: a second call waits for the first rather than
-		 * interleaving with it.
-		 */
-		async reconcile(input: ReconcileInput): Promise<ReconcileResult> {
-			const next = inFlight.then(
-				() => run(input),
-				() => run(input),
-			);
-			inFlight = next.catch(() => undefined) as Promise<ReconcileResult>;
-			return next;
-		},
-	};
-}
-
-export type Reconciler = ReturnType<typeof createReconciler>;
+/**
+ * The reconciliation operation.
+ *
+ * A caller hands over the complete set its data implies; the package works out
+ * what to add, replace, and remove. This is **never** run automatically — only
+ * the caller knows what its data implies, and a package that guessed a desired
+ * set would cancel notifications it does not understand.
+ *
+ * Overlapping calls are serialized rather than run concurrently, because two
+ * passes interleaving their cancels and creates is exactly how duplicates
+ * appear.
+ */
+
+import type { NotificationRequest, PendingEntry } from '../contract/notification';
+import type { ReconcileInput, ReconcileResult } from '../contract/reconcile';
+import type { ResolvedTone } from '../contract/channel';
+import type { NotificationEngineAdapter } from '../engine/adapter';
+import { DIAGNOSTIC_CODES } from '../contract/errors';
+import { anchorMoment, type TimeZoneReader } from '../schedule/anchor';
+import { resolveMoment } from '../schedule/resolve-moment';
+import { validateRequest } from '../schedule';
+import { isNotificationError } from '../contract/errors';
+import type { RejectedEntry } from '../contract/reconcile';
+import { splitDuplicates } from './duplicates';
+import { truncateToCeiling } from './truncate';
+import { createScheduleWriter } from '../schedule/writer';
+import { diff } from './diff';
+import { applyInChunks } from './chunk';
+
+export interface ReconcileDependencies {
+	readonly engine: NotificationEngineAdapter;
+	readonly resolveTone: (toneId: string) => ResolvedTone | undefined;
+	readonly timeZone: TimeZoneReader;
+	readonly now: () => number;
+	readonly canScheduleExactly: () => boolean;
+	readonly emit?: (code: string, message: string, context?: Record<string, unknown>) => void;
+	/** Overridable for tests that need to observe chunk boundaries. */
+	readonly chunkSize?: number;
+}
+
+/**
+ * Narrows the device set to the caller's declared domain.
+ *
+ * Everything outside it is invisible to this pass, which is what makes it safe
+ * to cancel strays: a notification from another domain or another library is
+ * never a stray, it simply is not ours.
+ */
+function inDomain(entry: PendingEntry, input: ReconcileInput): boolean {
+	if (entry.pushCreated && input.includePushCreated !== true) return false;
+	return entry.groupTag === input.domain;
+}
+
+export function createReconciler(deps: ReconcileDependencies) {
+	const emit = deps.emit ?? (() => {});
+	const writer = createScheduleWriter(deps.engine);
+	let inFlight: Promise<ReconcileResult> = Promise.resolve() as unknown as Promise<ReconcileResult>;
+
+	const run = async (input: ReconcileInput): Promise<ReconcileResult> => {
+		const startedAt = deps.now();
+		const zone = deps.timeZone();
+
+		const device = (await deps.engine.getPending()).filter(entry => inDomain(entry, input));
+		const existingIds = new Set(device.map(entry => entry.id));
+
+		// Duplicates first: a repeated identifier is refused before anything else
+		// looks at it, so no later stage has to decide which copy it meant.
+		const { unique, rejected: duplicateRejections } = splitDuplicates(input.desired, existingIds);
+		const rejected: RejectedEntry[] = [...duplicateRejections];
+
+		// Validate and anchor. A rejection here removes one entry; it never fails
+		// the pass, because 499 valid entries should not be lost to one bad one.
+		const valid: NotificationRequest[] = [];
+		const resolvedAt = new Map<string, number>();
+
+		for (const request of unique) {
+			try {
+				validateRequest(request, deps.resolveTone);
+				const anchored = anchorMoment(request.moment, zone);
+				const resolution = resolveMoment(anchored.resolvedAt, deps.now());
+				resolvedAt.set(request.id, resolution.at);
+				valid.push(request);
+			} catch (error) {
+				rejected.push({
+					id: request.id,
+					code: isNotificationError(error) ? error.code : 'UNKNOWN',
+					reason: error instanceof Error ? error.message : String(error),
+					occurrences: 1,
+					existingLeftInPlace: existingIds.has(request.id),
+				});
+			}
+		}
+
+		// Stop markers occupy real platform capacity, so the ceiling a consumer's
+		// notifications can actually use is smaller than the platform's own.
+		// Hiding that would let the package quietly reduce how many notifications
+		// fit and report a full set as registered when it was not.
+		const { kept, report: truncation } = truncateToCeiling(
+			valid,
+			resolvedAt,
+			await writer.capacity(),
+		);
+
+		if (truncation !== undefined) {
+			emit(
+				DIAGNOSTIC_CODES.TRUNCATED_OVER_CEILING,
+				`Desired set exceeded the platform ceiling of ${truncation.ceiling}; ${truncation.droppedCount} furthest-out entries were not registered. They are re-evaluated at the next window refresh.`,
+				{ ceiling: truncation.ceiling, dropped: truncation.droppedCount },
+			);
+		}
+
+		// Every rejected identifier is protected from cancellation. A rejection
+		// means the package could not tell what the caller intended, and
+		// destroying the existing notification on that basis would be the worst
+		// available answer (FR-028c).
+		const { operations, unchanged } = diff({
+			desired: kept,
+			resolvedAt,
+			device,
+			protectedIds: new Set(rejected.map(entry => entry.id)),
+		});
+
+		const created: string[] = [];
+		const replaced: string[] = [];
+		const cancelled: string[] = [];
+		const approximate = !deps.canScheduleExactly();
+
+		await applyInChunks(
+			operations,
+			async operation => {
+				if (operation.kind === 'cancel') {
+					await writer.cancel(operation.id);
+					cancelled.push(operation.id);
+					return;
+				}
+
+				const request = operation.request!;
+				const tone = deps.resolveTone(request.tone)!;
+				await writer.write({
+					request,
+					resolvedAt: operation.resolvedAt!,
+					tone,
+					anchoringGeneration:
+						(request.moment.anchoring ?? 'wallClock') === 'absolute' ? undefined : zone,
+					approximate,
+				});
+				(operation.kind === 'create' ? created : replaced).push(operation.id);
+			},
+			{ size: deps.chunkSize },
+		);
+
+		return {
+			domain: input.domain,
+			created,
+			replaced,
+			cancelled,
+			unchanged,
+			rejected,
+			truncated: truncation,
+			operationCount: operations.length,
+			durationMs: deps.now() - startedAt,
+		};
+	};
+
+	return {
+		/**
+		 * Serialized against itself: a second call waits for the first rather than
+		 * interleaving with it.
+		 */
+		async reconcile(input: ReconcileInput): Promise<ReconcileResult> {
+			const next = inFlight.then(
+				() => run(input),
+				() => run(input),
+			);
+			inFlight = next.catch(() => undefined) as Promise<ReconcileResult>;
+			return next;
+		},
+	};
+}
+
+export type Reconciler = ReturnType<typeof createReconciler>;

package/src/reconcile/truncate.ts

@@ -1,56 +1,56 @@
-/**
- * Platform-ceiling truncation.
- *
- * iOS keeps only the 64 soonest pending notifications and silently discards the
- * rest. The package computes the same cut deliberately, so the outcome is
- * reported rather than discovered as missing notifications.
- *
- * Soonest-first is the only rule that degrades gracefully: dropped entries are
- * not lost, they are simply not yet registered, and each window refresh
- * registers those that have moved into range.
- */
-
-import type { NotificationRequest } from '../contract/notification';
-import type { TruncationReport } from '../contract/reconcile';
-
-export interface TruncationOutcome {
-	readonly kept: readonly NotificationRequest[];
-	readonly report?: TruncationReport;
-}
-
-/**
- * Keeps the `ceiling` soonest entries.
- *
- * Ties on the delivery instant are broken by identifier so the cut is
- * deterministic — otherwise two runs over the same data could drop different
- * entries and the idempotence guarantee would not hold.
- */
-export function truncateToCeiling(
-	desired: readonly NotificationRequest[],
-	resolvedAt: ReadonlyMap<string, number>,
-	ceiling: number,
-): TruncationOutcome {
-	if (desired.length <= ceiling) {
-		return { kept: desired };
-	}
-
-	const ordered = [...desired].sort((a, b) => {
-		const aAt = resolvedAt.get(a.id) ?? a.moment.at;
-		const bAt = resolvedAt.get(b.id) ?? b.moment.at;
-		if (aAt !== bAt) return aAt - bAt;
-		return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
-	});
-
-	const kept = ordered.slice(0, ceiling);
-	const dropped = ordered.slice(ceiling);
-
-	return {
-		kept,
-		report: {
-			ceiling,
-			droppedCount: dropped.length,
-			droppedIds: dropped.map(entry => entry.id),
-			reEvaluatedOnNextRefresh: true,
-		},
-	};
-}
+/**
+ * Platform-ceiling truncation.
+ *
+ * iOS keeps only the 64 soonest pending notifications and silently discards the
+ * rest. The package computes the same cut deliberately, so the outcome is
+ * reported rather than discovered as missing notifications.
+ *
+ * Soonest-first is the only rule that degrades gracefully: dropped entries are
+ * not lost, they are simply not yet registered, and each window refresh
+ * registers those that have moved into range.
+ */
+
+import type { NotificationRequest } from '../contract/notification';
+import type { TruncationReport } from '../contract/reconcile';
+
+export interface TruncationOutcome {
+	readonly kept: readonly NotificationRequest[];
+	readonly report?: TruncationReport;
+}
+
+/**
+ * Keeps the `ceiling` soonest entries.
+ *
+ * Ties on the delivery instant are broken by identifier so the cut is
+ * deterministic — otherwise two runs over the same data could drop different
+ * entries and the idempotence guarantee would not hold.
+ */
+export function truncateToCeiling(
+	desired: readonly NotificationRequest[],
+	resolvedAt: ReadonlyMap<string, number>,
+	ceiling: number,
+): TruncationOutcome {
+	if (desired.length <= ceiling) {
+		return { kept: desired };
+	}
+
+	const ordered = [...desired].sort((a, b) => {
+		const aAt = resolvedAt.get(a.id) ?? a.moment.at;
+		const bAt = resolvedAt.get(b.id) ?? b.moment.at;
+		if (aAt !== bAt) return aAt - bAt;
+		return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+	});
+
+	const kept = ordered.slice(0, ceiling);
+	const dropped = ordered.slice(ceiling);
+
+	return {
+		kept,
+		report: {
+			ceiling,
+			droppedCount: dropped.length,
+			droppedIds: dropped.map(entry => entry.id),
+			reEvaluatedOnNextRefresh: true,
+		},
+	};
+}

package/src/recurrence/clock-guard.ts

@@ -1,71 +1,73 @@
-/**
- * Clock-discontinuity bounding.
- *
- * A device clock moved backwards makes past occurrences look future again. Left
- * alone, the next expansion would re-register every occurrence the user already
- * received, and moving the clock forward again would fire them all at once.
- *
- * The guard is deliberately blunt: occurrences at or before the last horizon the
- * series already expanded through are never re-emitted. The package would
- * rather lose an occurrence after a manual clock change than deliver a burst of
- * notifications for events that already happened.
- */
-
-import type { Occurrence } from './expand';
-
-/** A jump larger than this is treated as a clock change rather than ordinary drift. */
-export const CLOCK_DISCONTINUITY_THRESHOLD_MS = 60 * 60 * 1000;
-
-export interface ClockGuardInput {
-	readonly occurrences: readonly Occurrence[];
-	/** Horizon this series had already expanded through before now. */
-	readonly previousHorizon: number | undefined;
-	readonly now: number;
-	/** The clock reading when the series was last expanded, if known. */
-	readonly previousNow: number | undefined;
-}
-
-export interface ClockGuardResult {
-	readonly occurrences: readonly Occurrence[];
-	readonly suppressed: number;
-	readonly discontinuity: 'none' | 'backwards' | 'forwards';
-}
-
-/**
- * Drops occurrences that a clock discontinuity would otherwise resurrect.
- *
- * Forward jumps are detected and reported but not filtered: an occurrence that
- * became due because time genuinely passed is legitimate, and the platform's
- * own delivery is the right place for it to be resolved.
- */
-export function guardAgainstClockChange(input: ClockGuardInput): ClockGuardResult {
-	const { occurrences, previousHorizon, now, previousNow } = input;
-
-	let discontinuity: ClockGuardResult['discontinuity'] = 'none';
-	if (previousNow !== undefined) {
-		const delta = now - previousNow;
-		if (delta < -CLOCK_DISCONTINUITY_THRESHOLD_MS) {
-			discontinuity = 'backwards';
-		} else if (delta > CLOCK_DISCONTINUITY_THRESHOLD_MS * 24) {
-			discontinuity = 'forwards';
-		}
-	}
-
-	if (previousHorizon === undefined) {
-		return { occurrences, suppressed: 0, discontinuity };
-	}
-
-	// Anything at or before the previously-expanded horizon was already handled
-	// once. Re-emitting it would mean delivering a notification for an event the
-	// user has already seen.
-	const kept = occurrences.filter(occurrence => occurrence.at > previousHorizon || occurrence.at > now);
-	const alreadyHandled = occurrences.filter(
-		occurrence => occurrence.at <= previousHorizon && occurrence.at <= now,
-	);
-
-	return {
-		occurrences: kept,
-		suppressed: alreadyHandled.length,
-		discontinuity,
-	};
-}
+/**
+ * Clock-discontinuity bounding.
+ *
+ * A device clock moved backwards makes past occurrences look future again. Left
+ * alone, the next expansion would re-register every occurrence the user already
+ * received, and moving the clock forward again would fire them all at once.
+ *
+ * The guard is deliberately blunt: occurrences at or before the last horizon the
+ * series already expanded through are never re-emitted. The package would
+ * rather lose an occurrence after a manual clock change than deliver a burst of
+ * notifications for events that already happened.
+ */
+
+import type { Occurrence } from './expand';
+
+/** A jump larger than this is treated as a clock change rather than ordinary drift. */
+export const CLOCK_DISCONTINUITY_THRESHOLD_MS = 60 * 60 * 1000;
+
+export interface ClockGuardInput {
+	readonly occurrences: readonly Occurrence[];
+	/** Horizon this series had already expanded through before now. */
+	readonly previousHorizon: number | undefined;
+	readonly now: number;
+	/** The clock reading when the series was last expanded, if known. */
+	readonly previousNow: number | undefined;
+}
+
+export interface ClockGuardResult {
+	readonly occurrences: readonly Occurrence[];
+	readonly suppressed: number;
+	readonly discontinuity: 'none' | 'backwards' | 'forwards';
+}
+
+/**
+ * Drops occurrences that a clock discontinuity would otherwise resurrect.
+ *
+ * Forward jumps are detected and reported but not filtered: an occurrence that
+ * became due because time genuinely passed is legitimate, and the platform's
+ * own delivery is the right place for it to be resolved.
+ */
+export function guardAgainstClockChange(input: ClockGuardInput): ClockGuardResult {
+	const { occurrences, previousHorizon, now, previousNow } = input;
+
+	let discontinuity: ClockGuardResult['discontinuity'] = 'none';
+	if (previousNow !== undefined) {
+		const delta = now - previousNow;
+		if (delta < -CLOCK_DISCONTINUITY_THRESHOLD_MS) {
+			discontinuity = 'backwards';
+		} else if (delta > CLOCK_DISCONTINUITY_THRESHOLD_MS * 24) {
+			discontinuity = 'forwards';
+		}
+	}
+
+	if (previousHorizon === undefined) {
+		return { occurrences, suppressed: 0, discontinuity };
+	}
+
+	// Anything at or before the previously-expanded horizon was already handled
+	// once. Re-emitting it would mean delivering a notification for an event the
+	// user has already seen.
+	const kept = occurrences.filter(
+		occurrence => occurrence.at > previousHorizon || occurrence.at > now,
+	);
+	const alreadyHandled = occurrences.filter(
+		occurrence => occurrence.at <= previousHorizon && occurrence.at <= now,
+	);
+
+	return {
+		occurrences: kept,
+		suppressed: alreadyHandled.length,
+		discontinuity,
+	};
+}