@zykeco/expo-background-task 1.0.3 → 1.2.0

package/android/src/main/java/expo/modules/backgroundtask/BackgroundTaskModule.kt

@@ -1,5 +1,7 @@
 package expo.modules.backgroundtask
 
+import android.os.Handler
+import android.os.Looper
 import android.util.Log
 import com.facebook.react.common.build.ReactBuildConfig
 import expo.modules.interfaces.taskManager.TaskManagerInterface
@@ -19,10 +21,39 @@ class BackgroundTaskModule : Module() {
   override fun definition() = ModuleDefinition {
     Name("ExpoBackgroundTask")
 
+    Events("onTasksExpired")
+
+    OnStartObserving("onTasksExpired") {
+      BackgroundTaskScheduler.setOnTasksExpiredListener {
+        // onStopped() runs on a WorkManager thread — sendEvent requires main thread
+        Handler(Looper.getMainLooper()).post {
+          sendEvent("onTasksExpired", emptyMap<String, Any>())
+        }
+      }
+      // Deferred delivery: if a task was stopped before JS attached its listener,
+      // the flag is still pending — deliver now that JS is ready to receive it.
+      appContext.reactContext?.let { context ->
+        if (BackgroundTaskScheduler.consumeStoppedFlag(context)) {
+          Log.d(TAG, "Deferred task-stopped event — emitting onTasksExpired")
+          sendEvent("onTasksExpired", emptyMap<String, Any>())
+        }
+      }
+    }
+
+    OnStopObserving("onTasksExpired") {
+      BackgroundTaskScheduler.setOnTasksExpiredListener(null)
+    }
+
     AsyncFunction("getStatusAsync") {
       return@AsyncFunction 2 // WorkManager is always available on Android.
     }
 
+    AsyncFunction("getSchedulerDiagnosticsAsync") Coroutine { ->
+      appContext.reactContext?.let {
+        return@Coroutine BackgroundTaskScheduler.diagnostics(it)
+      } ?: throw MissingContextException()
+    }
+
     AsyncFunction("triggerTaskWorkerForTestingAsync") Coroutine { ->
       if (ReactBuildConfig.DEBUG) {
         Log.d(TAG, "Triggering tasks for testing")

package/android/src/main/java/expo/modules/backgroundtask/BackgroundTaskScheduler.kt

@@ -33,6 +33,10 @@ object BackgroundTaskScheduler {
   // Unique identifier (generated by us) to identify the worker
   private const val WORKER_IDENTIFIER = "EXPO_BACKGROUND_WORKER"
 
+  // SharedPreferences keys for deferred task-stopped delivery
+  private const val PREFS_NAME = "expo_background_task"
+  private const val KEY_TASK_WAS_STOPPED = "task_was_stopped"
+
   // Log tag
   private val TAG = BackgroundTaskScheduler::class.java.simpleName
 
@@ -54,6 +58,46 @@ object BackgroundTaskScheduler {
   @Volatile
   var inForeground: Boolean = false
 
+  // Listener for task stopped/expired events (set by BackgroundTaskModule)
+  // @Volatile: written on main thread (OnStartObserving), read on WorkManager thread (onStopped)
+  @Volatile
+  private var onTasksExpiredListener: (() -> Unit)? = null
+
+  fun setOnTasksExpiredListener(listener: (() -> Unit)?) {
+    onTasksExpiredListener = listener
+  }
+
+  /**
+   * Called by BackgroundTaskWork.onStopped() when the system stops the worker.
+   * Notifies the listener in real-time (if JS is still running) and persists a flag
+   * as a fallback for deferred delivery on next foreground.
+   */
+  fun onWorkerStopped(context: Context) {
+    Log.d(TAG, "Worker was stopped by the system — notifying listener")
+    // Try real-time notification (JS may still be running)
+    onTasksExpiredListener?.invoke()
+    // Persist flag as fallback for deferred delivery when JS attaches its listener.
+    // commit() is intentional: onStopped() runs as the process is being killed,
+    // so apply()'s async write may never flush to disk.
+    context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+      .edit()
+      .putBoolean(KEY_TASK_WAS_STOPPED, true)
+      .commit()
+  }
+
+  /**
+   * Check and clear the deferred "task was stopped" flag.
+   * Returns true if a previous task was stopped by the system.
+   */
+  fun consumeStoppedFlag(context: Context): Boolean {
+    val prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE)
+    val wasStopped = prefs.getBoolean(KEY_TASK_WAS_STOPPED, false)
+    if (wasStopped) {
+      prefs.edit().putBoolean(KEY_TASK_WAS_STOPPED, false).apply()
+    }
+    return wasStopped
+  }
+
   /**
    * Call when a task is registered
    */
@@ -259,6 +303,26 @@ object BackgroundTaskScheduler {
     }
   }
 
+  /**
+   * Returns diagnostic information about the scheduler state.
+   * Useful for debugging background task scheduling issues.
+   */
+  suspend fun diagnostics(context: Context): Map<String, Any?> {
+    val workInfo = getWorkerInfo(context)
+
+    val result = mutableMapOf<String, Any?>(
+      "identifier" to WORKER_IDENTIFIER,
+      "registeredConsumers" to numberOfRegisteredTasksOfThisType,
+      "intervalMinutes" to intervalMinutes,
+      "requiresNetworkConnectivity" to requiresNetwork,
+      "inForeground" to inForeground,
+      "workerState" to workInfo?.state?.name,
+      "hasPendingRequest" to (workInfo?.state == WorkInfo.State.ENQUEUED || workInfo?.state == WorkInfo.State.RUNNING),
+    )
+
+    return result
+  }
+
   /**
    * Returns the worker info object from the WorkManager if the worker has been
    * registered, otherwise returns null

package/android/src/main/java/expo/modules/backgroundtask/BackgroundTaskWork.kt

@@ -35,4 +35,10 @@ class BackgroundTaskWork(context: Context, params: WorkerParameters) : Coroutine
     }
     return Result.success()
   }
+
+  override fun onStopped() {
+    super.onStopped()
+    Log.d(TAG, "onStopped: Worker was stopped by the system")
+    BackgroundTaskScheduler.onWorkerStopped(applicationContext)
+  }
 }

package/build/BackgroundTask.d.ts

@@ -1,4 +1,4 @@
-import { BackgroundTaskOptions, BackgroundTaskStatus } from './BackgroundTask.types';
+import { BackgroundTaskOptions, BackgroundTaskStatus, SchedulerDiagnostics } from './BackgroundTask.types';
 /**
  * Returns the status for the Background Task API. On web, it always returns `BackgroundTaskStatus.Restricted`,
  * while on native platforms it returns `BackgroundTaskStatus.Available`.
@@ -49,15 +49,31 @@ export declare function unregisterTaskAsync(taskName: string): Promise<void>;
  */
 export declare function triggerTaskWorkerForTestingAsync(): Promise<boolean>;
 /**
- * Adds a listener that is called when the background executor expires. On iOS, tasks can run
- * for minutes, but the system can interrupt the process at any time. This listener is called
- * when the system decides to stop the background tasks and should be used to clean up resources
- * or save state. When the expiry handler is called, the main task runner is rescheduled automatically.
- * @platform ios
+ * Returns diagnostic information about the background task scheduler.
+ * Useful for debugging whether tasks are registered and scheduled correctly.
+ *
+ * @returns A promise that resolves with scheduler diagnostics. Fields vary by platform.
+ */
+export declare function getSchedulerDiagnosticsAsync(): Promise<SchedulerDiagnostics>;
+/**
+ * Adds a listener that is called when the OS stops a running background task.
+ *
+ * On iOS, this fires via the BGTask expiration handler when iOS reclaims resources.
+ * On Android, this fires when WorkManager stops the worker (e.g., system constraints,
+ * memory pressure). If the event cannot be delivered in real-time, it is delivered
+ * when the app next enters the foreground.
+ *
+ * Use this to clean up resources or save state before the task is terminated.
+ * The task runner is rescheduled automatically after expiration.
+ *
+ * **Android note:** This event uses at-least-once delivery — the listener may fire
+ * again on next app start if real-time delivery was also successful. Listeners
+ * should be idempotent.
+ *
  * @return An object with a `remove` method to unsubscribe the listener.
  */
 export declare function addExpirationListener(listener: () => void): {
     remove: () => void;
 };
-export { BackgroundTaskStatus, BackgroundTaskResult, BackgroundTaskOptions, } from './BackgroundTask.types';
+export { BackgroundTaskStatus, BackgroundTaskResult, BackgroundTaskOptions, SchedulerDiagnostics, } from './BackgroundTask.types';
 //# sourceMappingURL=BackgroundTask.d.ts.map

package/build/BackgroundTask.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BackgroundTask.d.ts","sourceRoot":"","sources":["../src/BackgroundTask.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAwBrF;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAa,OAAO,CAAC,oBAAoB,CAQnE,CAAC;AAGF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAGD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASzE;AAGD;;;;;GAKG;AACH,wBAAsB,gCAAgC,IAAI,OAAO,CAAC,OAAO,CAAC,CAUzE;AAGD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG;IAAE,MAAM,EAAE,MAAM,IAAI,CAAA;CAAE,CAKlF;AAGD,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"BackgroundTask.d.ts","sourceRoot":"","sources":["../src/BackgroundTask.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAwB3G;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QAAa,OAAO,CAAC,oBAAoB,CAQnE,CAAC;AAGF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAsB,iBAAiB,CACrC,QAAQ,EAAE,MAAM,EAChB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAGD;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASzE;AAGD;;;;;GAKG;AACH,wBAAsB,gCAAgC,IAAI,OAAO,CAAC,OAAO,CAAC,CAUzE;AAGD;;;;;GAKG;AACH,wBAAsB,4BAA4B,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAKlF;AAGD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG;IAAE,MAAM,EAAE,MAAM,IAAI,CAAA;CAAE,CAKlF;AAGD,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,wBAAwB,CAAC"}

package/build/BackgroundTask.js

@@ -123,11 +123,33 @@ export async function triggerTaskWorkerForTestingAsync() {
 }
 // @needsAudit
 /**
- * Adds a listener that is called when the background executor expires. On iOS, tasks can run
- * for minutes, but the system can interrupt the process at any time. This listener is called
- * when the system decides to stop the background tasks and should be used to clean up resources
- * or save state. When the expiry handler is called, the main task runner is rescheduled automatically.
- * @platform ios
+ * Returns diagnostic information about the background task scheduler.
+ * Useful for debugging whether tasks are registered and scheduled correctly.
+ *
+ * @returns A promise that resolves with scheduler diagnostics. Fields vary by platform.
+ */
+export async function getSchedulerDiagnosticsAsync() {
+    if (!ExpoBackgroundTaskModule.getSchedulerDiagnosticsAsync) {
+        throw new UnavailabilityError('BackgroundTask', 'getSchedulerDiagnosticsAsync');
+    }
+    return await ExpoBackgroundTaskModule.getSchedulerDiagnosticsAsync();
+}
+// @needsAudit
+/**
+ * Adds a listener that is called when the OS stops a running background task.
+ *
+ * On iOS, this fires via the BGTask expiration handler when iOS reclaims resources.
+ * On Android, this fires when WorkManager stops the worker (e.g., system constraints,
+ * memory pressure). If the event cannot be delivered in real-time, it is delivered
+ * when the app next enters the foreground.
+ *
+ * Use this to clean up resources or save state before the task is terminated.
+ * The task runner is rescheduled automatically after expiration.
+ *
+ * **Android note:** This event uses at-least-once delivery — the listener may fire
+ * again on next app start if real-time delivery was also successful. Listeners
+ * should be idempotent.
+ *
  * @return An object with a `remove` method to unsubscribe the listener.
  */
 export function addExpirationListener(listener) {

package/build/BackgroundTask.js.map

@@ -1 +1 @@
-{"version":3,"file":"BackgroundTask.js","sourceRoot":"","sources":["../src/BackgroundTask.ts"],"names":[],"mappings":"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","sourcesContent":["import { isRunningInExpoGo } from 'expo';\nimport { Platform, UnavailabilityError } from 'expo-modules-core';\nimport * as TaskManager from 'expo-task-manager';\n\nimport { BackgroundTaskOptions, BackgroundTaskStatus } from './BackgroundTask.types';\nimport ExpoBackgroundTaskModule from './ExpoBackgroundTaskModule';\n\n// Flag to warn about running on Apple simulator\nlet warnAboutRunningOniOSSimulator = false;\n\nlet warnedAboutExpoGo = false;\n\nfunction _validate(taskName: unknown) {\n  if (isRunningInExpoGo()) {\n    if (!warnedAboutExpoGo) {\n      const message =\n        '`Background Task` functionality is not available in Expo Go:\\n' +\n        'You can use this API and any others in a development build. Learn more: https://expo.fyi/dev-client.';\n      console.warn(message);\n      warnedAboutExpoGo = true;\n    }\n  }\n  if (!taskName || typeof taskName !== 'string') {\n    throw new TypeError('`taskName` must be a non-empty string.');\n  }\n}\n\n// @needsAudit\n/**\n * Returns the status for the Background Task API. On web, it always returns `BackgroundTaskStatus.Restricted`,\n * while on native platforms it returns `BackgroundTaskStatus.Available`.\n *\n * @returns A BackgroundTaskStatus enum value or `null` if not available.\n */\nexport const getStatusAsync = async (): Promise<BackgroundTaskStatus> => {\n  if (!ExpoBackgroundTaskModule.getStatusAsync) {\n    throw new UnavailabilityError('BackgroundTask', 'getStatusAsync');\n  }\n\n  return isRunningInExpoGo()\n    ? BackgroundTaskStatus.Restricted\n    : ExpoBackgroundTaskModule.getStatusAsync();\n};\n\n// @needsAudit\n/**\n * Registers a background task with the given name. Registered tasks are saved in persistent storage and restored once the app is initialized.\n * @param taskName Name of the task to register. The task needs to be defined first - see [`TaskManager.defineTask`](task-manager/#taskmanagerdefinetasktaskname-taskexecutor)\n * for more details.\n * @param options An object containing the background task options.\n *\n * @example\n * ```ts\n * import * as TaskManager from 'expo-task-manager';\n *\n * // Register the task outside of the component\n * TaskManager.defineTask(BACKGROUND_TASK_IDENTIFIER, () => {\n *   try {\n *     await AsyncStorage.setItem(LAST_TASK_DATE_KEY, Date.now().toString());\n *   } catch (error) {\n *     console.error('Failed to save the last fetch date', error);\n *     return BackgroundTaskResult.Failed;\n *   }\n *   return BackgroundTaskResult.Success;\n * });\n * ```\n *\n * You can now use the `registerTaskAsync` function to register the task:\n *\n * ```ts\n * BackgroundTask.registerTaskAsync(BACKGROUND_TASK_IDENTIFIER, {});\n * ```\n */\nexport async function registerTaskAsync(\n  taskName: string,\n  options: BackgroundTaskOptions = {}\n): Promise<void> {\n  if (!ExpoBackgroundTaskModule.registerTaskAsync) {\n    throw new UnavailabilityError('BackgroundTask', 'registerTaskAsync');\n  }\n  if (!TaskManager.isTaskDefined(taskName)) {\n    throw new Error(\n      `Task '${taskName}' is not defined. You must define a task using TaskManager.defineTask before registering.`\n    );\n  }\n\n  if ((await ExpoBackgroundTaskModule.getStatusAsync()) === BackgroundTaskStatus.Restricted) {\n    if (!warnAboutRunningOniOSSimulator) {\n      const message =\n        Platform.OS === 'ios'\n          ? `Background tasks are not supported on iOS simulators. Skipped registering task: ${taskName}.`\n          : `Background tasks are not available in the current environment. Skipped registering task: ${taskName}.`;\n      console.warn(message);\n      warnAboutRunningOniOSSimulator = true;\n    }\n    return;\n  }\n  _validate(taskName);\n  if (await TaskManager.isTaskRegisteredAsync(taskName)) {\n    return;\n  }\n  await ExpoBackgroundTaskModule.registerTaskAsync(taskName, options);\n}\n\n// @needsAudit\n/**\n * Unregisters a background task, so the application will no longer be executing this task.\n * @param taskName Name of the task to unregister.\n * @return A promise which fulfils when the task is fully unregistered.\n */\nexport async function unregisterTaskAsync(taskName: string): Promise<void> {\n  if (!ExpoBackgroundTaskModule.unregisterTaskAsync) {\n    throw new UnavailabilityError('BackgroundTask', 'unregisterTaskAsync');\n  }\n  _validate(taskName);\n  if (!(await TaskManager.isTaskRegisteredAsync(taskName))) {\n    return;\n  }\n  await ExpoBackgroundTaskModule.unregisterTaskAsync(taskName);\n}\n\n// @needsAudit\n/**\n * When in debug mode this function will trigger running the background tasks.\n * This function will only work for apps built in debug mode.\n * This method is only available in development mode. It will not work in production builds.\n * @returns A promise which fulfils when the task is triggered.\n */\nexport async function triggerTaskWorkerForTestingAsync(): Promise<boolean> {\n  if (__DEV__) {\n    if (!ExpoBackgroundTaskModule.triggerTaskWorkerForTestingAsync) {\n      throw new UnavailabilityError('BackgroundTask', 'triggerTaskWorkerForTestingAsync');\n    }\n    console.log('Calling triggerTaskWorkerForTestingAsync');\n    return await ExpoBackgroundTaskModule.triggerTaskWorkerForTestingAsync();\n  } else {\n    return Promise.resolve(false);\n  }\n}\n\n// @needsAudit\n/**\n * Adds a listener that is called when the background executor expires. On iOS, tasks can run\n * for minutes, but the system can interrupt the process at any time. This listener is called\n * when the system decides to stop the background tasks and should be used to clean up resources\n * or save state. When the expiry handler is called, the main task runner is rescheduled automatically.\n * @platform ios\n * @return An object with a `remove` method to unsubscribe the listener.\n */\nexport function addExpirationListener(listener: () => void): { remove: () => void } {\n  if (!ExpoBackgroundTaskModule.addListener) {\n    throw new UnavailabilityError('BackgroundTask', 'addListener');\n  }\n  return ExpoBackgroundTaskModule.addListener('onTasksExpired', listener);\n}\n\n// Export types\nexport {\n  BackgroundTaskStatus,\n  BackgroundTaskResult,\n  BackgroundTaskOptions,\n} from './BackgroundTask.types';\n"]}
+{"version":3,"file":"BackgroundTask.js","sourceRoot":"","sources":["../src/BackgroundTask.ts"],"names":[],"mappings":"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","sourcesContent":["import { isRunningInExpoGo } from 'expo';\nimport { Platform, UnavailabilityError } from 'expo-modules-core';\nimport * as TaskManager from 'expo-task-manager';\n\nimport { BackgroundTaskOptions, BackgroundTaskStatus, SchedulerDiagnostics } from './BackgroundTask.types';\nimport ExpoBackgroundTaskModule from './ExpoBackgroundTaskModule';\n\n// Flag to warn about running on Apple simulator\nlet warnAboutRunningOniOSSimulator = false;\n\nlet warnedAboutExpoGo = false;\n\nfunction _validate(taskName: unknown) {\n  if (isRunningInExpoGo()) {\n    if (!warnedAboutExpoGo) {\n      const message =\n        '`Background Task` functionality is not available in Expo Go:\\n' +\n        'You can use this API and any others in a development build. Learn more: https://expo.fyi/dev-client.';\n      console.warn(message);\n      warnedAboutExpoGo = true;\n    }\n  }\n  if (!taskName || typeof taskName !== 'string') {\n    throw new TypeError('`taskName` must be a non-empty string.');\n  }\n}\n\n// @needsAudit\n/**\n * Returns the status for the Background Task API. On web, it always returns `BackgroundTaskStatus.Restricted`,\n * while on native platforms it returns `BackgroundTaskStatus.Available`.\n *\n * @returns A BackgroundTaskStatus enum value or `null` if not available.\n */\nexport const getStatusAsync = async (): Promise<BackgroundTaskStatus> => {\n  if (!ExpoBackgroundTaskModule.getStatusAsync) {\n    throw new UnavailabilityError('BackgroundTask', 'getStatusAsync');\n  }\n\n  return isRunningInExpoGo()\n    ? BackgroundTaskStatus.Restricted\n    : ExpoBackgroundTaskModule.getStatusAsync();\n};\n\n// @needsAudit\n/**\n * Registers a background task with the given name. Registered tasks are saved in persistent storage and restored once the app is initialized.\n * @param taskName Name of the task to register. The task needs to be defined first - see [`TaskManager.defineTask`](task-manager/#taskmanagerdefinetasktaskname-taskexecutor)\n * for more details.\n * @param options An object containing the background task options.\n *\n * @example\n * ```ts\n * import * as TaskManager from 'expo-task-manager';\n *\n * // Register the task outside of the component\n * TaskManager.defineTask(BACKGROUND_TASK_IDENTIFIER, () => {\n *   try {\n *     await AsyncStorage.setItem(LAST_TASK_DATE_KEY, Date.now().toString());\n *   } catch (error) {\n *     console.error('Failed to save the last fetch date', error);\n *     return BackgroundTaskResult.Failed;\n *   }\n *   return BackgroundTaskResult.Success;\n * });\n * ```\n *\n * You can now use the `registerTaskAsync` function to register the task:\n *\n * ```ts\n * BackgroundTask.registerTaskAsync(BACKGROUND_TASK_IDENTIFIER, {});\n * ```\n */\nexport async function registerTaskAsync(\n  taskName: string,\n  options: BackgroundTaskOptions = {}\n): Promise<void> {\n  if (!ExpoBackgroundTaskModule.registerTaskAsync) {\n    throw new UnavailabilityError('BackgroundTask', 'registerTaskAsync');\n  }\n  if (!TaskManager.isTaskDefined(taskName)) {\n    throw new Error(\n      `Task '${taskName}' is not defined. You must define a task using TaskManager.defineTask before registering.`\n    );\n  }\n\n  if ((await ExpoBackgroundTaskModule.getStatusAsync()) === BackgroundTaskStatus.Restricted) {\n    if (!warnAboutRunningOniOSSimulator) {\n      const message =\n        Platform.OS === 'ios'\n          ? `Background tasks are not supported on iOS simulators. Skipped registering task: ${taskName}.`\n          : `Background tasks are not available in the current environment. Skipped registering task: ${taskName}.`;\n      console.warn(message);\n      warnAboutRunningOniOSSimulator = true;\n    }\n    return;\n  }\n  _validate(taskName);\n  if (await TaskManager.isTaskRegisteredAsync(taskName)) {\n    return;\n  }\n  await ExpoBackgroundTaskModule.registerTaskAsync(taskName, options);\n}\n\n// @needsAudit\n/**\n * Unregisters a background task, so the application will no longer be executing this task.\n * @param taskName Name of the task to unregister.\n * @return A promise which fulfils when the task is fully unregistered.\n */\nexport async function unregisterTaskAsync(taskName: string): Promise<void> {\n  if (!ExpoBackgroundTaskModule.unregisterTaskAsync) {\n    throw new UnavailabilityError('BackgroundTask', 'unregisterTaskAsync');\n  }\n  _validate(taskName);\n  if (!(await TaskManager.isTaskRegisteredAsync(taskName))) {\n    return;\n  }\n  await ExpoBackgroundTaskModule.unregisterTaskAsync(taskName);\n}\n\n// @needsAudit\n/**\n * When in debug mode this function will trigger running the background tasks.\n * This function will only work for apps built in debug mode.\n * This method is only available in development mode. It will not work in production builds.\n * @returns A promise which fulfils when the task is triggered.\n */\nexport async function triggerTaskWorkerForTestingAsync(): Promise<boolean> {\n  if (__DEV__) {\n    if (!ExpoBackgroundTaskModule.triggerTaskWorkerForTestingAsync) {\n      throw new UnavailabilityError('BackgroundTask', 'triggerTaskWorkerForTestingAsync');\n    }\n    console.log('Calling triggerTaskWorkerForTestingAsync');\n    return await ExpoBackgroundTaskModule.triggerTaskWorkerForTestingAsync();\n  } else {\n    return Promise.resolve(false);\n  }\n}\n\n// @needsAudit\n/**\n * Returns diagnostic information about the background task scheduler.\n * Useful for debugging whether tasks are registered and scheduled correctly.\n *\n * @returns A promise that resolves with scheduler diagnostics. Fields vary by platform.\n */\nexport async function getSchedulerDiagnosticsAsync(): Promise<SchedulerDiagnostics> {\n  if (!ExpoBackgroundTaskModule.getSchedulerDiagnosticsAsync) {\n    throw new UnavailabilityError('BackgroundTask', 'getSchedulerDiagnosticsAsync');\n  }\n  return await ExpoBackgroundTaskModule.getSchedulerDiagnosticsAsync();\n}\n\n// @needsAudit\n/**\n * Adds a listener that is called when the OS stops a running background task.\n *\n * On iOS, this fires via the BGTask expiration handler when iOS reclaims resources.\n * On Android, this fires when WorkManager stops the worker (e.g., system constraints,\n * memory pressure). If the event cannot be delivered in real-time, it is delivered\n * when the app next enters the foreground.\n *\n * Use this to clean up resources or save state before the task is terminated.\n * The task runner is rescheduled automatically after expiration.\n *\n * **Android note:** This event uses at-least-once delivery — the listener may fire\n * again on next app start if real-time delivery was also successful. Listeners\n * should be idempotent.\n *\n * @return An object with a `remove` method to unsubscribe the listener.\n */\nexport function addExpirationListener(listener: () => void): { remove: () => void } {\n  if (!ExpoBackgroundTaskModule.addListener) {\n    throw new UnavailabilityError('BackgroundTask', 'addListener');\n  }\n  return ExpoBackgroundTaskModule.addListener('onTasksExpired', listener);\n}\n\n// Export types\nexport {\n  BackgroundTaskStatus,\n  BackgroundTaskResult,\n  BackgroundTaskOptions,\n  SchedulerDiagnostics,\n} from './BackgroundTask.types';\n"]}

package/build/BackgroundTask.types.d.ts

@@ -68,4 +68,68 @@ export type BackgroundTaskOptions = {
      */
     requiresExternalPower?: boolean;
 };
+/**
+ * Diagnostic information about the background task scheduler state.
+ * Fields vary by platform — iOS-only fields are `undefined` on Android and vice versa.
+ */
+export type SchedulerDiagnostics = {
+    /** Native worker/task identifier */
+    identifier: string;
+    /** Number of currently registered task consumers */
+    registeredConsumers: number;
+    /** Whether a pending background task request exists */
+    hasPendingRequest: boolean;
+    /** Whether the task requires network connectivity */
+    requiresNetworkConnectivity: boolean;
+    /**
+     * Whether the device supports background tasks.
+     * @platform ios
+     */
+    supportsBackgroundTasks?: boolean;
+    /**
+     * The BGTask type used ('refresh' or 'processing').
+     * @platform ios
+     */
+    taskType?: string;
+    /**
+     * Configured interval in seconds.
+     * @platform ios
+     */
+    intervalSeconds?: number;
+    /**
+     * Whether the task requires external power.
+     * @platform ios
+     */
+    requiresExternalPower?: boolean;
+    /**
+     * ISO-8601 date string of the earliest time the next task can begin.
+     * @platform ios
+     */
+    earliestBeginDate?: string;
+    /**
+     * Seconds until the next scheduled run (can be negative if overdue).
+     * @platform ios
+     */
+    secondsUntilNextRun?: number;
+    /**
+     * The type of the pending request ('refresh' or 'processing').
+     * @platform ios
+     */
+    pendingRequestType?: string;
+    /**
+     * Configured interval in minutes.
+     * @platform android
+     */
+    intervalMinutes?: number;
+    /**
+     * Whether the app is currently in the foreground.
+     * @platform android
+     */
+    inForeground?: boolean;
+    /**
+     * WorkManager worker state (e.g. 'ENQUEUED', 'RUNNING').
+     * @platform android
+     */
+    workerState?: string;
+};
 //# sourceMappingURL=BackgroundTask.types.d.ts.map

package/build/BackgroundTask.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BackgroundTask.types.d.ts","sourceRoot":"","sources":["../src/BackgroundTask.types.ts"],"names":[],"mappings":"AACA;;GAEG;AACH,oBAAY,oBAAoB;IAC9B;;OAEG;IACH,UAAU,IAAI;IACd;;OAEG;IACH,SAAS,IAAI;CACd;AAGD;;GAEG;AACH,oBAAY,oBAAoB;IAC9B;;OAEG;IACH,OAAO,IAAI;IACX;;OAEG;IACH,MAAM,IAAI;CACX;AAGD;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC;IACvC;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC"}
+{"version":3,"file":"BackgroundTask.types.d.ts","sourceRoot":"","sources":["../src/BackgroundTask.types.ts"],"names":[],"mappings":"AACA;;GAEG;AACH,oBAAY,oBAAoB;IAC9B;;OAEG;IACH,UAAU,IAAI;IACd;;OAEG;IACH,SAAS,IAAI;CACd;AAGD;;GAEG;AACH,oBAAY,oBAAoB;IAC9B;;OAEG;IACH,OAAO,IAAI;IACX;;OAEG;IACH,MAAM,IAAI;CACX;AAGD;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG;IAClC;;;;;;;;;OASG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAC;IACtC;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC;IACvC;;;;;;OAMG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;CACjC,CAAC;AAEF;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,oCAAoC;IACpC,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,mBAAmB,EAAE,MAAM,CAAC;IAC5B,uDAAuD;IACvD,iBAAiB,EAAE,OAAO,CAAC;IAC3B,qDAAqD;IACrD,2BAA2B,EAAE,OAAO,CAAC;IACrC;;;OAGG;IACH,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;OAGG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;OAGG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC"}

package/build/BackgroundTask.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"BackgroundTask.types.js","sourceRoot":"","sources":["../src/BackgroundTask.types.ts"],"names":[],"mappings":"AAAA,cAAc;AACd;;GAEG;AACH,MAAM,CAAN,IAAY,oBASX;AATD,WAAY,oBAAoB;IAC9B;;OAEG;IACH,2EAAc,CAAA;IACd;;OAEG;IACH,yEAAa,CAAA;AACf,CAAC,EATW,oBAAoB,KAApB,oBAAoB,QAS/B;AAED,cAAc;AACd;;GAEG;AACH,MAAM,CAAN,IAAY,oBASX;AATD,WAAY,oBAAoB;IAC9B;;OAEG;IACH,qEAAW,CAAA;IACX;;OAEG;IACH,mEAAU,CAAA;AACZ,CAAC,EATW,oBAAoB,KAApB,oBAAoB,QAS/B","sourcesContent":["// @needsAudit\n/**\n * Availability status for background tasks\n */\nexport enum BackgroundTaskStatus {\n  /**\n   * Background tasks are unavailable.\n   */\n  Restricted = 1,\n  /**\n   * Background tasks are available for the app.\n   */\n  Available = 2,\n}\n\n// @needsAudit\n/**\n * Return value for background tasks.\n */\nexport enum BackgroundTaskResult {\n  /**\n   * The task finished successfully.\n   */\n  Success = 1,\n  /**\n   * The task failed.\n   */\n  Failed = 2,\n}\n\n// @needsAudit\n/**\n * Options for registering a background task\n */\nexport type BackgroundTaskOptions = {\n  /**\n   * Inexact interval in minutes between subsequent repeats of the background tasks. The final\n   * interval may differ from the specified one to minimize wakeups and battery usage.\n   * - Defaults to once every 12 hours (The minimum interval is 15 minutes)\n   * - The system controls the background task execution interval and treats the\n   * specified value as a minimum delay. Tasks won't run exactly on schedule. On iOS, short\n   * intervals are often ignored—the system typically runs background tasks during\n   * specific windows, such as overnight.\n   *\n   */\n  minimumInterval?: number;\n  /**\n   * Whether the task requires network connectivity.\n   *\n   * @default true\n   * @platform ios, android\n   */\n  requiresNetworkConnectivity?: boolean;\n  /**\n   * iOS-only: Which BGTask type to use.\n   * - `'refresh'` (default): BGAppRefreshTaskRequest — aggressive scheduling (~15-30 min),\n   *   ~30 s execution limit. Suitable for periodic syncs and content updates.\n   * - `'processing'`: BGProcessingTaskRequest — iOS defers at its own discretion\n   *   (hours/days), but allows several minutes of runtime. Suitable for heavy work\n   *   (ML training, DB migration). Supports `requiresNetworkConnectivity` and\n   *   `requiresExternalPower`.\n   *\n   * @default 'refresh'\n   * @platform ios\n   */\n  iosTaskType?: 'refresh' | 'processing';\n  /**\n   * iOS-only: Whether the task requires external power.\n   * Only relevant when `iosTaskType: 'processing'`.\n   *\n   * @default false\n   * @platform ios\n   */\n  requiresExternalPower?: boolean;\n};\n"]}
+{"version":3,"file":"BackgroundTask.types.js","sourceRoot":"","sources":["../src/BackgroundTask.types.ts"],"names":[],"mappings":"AAAA,cAAc;AACd;;GAEG;AACH,MAAM,CAAN,IAAY,oBASX;AATD,WAAY,oBAAoB;IAC9B;;OAEG;IACH,2EAAc,CAAA;IACd;;OAEG;IACH,yEAAa,CAAA;AACf,CAAC,EATW,oBAAoB,KAApB,oBAAoB,QAS/B;AAED,cAAc;AACd;;GAEG;AACH,MAAM,CAAN,IAAY,oBASX;AATD,WAAY,oBAAoB;IAC9B;;OAEG;IACH,qEAAW,CAAA;IACX;;OAEG;IACH,mEAAU,CAAA;AACZ,CAAC,EATW,oBAAoB,KAApB,oBAAoB,QAS/B","sourcesContent":["// @needsAudit\n/**\n * Availability status for background tasks\n */\nexport enum BackgroundTaskStatus {\n  /**\n   * Background tasks are unavailable.\n   */\n  Restricted = 1,\n  /**\n   * Background tasks are available for the app.\n   */\n  Available = 2,\n}\n\n// @needsAudit\n/**\n * Return value for background tasks.\n */\nexport enum BackgroundTaskResult {\n  /**\n   * The task finished successfully.\n   */\n  Success = 1,\n  /**\n   * The task failed.\n   */\n  Failed = 2,\n}\n\n// @needsAudit\n/**\n * Options for registering a background task\n */\nexport type BackgroundTaskOptions = {\n  /**\n   * Inexact interval in minutes between subsequent repeats of the background tasks. The final\n   * interval may differ from the specified one to minimize wakeups and battery usage.\n   * - Defaults to once every 12 hours (The minimum interval is 15 minutes)\n   * - The system controls the background task execution interval and treats the\n   * specified value as a minimum delay. Tasks won't run exactly on schedule. On iOS, short\n   * intervals are often ignored—the system typically runs background tasks during\n   * specific windows, such as overnight.\n   *\n   */\n  minimumInterval?: number;\n  /**\n   * Whether the task requires network connectivity.\n   *\n   * @default true\n   * @platform ios, android\n   */\n  requiresNetworkConnectivity?: boolean;\n  /**\n   * iOS-only: Which BGTask type to use.\n   * - `'refresh'` (default): BGAppRefreshTaskRequest — aggressive scheduling (~15-30 min),\n   *   ~30 s execution limit. Suitable for periodic syncs and content updates.\n   * - `'processing'`: BGProcessingTaskRequest — iOS defers at its own discretion\n   *   (hours/days), but allows several minutes of runtime. Suitable for heavy work\n   *   (ML training, DB migration). Supports `requiresNetworkConnectivity` and\n   *   `requiresExternalPower`.\n   *\n   * @default 'refresh'\n   * @platform ios\n   */\n  iosTaskType?: 'refresh' | 'processing';\n  /**\n   * iOS-only: Whether the task requires external power.\n   * Only relevant when `iosTaskType: 'processing'`.\n   *\n   * @default false\n   * @platform ios\n   */\n  requiresExternalPower?: boolean;\n};\n\n/**\n * Diagnostic information about the background task scheduler state.\n * Fields vary by platform — iOS-only fields are `undefined` on Android and vice versa.\n */\nexport type SchedulerDiagnostics = {\n  /** Native worker/task identifier */\n  identifier: string;\n  /** Number of currently registered task consumers */\n  registeredConsumers: number;\n  /** Whether a pending background task request exists */\n  hasPendingRequest: boolean;\n  /** Whether the task requires network connectivity */\n  requiresNetworkConnectivity: boolean;\n  /**\n   * Whether the device supports background tasks.\n   * @platform ios\n   */\n  supportsBackgroundTasks?: boolean;\n  /**\n   * The BGTask type used ('refresh' or 'processing').\n   * @platform ios\n   */\n  taskType?: string;\n  /**\n   * Configured interval in seconds.\n   * @platform ios\n   */\n  intervalSeconds?: number;\n  /**\n   * Whether the task requires external power.\n   * @platform ios\n   */\n  requiresExternalPower?: boolean;\n  /**\n   * ISO-8601 date string of the earliest time the next task can begin.\n   * @platform ios\n   */\n  earliestBeginDate?: string;\n  /**\n   * Seconds until the next scheduled run (can be negative if overdue).\n   * @platform ios\n   */\n  secondsUntilNextRun?: number;\n  /**\n   * The type of the pending request ('refresh' or 'processing').\n   * @platform ios\n   */\n  pendingRequestType?: string;\n  /**\n   * Configured interval in minutes.\n   * @platform android\n   */\n  intervalMinutes?: number;\n  /**\n   * Whether the app is currently in the foreground.\n   * @platform android\n   */\n  inForeground?: boolean;\n  /**\n   * WorkManager worker state (e.g. 'ENQUEUED', 'RUNNING').\n   * @platform android\n   */\n  workerState?: string;\n};\n"]}

package/build/ExpoBackgroundTaskModule.d.ts

@@ -1,5 +1,5 @@
 import { type NativeModule } from 'expo';
-import { BackgroundTaskOptions, BackgroundTaskStatus } from './BackgroundTask.types';
+import { BackgroundTaskOptions, BackgroundTaskStatus, SchedulerDiagnostics } from './BackgroundTask.types';
 type ExpoBackgroundTaskEvents = {
     onTasksExpired(): void;
 };
@@ -8,6 +8,7 @@ declare class ExpoBackgroundTaskModule extends NativeModule<ExpoBackgroundTaskEv
     registerTaskAsync(name: string, options: BackgroundTaskOptions): Promise<void>;
     unregisterTaskAsync(name: string): Promise<void>;
     triggerTaskWorkerForTestingAsync(): Promise<boolean>;
+    getSchedulerDiagnosticsAsync(): Promise<SchedulerDiagnostics>;
 }
 declare const _default: ExpoBackgroundTaskModule;
 export default _default;

package/build/ExpoBackgroundTaskModule.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExpoBackgroundTaskModule.d.ts","sourceRoot":"","sources":["../src/ExpoBackgroundTaskModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,MAAM,CAAC;AAE9D,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAErF,KAAK,wBAAwB,GAAG;IAC9B,cAAc,IAAI,IAAI,CAAC;CACxB,CAAC;AAEF,OAAO,OAAO,wBAAyB,SAAQ,YAAY,CAAC,wBAAwB,CAAC;IACnF,cAAc,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAC/C,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAC9E,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAChD,gCAAgC,IAAI,OAAO,CAAC,OAAO,CAAC;CACrD;;AAED,wBAAmF"}
+{"version":3,"file":"ExpoBackgroundTaskModule.d.ts","sourceRoot":"","sources":["../src/ExpoBackgroundTaskModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuB,KAAK,YAAY,EAAE,MAAM,MAAM,CAAC;AAE9D,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAE3G,KAAK,wBAAwB,GAAG;IAC9B,cAAc,IAAI,IAAI,CAAC;CACxB,CAAC;AAEF,OAAO,OAAO,wBAAyB,SAAQ,YAAY,CAAC,wBAAwB,CAAC;IACnF,cAAc,IAAI,OAAO,CAAC,oBAAoB,CAAC;IAC/C,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC;IAC9E,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAChD,gCAAgC,IAAI,OAAO,CAAC,OAAO,CAAC;IACpD,4BAA4B,IAAI,OAAO,CAAC,oBAAoB,CAAC;CAC9D;;AAED,wBAAmF"}

package/build/ExpoBackgroundTaskModule.js.map

@@ -1 +1 @@
-{"version":3,"file":"ExpoBackgroundTaskModule.js","sourceRoot":"","sources":["../src/ExpoBackgroundTaskModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAqB,MAAM,MAAM,CAAC;AAe9D,eAAe,mBAAmB,CAA2B,oBAAoB,CAAC,CAAC","sourcesContent":["import { requireNativeModule, type NativeModule } from 'expo';\n\nimport { BackgroundTaskOptions, BackgroundTaskStatus } from './BackgroundTask.types';\n\ntype ExpoBackgroundTaskEvents = {\n  onTasksExpired(): void;\n};\n\ndeclare class ExpoBackgroundTaskModule extends NativeModule<ExpoBackgroundTaskEvents> {\n  getStatusAsync(): Promise<BackgroundTaskStatus>;\n  registerTaskAsync(name: string, options: BackgroundTaskOptions): Promise<void>;\n  unregisterTaskAsync(name: string): Promise<void>;\n  triggerTaskWorkerForTestingAsync(): Promise<boolean>;\n}\n\nexport default requireNativeModule<ExpoBackgroundTaskModule>('ExpoBackgroundTask');\n"]}
+{"version":3,"file":"ExpoBackgroundTaskModule.js","sourceRoot":"","sources":["../src/ExpoBackgroundTaskModule.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAqB,MAAM,MAAM,CAAC;AAgB9D,eAAe,mBAAmB,CAA2B,oBAAoB,CAAC,CAAC","sourcesContent":["import { requireNativeModule, type NativeModule } from 'expo';\n\nimport { BackgroundTaskOptions, BackgroundTaskStatus, SchedulerDiagnostics } from './BackgroundTask.types';\n\ntype ExpoBackgroundTaskEvents = {\n  onTasksExpired(): void;\n};\n\ndeclare class ExpoBackgroundTaskModule extends NativeModule<ExpoBackgroundTaskEvents> {\n  getStatusAsync(): Promise<BackgroundTaskStatus>;\n  registerTaskAsync(name: string, options: BackgroundTaskOptions): Promise<void>;\n  unregisterTaskAsync(name: string): Promise<void>;\n  triggerTaskWorkerForTestingAsync(): Promise<boolean>;\n  getSchedulerDiagnosticsAsync(): Promise<SchedulerDiagnostics>;\n}\n\nexport default requireNativeModule<ExpoBackgroundTaskModule>('ExpoBackgroundTask');\n"]}

package/ios/BackgroundTaskModule.swift

@@ -69,12 +69,15 @@ public class BackgroundTaskModule: Module {
       return BackgroundTaskScheduler.supportsBackgroundTasks()
         ? BackgroundTaskStatus.available : .restricted
     }
+
+    AsyncFunction("getSchedulerDiagnosticsAsync") {
+      return await BackgroundTaskScheduler.diagnostics()
+    }
   }
 
+  // No payload validation needed — onTasksExpiredNotification is a module-private
+  // Notification.Name posted only by BackgroundTaskAppDelegateSubscriber.
   @objc func handleTasksExpiredNotification(_ notification: Notification) {
-    guard let url = notification.userInfo?["url"] as? URL else {
-      return
-    }
     self.sendEvent(onTasksExpired, [:])
   }
 }

package/ios/BackgroundTaskScheduler.swift

@@ -192,6 +192,38 @@ public class BackgroundTaskScheduler {
     return requests.contains(where: { $0.identifier == BackgroundTaskConstants.BackgroundWorkerIdentifier })
   }
 
+  /**
+   Returns diagnostic information about the scheduler state.
+   Useful for debugging background task scheduling issues.
+   */
+  public static func diagnostics() async -> [String: Any] {
+    let pending = await BGTaskScheduler.shared.pendingTaskRequests()
+    let matchingRequest = pending.first(where: {
+      $0.identifier == BackgroundTaskConstants.BackgroundWorkerIdentifier
+    })
+
+    var result: [String: Any] = [
+      "identifier": BackgroundTaskConstants.BackgroundWorkerIdentifier,
+      "registeredConsumers": numberOfRegisteredTasksOfThisType,
+      "taskType": taskType,
+      "intervalSeconds": intervalSeconds,
+      "requiresNetworkConnectivity": requiresNetwork,
+      "requiresExternalPower": requiresExternalPower,
+      "hasPendingRequest": matchingRequest != nil,
+      "supportsBackgroundTasks": supportsBackgroundTasks(),
+    ]
+
+    if let request = matchingRequest {
+      if let earliestBeginDate = request.earliestBeginDate {
+        result["earliestBeginDate"] = ISO8601DateFormatter().string(from: earliestBeginDate)
+        result["secondsUntilNextRun"] = earliestBeginDate.timeIntervalSinceNow
+      }
+      result["pendingRequestType"] = request is BGProcessingTaskRequest ? "processing" : "refresh"
+    }
+
+    return result
+  }
+
   /**
    Returns true if we're on a device that supports background tasks
    */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zykeco/expo-background-task",
-  "version": "1.0.3",
+  "version": "1.2.0",
   "description": "Expo Android and iOS module for Background Task APIs",
   "main": "build/BackgroundTask.js",
   "types": "build/BackgroundTask.d.ts",

package/src/BackgroundTask.ts

@@ -2,7 +2,7 @@ import { isRunningInExpoGo } from 'expo';
 import { Platform, UnavailabilityError } from 'expo-modules-core';
 import * as TaskManager from 'expo-task-manager';
 
-import { BackgroundTaskOptions, BackgroundTaskStatus } from './BackgroundTask.types';
+import { BackgroundTaskOptions, BackgroundTaskStatus, SchedulerDiagnostics } from './BackgroundTask.types';
 import ExpoBackgroundTaskModule from './ExpoBackgroundTaskModule';
 
 // Flag to warn about running on Apple simulator
@@ -140,11 +140,34 @@ export async function triggerTaskWorkerForTestingAsync(): Promise<boolean> {
 
 // @needsAudit
 /**
- * Adds a listener that is called when the background executor expires. On iOS, tasks can run
- * for minutes, but the system can interrupt the process at any time. This listener is called
- * when the system decides to stop the background tasks and should be used to clean up resources
- * or save state. When the expiry handler is called, the main task runner is rescheduled automatically.
- * @platform ios
+ * Returns diagnostic information about the background task scheduler.
+ * Useful for debugging whether tasks are registered and scheduled correctly.
+ *
+ * @returns A promise that resolves with scheduler diagnostics. Fields vary by platform.
+ */
+export async function getSchedulerDiagnosticsAsync(): Promise<SchedulerDiagnostics> {
+  if (!ExpoBackgroundTaskModule.getSchedulerDiagnosticsAsync) {
+    throw new UnavailabilityError('BackgroundTask', 'getSchedulerDiagnosticsAsync');
+  }
+  return await ExpoBackgroundTaskModule.getSchedulerDiagnosticsAsync();
+}
+
+// @needsAudit
+/**
+ * Adds a listener that is called when the OS stops a running background task.
+ *
+ * On iOS, this fires via the BGTask expiration handler when iOS reclaims resources.
+ * On Android, this fires when WorkManager stops the worker (e.g., system constraints,
+ * memory pressure). If the event cannot be delivered in real-time, it is delivered
+ * when the app next enters the foreground.
+ *
+ * Use this to clean up resources or save state before the task is terminated.
+ * The task runner is rescheduled automatically after expiration.
+ *
+ * **Android note:** This event uses at-least-once delivery — the listener may fire
+ * again on next app start if real-time delivery was also successful. Listeners
+ * should be idempotent.
+ *
  * @return An object with a `remove` method to unsubscribe the listener.
  */
 export function addExpirationListener(listener: () => void): { remove: () => void } {
@@ -159,4 +182,5 @@ export {
   BackgroundTaskStatus,
   BackgroundTaskResult,
   BackgroundTaskOptions,
+  SchedulerDiagnostics,
 } from './BackgroundTask.types';

package/src/BackgroundTask.types.ts

@@ -73,3 +73,68 @@ export type BackgroundTaskOptions = {
    */
   requiresExternalPower?: boolean;
 };
+
+/**
+ * Diagnostic information about the background task scheduler state.
+ * Fields vary by platform — iOS-only fields are `undefined` on Android and vice versa.
+ */
+export type SchedulerDiagnostics = {
+  /** Native worker/task identifier */
+  identifier: string;
+  /** Number of currently registered task consumers */
+  registeredConsumers: number;
+  /** Whether a pending background task request exists */
+  hasPendingRequest: boolean;
+  /** Whether the task requires network connectivity */
+  requiresNetworkConnectivity: boolean;
+  /**
+   * Whether the device supports background tasks.
+   * @platform ios
+   */
+  supportsBackgroundTasks?: boolean;
+  /**
+   * The BGTask type used ('refresh' or 'processing').
+   * @platform ios
+   */
+  taskType?: string;
+  /**
+   * Configured interval in seconds.
+   * @platform ios
+   */
+  intervalSeconds?: number;
+  /**
+   * Whether the task requires external power.
+   * @platform ios
+   */
+  requiresExternalPower?: boolean;
+  /**
+   * ISO-8601 date string of the earliest time the next task can begin.
+   * @platform ios
+   */
+  earliestBeginDate?: string;
+  /**
+   * Seconds until the next scheduled run (can be negative if overdue).
+   * @platform ios
+   */
+  secondsUntilNextRun?: number;
+  /**
+   * The type of the pending request ('refresh' or 'processing').
+   * @platform ios
+   */
+  pendingRequestType?: string;
+  /**
+   * Configured interval in minutes.
+   * @platform android
+   */
+  intervalMinutes?: number;
+  /**
+   * Whether the app is currently in the foreground.
+   * @platform android
+   */
+  inForeground?: boolean;
+  /**
+   * WorkManager worker state (e.g. 'ENQUEUED', 'RUNNING').
+   * @platform android
+   */
+  workerState?: string;
+};

package/src/ExpoBackgroundTaskModule.ts

@@ -1,6 +1,6 @@
 import { requireNativeModule, type NativeModule } from 'expo';
 
-import { BackgroundTaskOptions, BackgroundTaskStatus } from './BackgroundTask.types';
+import { BackgroundTaskOptions, BackgroundTaskStatus, SchedulerDiagnostics } from './BackgroundTask.types';
 
 type ExpoBackgroundTaskEvents = {
   onTasksExpired(): void;
@@ -11,6 +11,7 @@ declare class ExpoBackgroundTaskModule extends NativeModule<ExpoBackgroundTaskEv
   registerTaskAsync(name: string, options: BackgroundTaskOptions): Promise<void>;
   unregisterTaskAsync(name: string): Promise<void>;
   triggerTaskWorkerForTestingAsync(): Promise<boolean>;
+  getSchedulerDiagnosticsAsync(): Promise<SchedulerDiagnostics>;
 }
 
 export default requireNativeModule<ExpoBackgroundTaskModule>('ExpoBackgroundTask');