@matiks/rn-app-state 1.0.0

package/android/src/main/java/com/margelo/nitro/appstate/HybridAppState.kt

@@ -0,0 +1,188 @@
+package com.margelo.nitro.appstate
+
+import android.content.Context
+import android.content.SharedPreferences
+import android.os.Handler
+import android.os.Looper
+import android.util.Log
+import androidx.lifecycle.DefaultLifecycleObserver
+import androidx.lifecycle.LifecycleOwner
+import androidx.lifecycle.ProcessLifecycleOwner
+import com.facebook.proguard.annotations.DoNotStrip
+import androidx.annotation.Keep
+import com.margelo.nitro.NitroModules
+import java.util.UUID
+import java.util.concurrent.ConcurrentHashMap
+
+/**
+ * Thread-safe native app state module for Android.
+ * Uses ProcessLifecycleOwner to observe app lifecycle and notifies JS listeners.
+ *
+ * States:
+ *   - "active": App is in the foreground (resumed)
+ *   - "background": App is in the background (stopped)
+ *   - "killed": Only reported via `wasKilledLastSession` (not a live state)
+ *
+ * Thread safety:
+ *   - Listeners stored in ConcurrentHashMap for thread-safe access.
+ *   - State updates happen on the main thread (lifecycle callbacks are main-thread).
+ *   - getCurrentState() is safe to call from any thread (reads a volatile field).
+ */
+@DoNotStrip
+@Keep
+class HybridAppState : HybridAppStateModuleSpec() {
+
+    companion object {
+        private const val TAG = "HybridAppState"
+        private const val PREFS_NAME = "com.matiks.appstate"
+        private const val KEY_DID_EXIT_CLEANLY = "didExitCleanly"
+        private const val KEY_HAS_LAUNCHED_BEFORE = "hasLaunchedBefore"
+
+        /**
+         * Get SharedPreferences using NitroModules.applicationContext.
+         * Falls back gracefully if context is not yet available.
+         */
+        private fun getPrefs(): SharedPreferences? {
+            val ctx = NitroModules.applicationContext
+            if (ctx == null) {
+                Log.w(TAG, "NitroModules.applicationContext is null — SharedPreferences unavailable")
+                return null
+            }
+            return ctx.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+        }
+    }
+
+    // MARK: - State
+
+    /** Current app state. Volatile for cross-thread visibility. */
+    @Volatile
+    private var currentState: String = "active"
+
+    /** Whether the previous session was killed. */
+    override val wasKilledLastSession: Boolean
+
+    /** Registered JS listeners. ConcurrentHashMap for thread safety. */
+    private val listeners = ConcurrentHashMap<String, (event: AppStateChangeEvent) -> Unit>()
+
+    /** Main thread handler for dispatching lifecycle observer registration. */
+    private val mainHandler = Handler(Looper.getMainLooper())
+
+    /** Lifecycle observer instance (stored to allow removal on dispose). */
+    private val lifecycleObserver: DefaultLifecycleObserver
+
+    // MARK: - Init
+
+    init {
+        val prefs = getPrefs()
+
+        // Determine if the app was killed last session.
+        val hasLaunchedBefore = prefs?.getBoolean(KEY_HAS_LAUNCHED_BEFORE, false) ?: false
+        val didExitCleanly = prefs?.getBoolean(KEY_DID_EXIT_CLEANLY, false) ?: false
+
+        // First launch ever: no previous session, so not "killed".
+        // Subsequent launches: if the flag is false, the app was killed.
+        wasKilledLastSession = hasLaunchedBefore && !didExitCleanly
+
+        // Reset the flag. It will be set to true when we exit cleanly.
+        prefs?.edit()
+            ?.putBoolean(KEY_HAS_LAUNCHED_BEFORE, true)
+            ?.putBoolean(KEY_DID_EXIT_CLEANLY, false)
+            ?.apply()
+
+        Log.d(TAG, "Initialized. wasKilledLastSession=$wasKilledLastSession")
+
+        // Create lifecycle observer
+        lifecycleObserver = object : DefaultLifecycleObserver {
+            override fun onStart(owner: LifecycleOwner) {
+                // App came to foreground
+                updateState("active")
+            }
+
+            override fun onStop(owner: LifecycleOwner) {
+                // App went to background - mark clean exit
+                markCleanExit()
+                updateState("background")
+            }
+        }
+
+        // Register lifecycle observer on the main thread.
+        // ProcessLifecycleOwner.get().lifecycle must be accessed on main thread.
+        val registerBlock = Runnable {
+            try {
+                ProcessLifecycleOwner.get().lifecycle.addObserver(lifecycleObserver)
+                Log.d(TAG, "Lifecycle observer registered")
+            } catch (e: Exception) {
+                Log.e(TAG, "Failed to register lifecycle observer", e)
+            }
+        }
+
+        if (Looper.myLooper() == Looper.getMainLooper()) {
+            registerBlock.run()
+        } else {
+            mainHandler.post(registerBlock)
+        }
+    }
+
+    // MARK: - HybridAppStateModuleSpec Methods
+
+    override fun getCurrentState(): String {
+        return currentState
+    }
+
+    override fun addListener(onStateChange: (event: AppStateChangeEvent) -> Unit): AppStateListener {
+        val id = UUID.randomUUID().toString()
+        listeners[id] = onStateChange
+
+        val removeCallback: () -> Unit = {
+            listeners.remove(id)
+        }
+
+        return AppStateListener(removeCallback)
+    }
+
+    override fun getStateOnNotification(): String {
+        // Return the current state at the moment a notification is received.
+        // ProcessLifecycleOwner accurately tracks foreground/background,
+        // so currentState reflects the real state even during notification handling.
+        return currentState
+    }
+
+    // MARK: - Private Helpers
+
+    /**
+     * Update the current state and notify all listeners.
+     * Called from lifecycle callbacks (always on main thread).
+     */
+    private fun updateState(newState: String) {
+        if (newState == currentState) return
+        currentState = newState
+
+        Log.d(TAG, "State changed to: $newState")
+
+        val event = AppStateChangeEvent(state = newState)
+
+        // Snapshot and iterate. ConcurrentHashMap's values are safe to iterate
+        // even if a listener calls remove() during callback.
+        for ((_, listener) in listeners) {
+            try {
+                listener(event)
+            } catch (e: Exception) {
+                Log.e(TAG, "Error in app state listener callback", e)
+            }
+        }
+    }
+
+    /**
+     * Persist a flag indicating the app exited cleanly (not killed).
+     * Uses commit() (synchronous) to ensure it's written before process death.
+     */
+    private fun markCleanExit() {
+        try {
+            getPrefs()?.edit()
+                ?.putBoolean(KEY_DID_EXIT_CLEANLY, true)
+                ?.commit()
+        } catch (e: Exception) {
+            Log.e(TAG, "Failed to mark clean exit", e)
+        }
+    }
+}

