@symbiote-native/background-task 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A. Prokopenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,170 @@
+# @symbiote-native/background-task
+
+A wrapper package for [SymbioteNative](../../README.md) that makes
+[`expo-background-task`](https://github.com/expo/expo/tree/main/packages/expo-background-task)
+usable from **every** adapter — React, Vue, Svelte, Solid, and Angular. Like
+[`@symbiote-native/task-manager`](../task-manager), every export is a plain function or a
+one-time module-load side effect, so there is no hook/composable/service to wrap: the React,
+Vue, Svelte, Solid, and Angular entry points are plain re-exports of the same `core`.
+
+This is the modern replacement for [`@symbiote-native/background-fetch`](../background-fetch),
+built on `BGTaskScheduler` (iOS) / `WorkManager` (Android) instead of a periodic-fetch alarm.
+Like its sibling, this package registers a task with native so it fires **in the background on
+the OS's own schedule** — it does not define what the task does. Define the task first via
+[`@symbiote-native/task-manager`](../task-manager)'s `defineTask`, then register it for periodic
+execution via this package's `registerTaskAsync`.
+
+## Install
+
+**New app:**
+
+```bash
+npx @symbiote-native/cli new my-app --background-task
+```
+
+**Existing SymbioteNative app:**
+
+```bash
+npx @symbiote-native/cli add --background-task
+```
+
+Either way: installs `@symbiote-native/background-task` + `@symbiote-native/task-manager` and
+wires the native autolinking automatically — see [`@symbiote-native/cli`](../cli).
+
+<details>
+<summary>Manual install (no CLI — installing and wiring native autolinking by hand)</summary>
+
+```bash
+npm install @symbiote-native/background-task @symbiote-native/task-manager
+```
+
+`expo-background-task` and `expo-modules-core` come along as regular dependencies, pinned to
+exact versions — never install them yourself, and never add the `expo` meta-package to your
+project.
+
+## Required one-time step: native autolinking wiring
+
+Same one-time step as every other `expo-modules-core` package this project ships — see
+[`@symbiote-native/local-auth`'s README](../local-auth/README.md#required-one-time-step-native-autolinking-wiring)
+and the `symbiote-expo-native-module` project skill.
+
+iOS also needs `UIBackgroundModes: processing` and `BGTaskSchedulerPermittedIdentifiers` (the
+fixed identifier baked into `expo-background-task`'s own native Swift source,
+`BackgroundTaskConstants.swift`) in the app's Info.plist — `native-link.json`'s `ios.infoPlistArrayKeys`
+covers this ARRAY-valued case (see `@symbiote-native/expo-modules-link`), so it's wired
+automatically by the same postinstall step, no manual edit needed. Android needs no manual step
+either; its `AndroidManifest.xml` declares no extra permission.
+
+**The iOS Simulator has no `BGTaskScheduler` support at all** (Apple's own limitation — physical
+device only), so `BackgroundTaskStatus` reads `Restricted` there and `registerTaskAsync` is a
+no-op regardless of Info.plist. Test registration on a real device.
+
+</details>
+
+## Shape
+
+```
+src/core/     getStatusAsync / registerTaskAsync / unregisterTaskAsync /
+              triggerTaskWorkerForTestingAsync / addExpirationListener, plus
+              BackgroundTaskStatus / BackgroundTaskResult / IBackgroundTaskOptions.
+              native-module.ts resolves the native module via expo-modules-core's
+              requireNativeModule.
+src/angular/  @symbiote-native/background-task/angular — export * from '../core'
+```
+
+`./react`, `./vue`, `./svelte`, and `./solid` are `exports`-map aliases straight onto
+`src/core/`. `./angular` stays a physical file/subpath since Angular ships through a separate
+`ngc`/AOT build (`build-ngc/`).
+
+## Use it
+
+```ts
+// index.ts, alongside AppRegistry.registerComponent — identical on every adapter
+import { defineTask } from '@symbiote-native/task-manager';
+import {
+  registerTaskAsync,
+  BackgroundTaskResult,
+} from '@symbiote-native/background-task';
+
+const SYNC_TASK = 'background-sync';
+
+defineTask(SYNC_TASK, async () => {
+  try {
+    await runSync();
+    return BackgroundTaskResult.Success;
+  } catch (error) {
+    console.error('background-sync failed:', error);
+    return BackgroundTaskResult.Failed;
+  }
+});
+
+// Somewhere after the task is defined (a settings screen, app bootstrap, …):
+await registerTaskAsync(SYNC_TASK, { minimumInterval: 15 });
+```
+
+`@symbiote-native/task-manager` is the primitive both this package and
+[`@symbiote-native/background-fetch`](../background-fetch) build on — `defineTask` lives there,
+`registerTaskAsync`/`unregisterTaskAsync` live here. `defineTask` must run at the top of the JS
+bundle, outside any component, for the same reason documented in task-manager's own README: the
+app can be launched headlessly to run a background task, with no views mounted.
+
+```ts
+import {
+  getStatusAsync,
+  unregisterTaskAsync,
+  addExpirationListener,
+} from '@symbiote-native/background-task';
+
+const status = await getStatusAsync();
+
+// iOS only — the system can interrupt a running background task before it finishes.
+const subscription = addExpirationListener(() => {
+  console.warn('background-sync was interrupted before it finished');
+});
+subscription.remove();
+
+await unregisterTaskAsync(SYNC_TASK); // stop receiving executions of it
+```
+
+Identical import surface on every adapter — `@symbiote-native/background-task/react`,
+`/vue`, `/svelte`, `/solid`, `/angular` all re-export the same functions.
+
+## API
+
+```ts
+getStatusAsync(): Promise<BackgroundTaskStatus>
+registerTaskAsync(taskName: string, options?: IBackgroundTaskOptions): Promise<void>
+unregisterTaskAsync(taskName: string): Promise<void>
+triggerTaskWorkerForTestingAsync(): Promise<boolean>
+addExpirationListener(listener: () => void): { remove: () => void }
+```
+
+Plus `BackgroundTaskStatus`, `BackgroundTaskResult`, `IBackgroundTaskOptions` — ported from
+upstream's `BackgroundTask.types.ts`, the options type renamed with this repo's `I`-prefix
+convention for exported types (`ts-js-best-practices`).
+
+## Notes
+
+- **`registerTaskAsync` requires the task to already be defined.** It throws if
+  `@symbiote-native/task-manager`'s `isTaskDefined(taskName)` is `false` — call `defineTask`
+  first.
+- **`registerTaskAsync` is a no-op, twice over.** It skips silently (with a one-time console
+  warning) when the environment reports `BackgroundTaskStatus.Restricted` — the iOS Simulator has
+  no `BGTaskScheduler` support at all — and it skips again, quietly, when the task is already
+  registered (checked via `@symbiote-native/task-manager`'s `isTaskRegisteredAsync`).
+- **`triggerTaskWorkerForTestingAsync` only runs in a dev build.** It always resolves `false` in
+  production, matching upstream's own `__DEV__` gate — read here through a narrow local type
+  rather than the bare RN global, since this package's own type graph never imports
+  `react-native`.
+- **Expo Go is out of scope.** Upstream also warns when running inside Expo Go
+  (`isRunningInExpoGo`, imported from the `expo` meta-package) and reports
+  `BackgroundTaskStatus.Restricted` there. This project never installs `expo` — every app here is
+  a bare/dev-client build, never Expo Go — so that branch has no equivalent here and is
+  intentionally not ported.
+
+## Test it
+
+No Fabric/Descriptor angle at all — every function here is a pure async-function surface plus one
+event subscription, never a view or per-instance state. Tests inject a fake native-module object
+in place of the real `requireNativeModule` resolution and a fake `@symbiote-native/task-manager`
+module (`src/core/background-task.test.ts`) — no `installFabric()`, no ViewConfig.

package/build/angular/index.d.ts

@@ -0,0 +1 @@
+export * from '../core';

package/build/angular/index.js

@@ -0,0 +1,4 @@
+// @symbiote-native/background-task/angular: the Angular entry over the framework-agnostic core.
+// Same reasoning as the React/Vue entries — no per-instance state to wrap in a service, so this
+// is a plain re-export.
+export * from '../core/index.js';

package/build/core/background-task.d.ts

@@ -0,0 +1,25 @@
+import { BackgroundTaskStatus } from './types';
+import type { IBackgroundTaskOptions } from './types';
+/** Gets the current status for the Background Task API. */
+export declare function getStatusAsync(): Promise<BackgroundTaskStatus>;
+/**
+ * Registers a background task with the given name. The task must already be defined via
+ * `@symbiote-native/task-manager`'s `defineTask` — registration is driven by this package, but
+ * execution dispatch is task-manager's job.
+ */
+export declare function registerTaskAsync(taskName: string, options?: IBackgroundTaskOptions): Promise<void>;
+/** Unregisters a background task, so the app stops receiving executions of it. */
+export declare function unregisterTaskAsync(taskName: string): Promise<void>;
+/**
+ * Debug builds only: triggers the OS to run the registered background task immediately, instead
+ * of waiting for its real schedule. Always resolves `false` in a production build.
+ */
+export declare function triggerTaskWorkerForTestingAsync(): Promise<boolean>;
+/**
+ * Subscribes to the `onTasksExpired` event iOS fires when the system interrupts a running
+ * background task before it finishes — use it to clean up resources or save state.
+ * @platform ios
+ */
+export declare function addExpirationListener(listener: () => void): {
+    remove: () => void;
+};

package/build/core/background-task.js

@@ -0,0 +1,85 @@
+import { Platform, UnavailabilityError } from 'expo-modules-core';
+import { isTaskDefined, isTaskRegisteredAsync, } from '@symbiote-native/task-manager';
+import { expoBackgroundTask } from './native-module.js';
+import { BackgroundTaskStatus } from './types.js';
+const NATIVE_MODULE_NAME = 'BackgroundTask';
+let didWarnUnsupportedEnvironment = false;
+function assertValidTaskName(taskName) {
+    if (!taskName || typeof taskName !== 'string') {
+        throw new TypeError('`taskName` must be a non-empty string.');
+    }
+}
+function isDevBuild() {
+    return Boolean(globalThis.__DEV__);
+}
+// Upstream also warns when running inside Expo Go (`isRunningInExpoGo`, imported from the `expo`
+// meta-package). This project never installs `expo` — every app here is a bare/dev-client build,
+// never Expo Go — so that check, and the `BackgroundTaskStatus.Restricted` branch it drives in
+// upstream's own `getStatusAsync`, has no equivalent and is intentionally not ported.
+/** Gets the current status for the Background Task API. */
+export async function getStatusAsync() {
+    if (!expoBackgroundTask.getStatusAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getStatusAsync');
+    }
+    return expoBackgroundTask.getStatusAsync();
+}
+/**
+ * Registers a background task with the given name. The task must already be defined via
+ * `@symbiote-native/task-manager`'s `defineTask` — registration is driven by this package, but
+ * execution dispatch is task-manager's job.
+ */
+export async function registerTaskAsync(taskName, options = {}) {
+    if (!expoBackgroundTask.registerTaskAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'registerTaskAsync');
+    }
+    if (!isTaskDefined(taskName)) {
+        throw new Error(`Task '${taskName}' is not defined. You must define a task using defineTask (from @symbiote-native/task-manager) before registering.`);
+    }
+    if ((await getStatusAsync()) === BackgroundTaskStatus.Restricted) {
+        if (!didWarnUnsupportedEnvironment) {
+            didWarnUnsupportedEnvironment = true;
+            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);
+        }
+        return;
+    }
+    assertValidTaskName(taskName);
+    if (await isTaskRegisteredAsync(taskName))
+        return;
+    await expoBackgroundTask.registerTaskAsync(taskName, options);
+}
+/** Unregisters a background task, so the app stops receiving executions of it. */
+export async function unregisterTaskAsync(taskName) {
+    if (!expoBackgroundTask.unregisterTaskAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'unregisterTaskAsync');
+    }
+    assertValidTaskName(taskName);
+    if (!(await isTaskRegisteredAsync(taskName)))
+        return;
+    await expoBackgroundTask.unregisterTaskAsync(taskName);
+}
+/**
+ * Debug builds only: triggers the OS to run the registered background task immediately, instead
+ * of waiting for its real schedule. Always resolves `false` in a production build.
+ */
+export async function triggerTaskWorkerForTestingAsync() {
+    if (!isDevBuild())
+        return false;
+    if (!expoBackgroundTask.triggerTaskWorkerForTestingAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'triggerTaskWorkerForTestingAsync');
+    }
+    return expoBackgroundTask.triggerTaskWorkerForTestingAsync();
+}
+/**
+ * Subscribes to the `onTasksExpired` event iOS fires when the system interrupts a running
+ * background task before it finishes — use it to clean up resources or save state.
+ * @platform ios
+ */
+export function addExpirationListener(listener) {
+    if (!expoBackgroundTask.addListener) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'addListener');
+    }
+    return expoBackgroundTask.addListener('onTasksExpired', listener);
+}

