rn-persistent-timer 1.1.0

package/src/usePersistentTimer.tsx

@@ -0,0 +1,173 @@
+// rn-persistent-timer — usePersistentTimer Hook
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { useState, useEffect, useRef, useCallback } from 'react';
+import { PersistentTimerManager } from './PersistentTimerManager';
+import { formatTime } from './utils';
+import type {
+  TimerConfig,
+  TimerCallbacks,
+  TimerSnapshot,
+  AppState,
+  UsePersistentTimerReturn,
+} from './types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+function makeInitialSnapshot(config: TimerConfig): TimerSnapshot {
+  const mode = config.mode ?? 'stopwatch';
+  const duration = config.duration ?? 0;
+  return {
+    timerId: config.timerId,
+    elapsed: 0,
+    remaining: mode === 'countdown' ? duration : null,
+    state: 'idle',
+    appState: 'foreground',
+    startedAt: null,
+    pausedAt: null,
+    formattedElapsed: '00:00:00',
+    formattedRemaining: mode === 'countdown' ? formatTime(duration) : null,
+    progress: mode === 'countdown' ? 0 : null,
+  };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * React hook for persistent timers.
+ *
+ * @example
+ * ```tsx
+ * const { snapshot, start, pause, reset, isRunning } = usePersistentTimer({
+ *   timerId: 'workout-timer',
+ *   mode: 'stopwatch',
+ *   runInBackground: true,
+ *   onTick: (snap) => console.log(snap.formattedElapsed),
+ * });
+ * ```
+ */
+export function usePersistentTimer(
+  config: TimerConfig & TimerCallbacks,
+): UsePersistentTimerReturn {
+  const managerRef = useRef<PersistentTimerManager | null>(null);
+
+  const [snapshot, setSnapshot] = useState<TimerSnapshot>(() =>
+    makeInitialSnapshot(config),
+  );
+
+  // Stable callback refs — avoids re-creating the manager when callbacks change
+  const callbacksRef = useRef<TimerCallbacks>({});
+  callbacksRef.current = {
+    onTick: config.onTick,
+    onStart: config.onStart,
+    onPause: config.onPause,
+    onResume: config.onResume,
+    onReset: config.onReset,
+    onComplete: config.onComplete,
+    onBackground: config.onBackground,
+    onForeground: config.onForeground,
+    onRestore: config.onRestore,
+    onError: config.onError,
+  };
+
+  useEffect(() => {
+    const manager = new PersistentTimerManager({
+      timerId: config.timerId,
+      mode: config.mode,
+      duration: config.duration,
+      runInBackground: config.runInBackground,
+      runInKilledState: config.runInKilledState,
+      pauseOnBackground: config.pauseOnBackground,
+      resetOnForeground: config.resetOnForeground,
+      interval: config.interval,
+      showNotification: config.showNotification,
+      notification: config.notification,
+    });
+
+    // Snapshot callbacks — update React state then call user callback
+    type SnapshotCbKey = Exclude<keyof TimerCallbacks, 'onError'>;
+    const wire = (
+      managerEvent: Parameters<typeof manager.on>[0],
+      cbKey: SnapshotCbKey,
+    ) => {
+      manager.on(managerEvent, (snap: TimerSnapshot) => {
+        setSnapshot({ ...snap });
+        (callbacksRef.current[cbKey] as ((s: TimerSnapshot) => void) | undefined)?.(snap);
+      });
+    };
+
+    wire('onTick', 'onTick');
+    wire('onStart', 'onStart');
+    wire('onPause', 'onPause');
+    wire('onResume', 'onResume');
+    wire('onReset', 'onReset');
+    wire('onComplete', 'onComplete');
+    wire('onBackground', 'onBackground');
+    wire('onForeground', 'onForeground');
+    wire('onRestore', 'onRestore');
+
+    // Error callback — receives Error, not TimerSnapshot
+    manager.on('error', (err: Error) => {
+      callbacksRef.current.onError?.(err);
+    });
+
+    // Restore from killed state if applicable
+    if (config.runInKilledState) {
+      PersistentTimerManager.restore(config.timerId).then((restored) => {
+        if (!restored) {
+          return;
+        }
+
+        // Replay internal state onto the manager
+        (manager as any)._elapsed = restored.elapsed;
+        (manager as any)._state = restored.state;
+
+        const snap = manager.getSnapshot();
+        setSnapshot({ ...snap });
+        callbacksRef.current.onRestore?.(snap);
+
+        // Auto-resume if the timer was running when the app was killed
+        if (restored.state === 'running') {
+          manager.start();
+        }
+      });
+    }
+
+    managerRef.current = manager;
+
+    return () => {
+      manager.destroy();
+      managerRef.current = null;
+    };
+    // Re-create the manager only if timerId changes
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [config.timerId]);
+
+  // ─── Stable controls ──────────────────────────────────────────────────────
+
+  const start = useCallback(() => managerRef.current?.start(), []);
+  const pause = useCallback(() => managerRef.current?.pause(), []);
+  const resume = useCallback(() => managerRef.current?.resume(), []);
+  const reset = useCallback(() => managerRef.current?.reset(), []);
+  const stop = useCallback(() => managerRef.current?.stop(), []);
+  const destroy = useCallback(() => managerRef.current?.destroy(), []);
+  const getSnapshot = useCallback(
+    () => managerRef.current?.getSnapshot() ?? snapshot,
+    [snapshot],
+  );
+
+  return {
+    snapshot,
+    isRunning: snapshot.state === 'running',
+    isPaused: snapshot.state === 'paused',
+    isCompleted: snapshot.state === 'completed',
+    appState: snapshot.appState as AppState,
+    start,
+    pause,
+    resume,
+    reset,
+    stop,
+    destroy,
+    getSnapshot,
+  };
+}

package/src/utils.ts

@@ -0,0 +1,91 @@
+// rn-persistent-timer — Utility Functions
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Format a number of seconds into an `HH:MM:SS` string.
+ *
+ * @example
+ * formatTime(3661); // '01:01:01'
+ * formatTime(59);   // '00:00:59'
+ */
+export function formatTime(seconds: number): string {
+  const s = Math.max(0, Math.floor(seconds));
+  const h = Math.floor(s / 3600);
+  const m = Math.floor((s % 3600) / 60);
+  const sec = s % 60;
+  return [h, m, sec].map((v) => String(v).padStart(2, '0')).join(':');
+}
+
+/**
+ * Parse an `HH:MM:SS` or `MM:SS` string into total seconds.
+ *
+ * @example
+ * parseTime('01:30:00'); // 5400
+ * parseTime('05:30');    // 330
+ */
+export function parseTime(formatted: string): number {
+  const parts = formatted.split(':').map(Number);
+  if (parts.length === 3) {
+    return parts[0]! * 3600 + parts[1]! * 60 + parts[2]!;
+  }
+  if (parts.length === 2) {
+    return parts[0]! * 60 + parts[1]!;
+  }
+  return parts[0] ?? 0;
+}
+
+/**
+ * Returns `true` if the native background-timer module is available on this
+ * device / build. Always returns `false` in Expo Go.
+ */
+export async function isBackgroundTimerSupported(): Promise<boolean> {
+  const { NativeTimerModule } = await import('./NativeTimerModule');
+  return Boolean(NativeTimerModule);
+}
+
+/**
+ * Returns `true` if the killed-state persistence feature is supported.
+ * Requires the native module **and** platform capabilities
+ * (WorkManager on Android, BGTaskScheduler on iOS 13+).
+ */
+export async function isKilledStateTimerSupported(): Promise<boolean> {
+  const { NativeTimerModule } = await import('./NativeTimerModule');
+  if (!NativeTimerModule) {
+    return false;
+  }
+  try {
+    return await NativeTimerModule.isKilledStateSupported?.() ?? false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Return the IDs of all timers currently active in the native layer.
+ */
+export async function getActiveTimers(): Promise<string[]> {
+  const { NativeTimerModule } = await import('./NativeTimerModule');
+  if (!NativeTimerModule) {
+    return [];
+  }
+  try {
+    return await NativeTimerModule.getActiveTimers();
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Cancel every active timer in both the native layer and JS.
+ */
+export async function cancelAllTimers(): Promise<void> {
+  const { NativeTimerModule } = await import('./NativeTimerModule');
+  if (!NativeTimerModule) {
+    return;
+  }
+  try {
+    await NativeTimerModule.cancelAll();
+  } catch {
+    // Swallow — best-effort cleanup
+  }
+}