@zykeco/expo-background-task 1.0.0

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

@@ -0,0 +1,294 @@
+package expo.modules.backgroundtask
+
+import android.content.Context
+import android.os.Build
+import android.util.Log
+import androidx.work.Constraints
+import androidx.work.Data
+import androidx.work.ExistingPeriodicWorkPolicy
+import androidx.work.ExistingWorkPolicy
+import androidx.work.NetworkType
+import androidx.work.OneTimeWorkRequestBuilder
+import androidx.work.Operation
+import androidx.work.PeriodicWorkRequestBuilder
+import androidx.work.WorkInfo
+import androidx.work.WorkManager
+import com.google.common.util.concurrent.ListenableFuture
+import expo.modules.interfaces.taskManager.TaskServiceProviderHelper
+import kotlinx.coroutines.CancellationException
+import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.awaitAll
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.launch
+
+import kotlinx.coroutines.withContext
+import java.time.Duration
+import java.util.concurrent.TimeUnit
+
+object BackgroundTaskScheduler {
+  // Default interval
+  const val DEFAULT_INTERVAL_MINUTES = 60L * 24L // Once every day
+
+  // Unique identifier (generated by us) to identify the worker
+  private const val WORKER_IDENTIFIER = "EXPO_BACKGROUND_WORKER"
+
+  // Log tag
+  private val TAG = BackgroundTaskScheduler::class.java.simpleName
+
+  // Number of active task consumers
+  private var numberOfRegisteredTasksOfThisType = 0
+
+  // Interval
+  private var intervalMinutes: Long = DEFAULT_INTERVAL_MINUTES
+
+  // Whether network connectivity is required
+  private var requiresNetwork: Boolean = true
+
+  // Tracks whether in foreground
+  var inForeground: Boolean = false
+
+  /**
+   * Call when a task is registered
+   */
+  fun registerTask(context: Context, intervalMinutes: Long, requiresNetwork: Boolean? = null) {
+    numberOfRegisteredTasksOfThisType += 1
+    this.intervalMinutes = intervalMinutes
+    if (requiresNetwork != null) {
+      this.requiresNetwork = requiresNetwork
+    }
+
+    if (numberOfRegisteredTasksOfThisType == 1) {
+      CoroutineScope(Dispatchers.IO).launch {
+        // Only schedule if no worker is already running/enqueued
+        if (!isWorkerRunning(context)) {
+          scheduleWorker(context, context.packageName)
+        }
+      }
+    }
+  }
+
+  /**
+   * Call when a task is unregistered
+   */
+  fun unregisterTask(context: Context) {
+    numberOfRegisteredTasksOfThisType -= 1
+
+    if (numberOfRegisteredTasksOfThisType == 0) {
+      CoroutineScope(Dispatchers.IO).launch {
+        stopWorker(context)
+      }
+    }
+  }
+
+  /**
+   * Schedules the worker task to run. The worker should run periodically.
+   */
+  private suspend fun scheduleWorker(context: Context, appScopeKey: String, cancelExisting: Boolean = true, overriddenIntervalMinutes: Long = intervalMinutes): Boolean {
+    if (numberOfRegisteredTasksOfThisType == 0) {
+      Log.d(TAG, "Will not enqueue worker. No registered tasks to run.")
+      return false
+    }
+
+    // Stop the current worker (if any)
+    if (cancelExisting) {
+      stopWorker(context)
+    }
+
+    Log.d(TAG, "Enqueuing worker with identifier $WORKER_IDENTIFIER and '$overriddenIntervalMinutes' minutes delay.")
+
+    // Build the work request
+    val data = Data.Builder()
+      .putString("appScopeKey", appScopeKey)
+      .build()
+    val constraints = Constraints.Builder()
+      .setRequiredNetworkType(
+        if (requiresNetwork) NetworkType.CONNECTED else NetworkType.NOT_REQUIRED
+      )
+      .build()
+
+    // Get Work manager
+    val workManager = WorkManager.getInstance(context)
+
+    // We have two different paths here, since on Android 14-15 we need to use a periodic request
+    // builder since the OneTimeWorkRequest doesn't support setting initial delay (which is how we
+    // control executing a task periodically - we spawn a One-time work request when backgrounding,
+    // and when this is done we spawn a new one. This makes it a lot easier to debug since we can
+    // use adb to spawn jobs whenever we want)
+    // The following is the path we have to follow on  Android.O and later:
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      // Create the work request
+      val builder = OneTimeWorkRequestBuilder<BackgroundTaskWork>()
+        .setInputData(data)
+        .setConstraints(constraints)
+
+      // Add minimum interval here as well so that the work doesn't start immediately
+      builder.setInitialDelay(Duration.ofMinutes(overriddenIntervalMinutes))
+
+      // Create work request
+      val workRequest = builder.build()
+
+      // Enqueue the work
+      return try {
+        workManager.enqueueUniqueWork(
+          WORKER_IDENTIFIER,
+          // This is where we decide if we should cancel or replace the task - cancelling is done
+          // when spawning the first task, while appending is when we spawn from a running task
+          // to set up the next periodic run of the task
+          if (cancelExisting) ExistingWorkPolicy.REPLACE else ExistingWorkPolicy.APPEND,
+          workRequest
+        ).await()
+
+        true
+      } catch (e: Exception) {
+        Log.e(TAG, "Worker failed to start with error " + e.message)
+        false
+      }
+    } else {
+      val builder = PeriodicWorkRequestBuilder<BackgroundTaskWork>(
+        repeatIntervalTimeUnit = TimeUnit.MINUTES,
+        repeatInterval = intervalMinutes
+      )
+        .setInputData(data)
+        .setConstraints(constraints)
+
+      // Create work request
+      val workRequest = builder.build()
+
+      // Enqueue the work
+      return try {
+        workManager.enqueueUniquePeriodicWork(
+          WORKER_IDENTIFIER,
+          ExistingPeriodicWorkPolicy.CANCEL_AND_REENQUEUE,
+          workRequest
+        ).await()
+
+        true
+      } catch (e: Exception) {
+        Log.e(TAG, "Worker failed to start with error " + e.message)
+        false
+      }
+    }
+  }
+
+  /**
+   * Cancels the worker task
+   */
+  private suspend fun stopWorker(context: Context): Boolean {
+    if (!isWorkerRunning(context)) {
+      return false
+    }
+
+    Log.d(TAG, "Cancelling worker with identifier $WORKER_IDENTIFIER")
+
+    // Stop our main worker
+    val workManager = WorkManager.getInstance(context)
+    return try {
+      workManager.cancelUniqueWork(WORKER_IDENTIFIER).await()
+    } catch (e: Exception) {
+      Log.d(TAG, "Stopping worker failed with error " + e.message)
+      false
+    }
+  }
+
+  /**
+   * Returns true if the worker task is pending
+   */
+  private suspend fun isWorkerRunning(context: Context): Boolean {
+    val workInfo = getWorkerInfo(context)
+    return workInfo?.state == WorkInfo.State.RUNNING ||
+      workInfo?.state == WorkInfo.State.ENQUEUED
+  }
+
+  /**
+   * Runs tasks with the given appScopeKey
+   */
+  suspend fun runTasks(context: Context, appScopeKey: String) {
+    // Get task service
+    val taskService = TaskServiceProviderHelper.getTaskServiceImpl(context)
+      ?: throw MissingTaskServiceException()
+
+    Log.d(TAG, "runTasks: $appScopeKey")
+
+    // Get all task consumers
+    val consumers = taskService.getTaskConsumers(appScopeKey)
+    Log.d(TAG, "runTasks: number of consumers ${consumers.size}")
+
+    if (consumers.isEmpty()) {
+      return
+    }
+
+    // Make sure we're in the background before running a task
+    if (inForeground) {
+      // Schedule task in an hour (or at least minimumInterval) - the app is foregrounded and
+      // we don't want to run anything to avoid performance issues.
+      Log.d(TAG, "runTasks: App is in the foreground")
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+        scheduleWorker(context, appScopeKey, false, 60L.coerceAtMost(intervalMinutes))
+        Log.d(TAG, "runTasks: Scheduled new worker in $intervalMinutes minutes")
+      }
+      return
+    }
+
+    val tasks = consumers.filterIsInstance<BackgroundTaskConsumer>()
+      .map { bgTaskConsumer ->
+        Log.d(TAG, "runTasks: executing tasks for consumer of type ${bgTaskConsumer.taskType()}")
+        val taskCompletion = CompletableDeferred<Unit>()
+        try {
+          bgTaskConsumer.executeTask {
+            Log.d(TAG, "Task successfully finished")
+            taskCompletion.complete(Unit)
+          }
+        } catch (e: Exception) {
+          Log.e(TAG, "Task failed: ${e.message}")
+        }
+        taskCompletion
+      }
+    // Await all tasks to complete
+    tasks.awaitAll()
+
+    // Schedule next task
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      scheduleWorker(context, appScopeKey, false)
+    }
+  }
+
+  /**
+   * Returns the worker info object from the WorkManager if the worker has been
+   * registered, otherwise returns null
+   */
+  private suspend fun getWorkerInfo(context: Context): WorkInfo? {
+    // Get work manager
+    val workManager = WorkManager.getInstance(context)
+
+    return try {
+      val workInfos = workManager.getWorkInfosForUniqueWork(WORKER_IDENTIFIER).await()
+      return workInfos.firstOrNull()
+    } catch (e: Exception) {
+      Log.d(TAG, "Calling getWorkInfosForUniqueWork failed with error " + e.message)
+      null
+    }
+  }
+
+  /**
+   * Helper function for calling functions returning an Operation
+   */
+  private suspend fun Operation.await(): Boolean = withContext(Dispatchers.IO) {
+    result.get()
+    true
+  }
+
+  /**
+   * Helper function for calling functions returning a ListenableFuture
+   */
+  private suspend fun <T> ListenableFuture<T>.await(): T = withContext(Dispatchers.IO) {
+    try {
+      get()
+    } catch (e: CancellationException) {
+      cancel(true)
+      throw e
+    } catch (e: Exception) {
+      throw e
+    }
+  }
+}

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