package/build/core/index.d.ts

@@ -0,0 +1,3 @@
+export { getStatusAsync, registerTaskAsync, unregisterTaskAsync, triggerTaskWorkerForTestingAsync, addExpirationListener, } from './background-task';
+export { BackgroundTaskStatus, BackgroundTaskResult } from './types';
+export type { IBackgroundTaskOptions } from './types';

package/build/core/index.js

@@ -0,0 +1,2 @@
+export { getStatusAsync, registerTaskAsync, unregisterTaskAsync, triggerTaskWorkerForTestingAsync, addExpirationListener, } from './background-task.js';
+export { BackgroundTaskStatus, BackgroundTaskResult } from './types.js';

package/build/core/native-module.d.ts

@@ -0,0 +1,10 @@
+import { type EventSubscription } from 'expo-modules-core';
+export type INativeBackgroundTaskModule = {
+    getStatusAsync?(): Promise<number>;
+    registerTaskAsync?(taskName: string, options: Record<string, unknown>): Promise<void>;
+    unregisterTaskAsync?(taskName: string): Promise<void>;
+    /** Debug-build-only: forces the OS to run the registered background task immediately. */
+    triggerTaskWorkerForTestingAsync?(): Promise<boolean>;
+    addListener?(eventName: string, listener: () => void): EventSubscription;
+};
+export declare const expoBackgroundTask: INativeBackgroundTaskModule;

