@zykeco/expo-background-task 1.0.0

package/plugin/build/withBackgroundTask.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_plugins_1 = require("expo/config-plugins");
+const pkg = require('expo-background-task/package.json');
+const withBackgroundTask = (config) => {
+    return (0, config_plugins_1.withInfoPlist)(config, (config) => {
+        // Enable background mode processing
+        if (!Array.isArray(config.modResults.UIBackgroundModes)) {
+            config.modResults.UIBackgroundModes = [];
+        }
+        if (!config.modResults.UIBackgroundModes.includes('processing')) {
+            config.modResults.UIBackgroundModes.push('processing');
+        }
+        if (!config.modResults.UIBackgroundModes.includes('fetch')) {
+            config.modResults.UIBackgroundModes.push('fetch');
+        }
+        // With the new background task module we need to install the identifier in the Info.plist:
+        // BGTaskSchedulerPermittedIdentifiers should be an array of strings - we need to
+        // define our own identifier: com.expo.modules.backgroundtask.taskidentifer
+        if (!Array.isArray(config.modResults.BGTaskSchedulerPermittedIdentifiers)) {
+            config.modResults.BGTaskSchedulerPermittedIdentifiers = [];
+        }
+        if (!config.modResults.BGTaskSchedulerPermittedIdentifiers.includes('com.expo.modules.backgroundtask.processing')) {
+            config.modResults.BGTaskSchedulerPermittedIdentifiers = [
+                ...(config.modResults.BGTaskSchedulerPermittedIdentifiers || []),
+                'com.expo.modules.backgroundtask.processing',
+            ];
+        }
+        return config;
+    });
+};
+exports.default = (0, config_plugins_1.createRunOncePlugin)(withBackgroundTask, pkg.name, pkg.version);

package/plugin/src/withBackgroundTask.ts

@@ -0,0 +1,39 @@
+import { ConfigPlugin, createRunOncePlugin, withInfoPlist } from 'expo/config-plugins';
+
+const pkg = require('expo-background-task/package.json');
+
+const withBackgroundTask: ConfigPlugin = (config) => {
+  return withInfoPlist(config, (config) => {
+    // Enable background mode processing
+    if (!Array.isArray(config.modResults.UIBackgroundModes)) {
+      config.modResults.UIBackgroundModes = [];
+    }
+    if (!config.modResults.UIBackgroundModes.includes('processing')) {
+      config.modResults.UIBackgroundModes.push('processing');
+    }
+    if (!config.modResults.UIBackgroundModes.includes('fetch')) {
+      config.modResults.UIBackgroundModes.push('fetch');
+    }
+
+    // With the new background task module we need to install the identifier in the Info.plist:
+    // BGTaskSchedulerPermittedIdentifiers should be an array of strings - we need to
+    // define our own identifier: com.expo.modules.backgroundtask.taskidentifer
+    if (!Array.isArray(config.modResults.BGTaskSchedulerPermittedIdentifiers)) {
+      config.modResults.BGTaskSchedulerPermittedIdentifiers = [];
+    }
+    if (
+      !(config.modResults.BGTaskSchedulerPermittedIdentifiers as string[]).includes(
+        'com.expo.modules.backgroundtask.processing'
+      )
+    ) {
+      config.modResults.BGTaskSchedulerPermittedIdentifiers = [
+        ...((config.modResults.BGTaskSchedulerPermittedIdentifiers as string[]) || []),
+        'com.expo.modules.backgroundtask.processing',
+      ];
+    }
+
+    return config;
+  });
+};
+
+export default createRunOncePlugin(withBackgroundTask, pkg.name, pkg.version);

package/plugin/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "expo-module-scripts/tsconfig.plugin",
+  "compilerOptions": {
+    "outDir": "build",
+    "rootDir": "src"
+  },
+  "include": ["./src"],
+  "exclude": ["**/__mocks__/*", "**/__tests__/*"]
+}

package/plugin/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/withbackgroundtask.ts"],"version":"5.9.3"}

package/src/BackgroundTask.ts

@@ -0,0 +1,162 @@
+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 ExpoBackgroundTaskModule from './ExpoBackgroundTaskModule';
+
+// Flag to warn about running on Apple simulator
+let warnAboutRunningOniOSSimulator = false;
+
+let warnedAboutExpoGo = false;
+
+function _validate(taskName: unknown) {
+  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 (): Promise<BackgroundTaskStatus> => {
+  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: string,
+  options: BackgroundTaskOptions = {}
+): Promise<void> {
+  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: string): Promise<void> {
+  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(): Promise<boolean> {
+  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: () => void): { remove: () => void } {
+  if (!ExpoBackgroundTaskModule.addListener) {
+    throw new UnavailabilityError('BackgroundTask', 'addListener');
+  }
+  return ExpoBackgroundTaskModule.addListener('onTasksExpired', listener);
+}
+
+// Export types
+export {
+  BackgroundTaskStatus,
+  BackgroundTaskResult,
+  BackgroundTaskOptions,
+} from './BackgroundTask.types';

package/src/BackgroundTask.types.ts

@@ -0,0 +1,75 @@
+// @needsAudit
+/**
+ * Availability status for background tasks
+ */
+export enum BackgroundTaskStatus {
+  /**
+   * Background tasks are unavailable.
+   */
+  Restricted = 1,
+  /**
+   * Background tasks are available for the app.
+   */
+  Available = 2,
+}
+
+// @needsAudit
+/**
+ * Return value for background tasks.
+ */
+export enum BackgroundTaskResult {
+  /**
+   * The task finished successfully.
+   */
+  Success = 1,
+  /**
+   * The task failed.
+   */
+  Failed = 2,
+}
+
+// @needsAudit
+/**
+ * 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;
+};

package/src/ExpoBackgroundTaskModule.ts

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

package/src/ExpoBackgroundTaskModule.web.ts

@@ -0,0 +1,7 @@
+import { BackgroundTaskStatus } from './BackgroundTask.types';
+
+export default {
+  async getStatusAsync(): Promise<BackgroundTaskStatus> {
+    return BackgroundTaskStatus.Restricted;
+  },
+};

package/tsconfig.json

@@ -0,0 +1,9 @@
+// @generated by expo-module-scripts
+{
+  "extends": "expo-module-scripts/tsconfig.base",
+  "compilerOptions": {
+    "outDir": "./build"
+  },
+  "include": ["./src"],
+  "exclude": ["**/__mocks__/*", "**/__tests__/*", "**/__rsc_tests__/*"]
+}