@matiks/rn-app-state 1.0.0

package/src/useNitroAppState/useNitroAppState.native.ts

@@ -0,0 +1,142 @@
+import { useState, useEffect, useRef, useCallback } from 'react'
+import { NitroModules } from 'react-native-nitro-modules'
+import type {
+  AppStateModule,
+  AppStateChangeEvent,
+} from '../specs/AppState.nitro'
+import type { AppStateType, NitroAppStateResult } from './types'
+
+// Lazily create the HybridObject singleton.
+// This is safe because on native, NitroModules.createHybridObject is synchronous.
+let _module: AppStateModule | null = null
+
+function getModule(): AppStateModule {
+  if (_module == null) {
+    _module = NitroModules.createHybridObject<AppStateModule>('AppStateModule')
+  }
+  return _module
+}
+
+/**
+ * A reactive React hook that provides the current app lifecycle state
+ * using native code via Nitro Modules (JSI).
+ *
+ * States: 'active' | 'background' | 'killed'
+ *
+ * - 'active' and 'background' are live states that update reactively.
+ * - 'killed' is only the initial state on cold start if the previous
+ *   session was force-killed (it transitions to 'active' immediately).
+ *
+ * @example
+ * ```tsx
+ * const { appState, wasKilledLastSession } = useNitroAppState()
+ *
+ * useEffect(() => {
+ *   if (appState === 'active') {
+ *     // Refresh data, resume animations, etc.
+ *   }
+ * }, [appState])
+ * ```
+ */
+export function useNitroAppState(): NitroAppStateResult {
+  const moduleRef = useRef<AppStateModule | null>(null)
+
+  // Initialize module lazily
+  if (moduleRef.current == null) {
+    moduleRef.current = getModule()
+  }
+
+  const mod = moduleRef.current
+
+  // Determine initial state
+  const getInitialState = (): AppStateType => {
+    try {
+      if (mod.wasKilledLastSession) {
+        return 'killed'
+      }
+      return mod.getCurrentState() as AppStateType
+    } catch {
+      return 'active'
+    }
+  }
+
+  const [appState, setAppState] = useState<AppStateType>(getInitialState)
+  const [wasKilledLastSession] = useState<boolean>(() => {
+    try {
+      return mod.wasKilledLastSession
+    } catch {
+      return false
+    }
+  })
+
+  // Ref to track the latest appState for use in stable callbacks.
+  const appStateRef = useRef<AppStateType>(appState)
+  appStateRef.current = appState
+
+  useEffect(() => {
+    let listener: { remove: () => void } | null = null
+    let isMounted = true
+
+    try {
+      listener = mod.addListener((event: AppStateChangeEvent) => {
+        if (isMounted) {
+          const newState = event.state as AppStateType
+          setAppState(newState)
+        }
+      })
+    } catch (e) {
+      console.warn('[useNitroAppState] Failed to add listener:', e)
+    }
+
+    // If initial state was 'killed', transition to the real native state
+    // after mount. We use setTimeout with a mounted guard to avoid
+    // updating state on an unmounted component.
+    if (appStateRef.current === 'killed') {
+      const timer = setTimeout(() => {
+        if (isMounted) {
+          try {
+            const currentNativeState = mod.getCurrentState() as AppStateType
+            setAppState(currentNativeState)
+          } catch {
+            setAppState('active')
+          }
+        }
+      }, 0)
+
+      return () => {
+        isMounted = false
+        clearTimeout(timer)
+        try {
+          listener?.remove()
+        } catch {
+          // Ignore cleanup errors
+        }
+      }
+    }
+
+    return () => {
+      isMounted = false
+      try {
+        listener?.remove()
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  }, [mod])
+
+  // Stable callback that doesn't change identity on every state transition.
+  // Uses the module's synchronous native call instead of stale JS state.
+  const getStateOnNotification = useCallback((): AppStateType => {
+    try {
+      return mod.getStateOnNotification() as AppStateType
+    } catch {
+      return appStateRef.current
+    }
+  }, [mod])
+
+  return {
+    appState,
+    wasKilledLastSession,
+    getStateOnNotification,
+  }
+}

package/src/useNitroAppState/useNitroAppState.web.ts

@@ -0,0 +1,56 @@
+import { useState, useEffect, useCallback } from 'react';
+import { AppState } from 'react-native';
+import type { AppStateType, NitroAppStateResult } from './types';
+
+/**
+ * Web fallback for useNitroAppState.
+ *
+ * On web, NitroModules.createHybridObject() is not available.
+ * This fallback uses the standard React Native AppState API
+ * (which works on web via react-native-web's Page Visibility API).
+ *
+ * - 'killed' is never reported on web (no concept of app termination).
+ * - wasKilledLastSession is always false on web.
+ */
+export function useNitroAppState(): NitroAppStateResult {
+  const [appState, setAppState] = useState<AppStateType>(() => {
+    try {
+      const current = AppState.currentState;
+      if (current === 'active') return 'active';
+      return 'background';
+    } catch {
+      return 'active';
+    }
+  });
+
+  useEffect(() => {
+    const subscription = AppState.addEventListener('change', (nextAppState) => {
+      if (nextAppState === 'active') {
+        setAppState('active');
+      } else {
+        // 'inactive', 'background', 'unknown', 'extension' all map to 'background'
+        setAppState('background');
+      }
+    });
+
+    return () => {
+      subscription.remove();
+    };
+  }, []);
+
+  const getStateOnNotification = useCallback((): AppStateType => {
+    try {
+      const current = AppState.currentState;
+      if (current === 'active') return 'active';
+      return 'background';
+    } catch {
+      return appState;
+    }
+  }, [appState]);
+
+  return {
+    appState,
+    wasKilledLastSession: false,
+    getStateOnNotification,
+  };
+}