package/build/core/native-module.js

@@ -0,0 +1,3 @@
+import { requireNativeModule } from 'expo-modules-core';
+const EXPO_BACKGROUND_TASK_MODULE_NAME = 'ExpoBackgroundTask';
+export const expoBackgroundTask = requireNativeModule(EXPO_BACKGROUND_TASK_MODULE_NAME);

package/build/core/types.d.ts

@@ -0,0 +1,26 @@
+/** Availability status for the Background Task API. */
+export declare enum BackgroundTaskStatus {
+    /** Background tasks are unavailable — e.g. running on an iOS Simulator. */
+    Restricted = 1,
+    /** Background tasks are available for the app. */
+    Available = 2
+}
+/** Return value a background-task executor should resolve with. */
+export declare enum BackgroundTaskResult {
+    /** The task finished successfully. */
+    Success = 1,
+    /** The task failed. */
+    Failed = 2
+}
+/** Options accepted by {@link registerTaskAsync}. */
+export type IBackgroundTaskOptions = {
+    /**
+     * Inexact interval in minutes between subsequent repeats of the background task. 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 OS controls the real execution interval and treats this as a minimum delay only — on
+     *   iOS a short interval is often ignored, since the system typically runs background tasks
+     *   during specific windows (e.g. overnight).
+     */
+    minimumInterval?: number;
+};