package/android/src/main/java/com/margelo/nitro/appstate/NitroAppStatePackage.kt

@@ -0,0 +1,18 @@
+package com.margelo.nitro.appstate
+
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfoProvider
+import com.facebook.react.BaseReactPackage
+
+class NitroAppStatePackage : BaseReactPackage() {
+    override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? = null
+
+    override fun getReactModuleInfoProvider(): ReactModuleInfoProvider = ReactModuleInfoProvider { HashMap() }
+
+    companion object {
+        init {
+            NitroAppStateOnLoad.initializeNative()
+        }
+    }
+}

package/ios/HybridAppState.swift

@@ -0,0 +1,224 @@
+import UIKit
+import NitroModules
+
+/// Thread-safe native app state module for iOS.
+/// Observes UIApplication lifecycle notifications and notifies JS listeners.
+///
+/// States:
+///   - "active": App is in the foreground and interactive
+///   - "background": App is in the background or inactive (iOS inactive is merged into background)
+///   - "killed": Only reported via `wasKilledLastSession` (not a live state)
+///
+/// Thread safety:
+///   - Nitro calls methods on arbitrary threads.
+///   - UIApplication.shared.applicationState must be read on the main thread.
+///   - Listener storage uses a serial queue for thread-safe access.
+///   - Listener callbacks are dispatched on the main thread.
+class HybridAppState: HybridAppStateModuleSpec {
+
+    // MARK: - Constants
+
+    private static let killedFlagKey = "com.matiks.appstate.didExitCleanly"
+
+    // MARK: - State
+
+    /// Serial queue protecting listener dictionary access.
+    private let listenerQueue = DispatchQueue(label: "com.matiks.appstate.listeners")
+
+    /// All registered JS listeners, keyed by UUID.
+    private var listeners: [UUID: (AppStateChangeEvent) -> Void] = [:]
+
+    /// The current state as tracked by this module. Only mutated on the main thread.
+    private var currentState: String = "active"
+
+    /// Whether the previous session was killed (force-quit / OOM / crash).
+    private(set) var wasKilledLastSession: Bool = false
+
+    // MARK: - Init
+
+    override init() {
+        // Compute the killed flag before super.init(), then assign after.
+        // The C++ wrapper is created lazily (not during init), so the
+        // property will have the correct value by the time JS accesses it.
+        let defaults = UserDefaults.standard
+        let hasLaunchedBefore = defaults.object(forKey: HybridAppState.killedFlagKey) != nil
+        let didExitCleanly = defaults.bool(forKey: HybridAppState.killedFlagKey)
+
+        // First launch ever: no previous session, so not "killed".
+        // Subsequent launches: if the flag is false, the app was killed.
+        let killed = hasLaunchedBefore && !didExitCleanly
+
+        super.init()
+
+        self.wasKilledLastSession = killed
+
+        // Reset the flag to false. It will be set to true when we exit cleanly
+        // (entering background or willTerminate).
+        defaults.set(false, forKey: HybridAppState.killedFlagKey)
+        defaults.synchronize()
+
+        // Determine initial state from UIApplication (must be on main thread).
+        if Thread.isMainThread {
+            self.currentState = self.readApplicationState()
+        } else {
+            DispatchQueue.main.sync {
+                self.currentState = self.readApplicationState()
+            }
+        }
+
+        // Register for lifecycle notifications on the main thread.
+        let registerBlock = { [weak self] in
+            guard let self = self else { return }
+            let center = NotificationCenter.default
+            center.addObserver(
+                self,
+                selector: #selector(self.handleDidBecomeActive),
+                name: UIApplication.didBecomeActiveNotification,
+                object: nil
+            )
+            center.addObserver(
+                self,
+                selector: #selector(self.handleDidEnterBackground),
+                name: UIApplication.didEnterBackgroundNotification,
+                object: nil
+            )
+            center.addObserver(
+                self,
+                selector: #selector(self.handleWillResignActive),
+                name: UIApplication.willResignActiveNotification,
+                object: nil
+            )
+            center.addObserver(
+                self,
+                selector: #selector(self.handleWillTerminate),
+                name: UIApplication.willTerminateNotification,
+                object: nil
+            )
+        }
+
+        if Thread.isMainThread {
+            registerBlock()
+        } else {
+            DispatchQueue.main.async(execute: registerBlock)
+        }
+    }
+
+    deinit {
+        NotificationCenter.default.removeObserver(self)
+    }
+
+    // MARK: - HybridAppStateModuleSpec Methods
+
+    func getCurrentState() throws -> String {
+        if Thread.isMainThread {
+            return currentState
+        }
+        var state = ""
+        DispatchQueue.main.sync {
+            state = self.currentState
+        }
+        return state
+    }
+
+    func addListener(onStateChange: @escaping (AppStateChangeEvent) -> Void) throws -> AppStateListener {
+        let id = UUID()
+
+        listenerQueue.sync {
+            listeners[id] = onStateChange
+        }
+
+        let removeCallback: () -> Void = { [weak self] in
+            guard let self = self else { return }
+            self.listenerQueue.sync {
+                _ = self.listeners.removeValue(forKey: id)
+            }
+        }
+
+        return AppStateListener(remove: removeCallback)
+    }
+
+    func getStateOnNotification() throws -> String {
+        // Return the real UIApplication state at the moment of the call.
+        // This is useful when a push/silent notification wakes the app.
+        if Thread.isMainThread {
+            return readApplicationState()
+        }
+        var state = ""
+        DispatchQueue.main.sync {
+            state = self.readApplicationState()
+        }
+        return state
+    }
+
+    // MARK: - Lifecycle Handlers (always called on main thread by NotificationCenter)
+
+    @objc private func handleDidBecomeActive() {
+        updateState("active")
+    }
+
+    @objc private func handleDidEnterBackground() {
+        // Mark clean exit so next launch knows we weren't killed.
+        markCleanExit()
+        updateState("background")
+    }
+
+    @objc private func handleWillResignActive() {
+        // iOS fires willResignActive before didEnterBackground,
+        // and also when opening notification center, control center, etc.
+        // We treat this as "background" since the user only wants active/background/killed.
+        updateState("background")
+    }
+
+    @objc private func handleWillTerminate() {
+        // App is about to be terminated by the system or user.
+        // This is a clean termination, so mark it.
+        markCleanExit()
+    }
+
+    // MARK: - Private Helpers
+
+    /// Update the current state and notify all listeners.
+    /// Must be called on the main thread.
+    private func updateState(_ newState: String) {
+        guard newState != currentState else { return }
+        currentState = newState
+
+        let event = AppStateChangeEvent(state: newState)
+
+        // Snapshot listeners under the lock, then call outside the lock
+        // to avoid deadlocks if a listener calls remove() during callback.
+        var currentListeners: [(AppStateChangeEvent) -> Void] = []
+        listenerQueue.sync {
+            currentListeners = Array(self.listeners.values)
+        }
+
+        for listener in currentListeners {
+            listener(event)
+        }
+    }
+
+    /// Read UIApplication.shared.applicationState and map to our state strings.
+    /// MUST be called on the main thread.
+    private func readApplicationState() -> String {
+        let appState = UIApplication.shared.applicationState
+        switch appState {
+        case .active:
+            return "active"
+        case .background:
+            return "background"
+        case .inactive:
+            // iOS "inactive" is transitional (e.g., notification center open).
+            // Map to "background" since user only wants active/background/killed.
+            return "background"
+        @unknown default:
+            return "active"
+        }
+    }
+
+    /// Persist a flag indicating the app exited cleanly (not killed).
+    private func markCleanExit() {
+        let defaults = UserDefaults.standard
+        defaults.set(true, forKey: HybridAppState.killedFlagKey)
+        defaults.synchronize()
+    }
+}