@@ -0,0 +1,38 @@
+package expo.modules.backgroundtask
+
+import android.content.Context
+import android.util.Log
+import androidx.work.CoroutineWorker
+import androidx.work.Data
+import androidx.work.WorkerParameters
+
+class BackgroundTaskWork(context: Context, params: WorkerParameters) : CoroutineWorker(context, params) {
+  companion object {
+    private val TAG = BackgroundTaskWork::class.java.simpleName
+  }
+
+  /**
+   * The doWork function is called by the Android WorkManager to execute scheduled work.
+   */
+  override suspend fun doWork(): Result {
+    Log.i(TAG, "doWork: Running worker")
+
+    // Get the app scope key
+    val appScopeKey = inputData.getString("appScopeKey") ?: throw MissingAppScopeKey()
+
+    try {
+      // Run tasks async using the task service. This call will return when the task has finished
+      // ie. When JS task executor has notified the task manager that it is done.
+      BackgroundTaskScheduler.runTasks(applicationContext, appScopeKey)
+    } catch (e: Exception) {
+      // Wrap exception in Data:
+      val outputData = Data.Builder()
+        .putString("error", e.message)
+        .putString("stackTrace", e.stackTraceToString())
+        .build()
+
+      return Result.failure(outputData)
+    }
+    return Result.success()
+  }
+}