package/build/core/types.js

@@ -0,0 +1,16 @@
+/** Availability status for the Background Task API. */
+export var BackgroundTaskStatus;
+(function (BackgroundTaskStatus) {
+    /** Background tasks are unavailable — e.g. running on an iOS Simulator. */
+    BackgroundTaskStatus[BackgroundTaskStatus["Restricted"] = 1] = "Restricted";
+    /** Background tasks are available for the app. */
+    BackgroundTaskStatus[BackgroundTaskStatus["Available"] = 2] = "Available";
+})(BackgroundTaskStatus || (BackgroundTaskStatus = {}));
+/** Return value a background-task executor should resolve with. */
+export var BackgroundTaskResult;
+(function (BackgroundTaskResult) {
+    /** The task finished successfully. */
+    BackgroundTaskResult[BackgroundTaskResult["Success"] = 1] = "Success";
+    /** The task failed. */
+    BackgroundTaskResult[BackgroundTaskResult["Failed"] = 2] = "Failed";
+})(BackgroundTaskResult || (BackgroundTaskResult = {}));

package/build-ngc/angular/index.d.ts

@@ -0,0 +1 @@
+export * from '../core';

package/build-ngc/angular/index.js

@@ -0,0 +1,5 @@
+// @symbiote-native/background-task/angular: the Angular entry over the framework-agnostic core.
+// Same reasoning as the React/Vue entries — no per-instance state to wrap in a service, so this
+// is a plain re-export.
+export * from '../core';
+//# sourceMappingURL=index.js.map

package/build-ngc/angular/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/angular/index.ts"],"names":[],"mappings":"AAAA,gGAAgG;AAChG,gGAAgG;AAChG,wBAAwB;AACxB,cAAc,SAAS,CAAC"}

package/build-ngc/core/background-task.d.ts

@@ -0,0 +1,25 @@
+import { BackgroundTaskStatus } from './types';
+import type { IBackgroundTaskOptions } from './types';
+/** Gets the current status for the Background Task API. */
+export declare function getStatusAsync(): Promise<BackgroundTaskStatus>;
+/**
+ * Registers a background task with the given name. The task must already be defined via
+ * `@symbiote-native/task-manager`'s `defineTask` — registration is driven by this package, but
+ * execution dispatch is task-manager's job.
+ */
+export declare function registerTaskAsync(taskName: string, options?: IBackgroundTaskOptions): Promise<void>;
+/** Unregisters a background task, so the app stops receiving executions of it. */
+export declare function unregisterTaskAsync(taskName: string): Promise<void>;
+/**
+ * Debug builds only: triggers the OS to run the registered background task immediately, instead
+ * of waiting for its real schedule. Always resolves `false` in a production build.
+ */
+export declare function triggerTaskWorkerForTestingAsync(): Promise<boolean>;
+/**
+ * Subscribes to the `onTasksExpired` event iOS fires when the system interrupts a running
+ * background task before it finishes — use it to clean up resources or save state.
+ * @platform ios
+ */
+export declare function addExpirationListener(listener: () => void): {
+    remove: () => void;
+};

package/build-ngc/core/background-task.js

