@symbiote-native/task-manager 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,164 @@
+# @symbiote-native/task-manager
+
+A wrapper package for [SymbioteNative](../../README.md) that makes
+[`expo-task-manager`](https://github.com/expo/expo/tree/main/packages/expo-task-manager)
+usable from **every** adapter — React, Vue, Svelte, Solid, and Angular. Like
+[`@symbiote-native/local-auth`](../local-auth), 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 package is the low-level primitive other background-work packages register tasks through
+(background location, geofencing, background notification delivery) — it does **not** itself
+schedule anything. It defines tasks, tracks which are registered, dispatches native's
+task-execute event to the matching executor, and acks completion. Starting a task running (e.g.
+periodic scheduling, geofence triggers) is each consumer's own job, done through its own native
+module.
+
+## Install
+
+**New app:**
+
+```bash
+npx @symbiote-native/cli new my-app --task-manager
+```
+
+**Existing SymbioteNative app:**
+
+```bash
+npx @symbiote-native/cli add --task-manager
+```
+
+Either way: installs `@symbiote-native/task-manager` and wires the native autolinking
+automatically — see [`@symbiote-native/cli`](../cli). Most apps get this transitively anyway, pulled in by
+`--location`/`--audio`/`--background-fetch`/`--background-task`/`--notifications`.
+
+<details>
+<summary>Manual install (no CLI — installing and wiring native autolinking by hand)</summary>
+
+```bash
+npm install @symbiote-native/task-manager
+```
+
+`expo-task-manager`, `unimodules-app-loader`, 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. Android's headless-boot loader
+(`RNHeadlessAppLoader`) and iOS's `TaskManagerAppDelegateSubscriber` are both discovered
+automatically by Expo's own autolinking the moment this package is installed — no extra
+`native-link.json` entry, no app-level edit.
+
+One iOS `Info.plist` key IS wired: `UIBackgroundModes: fetch`
+(`native-link.json`'s `ios.infoPlistArrayKeys`) — upstream's own `withTaskManager.ts` config
+plugin adds this unconditionally, as the baseline mode any registered task's background delivery
+relies on, independent of which consumer package (`background-fetch`, `location`, …) actually
+registers a task. `@symbiote-native/expo-modules-link` merges it into the same array those
+packages populate, so it lands once either way.
+
+</details>
+
+## Shape
+
+```
+src/core/     defineTask / isTaskDefined / isTaskRegisteredAsync / getTaskOptionsAsync /
+              getRegisteredTasksAsync / unregisterTaskAsync / unregisterAllTasksAsync /
+              isAvailableAsync, plus the task-body/executor types. native-module.ts resolves the
+              native module via expo-modules-core's requireNativeModule and wires one listener at
+              module load — native invokes it whenever a defined task should run.
+src/angular/  @symbiote-native/task-manager/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
+
+`defineTask` must run at the top of the JS bundle, outside any component — the app can be
+launched headlessly to run a background task, with no views mounted, so a task defined inside a
+component lifecycle method would simply never register on that launch.
+
+```ts
+// index.ts, alongside AppRegistry.registerComponent — identical on every adapter
+import { defineTask } from '@symbiote-native/task-manager';
+
+const SYNC_TASK = 'background-sync';
+
+defineTask(SYNC_TASK, async ({ data, error }) => {
+  if (error) {
+    console.error('background-sync failed:', error);
+    return;
+  }
+  await runSync(data);
+});
+```
+
+A consumer registers the task with native through its own native module —
+[`@symbiote-native/location`](../location)'s `startLocationUpdatesAsync`/`startGeofencingAsync`,
+[`@symbiote-native/background-fetch`](../background-fetch)'s `registerTaskAsync`,
+[`@symbiote-native/background-task`](../background-task)'s `registerTaskAsync`, or
+[`@symbiote-native/notifications`](../notifications)'s `registerTaskAsync`. Once registered,
+`isTaskRegisteredAsync`/`getTaskOptionsAsync`/`getRegisteredTasksAsync` reflect it:
+
+```ts
+import {
+  getRegisteredTasksAsync,
+  isTaskRegisteredAsync,
+  unregisterTaskAsync,
+} from '@symbiote-native/task-manager';
+
+const isRunning = await isTaskRegisteredAsync(SYNC_TASK);
+const tasks = await getRegisteredTasksAsync();
+await unregisterTaskAsync(SYNC_TASK); // stop receiving updates for this task
+```
+
+Identical import surface on every adapter — `@symbiote-native/task-manager/react`,
+`/vue`, `/svelte`, `/solid`, `/angular` all re-export the same functions.
+
+## API
+
+```ts
+defineTask<TData>(taskName: string, taskExecutor: ITaskManagerTaskExecutor<TData>): void
+isTaskDefined(taskName: string): boolean
+isTaskRegisteredAsync(taskName: string): Promise<boolean>
+getTaskOptionsAsync<TOptions>(taskName: string): Promise<TOptions>
+getRegisteredTasksAsync<TOptions>(): Promise<ITaskManagerTask<TOptions>[]>
+unregisterTaskAsync(taskName: string): Promise<void>
+unregisterAllTasksAsync(): Promise<void>
+isAvailableAsync(): Promise<boolean>
+```
+
+Plus `ITaskManagerError`, `ITaskManagerTask`, `ITaskManagerTaskBody`,
+`ITaskManagerTaskBodyExecutionInfo`, `ITaskManagerTaskExecutor` — ported from upstream's
+`TaskManager.ts`, renamed with this repo's `I`-prefix convention for exported types
+(`ts-js-best-practices`). Unlike upstream, there is no `registerTaskAsync` free function here —
+upstream never exposes one either; registration is always driven by the consumer that needs the
+task (`@symbiote-native/location`, `@symbiote-native/background-fetch`,
+`@symbiote-native/background-task`, `@symbiote-native/notifications`).
+
+## Notes
+
+- **`isAvailableAsync` resolves `false` rather than throwing when the native method is missing** —
+  every other guarded function throws an `UnavailabilityError`. This matches upstream's own
+  contract: "can this API be used at all" has to answer even where the rest of the surface can't.
+- **A defined task that native fires but nobody registered still gets acked and unregistered.**
+  If `defineTask` for a given name was renamed or deleted from the bundle after the task was
+  registered, the dangling native registration is cleaned up automatically instead of leaking a
+  wakelock forever.
+- **A task executor that throws still acks native.** The failure is logged, but
+  `notifyTaskFinishedAsync` always fires in a `finally`, so a bug in one task's executor can't
+  leave the OS believing the task never completed.
+
+## Test it
+
+No Fabric/Descriptor angle at all — every function here is a pure async-function surface plus one
+module-load event listener, never a view or per-instance state. Tests inject a fake native-module
+object in place of the real `requireNativeModule` resolution and fire the wired listener directly
+(`src/core/task-manager.test.ts`) — no `installFabric()`, no ViewConfig. The headless-relaunch
+mechanics themselves (native tearing down and re-executing the whole JS bundle with no UI mounted)
+are OS-level and can only be verified on a real device — see the `symbiote-expo-native-module`
+skill §10e for what's traced from source versus still unverified.

package/build/angular/index.d.ts

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

package/build/angular/index.js

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

package/build/core/index.d.ts

@@ -0,0 +1,2 @@
+export { defineTask, isTaskDefined, isTaskRegisteredAsync, getTaskOptionsAsync, getRegisteredTasksAsync, unregisterTaskAsync, unregisterAllTasksAsync, isAvailableAsync, } from './task-manager';
+export type { ITaskManagerError, ITaskManagerTask, ITaskManagerTaskBody, ITaskManagerTaskBodyExecutionInfo, ITaskManagerTaskExecutor, } from './types';

package/build/core/index.js

@@ -0,0 +1 @@
+export { defineTask, isTaskDefined, isTaskRegisteredAsync, getTaskOptionsAsync, getRegisteredTasksAsync, unregisterTaskAsync, unregisterAllTasksAsync, isAvailableAsync, } from './task-manager.js';

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

@@ -0,0 +1,22 @@
+import { type EventSubscription } from 'expo-modules-core';
+import type { ITaskManagerTaskBody } from './types';
+export type INativeTaskManagerModule = {
+    /** Name of the event native emits when a defined task should run. */
+    EVENT_NAME: string;
+    addListener(eventName: string, listener: (event: ITaskManagerTaskBody) => void): EventSubscription;
+    isAvailableAsync?(): Promise<boolean>;
+    isTaskRegisteredAsync?(taskName: string): Promise<boolean>;
+    getTaskOptionsAsync?<TOptions>(taskName: string): Promise<TOptions>;
+    getRegisteredTasksAsync?(): Promise<{
+        taskName: string;
+        taskType: string;
+        options: unknown;
+    }[]>;
+    unregisterTaskAsync?(taskName: string): Promise<void>;
+    unregisterAllTasksAsync?(): Promise<void>;
+    notifyTaskFinishedAsync?(taskName: string, payload: {
+        eventId: string;
+        result: unknown;
+    }): Promise<void>;
+};
+export declare const expoTaskManager: INativeTaskManagerModule;

package/build/core/native-module.js

@@ -0,0 +1,3 @@
+import { requireNativeModule } from 'expo-modules-core';
+const EXPO_TASK_MANAGER_MODULE_NAME = 'ExpoTaskManager';
+export const expoTaskManager = requireNativeModule(EXPO_TASK_MANAGER_MODULE_NAME);

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

@@ -0,0 +1,28 @@
+import type { ITaskManagerTask, ITaskManagerTaskExecutor } from './types';
+/**
+ * Defines a task executor. Must be called in the global scope of the JS bundle — never inside a
+ * component lifecycle method — because when the app is launched in the background there are no
+ * views mounted, only this module-scope registration for native to find.
+ */
+export declare function defineTask<TData = unknown>(taskName: string, taskExecutor: ITaskManagerTaskExecutor<TData>): void;
+/** Whether a task with the given name has been defined via `defineTask`. */
+export declare function isTaskDefined(taskName: string): boolean;
+/**
+ * Whether the task is registered with native. Registered tasks persist across sessions; a task
+ * can be defined without being registered (registration is driven by the task's own consumer,
+ * e.g. `Location.startLocationUpdatesAsync`).
+ */
+export declare function isTaskRegisteredAsync(taskName: string): Promise<boolean>;
+/** The `options` a task was registered with, or rejects if the task can't be found. */
+export declare function getTaskOptionsAsync<TOptions>(taskName: string): Promise<TOptions>;
+/** Every task registered in the app, with the `options` each was registered with. */
+export declare function getRegisteredTasksAsync<TOptions = unknown>(): Promise<ITaskManagerTask<TOptions>[]>;
+/**
+ * Unregisters a task so the app stops receiving updates for it. Prefer the specialized method of
+ * whichever module registered the task (e.g. `Location.stopLocationUpdatesAsync`) when one exists.
+ */
+export declare function unregisterTaskAsync(taskName: string): Promise<void>;
+/** Unregisters every task registered for the running app. */
+export declare function unregisterAllTasksAsync(): Promise<void>;
+/** Whether the TaskManager API can be used in this app. Always `false` outside a device build. */
+export declare function isAvailableAsync(): Promise<boolean>;

package/build/core/task-manager.js

@@ -0,0 +1,112 @@
+import { UnavailabilityError } from 'expo-modules-core';
+import { expoTaskManager } from './native-module.js';
+const NATIVE_MODULE_NAME = 'expo-task-manager';
+// The registry is necessarily heterogeneous — each task's own TData differs — so the executor's
+// data parameter is typed `any` here only, exactly like upstream's own
+// `Map<string, TaskManagerTaskExecutor<any>>`. `defineTask`'s own signature stays fully typed;
+// this is the one place bridging distinct `ITaskManagerTaskExecutor<TData>` instances into one
+// registry, which a cast could not do more soundly than `any` already does.
+const tasks = new Map();
+function assertValidTaskName(taskName) {
+    if (!taskName || typeof taskName !== 'string') {
+        throw new TypeError('`taskName` must be a non-empty string.');
+    }
+}
+/**
+ * Defines a task executor. Must be called in the global scope of the JS bundle — never inside a
+ * component lifecycle method — because when the app is launched in the background there are no
+ * views mounted, only this module-scope registration for native to find.
+ */
+export function defineTask(taskName, taskExecutor) {
+    if (!taskName || typeof taskName !== 'string') {
+        console.warn("TaskManager.defineTask: 'taskName' argument must be a non-empty string.");
+        return;
+    }
+    if (!taskExecutor || typeof taskExecutor !== 'function') {
+        console.warn("TaskManager.defineTask: 'task' argument must be a function.");
+        return;
+    }
+    tasks.set(taskName, taskExecutor);
+}
+/** Whether a task with the given name has been defined via `defineTask`. */
+export function isTaskDefined(taskName) {
+    return tasks.has(taskName);
+}
+/**
+ * Whether the task is registered with native. Registered tasks persist across sessions; a task
+ * can be defined without being registered (registration is driven by the task's own consumer,
+ * e.g. `Location.startLocationUpdatesAsync`).
+ */
+export async function isTaskRegisteredAsync(taskName) {
+    if (!expoTaskManager.isTaskRegisteredAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'isTaskRegisteredAsync');
+    }
+    assertValidTaskName(taskName);
+    return expoTaskManager.isTaskRegisteredAsync(taskName);
+}
+/** The `options` a task was registered with, or rejects if the task can't be found. */
+export async function getTaskOptionsAsync(taskName) {
+    if (!expoTaskManager.getTaskOptionsAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getTaskOptionsAsync');
+    }
+    assertValidTaskName(taskName);
+    return expoTaskManager.getTaskOptionsAsync(taskName);
+}
+/** Every task registered in the app, with the `options` each was registered with. */
+export async function getRegisteredTasksAsync() {
+    if (!expoTaskManager.getRegisteredTasksAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getRegisteredTasksAsync');
+    }
+    return expoTaskManager.getRegisteredTasksAsync();
+}
+/**
+ * Unregisters a task so the app stops receiving updates for it. Prefer the specialized method of
+ * whichever module registered the task (e.g. `Location.stopLocationUpdatesAsync`) when one exists.
+ */
+export async function unregisterTaskAsync(taskName) {
+    if (!expoTaskManager.unregisterTaskAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'unregisterTaskAsync');
+    }
+    assertValidTaskName(taskName);
+    await expoTaskManager.unregisterTaskAsync(taskName);
+}
+/** Unregisters every task registered for the running app. */
+export async function unregisterAllTasksAsync() {
+    if (!expoTaskManager.unregisterAllTasksAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'unregisterAllTasksAsync');
+    }
+    await expoTaskManager.unregisterAllTasksAsync();
+}
+/** Whether the TaskManager API can be used in this app. Always `false` outside a device build. */
+export async function isAvailableAsync() {
+    if (!expoTaskManager.isAvailableAsync)
+        return false;
+    return expoTaskManager.isAvailableAsync();
+}
+// Wired once at module load, exactly like every adapter's `defineTask` call site — native fires
+// this event whenever a defined task should run, and we look the executor up by name. The task
+// itself may have been dropped from the bundle (renamed, deleted) since it was registered, so an
+// unknown taskName still needs to ack native and clean up the stale registration.
+expoTaskManager.addListener(expoTaskManager.EVENT_NAME, (body) => {
+    const { data, error, executionInfo } = body;
+    const { eventId, taskName } = executionInfo;
+    const taskExecutor = tasks.get(taskName);
+    if (taskExecutor) {
+        void taskExecutor({ data, error, executionInfo })
+            .catch((taskError) => {
+            console.error(`TaskManager: Task "${taskName}" failed:`, taskError);
+        })
+            .finally(() => {
+            void expoTaskManager.notifyTaskFinishedAsync?.(taskName, {
+                eventId,
+                result: null,
+            });
+        });
+        return;
+    }
+    console.warn(`TaskManager: Execution of "${taskName}" was requested but it is not defined. ` +
+        `Available tasks: [${[...tasks.keys()].join(', ')}]. Make sure "defineTask" is called during initialization.`);
+    void expoTaskManager
+        .notifyTaskFinishedAsync?.(taskName, { eventId, result: null })
+        .then(() => expoTaskManager.unregisterTaskAsync?.(taskName));
+});

package/build/core/types.d.ts

@@ -0,0 +1,32 @@
+export type ITaskManagerError = {
+    code: string | number;
+    message: string;
+};
+/** Additional details about execution, threaded through to the task executor. */
+export type ITaskManagerTaskBodyExecutionInfo = {
+    /** State of the application. @platform ios */
+    appState?: 'active' | 'background' | 'inactive';
+    /** Unique ID of the task event. */
+    eventId: string;
+    /** Name of the task. */
+    taskName: string;
+};
+/** What native hands the task executor when it runs the task. */
+export type ITaskManagerTaskBody<TData = unknown> = {
+    /** Data passed to the task executor; its shape depends on the task's own consumer (location, geofencing, …). */
+    data: TData;
+    /** Error object if the task failed, or `null` otherwise. */
+    error: ITaskManagerError | null;
+    executionInfo: ITaskManagerTaskBodyExecutionInfo;
+};
+/** An already-registered task, as reported by `getRegisteredTasksAsync`. */
+export type ITaskManagerTask<TOptions = unknown> = {
+    /** Name the task is registered under. */
+    taskName: string;
+    /** Type of the task — depends on how it was registered (its consumer's own name). */
+    taskType: string;
+    /** `options` the task was registered with. */
+    options: TOptions;
+};
+/** A function that handles a defined task. */
+export type ITaskManagerTaskExecutor<TData = unknown> = (body: ITaskManagerTaskBody<TData>) => Promise<unknown>;

package/build/core/types.js

@@ -0,0 +1 @@
+export {};

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/task-manager/angular: the Angular entry over the framework-agnostic core. Same
+// reasoning as the React/Vue entries — no per-instance state or event stream 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,kGAAkG;AAClG,0FAA0F;AAC1F,yCAAyC;AACzC,cAAc,SAAS,CAAC"}

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

@@ -0,0 +1,2 @@
+export { defineTask, isTaskDefined, isTaskRegisteredAsync, getTaskOptionsAsync, getRegisteredTasksAsync, unregisterTaskAsync, unregisterAllTasksAsync, isAvailableAsync, } from './task-manager';
+export type { ITaskManagerError, ITaskManagerTask, ITaskManagerTaskBody, ITaskManagerTaskBodyExecutionInfo, ITaskManagerTaskExecutor, } from './types';

package/build-ngc/core/index.js

@@ -0,0 +1,2 @@
+export { defineTask, isTaskDefined, isTaskRegisteredAsync, getTaskOptionsAsync, getRegisteredTasksAsync, unregisterTaskAsync, unregisterAllTasksAsync, isAvailableAsync, } from './task-manager';
+//# 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,UAAU,EACV,aAAa,EACb,qBAAqB,EACrB,mBAAmB,EACnB,uBAAuB,EACvB,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,GACjB,MAAM,gBAAgB,CAAC"}

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

@@ -0,0 +1,22 @@
+import { type EventSubscription } from 'expo-modules-core';
+import type { ITaskManagerTaskBody } from './types';
+export type INativeTaskManagerModule = {
+    /** Name of the event native emits when a defined task should run. */
+    EVENT_NAME: string;
+    addListener(eventName: string, listener: (event: ITaskManagerTaskBody) => void): EventSubscription;
+    isAvailableAsync?(): Promise<boolean>;
+    isTaskRegisteredAsync?(taskName: string): Promise<boolean>;
+    getTaskOptionsAsync?<TOptions>(taskName: string): Promise<TOptions>;
+    getRegisteredTasksAsync?(): Promise<{
+        taskName: string;
+        taskType: string;
+        options: unknown;
+    }[]>;
+    unregisterTaskAsync?(taskName: string): Promise<void>;
+    unregisterAllTasksAsync?(): Promise<void>;
+    notifyTaskFinishedAsync?(taskName: string, payload: {
+        eventId: string;
+        result: unknown;
+    }): Promise<void>;
+};
+export declare const expoTaskManager: INativeTaskManagerModule;

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

@@ -0,0 +1,4 @@
+import { requireNativeModule } from 'expo-modules-core';
+const EXPO_TASK_MANAGER_MODULE_NAME = 'ExpoTaskManager';
+export const expoTaskManager = requireNativeModule(EXPO_TASK_MANAGER_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;AAGhF,MAAM,6BAA6B,GAAG,iBAAiB,CAAC;AA8BxD,MAAM,CAAC,MAAM,eAAe,GAAG,mBAAmB,CAChD,6BAA6B,CAC9B,CAAC"}

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

@@ -0,0 +1,28 @@
+import type { ITaskManagerTask, ITaskManagerTaskExecutor } from './types';
+/**
+ * Defines a task executor. Must be called in the global scope of the JS bundle — never inside a
+ * component lifecycle method — because when the app is launched in the background there are no
+ * views mounted, only this module-scope registration for native to find.
+ */
+export declare function defineTask<TData = unknown>(taskName: string, taskExecutor: ITaskManagerTaskExecutor<TData>): void;
+/** Whether a task with the given name has been defined via `defineTask`. */
+export declare function isTaskDefined(taskName: string): boolean;
+/**
+ * Whether the task is registered with native. Registered tasks persist across sessions; a task
+ * can be defined without being registered (registration is driven by the task's own consumer,
+ * e.g. `Location.startLocationUpdatesAsync`).
+ */
+export declare function isTaskRegisteredAsync(taskName: string): Promise<boolean>;
+/** The `options` a task was registered with, or rejects if the task can't be found. */
+export declare function getTaskOptionsAsync<TOptions>(taskName: string): Promise<TOptions>;
+/** Every task registered in the app, with the `options` each was registered with. */
+export declare function getRegisteredTasksAsync<TOptions = unknown>(): Promise<ITaskManagerTask<TOptions>[]>;
+/**
+ * Unregisters a task so the app stops receiving updates for it. Prefer the specialized method of
+ * whichever module registered the task (e.g. `Location.stopLocationUpdatesAsync`) when one exists.
+ */
+export declare function unregisterTaskAsync(taskName: string): Promise<void>;
+/** Unregisters every task registered for the running app. */
+export declare function unregisterAllTasksAsync(): Promise<void>;
+/** Whether the TaskManager API can be used in this app. Always `false` outside a device build. */
+export declare function isAvailableAsync(): Promise<boolean>;

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

@@ -0,0 +1,113 @@
+import { UnavailabilityError } from 'expo-modules-core';
+import { expoTaskManager } from './native-module';
+const NATIVE_MODULE_NAME = 'expo-task-manager';
+// The registry is necessarily heterogeneous — each task's own TData differs — so the executor's
+// data parameter is typed `any` here only, exactly like upstream's own
+// `Map<string, TaskManagerTaskExecutor<any>>`. `defineTask`'s own signature stays fully typed;
+// this is the one place bridging distinct `ITaskManagerTaskExecutor<TData>` instances into one
+// registry, which a cast could not do more soundly than `any` already does.
+const tasks = new Map();
+function assertValidTaskName(taskName) {
+    if (!taskName || typeof taskName !== 'string') {
+        throw new TypeError('`taskName` must be a non-empty string.');
+    }
+}
+/**
+ * Defines a task executor. Must be called in the global scope of the JS bundle — never inside a
+ * component lifecycle method — because when the app is launched in the background there are no
+ * views mounted, only this module-scope registration for native to find.
+ */
+export function defineTask(taskName, taskExecutor) {
+    if (!taskName || typeof taskName !== 'string') {
+        console.warn("TaskManager.defineTask: 'taskName' argument must be a non-empty string.");
+        return;
+    }
+    if (!taskExecutor || typeof taskExecutor !== 'function') {
+        console.warn("TaskManager.defineTask: 'task' argument must be a function.");
+        return;
+    }
+    tasks.set(taskName, taskExecutor);
+}
+/** Whether a task with the given name has been defined via `defineTask`. */
+export function isTaskDefined(taskName) {
+    return tasks.has(taskName);
+}
+/**
+ * Whether the task is registered with native. Registered tasks persist across sessions; a task
+ * can be defined without being registered (registration is driven by the task's own consumer,
+ * e.g. `Location.startLocationUpdatesAsync`).
+ */
+export async function isTaskRegisteredAsync(taskName) {
+    if (!expoTaskManager.isTaskRegisteredAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'isTaskRegisteredAsync');
+    }
+    assertValidTaskName(taskName);
+    return expoTaskManager.isTaskRegisteredAsync(taskName);
+}
+/** The `options` a task was registered with, or rejects if the task can't be found. */
+export async function getTaskOptionsAsync(taskName) {
+    if (!expoTaskManager.getTaskOptionsAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getTaskOptionsAsync');
+    }
+    assertValidTaskName(taskName);
+    return expoTaskManager.getTaskOptionsAsync(taskName);
+}
+/** Every task registered in the app, with the `options` each was registered with. */
+export async function getRegisteredTasksAsync() {
+    if (!expoTaskManager.getRegisteredTasksAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getRegisteredTasksAsync');
+    }
+    return expoTaskManager.getRegisteredTasksAsync();
+}
+/**
+ * Unregisters a task so the app stops receiving updates for it. Prefer the specialized method of
+ * whichever module registered the task (e.g. `Location.stopLocationUpdatesAsync`) when one exists.
+ */
+export async function unregisterTaskAsync(taskName) {
+    if (!expoTaskManager.unregisterTaskAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'unregisterTaskAsync');
+    }
+    assertValidTaskName(taskName);
+    await expoTaskManager.unregisterTaskAsync(taskName);
+}
+/** Unregisters every task registered for the running app. */
+export async function unregisterAllTasksAsync() {
+    if (!expoTaskManager.unregisterAllTasksAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'unregisterAllTasksAsync');
+    }
+    await expoTaskManager.unregisterAllTasksAsync();
+}
+/** Whether the TaskManager API can be used in this app. Always `false` outside a device build. */
+export async function isAvailableAsync() {
+    if (!expoTaskManager.isAvailableAsync)
+        return false;
+    return expoTaskManager.isAvailableAsync();
+}
+// Wired once at module load, exactly like every adapter's `defineTask` call site — native fires
+// this event whenever a defined task should run, and we look the executor up by name. The task
+// itself may have been dropped from the bundle (renamed, deleted) since it was registered, so an
+// unknown taskName still needs to ack native and clean up the stale registration.
+expoTaskManager.addListener(expoTaskManager.EVENT_NAME, (body) => {
+    const { data, error, executionInfo } = body;
+    const { eventId, taskName } = executionInfo;
+    const taskExecutor = tasks.get(taskName);
+    if (taskExecutor) {
+        void taskExecutor({ data, error, executionInfo })
+            .catch((taskError) => {
+            console.error(`TaskManager: Task "${taskName}" failed:`, taskError);
+        })
+            .finally(() => {
+            void expoTaskManager.notifyTaskFinishedAsync?.(taskName, {
+                eventId,
+                result: null,
+            });
+        });
+        return;
+    }
+    console.warn(`TaskManager: Execution of "${taskName}" was requested but it is not defined. ` +
+        `Available tasks: [${[...tasks.keys()].join(', ')}]. Make sure "defineTask" is called during initialization.`);
+    void expoTaskManager
+        .notifyTaskFinishedAsync?.(taskName, { eventId, result: null })
+        .then(() => expoTaskManager.unregisterTaskAsync?.(taskName));
+});
+//# sourceMappingURL=task-manager.js.map

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

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

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

@@ -0,0 +1,32 @@
+export type ITaskManagerError = {
+    code: string | number;
+    message: string;
+};
+/** Additional details about execution, threaded through to the task executor. */
+export type ITaskManagerTaskBodyExecutionInfo = {
+    /** State of the application. @platform ios */
+    appState?: 'active' | 'background' | 'inactive';
+    /** Unique ID of the task event. */
+    eventId: string;
+    /** Name of the task. */
+    taskName: string;
+};
+/** What native hands the task executor when it runs the task. */
+export type ITaskManagerTaskBody<TData = unknown> = {
+    /** Data passed to the task executor; its shape depends on the task's own consumer (location, geofencing, …). */
+    data: TData;
+    /** Error object if the task failed, or `null` otherwise. */
+    error: ITaskManagerError | null;
+    executionInfo: ITaskManagerTaskBodyExecutionInfo;
+};
+/** An already-registered task, as reported by `getRegisteredTasksAsync`. */
+export type ITaskManagerTask<TOptions = unknown> = {
+    /** Name the task is registered under. */
+    taskName: string;
+    /** Type of the task — depends on how it was registered (its consumer's own name). */
+    taskType: string;
+    /** `options` the task was registered with. */
+    options: TOptions;
+};
+/** A function that handles a defined task. */
+export type ITaskManagerTaskExecutor<TData = unknown> = (body: ITaskManagerTaskBody<TData>) => Promise<unknown>;

package/build-ngc/core/types.js

@@ -0,0 +1,2 @@
+export {};
+//# 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":""}

package/native-link.json

@@ -0,0 +1,22 @@
+{
+  "android": {
+    "gradleProjectName": "expo-task-manager",
+    "modules": [
+      {
+        "importPath": "expo.modules.taskManager.TaskManagerModule",
+        "className": "TaskManagerModule",
+        "nativeName": "ExpoTaskManager"
+      }
+    ],
+    "services": [
+      {
+        "importPath": "expo.modules.constants.ConstantsService",
+        "className": "ConstantsService",
+        "gradleProjectName": "expo-constants"
+      }
+    ]
+  },
+  "ios": {
+    "infoPlistArrayKeys": { "UIBackgroundModes": ["fetch"] }
+  }
+}

package/package.json

@@ -0,0 +1,152 @@
+{
+  "name": "@symbiote-native/task-manager",
+  "version": "0.1.0",
+  "description": "expo-task-manager wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, Svelte, Solid, and Angular adapters. Defines and tracks background tasks that native code invokes headlessly.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OneEyed1366/symbiote-native.git",
+    "directory": "packages/task-manager"
+  },
+  "homepage": "https://github.com/OneEyed1366/symbiote-native/tree/master/packages/task-manager#readme",
+  "bugs": {
+    "url": "https://github.com/OneEyed1366/symbiote-native/issues"
+  },
+  "author": "Andrey Prokopenko <psevdoproger@gmail.com>",
+  "keywords": [
+    "react-native",
+    "symbiote-native",
+    "expo-task-manager",
+    "react",
+    "vue",
+    "svelte",
+    "solid",
+    "angular",
+    "background",
+    "task"
+  ],
+  "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-task-manager": "57.0.15",
+    "unimodules-app-loader": "57.0.1",
+    "expo-constants": "57.0.19",
+    "expo-modules-core": "57.0.5"
+  },
+  "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/react": "^3.0.2",
+    "@symbiote-native/solid": "^3.0.2",
+    "@symbiote-native/engine": "^1.3.0",
+    "@symbiote-native/vue": "^3.0.2",
+    "@symbiote-native/svelte": "^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/angular": "3.1.0",
+    "@symbiote-native/svelte": "3.0.2",
+    "@symbiote-native/solid": "3.0.2",
+    "@symbiote-native/react": "3.0.2",
+    "@symbiote-native/engine": "1.3.0",
+    "@symbiote-native/test-utils": "0.4.2",
+    "@symbiote-native/vue": "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/task-manager/angular: the Angular entry over the framework-agnostic core. Same
+// reasoning as the React/Vue entries — no per-instance state or event stream to wrap in a
+// service, so this is a plain re-export.
+export * from '../core';

package/src/core/index.ts

@@ -0,0 +1,17 @@
+export {
+  defineTask,
+  isTaskDefined,
+  isTaskRegisteredAsync,
+  getTaskOptionsAsync,
+  getRegisteredTasksAsync,
+  unregisterTaskAsync,
+  unregisterAllTasksAsync,
+  isAvailableAsync,
+} from './task-manager';
+export type {
+  ITaskManagerError,
+  ITaskManagerTask,
+  ITaskManagerTaskBody,
+  ITaskManagerTaskBodyExecutionInfo,
+  ITaskManagerTaskExecutor,
+} from './types';

package/src/core/native-module.ts

@@ -0,0 +1,36 @@
+import { requireNativeModule, type EventSubscription } from 'expo-modules-core';
+import type { ITaskManagerTaskBody } from './types';
+
+const EXPO_TASK_MANAGER_MODULE_NAME = 'ExpoTaskManager';
+
+// 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
+// rather than assuming the native module implements the whole surface (same pattern
+// packages/local-auth/src/core/native-module.ts uses). `addListener` stays REQUIRED, mirroring
+// packages/sensors/src/core/device-sensor.ts's INativeSensorModule — a modern expo-modules-core
+// Module always implements the EventEmitter interface itself, so no LegacyEventEmitter shim is
+// needed here (that shim exists for older native modules that predate it).
+export type INativeTaskManagerModule = {
+  /** Name of the event native emits when a defined task should run. */
+  EVENT_NAME: string;
+  addListener(
+    eventName: string,
+    listener: (event: ITaskManagerTaskBody) => void,
+  ): EventSubscription;
+  isAvailableAsync?(): Promise<boolean>;
+  isTaskRegisteredAsync?(taskName: string): Promise<boolean>;
+  getTaskOptionsAsync?<TOptions>(taskName: string): Promise<TOptions>;
+  getRegisteredTasksAsync?(): Promise<
+    { taskName: string; taskType: string; options: unknown }[]
+  >;
+  unregisterTaskAsync?(taskName: string): Promise<void>;
+  unregisterAllTasksAsync?(): Promise<void>;
+  notifyTaskFinishedAsync?(
+    taskName: string,
+    payload: { eventId: string; result: unknown },
+  ): Promise<void>;
+};
+
+export const expoTaskManager = requireNativeModule<INativeTaskManagerModule>(
+  EXPO_TASK_MANAGER_MODULE_NAME,
+);

package/src/core/task-manager.ts

@@ -0,0 +1,154 @@
+import { UnavailabilityError } from 'expo-modules-core';
+import { expoTaskManager } from './native-module';
+import type {
+  ITaskManagerTask,
+  ITaskManagerTaskBody,
+  ITaskManagerTaskExecutor,
+} from './types';
+
+const NATIVE_MODULE_NAME = 'expo-task-manager';
+
+// The registry is necessarily heterogeneous — each task's own TData differs — so the executor's
+// data parameter is typed `any` here only, exactly like upstream's own
+// `Map<string, TaskManagerTaskExecutor<any>>`. `defineTask`'s own signature stays fully typed;
+// this is the one place bridging distinct `ITaskManagerTaskExecutor<TData>` instances into one
+// registry, which a cast could not do more soundly than `any` already does.
+const tasks = new Map<string, ITaskManagerTaskExecutor<any>>();
+
+function assertValidTaskName(taskName: unknown): asserts taskName is string {
+  if (!taskName || typeof taskName !== 'string') {
+    throw new TypeError('`taskName` must be a non-empty string.');
+  }
+}
+
+/**
+ * Defines a task executor. Must be called in the global scope of the JS bundle — never inside a
+ * component lifecycle method — because when the app is launched in the background there are no
+ * views mounted, only this module-scope registration for native to find.
+ */
+export function defineTask<TData = unknown>(
+  taskName: string,
+  taskExecutor: ITaskManagerTaskExecutor<TData>,
+): void {
+  if (!taskName || typeof taskName !== 'string') {
+    console.warn(
+      "TaskManager.defineTask: 'taskName' argument must be a non-empty string.",
+    );
+    return;
+  }
+  if (!taskExecutor || typeof taskExecutor !== 'function') {
+    console.warn("TaskManager.defineTask: 'task' argument must be a function.");
+    return;
+  }
+  tasks.set(taskName, taskExecutor);
+}
+
+/** Whether a task with the given name has been defined via `defineTask`. */
+export function isTaskDefined(taskName: string): boolean {
+  return tasks.has(taskName);
+}
+
+/**
+ * Whether the task is registered with native. Registered tasks persist across sessions; a task
+ * can be defined without being registered (registration is driven by the task's own consumer,
+ * e.g. `Location.startLocationUpdatesAsync`).
+ */
+export async function isTaskRegisteredAsync(
+  taskName: string,
+): Promise<boolean> {
+  if (!expoTaskManager.isTaskRegisteredAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'isTaskRegisteredAsync');
+  }
+  assertValidTaskName(taskName);
+  return expoTaskManager.isTaskRegisteredAsync(taskName);
+}
+
+/** The `options` a task was registered with, or rejects if the task can't be found. */
+export async function getTaskOptionsAsync<TOptions>(
+  taskName: string,
+): Promise<TOptions> {
+  if (!expoTaskManager.getTaskOptionsAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getTaskOptionsAsync');
+  }
+  assertValidTaskName(taskName);
+  return expoTaskManager.getTaskOptionsAsync<TOptions>(taskName);
+}
+
+/** Every task registered in the app, with the `options` each was registered with. */
+export async function getRegisteredTasksAsync<TOptions = unknown>(): Promise<
+  ITaskManagerTask<TOptions>[]
+> {
+  if (!expoTaskManager.getRegisteredTasksAsync) {
+    throw new UnavailabilityError(
+      NATIVE_MODULE_NAME,
+      'getRegisteredTasksAsync',
+    );
+  }
+  return expoTaskManager.getRegisteredTasksAsync() as Promise<
+    ITaskManagerTask<TOptions>[]
+  >;
+}
+
+/**
+ * Unregisters a task so the app stops receiving updates for it. Prefer the specialized method of
+ * whichever module registered the task (e.g. `Location.stopLocationUpdatesAsync`) when one exists.
+ */
+export async function unregisterTaskAsync(taskName: string): Promise<void> {
+  if (!expoTaskManager.unregisterTaskAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'unregisterTaskAsync');
+  }
+  assertValidTaskName(taskName);
+  await expoTaskManager.unregisterTaskAsync(taskName);
+}
+
+/** Unregisters every task registered for the running app. */
+export async function unregisterAllTasksAsync(): Promise<void> {
+  if (!expoTaskManager.unregisterAllTasksAsync) {
+    throw new UnavailabilityError(
+      NATIVE_MODULE_NAME,
+      'unregisterAllTasksAsync',
+    );
+  }
+  await expoTaskManager.unregisterAllTasksAsync();
+}
+
+/** Whether the TaskManager API can be used in this app. Always `false` outside a device build. */
+export async function isAvailableAsync(): Promise<boolean> {
+  if (!expoTaskManager.isAvailableAsync) return false;
+  return expoTaskManager.isAvailableAsync();
+}
+
+// Wired once at module load, exactly like every adapter's `defineTask` call site — native fires
+// this event whenever a defined task should run, and we look the executor up by name. The task
+// itself may have been dropped from the bundle (renamed, deleted) since it was registered, so an
+// unknown taskName still needs to ack native and clean up the stale registration.
+expoTaskManager.addListener(
+  expoTaskManager.EVENT_NAME,
+  (body: ITaskManagerTaskBody) => {
+    const { data, error, executionInfo } = body;
+    const { eventId, taskName } = executionInfo;
+    const taskExecutor = tasks.get(taskName);
+
+    if (taskExecutor) {
+      void taskExecutor({ data, error, executionInfo })
+        .catch((taskError: unknown) => {
+          console.error(`TaskManager: Task "${taskName}" failed:`, taskError);
+        })
+        .finally(() => {
+          void expoTaskManager.notifyTaskFinishedAsync?.(taskName, {
+            eventId,
+            result: null,
+          });
+        });
+      return;
+    }
+
+    console.warn(
+      `TaskManager: Execution of "${taskName}" was requested but it is not defined. ` +
+        `Available tasks: [${[...tasks.keys()].join(', ')}]. Make sure "defineTask" is called during initialization.`,
+    );
+    void expoTaskManager
+      .notifyTaskFinishedAsync?.(taskName, { eventId, result: null })
+      .then(() => expoTaskManager.unregisterTaskAsync?.(taskName));
+  },
+);

package/src/core/types.ts

@@ -0,0 +1,38 @@
+export type ITaskManagerError = {
+  code: string | number;
+  message: string;
+};
+
+/** Additional details about execution, threaded through to the task executor. */
+export type ITaskManagerTaskBodyExecutionInfo = {
+  /** State of the application. @platform ios */
+  appState?: 'active' | 'background' | 'inactive';
+  /** Unique ID of the task event. */
+  eventId: string;
+  /** Name of the task. */
+  taskName: string;
+};
+
+/** What native hands the task executor when it runs the task. */
+export type ITaskManagerTaskBody<TData = unknown> = {
+  /** Data passed to the task executor; its shape depends on the task's own consumer (location, geofencing, …). */
+  data: TData;
+  /** Error object if the task failed, or `null` otherwise. */
+  error: ITaskManagerError | null;
+  executionInfo: ITaskManagerTaskBodyExecutionInfo;
+};
+
+/** An already-registered task, as reported by `getRegisteredTasksAsync`. */
+export type ITaskManagerTask<TOptions = unknown> = {
+  /** Name the task is registered under. */
+  taskName: string;
+  /** Type of the task — depends on how it was registered (its consumer's own name). */
+  taskType: string;
+  /** `options` the task was registered with. */
+  options: TOptions;
+};
+
+/** A function that handles a defined task. */
+export type ITaskManagerTaskExecutor<TData = unknown> = (
+  body: ITaskManagerTaskBody<TData>,
+) => Promise<unknown>;