package/app.plugin.js

@@ -0,0 +1 @@
+module.exports = require('./plugin/build/withBackgroundTask');

package/build/BackgroundTask.d.ts

@@ -0,0 +1,63 @@
+import { BackgroundTaskOptions, BackgroundTaskStatus } 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`.
+ *
+ * @returns A BackgroundTaskStatus enum value or `null` if not available.
+ */
+export declare const getStatusAsync: () => Promise<BackgroundTaskStatus>;
+/**
+ * Registers a background task with the given name. Registered tasks are saved in persistent storage and restored once the app is initialized.
+ * @param taskName Name of the task to register. The task needs to be defined first - see [`TaskManager.defineTask`](task-manager/#taskmanagerdefinetasktaskname-taskexecutor)
+ * for more details.
+ * @param options An object containing the background task options.
+ *
+ * @example
+ * ```ts
+ * import * as TaskManager from 'expo-task-manager';
+ *
+ * // Register the task outside of the component
+ * TaskManager.defineTask(BACKGROUND_TASK_IDENTIFIER, () => {
+ *   try {
+ *     await AsyncStorage.setItem(LAST_TASK_DATE_KEY, Date.now().toString());
+ *   } catch (error) {
+ *     console.error('Failed to save the last fetch date', error);
+ *     return BackgroundTaskResult.Failed;
+ *   }
+ *   return BackgroundTaskResult.Success;
+ * });
+ * ```
+ *
+ * You can now use the `registerTaskAsync` function to register the task:
+ *
+ * ```ts
+ * BackgroundTask.registerTaskAsync(BACKGROUND_TASK_IDENTIFIER, {});
+ * ```
+ */
+export declare function registerTaskAsync(taskName: string, options?: BackgroundTaskOptions): Promise<void>;
+/**
+ * Unregisters a background task, so the application will no longer be executing this task.
+ * @param taskName Name of the task to unregister.
+ * @return A promise which fulfils when the task is fully unregistered.
+ */
+export declare function unregisterTaskAsync(taskName: string): Promise<void>;
+/**
+ * When in debug mode this function will trigger running the background tasks.
+ * This function will only work for apps built in debug mode.
+ * This method is only available in development mode. It will not work in production builds.
+ * @returns A promise which fulfils when the task is triggered.
+ */
+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
+ * @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';
+//# sourceMappingURL=BackgroundTask.d.ts.map

package/build/BackgroundTask.d.ts.map

@@ -0,0 +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"}

package/build/BackgroundTask.js

@@ -0,0 +1,141 @@
+import { isRunningInExpoGo } from 'expo';
+import { Platform, UnavailabilityError } from 'expo-modules-core';
+import * as TaskManager from 'expo-task-manager';
+import { BackgroundTaskStatus } from './BackgroundTask.types';
+import ExpoBackgroundTaskModule from './ExpoBackgroundTaskModule';
+// Flag to warn about running on Apple simulator
+let warnAboutRunningOniOSSimulator = false;
+let warnedAboutExpoGo = false;
+function _validate(taskName) {
+    if (isRunningInExpoGo()) {
+        if (!warnedAboutExpoGo) {
+            const message = '`Background Task` functionality is not available in Expo Go:\n' +
+                'You can use this API and any others in a development build. Learn more: https://expo.fyi/dev-client.';
+            console.warn(message);
+            warnedAboutExpoGo = true;
+        }
+    }
+    if (!taskName || typeof taskName !== 'string') {
+        throw new TypeError('`taskName` must be a non-empty string.');
+    }
+}
+// @needsAudit
+/**
+ * Returns the status for the Background Task API. On web, it always returns `BackgroundTaskStatus.Restricted`,
+ * while on native platforms it returns `BackgroundTaskStatus.Available`.
+ *
+ * @returns A BackgroundTaskStatus enum value or `null` if not available.
+ */
+export const getStatusAsync = async () => {
+    if (!ExpoBackgroundTaskModule.getStatusAsync) {
+        throw new UnavailabilityError('BackgroundTask', 'getStatusAsync');
+    }
+    return isRunningInExpoGo()
+        ? BackgroundTaskStatus.Restricted
+        : ExpoBackgroundTaskModule.getStatusAsync();
+};
+// @needsAudit
+/**
+ * Registers a background task with the given name. Registered tasks are saved in persistent storage and restored once the app is initialized.
+ * @param taskName Name of the task to register. The task needs to be defined first - see [`TaskManager.defineTask`](task-manager/#taskmanagerdefinetasktaskname-taskexecutor)
+ * for more details.
+ * @param options An object containing the background task options.
+ *
+ * @example
+ * ```ts
+ * import * as TaskManager from 'expo-task-manager';
+ *
+ * // Register the task outside of the component
+ * TaskManager.defineTask(BACKGROUND_TASK_IDENTIFIER, () => {
+ *   try {
+ *     await AsyncStorage.setItem(LAST_TASK_DATE_KEY, Date.now().toString());
+ *   } catch (error) {
+ *     console.error('Failed to save the last fetch date', error);
+ *     return BackgroundTaskResult.Failed;
+ *   }
+ *   return BackgroundTaskResult.Success;
+ * });
+ * ```
+ *
+ * You can now use the `registerTaskAsync` function to register the task:
+ *
+ * ```ts
+ * BackgroundTask.registerTaskAsync(BACKGROUND_TASK_IDENTIFIER, {});
+ * ```
+ */
+export async function registerTaskAsync(taskName, options = {}) {
+    if (!ExpoBackgroundTaskModule.registerTaskAsync) {
+        throw new UnavailabilityError('BackgroundTask', 'registerTaskAsync');
+    }
+    if (!TaskManager.isTaskDefined(taskName)) {
+        throw new Error(`Task '${taskName}' is not defined. You must define a task using TaskManager.defineTask before registering.`);
+    }
+    if ((await ExpoBackgroundTaskModule.getStatusAsync()) === BackgroundTaskStatus.Restricted) {
+        if (!warnAboutRunningOniOSSimulator) {
+            const message = Platform.OS === 'ios'
+                ? `Background tasks are not supported on iOS simulators. Skipped registering task: ${taskName}.`
+                : `Background tasks are not available in the current environment. Skipped registering task: ${taskName}.`;
+            console.warn(message);
+            warnAboutRunningOniOSSimulator = true;
+        }
+        return;
+    }
+    _validate(taskName);
+    if (await TaskManager.isTaskRegisteredAsync(taskName)) {
+        return;
+    }
+    await ExpoBackgroundTaskModule.registerTaskAsync(taskName, options);
+}
+// @needsAudit
+/**
+ * Unregisters a background task, so the application will no longer be executing this task.
+ * @param taskName Name of the task to unregister.
+ * @return A promise which fulfils when the task is fully unregistered.
+ */
+export async function unregisterTaskAsync(taskName) {
+    if (!ExpoBackgroundTaskModule.unregisterTaskAsync) {
+        throw new UnavailabilityError('BackgroundTask', 'unregisterTaskAsync');
+    }
+    _validate(taskName);
+    if (!(await TaskManager.isTaskRegisteredAsync(taskName))) {
+        return;
+    }
+    await ExpoBackgroundTaskModule.unregisterTaskAsync(taskName);
+}
+// @needsAudit
+/**
+ * When in debug mode this function will trigger running the background tasks.
+ * This function will only work for apps built in debug mode.
+ * This method is only available in development mode. It will not work in production builds.
+ * @returns A promise which fulfils when the task is triggered.
+ */
+export async function triggerTaskWorkerForTestingAsync() {
+    if (__DEV__) {
+        if (!ExpoBackgroundTaskModule.triggerTaskWorkerForTestingAsync) {
+            throw new UnavailabilityError('BackgroundTask', 'triggerTaskWorkerForTestingAsync');
+        }
+        console.log('Calling triggerTaskWorkerForTestingAsync');
+        return await ExpoBackgroundTaskModule.triggerTaskWorkerForTestingAsync();
+    }
+    else {
+        return Promise.resolve(false);
+    }
+}
+// @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
+ * @return An object with a `remove` method to unsubscribe the listener.
+ */
+export function addExpirationListener(listener) {
+    if (!ExpoBackgroundTaskModule.addListener) {
+        throw new UnavailabilityError('BackgroundTask', 'addListener');
+    }
+    return ExpoBackgroundTaskModule.addListener('onTasksExpired', listener);
+}
+// Export types
+export { BackgroundTaskStatus, BackgroundTaskResult, } from './BackgroundTask.types';
+//# sourceMappingURL=BackgroundTask.js.map

package/build/BackgroundTask.js.map

@@ -0,0 +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"]}

package/build/BackgroundTask.types.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Availability status for background tasks
+ */
+export declare enum BackgroundTaskStatus {
+    /**
+     * Background tasks are unavailable.
+     */
+    Restricted = 1,
+    /**
+     * Background tasks are available for the app.
+     */
+    Available = 2
+}
+/**
+ * Return value for background tasks.
+ */
+export declare enum BackgroundTaskResult {
+    /**
+     * The task finished successfully.
+     */
+    Success = 1,
+    /**
+     * The task failed.
+     */
+    Failed = 2
+}
+/**
+ * Options for registering a background task
+ */
+export type BackgroundTaskOptions = {
+    /**
+     * Inexact interval in minutes between subsequent repeats of the background tasks. The final
+     * interval may differ from the specified one to minimize wakeups and battery usage.
+     * - Defaults to once every 12 hours (The minimum interval is 15 minutes)
+     * - The system controls the background task execution interval and treats the
+     * specified value as a minimum delay. Tasks won't run exactly on schedule. On iOS, short
+     * intervals are often ignored—the system typically runs background tasks during
+     * specific windows, such as overnight.
+     *
+     */
+    minimumInterval?: number;
+    /**
+     * Whether the task requires network connectivity.
+     *
+     * @default true
+     * @platform ios, android
+     */
+    requiresNetworkConnectivity?: boolean;
+    /**
+     * iOS-only: Which BGTask type to use.
+     * - `'refresh'` (default): BGAppRefreshTaskRequest — aggressive scheduling (~15-30 min),
+     *   ~30 s execution limit. Suitable for periodic syncs and content updates.
+     * - `'processing'`: BGProcessingTaskRequest — iOS defers at its own discretion
+     *   (hours/days), but allows several minutes of runtime. Suitable for heavy work
+     *   (ML training, DB migration). Supports `requiresNetworkConnectivity` and
+     *   `requiresExternalPower`.
+     *
+     * @default 'refresh'
+     * @platform ios
+     */
+    iosTaskType?: 'refresh' | 'processing';
+    /**
+     * iOS-only: Whether the task requires external power.
+     * Only relevant when `iosTaskType: 'processing'`.
+     *
+     * @default false
+     * @platform ios
+     */
+    requiresExternalPower?: boolean;
+};
+//# sourceMappingURL=BackgroundTask.types.d.ts.map

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

@@ -0,0 +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"}

package/build/BackgroundTask.types.js

@@ -0,0 +1,31 @@
+// @needsAudit
+/**
+ * Availability status for background tasks
+ */
+export var BackgroundTaskStatus;
+(function (BackgroundTaskStatus) {
+    /**
+     * Background tasks are unavailable.
+     */
+    BackgroundTaskStatus[BackgroundTaskStatus["Restricted"] = 1] = "Restricted";
+    /**
+     * Background tasks are available for the app.
+     */
+    BackgroundTaskStatus[BackgroundTaskStatus["Available"] = 2] = "Available";
+})(BackgroundTaskStatus || (BackgroundTaskStatus = {}));
+// @needsAudit
+/**
+ * Return value for background tasks.
+ */
+export var BackgroundTaskResult;
+(function (BackgroundTaskResult) {
+    /**
+     * The task finished successfully.
+     */
+    BackgroundTaskResult[BackgroundTaskResult["Success"] = 1] = "Success";
+    /**
+     * The task failed.
+     */
+    BackgroundTaskResult[BackgroundTaskResult["Failed"] = 2] = "Failed";
+})(BackgroundTaskResult || (BackgroundTaskResult = {}));
+//# sourceMappingURL=BackgroundTask.types.js.map

package/build/BackgroundTask.types.js.map

@@ -0,0 +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"]}