@@ -0,0 +1,86 @@
+import { Platform, UnavailabilityError } from 'expo-modules-core';
+import { isTaskDefined, isTaskRegisteredAsync, } from '@symbiote-native/task-manager';
+import { expoBackgroundTask } from './native-module';
+import { BackgroundTaskStatus } from './types';
+const NATIVE_MODULE_NAME = 'BackgroundTask';
+let didWarnUnsupportedEnvironment = false;
+function assertValidTaskName(taskName) {
+    if (!taskName || typeof taskName !== 'string') {
+        throw new TypeError('`taskName` must be a non-empty string.');
+    }
+}
+function isDevBuild() {
+    return Boolean(globalThis.__DEV__);
+}
+// Upstream also warns when running inside Expo Go (`isRunningInExpoGo`, imported from the `expo`
+// meta-package). This project never installs `expo` — every app here is a bare/dev-client build,
+// never Expo Go — so that check, and the `BackgroundTaskStatus.Restricted` branch it drives in
+// upstream's own `getStatusAsync`, has no equivalent and is intentionally not ported.
+/** Gets the current status for the Background Task API. */
+export async function getStatusAsync() {
+    if (!expoBackgroundTask.getStatusAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getStatusAsync');
+    }
+    return expoBackgroundTask.getStatusAsync();
+}
+/**
+ * Registers a background task with the given name. The task must already be defined via
+ * `@symbiote-native/task-manager`'s `defineTask` — registration is driven by this package, but
+ * execution dispatch is task-manager's job.
+ */
+export async function registerTaskAsync(taskName, options = {}) {
+    if (!expoBackgroundTask.registerTaskAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'registerTaskAsync');
+    }
+    if (!isTaskDefined(taskName)) {
+        throw new Error(`Task '${taskName}' is not defined. You must define a task using defineTask (from @symbiote-native/task-manager) before registering.`);
+    }
+    if ((await getStatusAsync()) === BackgroundTaskStatus.Restricted) {
+        if (!didWarnUnsupportedEnvironment) {
+            didWarnUnsupportedEnvironment = true;
+            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);
+        }
+        return;
+    }
+    assertValidTaskName(taskName);
+    if (await isTaskRegisteredAsync(taskName))
+        return;
+    await expoBackgroundTask.registerTaskAsync(taskName, options);
+}
+/** Unregisters a background task, so the app stops receiving executions of it. */
+export async function unregisterTaskAsync(taskName) {
+    if (!expoBackgroundTask.unregisterTaskAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'unregisterTaskAsync');
+    }
+    assertValidTaskName(taskName);
+    if (!(await isTaskRegisteredAsync(taskName)))
+        return;
+    await expoBackgroundTask.unregisterTaskAsync(taskName);
+}
+/**
+ * Debug builds only: triggers the OS to run the registered background task immediately, instead
+ * of waiting for its real schedule. Always resolves `false` in a production build.
+ */
+export async function triggerTaskWorkerForTestingAsync() {
+    if (!isDevBuild())
+        return false;
+    if (!expoBackgroundTask.triggerTaskWorkerForTestingAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'triggerTaskWorkerForTestingAsync');
+    }
+    return expoBackgroundTask.triggerTaskWorkerForTestingAsync();
+}
+/**
+ * Subscribes to the `onTasksExpired` event iOS fires when the system interrupts a running
+ * background task before it finishes — use it to clean up resources or save state.
+ * @platform ios
+ */
+export function addExpirationListener(listener) {
+    if (!expoBackgroundTask.addListener) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'addListener');
+    }
+    return expoBackgroundTask.addListener('onTasksExpired', listener);
+}
+//# sourceMappingURL=background-task.js.map

package/build-ngc/core/background-task.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-task.js","sourceRoot":"","sources":["../../src/core/background-task.ts"],"names":[],"mappings":"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"}

package/build-ngc/core/index.d.ts

@@ -0,0 +1,3 @@
+export { getStatusAsync, registerTaskAsync, unregisterTaskAsync, triggerTaskWorkerForTestingAsync, addExpirationListener, } from './background-task';
+export { BackgroundTaskStatus, BackgroundTaskResult } from './types';
+export type { IBackgroundTaskOptions } from './types';

package/build-ngc/core/index.js

@@ -0,0 +1,3 @@
+export { getStatusAsync, registerTaskAsync, unregisterTaskAsync, triggerTaskWorkerForTestingAsync, addExpirationListener, } from './background-task';
+export { BackgroundTaskStatus, BackgroundTaskResult } from './types';
+//# sourceMappingURL=index.js.map

package/build-ngc/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,gCAAgC,EAChC,qBAAqB,GACtB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC"}

package/build-ngc/core/native-module.d.ts

@@ -0,0 +1,10 @@
+import { type EventSubscription } from 'expo-modules-core';
+export type INativeBackgroundTaskModule = {
+    getStatusAsync?(): Promise<number>;
+    registerTaskAsync?(taskName: string, options: Record<string, unknown>): Promise<void>;
+    unregisterTaskAsync?(taskName: string): Promise<void>;
+    /** Debug-build-only: forces the OS to run the registered background task immediately. */
+    triggerTaskWorkerForTestingAsync?(): Promise<boolean>;
+    addListener?(eventName: string, listener: () => void): EventSubscription;
+};
+export declare const expoBackgroundTask: INativeBackgroundTaskModule;

package/build-ngc/core/native-module.js

@@ -0,0 +1,4 @@
+import { requireNativeModule } from 'expo-modules-core';
+const EXPO_BACKGROUND_TASK_MODULE_NAME = 'ExpoBackgroundTask';
+export const expoBackgroundTask = requireNativeModule(EXPO_BACKGROUND_TASK_MODULE_NAME);
+//# sourceMappingURL=native-module.js.map