package/nitro.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://nitro.margelo.com/nitro.schema.json",
+  "cxxNamespace": [
+    "appstate"
+  ],
+  "ios": {
+    "iosModuleName": "NitroAppState"
+  },
+  "android": {
+    "androidNamespace": [
+      "appstate"
+    ],
+    "androidCxxLibName": "NitroAppState"
+  },
+  "autolinking": {
+    "AppStateModule": {
+      "swift": "HybridAppState",
+      "kotlin": "HybridAppState"
+    }
+  },
+  "ignorePaths": [
+    "**/node_modules"
+  ]
+}

package/nitrogen/generated/.gitattributes

@@ -0,0 +1 @@
+** linguist-generated=true

package/nitrogen/generated/android/NitroAppState+autolinking.cmake

@@ -0,0 +1,81 @@
+#
+# NitroAppState+autolinking.cmake
+# This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+# https://github.com/mrousavy/nitro
+# Copyright © Marc Rousavy @ Margelo
+#
+
+# This is a CMake file that adds all files generated by Nitrogen
+# to the current CMake project.
+#
+# To use it, add this to your CMakeLists.txt:
+# ```cmake
+# include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/NitroAppState+autolinking.cmake)
+# ```
+
+# Define a flag to check if we are building properly
+add_definitions(-DBUILDING_NITROAPPSTATE_WITH_GENERATED_CMAKE_PROJECT)
+
+# Enable Raw Props parsing in react-native (for Nitro Views)
+add_definitions(-DRN_SERIALIZABLE_STATE)
+
+# Add all headers that were generated by Nitrogen
+include_directories(
+  "../nitrogen/generated/shared/c++"
+  "../nitrogen/generated/android/c++"
+  "../nitrogen/generated/android/"
+)
+
+# Add all .cpp sources that were generated by Nitrogen
+target_sources(
+  # CMake project name (Android C++ library name)
+  NitroAppState PRIVATE
+  # Autolinking Setup
+  ../nitrogen/generated/android/NitroAppStateOnLoad.cpp
+  # Shared Nitrogen C++ sources
+  ../nitrogen/generated/shared/c++/HybridAppStateModuleSpec.cpp
+  # Android-specific Nitrogen C++ sources
+  ../nitrogen/generated/android/c++/JHybridAppStateModuleSpec.cpp
+)
+
+# From node_modules/react-native/ReactAndroid/cmake-utils/folly-flags.cmake
+# Used in node_modules/react-native/ReactAndroid/cmake-utils/ReactNative-application.cmake
+target_compile_definitions(
+  NitroAppState PRIVATE
+  -DFOLLY_NO_CONFIG=1
+  -DFOLLY_HAVE_CLOCK_GETTIME=1
+  -DFOLLY_USE_LIBCPP=1
+  -DFOLLY_CFG_NO_COROUTINES=1
+  -DFOLLY_MOBILE=1
+  -DFOLLY_HAVE_RECVMMSG=1
+  -DFOLLY_HAVE_PTHREAD=1
+  # Once we target android-23 above, we can comment
+  # the following line. NDK uses GNU style stderror_r() after API 23.
+  -DFOLLY_HAVE_XSI_STRERROR_R=1
+)
+
+# Add all libraries required by the generated specs
+find_package(fbjni REQUIRED) # <-- Used for communication between Java <-> C++
+find_package(ReactAndroid REQUIRED) # <-- Used to set up React Native bindings (e.g. CallInvoker/TurboModule)
+find_package(react-native-nitro-modules REQUIRED) # <-- Used to create all HybridObjects and use the Nitro core library
+
+# Link all libraries together
+target_link_libraries(
+        NitroAppState
+        fbjni::fbjni                              # <-- Facebook C++ JNI helpers
+        ReactAndroid::jsi                         # <-- RN: JSI
+        react-native-nitro-modules::NitroModules  # <-- NitroModules Core :)
+)
+
+# Link react-native (different prefab between RN 0.75 and RN 0.76)
+if(ReactAndroid_VERSION_MINOR GREATER_EQUAL 76)
+    target_link_libraries(
+        NitroAppState
+        ReactAndroid::reactnative                 # <-- RN: Native Modules umbrella prefab
+    )
+else()
+    target_link_libraries(
+        NitroAppState
+        ReactAndroid::react_nativemodule_core     # <-- RN: TurboModules Core
+    )
+endif()

