@chipmobilesdk/rn-notification 0.4.0 → 0.5.0

package/src/schedule/anchor.ts

@@ -1,267 +1,294 @@
-/**
- * Time-zone anchoring and re-anchoring.
- *
- * Wall-clock is the default because reminders are wall-clock things: an 08:00
- * reminder should stay 08:00 after the user crosses a time zone, and a caller
- * who does not choose should get what their users expect rather than a silent
- * shift.
- *
- * The cost is re-anchoring. When the device zone changes, every scheduled
- * wall-clock entry must be rewritten to preserve the clock time it named, and
- * every absolute entry must be left completely alone.
- *
- * The limit this cannot fix is stated rather than hidden: a wall-clock
- * notification whose moment arrives while the app has not run since the zone
- * changed fires at the previously anchored instant. The anchoring generation on
- * each entry is what makes that detectable instead of invisible.
- */
-
-import type { AnchoringMode, PendingEntry } from '../contract/notification';
-import { DEFAULT_ANCHORING_MODE } from '../contract/notification';
-
-/** Reads the platform time zone. Injected so the pure logic needs no native module. */
-export type TimeZoneReader = () => string;
-
-/**
- * Resolves the platform zone via `react-native-localize`.
- *
- * Pure JavaScript is not sufficient here: `Intl.DateTimeFormat().resolvedOptions().timeZone`
- * is documented in React Native as not reliably updating when the device zone
- * changes, so it cannot back re-anchoring. Falls back to `Intl` only when the
- * module is absent, which is better than failing outright.
- */
-export function createPlatformTimeZoneReader(): TimeZoneReader {
-	return () => {
-		try {
-			const localize = require('react-native-localize') as { getTimeZone(): string };
-			return localize.getTimeZone();
-		} catch {
-			try {
-				return Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC';
-			} catch {
-				return 'UTC';
-			}
-		}
-	};
-}
-
-/** The calendar fields a wall-clock moment actually names. */
-export interface WallClockParts {
-	readonly year: number;
-	readonly month: number;
-	readonly day: number;
-	readonly hour: number;
-	readonly minute: number;
-	readonly second: number;
-}
-
-/**
- * Whether a zone name is one the runtime can actually format against.
- *
- * Hermes throws a hard `JSRangeErrorException: Invalid timezone name!` for a
- * bad zone, which kills the JavaScript thread rather than returning an error.
- * A stored anchoring generation is data that can be wrong — a corrupted record,
- * an entry written by an older build, or a defect like the one that stored a
- * tone id here — so it must be checked before it reaches `Intl`.
- */
-export function isValidTimeZone(timeZone: string): boolean {
-	if (timeZone.length === 0) return false;
-	try {
-		new Intl.DateTimeFormat('en-US', { timeZone }).format(0);
-		return true;
-	} catch {
-		return false;
-	}
-}
-
-/**
- * Decomposes an instant into the clock reading it produces in a given zone.
- *
- * Falls back to UTC for an unusable zone rather than throwing: a bad stored
- * value should degrade one entry's anchoring, not crash the app.
- */
-export function partsInZone(instant: number, timeZone: string): WallClockParts {
-	const zone = isValidTimeZone(timeZone) ? timeZone : 'UTC';
-	const formatter = new Intl.DateTimeFormat('en-US', {
-		timeZone: zone,
-		year: 'numeric',
-		month: '2-digit',
-		day: '2-digit',
-		hour: '2-digit',
-		minute: '2-digit',
-		second: '2-digit',
-		hour12: false,
-	});
-
-	const fields: Record<string, number> = {};
-	for (const part of formatter.formatToParts(new Date(instant))) {
-		if (part.type !== 'literal') {
-			fields[part.type] = Number.parseInt(part.value, 10);
-		}
-	}
-
-	return {
-		year: fields.year,
-		month: fields.month,
-		day: fields.day,
-		// Intl renders midnight as hour 24 in some environments; normalize it.
-		hour: fields.hour === 24 ? 0 : fields.hour,
-		minute: fields.minute,
-		second: fields.second,
-	};
-}
-
-/** The zone's offset from UTC, in milliseconds, at a given instant. */
-function offsetAt(instant: number, timeZone: string): number {
-	const parts = partsInZone(instant, timeZone);
-	const asUtc = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
-	return asUtc - Math.floor(instant / 1000) * 1000;
-}
-
-/**
- * Finds the instant at which a zone shows the given clock reading.
- *
- * Two passes, because the offset itself depends on the instant: the first guess
- * uses the offset at the naive UTC interpretation, the second corrects for a
- * daylight-saving boundary crossed by that guess.
- *
- * Daylight-saving resolution, per the documented rule:
- * - a clock time that does not exist resolves **forward** to the next valid instant;
- * - a clock time that occurs twice resolves to its **first** occurrence, so
- *   exactly one notification results rather than two.
- */
-export function instantForParts(parts: WallClockParts, timeZone: string): number {
-	const naive = Date.UTC(parts.year, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second);
-
-	let candidate = naive - offsetAt(naive, timeZone);
-	candidate = naive - offsetAt(candidate, timeZone);
-
-	const rendered = partsInZone(candidate, timeZone);
-
-	if (rendered.hour === parts.hour && rendered.minute === parts.minute) {
-		// Ambiguous readings (the repeated hour) land here on the first, earlier
-		// offset, which is the documented choice.
-		return candidate;
-	}
-
-	// The reading does not exist in this zone — a spring-forward gap. Step
-	// forward to the next instant that does exist rather than skipping the
-	// occurrence or failing.
-	const gapStep = 60 * 60 * 1000;
-	for (let attempt = 1; attempt <= 4; attempt += 1) {
-		const shifted = candidate + gapStep * attempt;
-		const shiftedParts = partsInZone(shifted, timeZone);
-		if (shiftedParts.day === parts.day || shiftedParts.hour > parts.hour) {
-			return shifted;
-		}
-	}
-
-	return candidate;
-}
-
-export interface AnchorInput {
-	readonly at: number;
-	readonly anchoring?: AnchoringMode;
-}
-
-export interface AnchoredMoment {
-	readonly resolvedAt: number;
-	readonly anchoring: AnchoringMode;
-	/** The zone this was anchored against. Absent for absolute-instant moments. */
-	readonly generation?: string;
-}
-
-/**
- * Resolves a caller-supplied moment into a firing instant.
- *
- * An absolute moment passes through untouched — that is the entire distinction.
- */
-export function anchorMoment(input: AnchorInput, timeZone: string): AnchoredMoment {
-	const anchoring = input.anchoring ?? DEFAULT_ANCHORING_MODE;
-
-	if (anchoring === 'absolute') {
-		return { resolvedAt: input.at, anchoring };
-	}
-
-	return { resolvedAt: input.at, anchoring, generation: timeZone };
-}
-
-export interface ReAnchorPlan {
-	/** Entries whose firing instant must be rewritten, with their new instant. */
-	readonly rewrites: readonly { readonly entry: PendingEntry; readonly resolvedAt: number }[];
-	readonly fromZone: string | undefined;
-	readonly toZone: string;
-	readonly zoneChanged: boolean;
-	/**
-	 * Entries carrying an anchoring generation the runtime cannot interpret.
-	 *
-	 * Left alone rather than re-anchored against a guess. Reported so a corrupted
-	 * or older-build record is visible instead of quietly producing wrong firing
-	 * instants.
-	 */
-	readonly unreadableGeneration: readonly string[];
-}
-
-/**
- * Computes what a zone change requires.
- *
- * Returns an empty plan when the zone has not moved, which is what makes
- * re-anchoring idempotent: the no-change check costs one comparison per entry
- * and issues zero platform operations.
- */
-export function planReAnchor(
-	pending: readonly PendingEntry[],
-	currentZone: string,
-): ReAnchorPlan {
-	const rewrites: { entry: PendingEntry; resolvedAt: number }[] = [];
-	const unreadableGeneration: string[] = [];
-	let fromZone: string | undefined;
-
-	for (const entry of pending) {
-		// Absolute-instant entries are never re-anchored, re-scheduled, or touched.
-		if (entry.anchoring === 'absolute') continue;
-
-		const generation = entry.anchoringGeneration;
-		if (generation === undefined || generation === currentZone) continue;
-
-		// A stored generation is data, and data can be wrong. Re-anchoring against
-		// a zone the runtime cannot read would move the entry to an arbitrary
-		// instant, which is worse than leaving it where it is and saying so.
-		if (!isValidTimeZone(generation)) {
-			unreadableGeneration.push(entry.id);
-			continue;
-		}
-
-		fromZone ??= generation;
-
-		// Preserve the clock reading the entry originally named, not the instant.
-		const originalParts = partsInZone(entry.resolvedAt, generation);
-		const resolvedAt = instantForParts(originalParts, currentZone);
-
-		if (resolvedAt !== entry.resolvedAt) {
-			rewrites.push({ entry, resolvedAt });
-		}
-	}
-
-	return {
-		rewrites,
-		fromZone,
-		toZone: currentZone,
-		zoneChanged: rewrites.length > 0 || fromZone !== undefined,
-		unreadableGeneration,
-	};
-}
-
-/**
- * True when an entry was anchored against a zone the device has since left.
- *
- * This is the FR-007c condition: the entry will fire at its old instant, and a
- * consumer can detect and explain that rather than being told nothing happened.
- */
-export function isStaleAnchor(entry: PendingEntry, currentZone: string): boolean {
-	return (
-		entry.anchoring === 'wallClock' &&
-		entry.anchoringGeneration !== undefined &&
-		entry.anchoringGeneration !== currentZone
-	);
-}
+/**
+ * Time-zone anchoring and re-anchoring.
+ *
+ * Wall-clock is the default because reminders are wall-clock things: an 08:00
+ * reminder should stay 08:00 after the user crosses a time zone, and a caller
+ * who does not choose should get what their users expect rather than a silent
+ * shift.
+ *
+ * The cost is re-anchoring. When the device zone changes, every scheduled
+ * wall-clock entry must be rewritten to preserve the clock time it named, and
+ * every absolute entry must be left completely alone.
+ *
+ * The limit this cannot fix is stated rather than hidden: a wall-clock
+ * notification whose moment arrives while the app has not run since the zone
+ * changed fires at the previously anchored instant. The anchoring generation on
+ * each entry is what makes that detectable instead of invisible.
+ */
+
+import {
+	getDateTimeFormat,
+	isValidTimeZone as isZoneValid,
+	lazyPeer,
+} from '@chipmobilesdk/rn-core';
+
+import type { AnchoringMode, PendingEntry } from '../contract/notification';
+import { DEFAULT_ANCHORING_MODE } from '../contract/notification';
+
+/** Reads the platform time zone. Injected so the pure logic needs no native module. */
+export type TimeZoneReader = () => string;
+
+const localizePeer = lazyPeer('react-native-localize', () => {
+	// Inside `try`, so Metro bundles an app that leaves this optional peer out.
+	try {
+		return require('react-native-localize') as { getTimeZone(): string };
+	} catch (cause) {
+		throw cause;
+	}
+});
+
+/**
+ * Resolves the platform zone via `react-native-localize`.
+ *
+ * Pure JavaScript is not sufficient here: `Intl.DateTimeFormat().resolvedOptions().timeZone`
+ * is documented in React Native as not reliably updating when the device zone
+ * changes, so it cannot back re-anchoring. Falls back to `Intl` only when the
+ * module is absent, which is better than failing outright.
+ */
+export function createPlatformTimeZoneReader(): TimeZoneReader {
+	return () => {
+		const localize = localizePeer.get();
+		try {
+			if (localize.ok) return localize.module.getTimeZone();
+			return Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC';
+		} catch {
+			try {
+				return Intl.DateTimeFormat().resolvedOptions().timeZone ?? 'UTC';
+			} catch {
+				return 'UTC';
+			}
+		}
+	};
+}
+
+/** The calendar fields a wall-clock moment actually names. */
+export interface WallClockParts {
+	readonly year: number;
+	readonly month: number;
+	readonly day: number;
+	readonly hour: number;
+	readonly minute: number;
+	readonly second: number;
+}
+
+/**
+ * Whether a zone name is one the runtime can actually format against.
+ *
+ * Hermes throws a hard `JSRangeErrorException: Invalid timezone name!` for a
+ * bad zone, which kills the JavaScript thread rather than returning an error.
+ * A stored anchoring generation is data that can be wrong — a corrupted record,
+ * an entry written by an older build, or a defect like the one that stored a
+ * tone id here — so it must be checked before it reaches `Intl`.
+ */
+export function isValidTimeZone(timeZone: string): boolean {
+	// rn-core memoizes the answer per zone: a recurrence expansion asks thousands
+	// of times about the same few zones (PERF-01).
+	return isZoneValid(timeZone);
+}
+
+/** The options `partsInZone` formats with; one shared formatter per zone. */
+const PARTS_OPTIONS = {
+	year: 'numeric',
+	month: '2-digit',
+	day: '2-digit',
+	hour: '2-digit',
+	minute: '2-digit',
+	second: '2-digit',
+	hour12: false,
+} as const;
+
+/**
+ * Decomposes an instant into the clock reading it produces in a given zone.
+ *
+ * Falls back to UTC for an unusable zone rather than throwing: a bad stored
+ * value should degrade one entry's anchoring, not crash the app.
+ */
+export function partsInZone(instant: number, timeZone: string): WallClockParts {
+	const zone = isValidTimeZone(timeZone) ? timeZone : 'UTC';
+	// Built once per zone and reused (PERF-01): constructing one per call was
+	// most of the cost of expanding a recurrence.
+	const formatter = getDateTimeFormat('en-US', { ...PARTS_OPTIONS, timeZone: zone });
+
+	const fields: Record<string, number> = {};
+	for (const part of formatter.formatToParts(new Date(instant))) {
+		if (part.type !== 'literal') {
+			fields[part.type] = Number.parseInt(part.value, 10);
+		}
+	}
+
+	return {
+		year: fields.year,
+		month: fields.month,
+		day: fields.day,
+		// Intl renders midnight as hour 24 in some environments; normalize it.
+		hour: fields.hour === 24 ? 0 : fields.hour,
+		minute: fields.minute,
+		second: fields.second,
+	};
+}
+
+/** The zone's offset from UTC, in milliseconds, at a given instant. */
+function offsetAt(instant: number, timeZone: string): number {
+	const parts = partsInZone(instant, timeZone);
+	const asUtc = Date.UTC(
+		parts.year,
+		parts.month - 1,
+		parts.day,
+		parts.hour,
+		parts.minute,
+		parts.second,
+	);
+	return asUtc - Math.floor(instant / 1000) * 1000;
+}
+
+/**
+ * Finds the instant at which a zone shows the given clock reading.
+ *
+ * Two passes, because the offset itself depends on the instant: the first guess
+ * uses the offset at the naive UTC interpretation, the second corrects for a
+ * daylight-saving boundary crossed by that guess.
+ *
+ * Daylight-saving resolution, per the documented rule:
+ * - a clock time that does not exist resolves **forward** to the next valid instant;
+ * - a clock time that occurs twice resolves to its **first** occurrence, so
+ *   exactly one notification results rather than two.
+ */
+export function instantForParts(parts: WallClockParts, timeZone: string): number {
+	const naive = Date.UTC(
+		parts.year,
+		parts.month - 1,
+		parts.day,
+		parts.hour,
+		parts.minute,
+		parts.second,
+	);
+
+	let candidate = naive - offsetAt(naive, timeZone);
+	candidate = naive - offsetAt(candidate, timeZone);
+
+	const rendered = partsInZone(candidate, timeZone);
+
+	if (rendered.hour === parts.hour && rendered.minute === parts.minute) {
+		// Ambiguous readings (the repeated hour) land here on the first, earlier
+		// offset, which is the documented choice.
+		return candidate;
+	}
+
+	// The reading does not exist in this zone — a spring-forward gap. Step
+	// forward to the next instant that does exist rather than skipping the
+	// occurrence or failing.
+	const gapStep = 60 * 60 * 1000;
+	for (let attempt = 1; attempt <= 4; attempt += 1) {
+		const shifted = candidate + gapStep * attempt;
+		const shiftedParts = partsInZone(shifted, timeZone);
+		if (shiftedParts.day === parts.day || shiftedParts.hour > parts.hour) {
+			return shifted;
+		}
+	}
+
+	return candidate;
+}
+
+export interface AnchorInput {
+	readonly at: number;
+	readonly anchoring?: AnchoringMode;
+}
+
+export interface AnchoredMoment {
+	readonly resolvedAt: number;
+	readonly anchoring: AnchoringMode;
+	/** The zone this was anchored against. Absent for absolute-instant moments. */
+	readonly generation?: string;
+}
+
+/**
+ * Resolves a caller-supplied moment into a firing instant.
+ *
+ * An absolute moment passes through untouched — that is the entire distinction.
+ */
+export function anchorMoment(input: AnchorInput, timeZone: string): AnchoredMoment {
+	const anchoring = input.anchoring ?? DEFAULT_ANCHORING_MODE;
+
+	if (anchoring === 'absolute') {
+		return { resolvedAt: input.at, anchoring };
+	}
+
+	return { resolvedAt: input.at, anchoring, generation: timeZone };
+}
+
+export interface ReAnchorPlan {
+	/** Entries whose firing instant must be rewritten, with their new instant. */
+	readonly rewrites: readonly { readonly entry: PendingEntry; readonly resolvedAt: number }[];
+	readonly fromZone: string | undefined;
+	readonly toZone: string;
+	readonly zoneChanged: boolean;
+	/**
+	 * Entries carrying an anchoring generation the runtime cannot interpret.
+	 *
+	 * Left alone rather than re-anchored against a guess. Reported so a corrupted
+	 * or older-build record is visible instead of quietly producing wrong firing
+	 * instants.
+	 */
+	readonly unreadableGeneration: readonly string[];
+}
+
+/**
+ * Computes what a zone change requires.
+ *
+ * Returns an empty plan when the zone has not moved, which is what makes
+ * re-anchoring idempotent: the no-change check costs one comparison per entry
+ * and issues zero platform operations.
+ */
+export function planReAnchor(pending: readonly PendingEntry[], currentZone: string): ReAnchorPlan {
+	const rewrites: { entry: PendingEntry; resolvedAt: number }[] = [];
+	const unreadableGeneration: string[] = [];
+	let fromZone: string | undefined;
+
+	for (const entry of pending) {
+		// Absolute-instant entries are never re-anchored, re-scheduled, or touched.
+		if (entry.anchoring === 'absolute') continue;
+
+		const generation = entry.anchoringGeneration;
+		if (generation === undefined || generation === currentZone) continue;
+
+		// A stored generation is data, and data can be wrong. Re-anchoring against
+		// a zone the runtime cannot read would move the entry to an arbitrary
+		// instant, which is worse than leaving it where it is and saying so.
+		if (!isValidTimeZone(generation)) {
+			unreadableGeneration.push(entry.id);
+			continue;
+		}
+
+		fromZone ??= generation;
+
+		// Preserve the clock reading the entry originally named, not the instant.
+		const originalParts = partsInZone(entry.resolvedAt, generation);
+		const resolvedAt = instantForParts(originalParts, currentZone);
+
+		if (resolvedAt !== entry.resolvedAt) {
+			rewrites.push({ entry, resolvedAt });
+		}
+	}
+
+	return {
+		rewrites,
+		fromZone,
+		toZone: currentZone,
+		zoneChanged: rewrites.length > 0 || fromZone !== undefined,
+		unreadableGeneration,
+	};
+}
+
+/**
+ * True when an entry was anchored against a zone the device has since left.
+ *
+ * This is the FR-007c condition: the entry will fire at its old instant, and a
+ * consumer can detect and explain that rather than being told nothing happened.
+ */
+export function isStaleAnchor(entry: PendingEntry, currentZone: string): boolean {
+	return (
+		entry.anchoring === 'wallClock' &&
+		entry.anchoringGeneration !== undefined &&
+		entry.anchoringGeneration !== currentZone
+	);
+}