package/build-ngc/core/native-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-module.js","sourceRoot":"","sources":["../../src/core/native-module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAA0B,MAAM,mBAAmB,CAAC;AAEhF,MAAM,gCAAgC,GAAG,oBAAoB,CAAC;AAqB9D,MAAM,CAAC,MAAM,kBAAkB,GAC7B,mBAAmB,CACjB,gCAAgC,CACjC,CAAC"}

package/build-ngc/core/types.d.ts

@@ -0,0 +1,26 @@
+/** Availability status for the Background Task API. */
+export declare enum BackgroundTaskStatus {
+    /** Background tasks are unavailable — e.g. running on an iOS Simulator. */
+    Restricted = 1,
+    /** Background tasks are available for the app. */
+    Available = 2
+}
+/** Return value a background-task executor should resolve with. */
+export declare enum BackgroundTaskResult {
+    /** The task finished successfully. */
+    Success = 1,
+    /** The task failed. */
+    Failed = 2
+}
+/** Options accepted by {@link registerTaskAsync}. */
+export type IBackgroundTaskOptions = {
+    /**
+     * Inexact interval in minutes between subsequent repeats of the background task. 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 OS controls the real execution interval and treats this as a minimum delay only — on
+     *   iOS a short interval is often ignored, since the system typically runs background tasks
+     *   during specific windows (e.g. overnight).
+     */
+    minimumInterval?: number;
+};

package/build-ngc/core/types.js

@@ -0,0 +1,17 @@
+/** Availability status for the Background Task API. */
+export var BackgroundTaskStatus;
+(function (BackgroundTaskStatus) {
+    /** Background tasks are unavailable — e.g. running on an iOS Simulator. */
+    BackgroundTaskStatus[BackgroundTaskStatus["Restricted"] = 1] = "Restricted";
+    /** Background tasks are available for the app. */
+    BackgroundTaskStatus[BackgroundTaskStatus["Available"] = 2] = "Available";
+})(BackgroundTaskStatus || (BackgroundTaskStatus = {}));
+/** Return value a background-task executor should resolve with. */
+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=types.js.map

package/build-ngc/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA,uDAAuD;AACvD,MAAM,CAAN,IAAY,oBAKX;AALD,WAAY,oBAAoB;IAC9B,2EAA2E;IAC3E,2EAAc,CAAA;IACd,kDAAkD;IAClD,yEAAa,CAAA;AACf,CAAC,EALW,oBAAoB,KAApB,oBAAoB,QAK/B;AAED,mEAAmE;AACnE,MAAM,CAAN,IAAY,oBAKX;AALD,WAAY,oBAAoB;IAC9B,sCAAsC;IACtC,qEAAW,CAAA;IACX,uBAAuB;IACvB,mEAAU,CAAA;AACZ,CAAC,EALW,oBAAoB,KAApB,oBAAoB,QAK/B"}

package/native-link.json

@@ -0,0 +1,20 @@
+{
+  "android": {
+    "gradleProjectName": "expo-background-task",
+    "modules": [
+      {
+        "importPath": "expo.modules.backgroundtask.BackgroundTaskModule",
+        "className": "BackgroundTaskModule",
+        "nativeName": "ExpoBackgroundTask"
+      }
+    ]
+  },
+  "ios": {
+    "infoPlistArrayKeys": {
+      "UIBackgroundModes": ["processing"],
+      "BGTaskSchedulerPermittedIdentifiers": [
+        "com.expo.modules.backgroundtask.processing"
+      ]
+    }
+  }
+}

package/package.json

