@zykeco/expo-background-task 1.1.0 → 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,6 +21,29 @@ 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.
     }

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
    */

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

@@ -56,11 +56,20 @@ export declare function triggerTaskWorkerForTestingAsync(): Promise<boolean>;
  */
 export declare function getSchedulerDiagnosticsAsync(): Promise<SchedulerDiagnostics>;
 /**
- * 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
+ * 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): {

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,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;;;;;;;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,EACrB,oBAAoB,GACrB,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

@@ -136,11 +136,20 @@ export async function getSchedulerDiagnosticsAsync() {
 }
 // @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
+ * 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, 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 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  SchedulerDiagnostics,\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/ios/BackgroundTaskModule.swift

@@ -75,10 +75,9 @@ public class BackgroundTaskModule: Module {
     }
   }
 
+  // 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zykeco/expo-background-task",
-  "version": "1.1.0",
+  "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

@@ -154,11 +154,20 @@ export async function getSchedulerDiagnosticsAsync(): Promise<SchedulerDiagnosti
 
 // @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
+ * 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 } {