rn-persistent-timer 1.1.0

package/src/PersistentTimerManager.ts

@@ -0,0 +1,410 @@
+// rn-persistent-timer — PersistentTimerManager
+// Handles foreground, background, and killed-state timer logic
+// ─────────────────────────────────────────────────────────────────────────────
+
+import { AppState as RNAppState, AppStateStatus } from 'react-native';
+import AsyncStorage from '@react-native-async-storage/async-storage';
+import { NativeTimerModule } from './NativeTimerModule';
+import { formatTime } from './utils';
+import type {
+  TimerConfig,
+  TimerState,
+  AppState,
+  TimerSnapshot,
+  TimerCallbacks,
+  PersistedTimerRecord,
+  RestoredTimerData,
+} from './types';
+
+const STORAGE_KEY_PREFIX = '@rn_persistent_timer_';
+
+type EventName = keyof TimerCallbacks | 'stop' | 'error';
+type HandlerMap = Partial<Record<EventName, Function[]>>;
+
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class PersistentTimerManager {
+  private _config: Required<TimerConfig>;
+  private _state: TimerState = 'idle';
+  private _elapsed = 0;
+  private _startedAt: number | null = null;
+  private _pausedAt: number | null = null;
+  private _tickInterval: ReturnType<typeof setInterval> | null = null;
+  private _handlers: HandlerMap = {};
+  private _appState: AppState = 'foreground';
+  private _appStateSubscription: ReturnType<
+    typeof RNAppState.addEventListener
+  > | null = null;
+
+  constructor(config: TimerConfig) {
+    this._config = {
+      timerId: config.timerId,
+      mode: config.mode ?? 'stopwatch',
+      duration: config.duration ?? 0,
+      runInBackground: config.runInBackground !== false, // default true
+      runInKilledState: config.runInKilledState === true, // default false
+      pauseOnBackground: config.pauseOnBackground === true,
+      resetOnForeground: config.resetOnForeground === true,
+      interval: config.interval ?? 1000,
+      showNotification: config.showNotification !== false,
+      notification: config.notification ?? {},
+    };
+  }
+
+  // ─── Public API ─────────────────────────────────────────────────────────────
+
+  start(): void {
+    if (this._state === 'running') {
+      return;
+    }
+    if (this._state === 'completed') {
+      console.warn(
+        '[rn-persistent-timer] Timer already completed. Call reset() first.',
+      );
+      return;
+    }
+
+    this._startedAt = Date.now() - this._elapsed * 1000;
+    this._state = 'running';
+
+    this._startJSTick();
+    this._listenAppState();
+
+    if (this._config.runInBackground) {
+      this._startNativeBackground();
+    }
+    if (this._config.runInKilledState) {
+      void this._persistState();
+    }
+
+    this._emit('onStart', this.getSnapshot());
+  }
+
+  pause(): void {
+    if (this._state !== 'running') {
+      return;
+    }
+    this._pausedAt = Date.now();
+    this._elapsed = Math.floor((Date.now() - (this._startedAt ?? Date.now())) / 1000);
+    this._state = 'paused';
+
+    this._stopJSTick();
+    this._stopNativeBackground();
+
+    if (this._config.runInKilledState) {
+      void this._persistState();
+    }
+    this._emit('onPause', this.getSnapshot());
+  }
+
+  resume(): void {
+    if (this._state !== 'paused') {
+      return;
+    }
+    this._startedAt = Date.now() - this._elapsed * 1000;
+    this._pausedAt = null;
+    this._state = 'running';
+
+    this._startJSTick();
+    if (this._config.runInBackground) {
+      this._startNativeBackground();
+    }
+    if (this._config.runInKilledState) {
+      void this._persistState();
+    }
+    this._emit('onResume', this.getSnapshot());
+  }
+
+  stop(): void {
+    if (this._state === 'idle') {
+      return;
+    }
+    this._stopJSTick();
+    this._stopNativeBackground();
+    this._state = 'idle';
+    void this._clearPersistedState();
+    this._emit('stop', this.getSnapshot());
+  }
+
+  reset(): void {
+    this._stopJSTick();
+    this._stopNativeBackground();
+    this._elapsed = 0;
+    this._startedAt = null;
+    this._pausedAt = null;
+    this._state = 'idle';
+    void this._clearPersistedState();
+    this._emit('onReset', this.getSnapshot());
+  }
+
+  getSnapshot(): TimerSnapshot {
+    const elapsed = this._getElapsed();
+    const remaining =
+      this._config.mode === 'countdown'
+        ? Math.max(0, this._config.duration - elapsed)
+        : null;
+    const progress =
+      this._config.mode === 'countdown' && this._config.duration > 0
+        ? 1 - (remaining ?? 0) / this._config.duration
+        : null;
+
+    return {
+      timerId: this._config.timerId,
+      elapsed,
+      remaining,
+      state: this._state,
+      appState: this._appState,
+      startedAt: this._startedAt,
+      pausedAt: this._pausedAt,
+      formattedElapsed: formatTime(elapsed),
+      formattedRemaining: remaining !== null ? formatTime(remaining) : null,
+      progress,
+    };
+  }
+
+  destroy(): void {
+    this.stop();
+    if (this._appStateSubscription) {
+      this._appStateSubscription.remove();
+      this._appStateSubscription = null;
+    }
+    this._handlers = {};
+  }
+
+  on(event: EventName, handler: Function): void {
+    if (!this._handlers[event]) {
+      this._handlers[event] = [];
+    }
+    this._handlers[event]!.push(handler);
+  }
+
+  off(event: EventName, handler: Function): void {
+    if (!this._handlers[event]) {
+      return;
+    }
+    this._handlers[event] = this._handlers[event]!.filter((h) => h !== handler);
+  }
+
+  // ─── Internal Tick ───────────────────────────────────────────────────────────
+
+  private _startJSTick(): void {
+    this._stopJSTick();
+    this._tickInterval = setInterval(() => {
+      this._onTick();
+    }, this._config.interval);
+  }
+
+  private _stopJSTick(): void {
+    if (this._tickInterval !== null) {
+      clearInterval(this._tickInterval);
+      this._tickInterval = null;
+    }
+  }
+
+  private _onTick(): void {
+    const snap = this.getSnapshot();
+
+    if (this._config.mode === 'countdown' && snap.remaining === 0) {
+      this._state = 'completed';
+      this._stopJSTick();
+      this._stopNativeBackground();
+      void this._clearPersistedState();
+      this._emit('onComplete', snap);
+      return;
+    }
+
+    this._emit('onTick', snap);
+  }
+
+  private _getElapsed(): number {
+    if (this._state === 'running' && this._startedAt !== null) {
+      return Math.floor((Date.now() - this._startedAt) / 1000);
+    }
+    return this._elapsed;
+  }
+
+  // ─── App State ───────────────────────────────────────────────────────────────
+
+  private _listenAppState(): void {
+    if (this._appStateSubscription) {
+      return;
+    }
+
+    this._appStateSubscription = RNAppState.addEventListener(
+      'change',
+      (nextAppState: AppStateStatus) => {
+        const prev = this._appState;
+
+        if (nextAppState === 'active') {
+          this._appState = 'foreground';
+
+          if (prev === 'background' && this._config.runInBackground) {
+            this._syncFromNative();
+          }
+
+          if (this._config.resetOnForeground) {
+            this.reset();
+            return;
+          }
+
+          if (this._state === 'running') {
+            this._startJSTick();
+          }
+
+          this._emit('onForeground', this.getSnapshot());
+        } else if (
+          nextAppState === 'background' ||
+          nextAppState === 'inactive'
+        ) {
+          this._appState = 'background';
+
+          if (this._config.pauseOnBackground) {
+            this.pause();
+          } else {
+            this._stopJSTick();
+          }
+
+          this._emit('onBackground', this.getSnapshot());
+        }
+      },
+    );
+  }
+
+  // ─── Native Background ───────────────────────────────────────────────────────
+
+  private _startNativeBackground(): void {
+    if (!NativeTimerModule) {
+      return;
+    }
+    try {
+      NativeTimerModule.startTimer({
+        timerId: this._config.timerId,
+        mode: this._config.mode,
+        duration: this._config.duration,
+        elapsed: this._getElapsed(),
+        startedAt: this._startedAt ?? Date.now(),
+        showNotification: this._config.showNotification,
+        notification: this._config.notification as Record<string, unknown>,
+      });
+    } catch (e) {
+      this._emit('error', e);
+    }
+  }
+
+  private _stopNativeBackground(): void {
+    if (!NativeTimerModule) {
+      return;
+    }
+    try {
+      NativeTimerModule.stopTimer(this._config.timerId);
+    } catch (e) {
+      this._emit('error', e);
+    }
+  }
+
+  private _syncFromNative(): void {
+    if (!NativeTimerModule) {
+      return;
+    }
+    NativeTimerModule.getElapsed(this._config.timerId)
+      .then((nativeElapsed) => {
+        if (nativeElapsed != null) {
+          this._elapsed = nativeElapsed;
+          this._startedAt = Date.now() - nativeElapsed * 1000;
+        }
+      })
+      .catch(() => {
+        // Fallback: wall-clock diff handles it via _startedAt
+      });
+  }
+
+  // ─── Killed-State Persistence ────────────────────────────────────────────────
+
+  private async _persistState(): Promise<void> {
+    try {
+      const record: PersistedTimerRecord = {
+        timerId: this._config.timerId,
+        config: this._config,
+        state: this._state,
+        elapsed: this._getElapsed(),
+        startedAt: this._startedAt,
+        pausedAt: this._pausedAt,
+        savedAt: Date.now(),
+      };
+      await AsyncStorage.setItem(
+        `${STORAGE_KEY_PREFIX}${this._config.timerId}`,
+        JSON.stringify(record),
+      );
+    } catch (e) {
+      console.warn('[rn-persistent-timer] Failed to persist state:', e);
+    }
+  }
+
+  private async _clearPersistedState(): Promise<void> {
+    try {
+      await AsyncStorage.removeItem(
+        `${STORAGE_KEY_PREFIX}${this._config.timerId}`,
+      );
+    } catch {
+      // Swallow
+    }
+  }
+
+  // ─── Static Restore ──────────────────────────────────────────────────────────
+
+  static async restore(
+    timerId: string,
+  ): Promise<RestoredTimerData | null> {
+    try {
+      const raw = await AsyncStorage.getItem(
+        `${STORAGE_KEY_PREFIX}${timerId}`,
+      );
+      if (!raw) {
+        return null;
+      }
+
+      const saved: PersistedTimerRecord = JSON.parse(raw);
+      const now = Date.now();
+      const secondsSinceSave = Math.floor((now - saved.savedAt) / 1000);
+
+      let elapsed = saved.elapsed;
+      if (saved.state === 'running') {
+        elapsed = saved.elapsed + secondsSinceSave;
+      }
+
+      // Cap countdown timers at their duration
+      if (
+        saved.config.mode === 'countdown' &&
+        elapsed >= saved.config.duration
+      ) {
+        elapsed = saved.config.duration;
+        saved.state = 'completed';
+      }
+
+      return {
+        config: saved.config,
+        state: saved.state,
+        elapsed,
+        secondsLost: secondsSinceSave,
+      };
+    } catch {
+      return null;
+    }
+  }
+
+  // ─── Event Emitter ───────────────────────────────────────────────────────────
+
+  private _emit(event: EventName, data: unknown): void {
+    const handlers = this._handlers[event] ?? [];
+    for (const h of handlers) {
+      try {
+        h(data);
+      } catch (e) {
+        console.error(
+          `[rn-persistent-timer] Handler error for "${event}":`,
+          e,
+        );
+      }
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,41 @@
+// rn-persistent-timer — Public API Barrel
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Hook
+export { usePersistentTimer } from './usePersistentTimer';
+
+// Class
+export { PersistentTimerManager } from './PersistentTimerManager';
+
+// Utilities
+export {
+  formatTime,
+  parseTime,
+  isBackgroundTimerSupported,
+  isKilledStateTimerSupported,
+  getActiveTimers,
+  cancelAllTimers,
+} from './utils';
+
+// Types — re-export everything so consumers only need one import path
+export type {
+  TimerMode,
+  TimerState,
+  AppState,
+  TimerConfig,
+  AndroidNotificationConfig,
+  TimerSnapshot,
+  TimerCallbacks,
+  PersistentTimerControls,
+  UsePersistentTimerReturn,
+  PersistedTimerRecord,
+  RestoredTimerData,
+} from './types';
+
+// Native internals (advanced use only)
+export {
+  NativeTimerModule,
+  NativeTimerEmitter,
+  NATIVE_EVENTS,
+} from './NativeTimerModule';
+export type { INativeTimerModule, NativeStartOptions, NativeEventName } from './NativeTimerModule';

package/src/types.ts

@@ -0,0 +1,198 @@
+// rn-persistent-timer — Shared TypeScript Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type TimerMode = 'countdown' | 'stopwatch';
+export type TimerState = 'idle' | 'running' | 'paused' | 'completed';
+export type AppState = 'foreground' | 'background' | 'killed';
+
+// ─── Configuration ────────────────────────────────────────────────────────────
+
+export interface AndroidNotificationConfig {
+  /** Notification title shown in status bar */
+  title?: string;
+  /** Notification body. Use {time} as a placeholder for the current timer value */
+  body?: string;
+  /** Android notification channel ID */
+  channelId?: string;
+  /** Android notification channel name */
+  channelName?: string;
+  /** Drawable resource name for the notification icon */
+  icon?: string;
+  /** Accent color (hex, e.g. '#FF5733') */
+  color?: string;
+  /** Show elapsed / remaining time in the notification */
+  showTime?: boolean;
+  /** Add pause / resume action buttons to the notification */
+  showActions?: boolean;
+}
+
+export interface TimerConfig {
+  /**
+   * Unique ID for this timer instance. Required.
+   * Used as the key for persistence and native interop.
+   */
+  timerId: string;
+
+  /**
+   * Timer mode.
+   * - `'countdown'` — counts down from `duration` to 0.
+   * - `'stopwatch'` — counts up from 0.
+   * @default 'stopwatch'
+   */
+  mode?: TimerMode;
+
+  /**
+   * Duration in seconds. Required when `mode === 'countdown'`.
+   */
+  duration?: number;
+
+  /**
+   * Keep the timer running when the app goes to the **background**.
+   * On Android this starts a Foreground Service; on iOS it uses
+   * `UIBackgroundTaskIdentifier` + `BGTaskScheduler`.
+   * @default true
+   */
+  runInBackground?: boolean;
+
+  /**
+   * Keep the timer alive even after the app is **killed** from the
+   * task manager. State is persisted via AsyncStorage and restored
+   * when the app is re-opened.
+   * Requires additional native setup — see README.
+   * @default false
+   */
+  runInKilledState?: boolean;
+
+  /**
+   * Tick interval in milliseconds.
+   * @default 1000
+   */
+  interval?: number;
+
+  /**
+   * Show a persistent notification while the timer is active (Android).
+   * Required for reliable background execution on Android 8+.
+   * @default true  (when runInBackground is true)
+   */
+  showNotification?: boolean;
+
+  /** Android notification customisation. */
+  notification?: AndroidNotificationConfig;
+
+  /**
+   * Automatically pause when the app moves to the background.
+   * Overrides `runInBackground` when `true`.
+   * @default false
+   */
+  pauseOnBackground?: boolean;
+
+  /**
+   * Automatically reset when the app returns to the foreground from a
+   * killed state.
+   * @default false
+   */
+  resetOnForeground?: boolean;
+}
+
+// ─── Snapshot ─────────────────────────────────────────────────────────────────
+
+export interface TimerSnapshot {
+  /** Timer ID */
+  timerId: string;
+  /** Elapsed seconds since the timer last started */
+  elapsed: number;
+  /** Remaining seconds — countdown mode only, otherwise `null` */
+  remaining: number | null;
+  /** Current timer state */
+  state: TimerState;
+  /** Current app state at the time the snapshot was taken */
+  appState: AppState;
+  /** Unix-ms timestamp when the timer was (last) started */
+  startedAt: number | null;
+  /** Unix-ms timestamp when the timer was paused */
+  pausedAt: number | null;
+  /** Elapsed time formatted as `HH:MM:SS` */
+  formattedElapsed: string;
+  /** Remaining time formatted as `HH:MM:SS` — countdown only, otherwise `null` */
+  formattedRemaining: string | null;
+  /** Progress from 0 to 1 — countdown only, otherwise `null` */
+  progress: number | null;
+}
+
+// ─── Callbacks ────────────────────────────────────────────────────────────────
+
+export interface TimerCallbacks {
+  /** Fires every tick (based on `interval`). */
+  onTick?: (snapshot: TimerSnapshot) => void;
+  /** Fires when the timer starts. */
+  onStart?: (snapshot: TimerSnapshot) => void;
+  /** Fires when the timer is paused. */
+  onPause?: (snapshot: TimerSnapshot) => void;
+  /** Fires when the timer is resumed. */
+  onResume?: (snapshot: TimerSnapshot) => void;
+  /** Fires when the timer is reset. */
+  onReset?: (snapshot: TimerSnapshot) => void;
+  /** Fires when a countdown timer reaches zero. */
+  onComplete?: (snapshot: TimerSnapshot) => void;
+  /** Fires when the app moves to the background. */
+  onBackground?: (snapshot: TimerSnapshot) => void;
+  /** Fires when the app returns to the foreground. */
+  onForeground?: (snapshot: TimerSnapshot) => void;
+  /** Fires when timer state is restored after an app kill. */
+  onRestore?: (snapshot: TimerSnapshot) => void;
+  /** Fires on any internal error. */
+  onError?: (error: Error) => void;
+}
+
+// ─── Controls ─────────────────────────────────────────────────────────────────
+
+export interface PersistentTimerControls {
+  /** Start (or restart from 0) the timer. */
+  start: () => void;
+  /** Pause the timer. */
+  pause: () => void;
+  /** Resume from a paused state. */
+  resume: () => void;
+  /** Stop the timer and reset elapsed to 0. */
+  reset: () => void;
+  /** Stop the timer without resetting elapsed time. */
+  stop: () => void;
+  /** Get the current snapshot synchronously. */
+  getSnapshot: () => TimerSnapshot;
+  /** Destroy the timer and remove all listeners. */
+  destroy: () => void;
+}
+
+// ─── Hook Return ──────────────────────────────────────────────────────────────
+
+export interface UsePersistentTimerReturn extends PersistentTimerControls {
+  /** Latest reactive timer snapshot. */
+  snapshot: TimerSnapshot;
+  /** `true` when `state === 'running'`. */
+  isRunning: boolean;
+  /** `true` when `state === 'paused'`. */
+  isPaused: boolean;
+  /** `true` when `state === 'completed'` (countdown). */
+  isCompleted: boolean;
+  /** Current app state. */
+  appState: AppState;
+}
+
+// ─── Persistence Record ───────────────────────────────────────────────────────
+
+export interface PersistedTimerRecord {
+  timerId: string;
+  config: Required<TimerConfig>;
+  state: TimerState;
+  elapsed: number;
+  startedAt: number | null;
+  pausedAt: number | null;
+  savedAt: number;
+}
+
+export interface RestoredTimerData {
+  config: Required<TimerConfig>;
+  state: TimerState;
+  elapsed: number;
+  secondsLost: number;
+}