@@ -0,0 +1,153 @@
+{
+  "name": "@symbiote-native/background-task",
+  "version": "0.1.0",
+  "description": "expo-background-task wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, Svelte, Solid, and Angular adapters. Periodic background work via BGTaskScheduler (iOS) / WorkManager (Android), registered through @symbiote-native/task-manager.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OneEyed1366/symbiote-native.git",
+    "directory": "packages/background-task"
+  },
+  "homepage": "https://github.com/OneEyed1366/symbiote-native/tree/master/packages/background-task#readme",
+  "bugs": {
+    "url": "https://github.com/OneEyed1366/symbiote-native/issues"
+  },
+  "author": "Andrey Prokopenko <psevdoproger@gmail.com>",
+  "keywords": [
+    "react-native",
+    "symbiote-native",
+    "expo-background-task",
+    "react",
+    "vue",
+    "svelte",
+    "solid",
+    "angular",
+    "background",
+    "task",
+    "workmanager",
+    "bgtaskscheduler"
+  ],
+  "type": "module",
+  "main": "./build/core/index.js",
+  "module": "./build/core/index.js",
+  "types": "./build/core/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./vue": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./react": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./svelte": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./solid": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./angular": {
+      "types": "./build-ngc/angular/index.d.ts",
+      "react-native": "./build-ngc/angular/index.js",
+      "default": "./src/angular/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "build",
+    "build-ngc",
+    "native-link.json",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/*.detox.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "expo-background-task": "57.0.15",
+    "expo-modules-core": "57.0.5",
+    "@symbiote-native/task-manager": "0.1.0"
+  },
+  "peerDependencies": {
+    "@angular/core": ">=20",
+    "@vue/runtime-core": "^3.5.13",
+    "react": ">=19.0.0",
+    "react-native": ">=0.86",
+    "solid-js": ">=1.9.0",
+    "svelte": ">=5.56.0",
+    "vue": ">=3.5.0",
+    "@symbiote-native/angular": "^3.1.0",
+    "@symbiote-native/engine": "^1.3.0",
+    "@symbiote-native/react": "^3.0.2",
+    "@symbiote-native/solid": "^3.0.2",
+    "@symbiote-native/svelte": "^3.0.2",
+    "@symbiote-native/vue": "^3.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@symbiote-native/angular": {
+      "optional": true
+    },
+    "@symbiote-native/react": {
+      "optional": true
+    },
+    "@symbiote-native/solid": {
+      "optional": true
+    },
+    "@symbiote-native/svelte": {
+      "optional": true
+    },
+    "@symbiote-native/vue": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "@vue/runtime-core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/compiler": "~22.0.8",
+    "@angular/compiler-cli": "~22.0.8",
+    "@angular/core": "~22.0.8",
+    "@types/node": "^26.0.0",
+    "@types/react": "^19.2.0",
+    "@vue/runtime-core": "^3.5.13",
+    "react": "19.2.3",
+    "solid-js": "^1.9.14",
+    "svelte": "^5.56.0",
+    "typescript": "~6.0.0",
+    "@symbiote-native/react": "3.0.2",
+    "@symbiote-native/angular": "3.1.0",
+    "@symbiote-native/engine": "1.3.0",
+    "@symbiote-native/svelte": "3.0.2",
+    "@symbiote-native/vue": "3.0.2",
+    "@symbiote-native/test-utils": "0.4.2",
+    "@symbiote-native/solid": "3.0.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --build",
+    "clean": "rm -rf build-ngc",
+    "ng:build": "pnpm run clean && ngc -p tsconfig.angular.json",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\""
+  }
+}

package/src/angular/index.ts

@@ -0,0 +1,4 @@
+// @symbiote-native/background-task/angular: the Angular entry over the framework-agnostic core.
+// Same reasoning as the React/Vue entries — no per-instance state to wrap in a service, so this
+// is a plain re-export.
+export * from '../core';

package/src/core/background-task.ts

@@ -0,0 +1,113 @@
+import { Platform, UnavailabilityError } from 'expo-modules-core';
+import {
+  isTaskDefined,
+  isTaskRegisteredAsync,
+} from '@symbiote-native/task-manager';
+import { expoBackgroundTask } from './native-module';
+import { BackgroundTaskStatus } from './types';
+import type { IBackgroundTaskOptions } from './types';
+
+const NATIVE_MODULE_NAME = 'BackgroundTask';
+
+let didWarnUnsupportedEnvironment = false;
+
+function assertValidTaskName(taskName: unknown): asserts taskName is string {
+  if (!taskName || typeof taskName !== 'string') {
+    throw new TypeError('`taskName` must be a non-empty string.');
+  }
+}
+
+// Metro/Hermes define a global `__DEV__` boolean; nothing in this package's own type graph does
+// (react-native is a peer, never imported here), so read it through a narrow local type instead
+// of a bare identifier `tsc` would reject as undeclared. Resolves to `false` — i.e. "production
+// build" — in any environment that never sets it (a plain Node/Vitest run included), matching
+// upstream's own use of the identical global.
+type IDevGlobal = { __DEV__?: boolean };
+function isDevBuild(): boolean {
+  return Boolean((globalThis as IDevGlobal).__DEV__);
+}
+
+// Upstream also warns when running inside Expo Go (`isRunningInExpoGo`, imported from the `expo`
+// meta-package). This project never installs `expo` — every app here is a bare/dev-client build,
+// never Expo Go — so that check, and the `BackgroundTaskStatus.Restricted` branch it drives in
+// upstream's own `getStatusAsync`, has no equivalent and is intentionally not ported.
+
+/** Gets the current status for the Background Task API. */
+export async function getStatusAsync(): Promise<BackgroundTaskStatus> {
+  if (!expoBackgroundTask.getStatusAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getStatusAsync');
+  }
+  return expoBackgroundTask.getStatusAsync() as Promise<BackgroundTaskStatus>;
+}
+
+/**
+ * Registers a background task with the given name. The task must already be defined via
+ * `@symbiote-native/task-manager`'s `defineTask` — registration is driven by this package, but
+ * execution dispatch is task-manager's job.
+ */
+export async function registerTaskAsync(
+  taskName: string,
+  options: IBackgroundTaskOptions = {},
+): Promise<void> {
+  if (!expoBackgroundTask.registerTaskAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'registerTaskAsync');
+  }
+  if (!isTaskDefined(taskName)) {
+    throw new Error(
+      `Task '${taskName}' is not defined. You must define a task using defineTask (from @symbiote-native/task-manager) before registering.`,
+    );
+  }
+  if ((await getStatusAsync()) === BackgroundTaskStatus.Restricted) {
+    if (!didWarnUnsupportedEnvironment) {
+      didWarnUnsupportedEnvironment = true;
+      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);
+    }
+    return;
+  }
+  assertValidTaskName(taskName);
+  if (await isTaskRegisteredAsync(taskName)) return;
+  await expoBackgroundTask.registerTaskAsync(taskName, options);
+}
+
+/** Unregisters a background task, so the app stops receiving executions of it. */
+export async function unregisterTaskAsync(taskName: string): Promise<void> {
+  if (!expoBackgroundTask.unregisterTaskAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'unregisterTaskAsync');
+  }
+  assertValidTaskName(taskName);
+  if (!(await isTaskRegisteredAsync(taskName))) return;
+  await expoBackgroundTask.unregisterTaskAsync(taskName);
+}
+
+/**
+ * Debug builds only: triggers the OS to run the registered background task immediately, instead
+ * of waiting for its real schedule. Always resolves `false` in a production build.
+ */
+export async function triggerTaskWorkerForTestingAsync(): Promise<boolean> {
+  if (!isDevBuild()) return false;
+  if (!expoBackgroundTask.triggerTaskWorkerForTestingAsync) {
+    throw new UnavailabilityError(
+      NATIVE_MODULE_NAME,
+      'triggerTaskWorkerForTestingAsync',
+    );
+  }
+  return expoBackgroundTask.triggerTaskWorkerForTestingAsync();
+}
+
+/**
+ * Subscribes to the `onTasksExpired` event iOS fires when the system interrupts a running
+ * background task before it finishes — use it to clean up resources or save state.
+ * @platform ios
+ */
+export function addExpirationListener(listener: () => void): {
+  remove: () => void;
+} {
+  if (!expoBackgroundTask.addListener) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'addListener');
+  }
+  return expoBackgroundTask.addListener('onTasksExpired', listener);
+}

