expo-background-task 0.0.0

package/plugin/src/withBackgroundTask.ts

@@ -0,0 +1,36 @@
+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');
+    }
+
+    // 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/src/BackgroundTask.ts

@@ -0,0 +1,105 @@
+import { UnavailabilityError } from 'expo-modules-core';
+import * as TaskManager from 'expo-task-manager';
+
+import { BackgroundTaskOptions, BackgroundTaskStatus } from './BackgroundTask.types';
+import ExpoBackgroundTaskModule from './ExpoBackgroundTaskModule';
+
+// @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 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.`
+    );
+  }
+  console.log('Calling ExpoBackgroundTaskModule.registerTaskAsync', { taskName, options });
+  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');
+  }
+  console.log('Calling ExpoBackgroundTaskModule.unregisterTaskAsync', taskName);
+  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.
+ * @todo(chrfalch): When we have a usable devtools plugin we can enable this function.
+ * @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);
+//   }
+// }
+
+// Export types
+export {
+  BackgroundTaskStatus,
+  BackgroundTaskResult,
+  BackgroundTaskOptions,
+} from './BackgroundTask.types';

package/src/BackgroundTask.types.ts

@@ -0,0 +1,45 @@
+// @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)
+   * - On iOS, the system determines the interval for background task execution,
+   *  but will wait until the specified minimum interval has elapsed before starting a task.
+   * @platform android
+   */
+  minimumInterval?: number;
+};

package/src/ExpoBackgroundTaskModule.ts

@@ -0,0 +1,12 @@
+import { requireNativeModule, type NativeModule } from 'expo';
+
+import { BackgroundTaskOptions, BackgroundTaskStatus } from './BackgroundTask.types';
+
+declare class ExpoBackgroundTaskModule extends NativeModule {
+  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__/*"]
+}