package/nitrogen/generated/android/NitroAppState+autolinking.gradle

@@ -0,0 +1,27 @@
+///
+/// NitroAppState+autolinking.gradle
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+/// This is a Gradle file that adds all files generated by Nitrogen
+/// to the current Gradle project.
+///
+/// To use it, add this to your build.gradle:
+/// ```gradle
+/// apply from: '../nitrogen/generated/android/NitroAppState+autolinking.gradle'
+/// ```
+
+logger.warn("[NitroModules] 🔥 NitroAppState is boosted by nitro!")
+
+android {
+  sourceSets {
+    main {
+      java.srcDirs += [
+        // Nitrogen files
+        "${project.projectDir}/../nitrogen/generated/android/kotlin"
+      ]
+    }
+  }
+}

package/nitrogen/generated/android/NitroAppStateOnLoad.cpp

@@ -0,0 +1,48 @@
+///
+/// NitroAppStateOnLoad.cpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#ifndef BUILDING_NITROAPPSTATE_WITH_GENERATED_CMAKE_PROJECT
+#error NitroAppStateOnLoad.cpp is not being built with the autogenerated CMakeLists.txt project. Is a different CMakeLists.txt building this?
+#endif
+
+#include "NitroAppStateOnLoad.hpp"
+
+#include <jni.h>
+#include <fbjni/fbjni.h>
+#include <NitroModules/HybridObjectRegistry.hpp>
+
+#include "JHybridAppStateModuleSpec.hpp"
+#include "JFunc_void.hpp"
+#include "JFunc_void_AppStateChangeEvent.hpp"
+#include <NitroModules/DefaultConstructableObject.hpp>
+
+namespace margelo::nitro::appstate {
+
+int initialize(JavaVM* vm) {
+  using namespace margelo::nitro;
+  using namespace margelo::nitro::appstate;
+  using namespace facebook;
+
+  return facebook::jni::initialize(vm, [] {
+    // Register native JNI methods
+    margelo::nitro::appstate::JHybridAppStateModuleSpec::registerNatives();
+    margelo::nitro::appstate::JFunc_void_cxx::registerNatives();
+    margelo::nitro::appstate::JFunc_void_AppStateChangeEvent_cxx::registerNatives();
+
+    // Register Nitro Hybrid Objects
+    HybridObjectRegistry::registerHybridObjectConstructor(
+      "AppStateModule",
+      []() -> std::shared_ptr<HybridObject> {
+        static DefaultConstructableObject<JHybridAppStateModuleSpec::javaobject> object("com/margelo/nitro/appstate/HybridAppState");
+        auto instance = object.create();
+        return instance->cthis()->shared();
+      }
+    );
+  });
+}
+
+} // namespace margelo::nitro::appstate

package/nitrogen/generated/android/NitroAppStateOnLoad.hpp

@@ -0,0 +1,25 @@
+///
+/// NitroAppStateOnLoad.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#include <jni.h>
+#include <NitroModules/NitroDefines.hpp>
+
+namespace margelo::nitro::appstate {
+
+  /**
+   * Initializes the native (C++) part of NitroAppState, and autolinks all Hybrid Objects.
+   * Call this in your `JNI_OnLoad` function (probably inside `cpp-adapter.cpp`).
+   * Example:
+   * ```cpp (cpp-adapter.cpp)
+   * JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+   *   return margelo::nitro::appstate::initialize(vm);
+   * }
+   * ```
+   */
+  int initialize(JavaVM* vm);
+
+} // namespace margelo::nitro::appstate