package/src/core/index.ts

@@ -0,0 +1,9 @@
+export {
+  getStatusAsync,
+  registerTaskAsync,
+  unregisterTaskAsync,
+  triggerTaskWorkerForTestingAsync,
+  addExpirationListener,
+} from './background-task';
+export { BackgroundTaskStatus, BackgroundTaskResult } from './types';
+export type { IBackgroundTaskOptions } from './types';

package/src/core/native-module.ts

@@ -0,0 +1,27 @@
+import { requireNativeModule, type EventSubscription } from 'expo-modules-core';
+
+const EXPO_BACKGROUND_TASK_MODULE_NAME = 'ExpoBackgroundTask';
+
+// Every method is optional — each call site checks for its presence before calling through and
+// throws an UnavailabilityError itself, matching upstream's own per-platform capability checks
+// (same pattern as packages/task-manager/src/core/native-module.ts's INativeTaskManagerModule).
+// Upstream types this module as a `NativeModule<Events>` subclass (imported from the `expo`
+// meta-package, which this project never installs); a plain requireNativeModule() call resolves
+// the same underlying object, and expo-modules-core's own EventEmitter interface (`addListener`)
+// covers the one event this module fires (`onTasksExpired`).
+export type INativeBackgroundTaskModule = {
+  getStatusAsync?(): Promise<number>;
+  registerTaskAsync?(
+    taskName: string,
+    options: Record<string, unknown>,
+  ): Promise<void>;
+  unregisterTaskAsync?(taskName: string): Promise<void>;
+  /** Debug-build-only: forces the OS to run the registered background task immediately. */
+  triggerTaskWorkerForTestingAsync?(): Promise<boolean>;
+  addListener?(eventName: string, listener: () => void): EventSubscription;
+};
+
+export const expoBackgroundTask =
+  requireNativeModule<INativeBackgroundTaskModule>(
+    EXPO_BACKGROUND_TASK_MODULE_NAME,
+  );

package/src/core/types.ts

@@ -0,0 +1,28 @@
+/** Availability status for the Background Task API. */
+export enum BackgroundTaskStatus {
+  /** Background tasks are unavailable — e.g. running on an iOS Simulator. */
+  Restricted = 1,
+  /** Background tasks are available for the app. */
+  Available = 2,
+}
+
+/** Return value a background-task executor should resolve with. */
+export enum BackgroundTaskResult {
+  /** The task finished successfully. */
+  Success = 1,
+  /** The task failed. */
+  Failed = 2,
+}
+
+/** Options accepted by {@link registerTaskAsync}. */
+export type IBackgroundTaskOptions = {
+  /**
+   * Inexact interval in minutes between subsequent repeats of the background task. 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 OS controls the real execution interval and treats this as a minimum delay only — on
+   *   iOS a short interval is often ignored, since the system typically runs background tasks
+   *   during specific windows (e.g. overnight).
+   */
+  minimumInterval?: number;
+};