JavaScript APIs / oro:background

oro:background

oro:background schedules Android runtime-owned share-file cleanup, not arbitrary JavaScript. The oro:background/deferred subpath schedules registered native work on Android and Linux; probe its support and execution scope separately.

Examples#

Inspect the Android cleanup gate and the separate deferred native executor:

import background from 'oro:background'
import deferred from 'oro:background/deferred'
import platform from 'oro:platform'

const backend = await platform.getSupport('background')
if (backend.implementation === 'implemented' && background.available) {
  console.log(await background.status())
}
const support = await deferred.getSupport()
console.log(support.available, support.registeredKinds)

The document opt-in flag is not proof of scheduler availability. Android share-prune removes expired runtime-owned share files; deferred work runs registered native kinds, not arbitrary JavaScript.

API reference#

Module specifiers#

oro:background
oro:background/deferred

TypeScript declarations#

These declarations are generated from the runtime's published TypeScript surface.

oro:background#

declare module "oro:background" {
    /**
     * Checks the supported native task kind. This does not register a JS handler or
     * authorize future application work. Other platforms reject with ENOSYS.
     * @param {'share-prune'} taskKind
     * @returns {Promise<BackgroundTaskSupport>}
     */
    export function register(taskKind: "share-prune"): Promise<BackgroundTaskSupport>;
    /**
     * Schedules one unique, persisted Android share-prune job. Scheduling replaces
     * the previous cleanup of that kind. Android decides timing and boot recovery;
     * force-stop prevents execution until relaunch. The task removes only expired
     * runtime-owned share files; it never executes JS, contacts servers, or retries
     * application mutations. Failed native cleanup has at most three attempts with
     * Android exponential backoff starting at 30 seconds. Requires background.enabled.
     * @param {BackgroundScheduleOptions} options
     * @returns {Promise<BackgroundTaskState>}
     */
    export function schedule(options: BackgroundScheduleOptions): Promise<BackgroundTaskState>;
    /**
     * Cancels the unique native cleanup. A running deletion may finish its current
     * file before observing cancellation. Already removed expired files stay removed.
     * @param {'share-prune'} [taskKind='share-prune']
     * @returns {Promise<BackgroundTaskState>}
     */
    export function cancel(taskKind?: "share-prune"): Promise<BackgroundTaskState>;
    /**
     * Reads actual native scheduling availability and durable state. An interrupted
     * record with no retained OS job is explicit; it is not silently re-enqueued.
     * Other platforms reject with ENOSYS.
     * @param {'share-prune'} [taskKind='share-prune']
     * @returns {Promise<BackgroundTaskStatus>}
     */
    export function status(taskKind?: "share-prune"): Promise<BackgroundTaskStatus>;
    /**
     * Whether this document requested the native Android cleanup capability.
     * Read status() for actual manifest and scheduler availability.
     * @type {boolean}
     */
    export const available: boolean;
    /**
     * @typedef {object} BackgroundModule
     * @property {typeof available} available
     * @property {typeof register} register
     * @property {typeof schedule} schedule
     * @property {typeof cancel} cancel
     * @property {typeof status} status
     */
    /** @type {BackgroundModule} Native task entry points and the document's opt-in flag. */
    export const background: BackgroundModule;
    export default background;
    export type BackgroundScheduleOptions = {
        /**
         * Native cleanup only; serialized payloads are rejected.
         */
        kind: "share-prune";
        /**
         * Earliest execution delay, from 0 through seven days.
         */
        delayMs?: number;
        requiresCharging?: boolean;
        requiresBatteryNotLow?: boolean;
    };
    export type BackgroundTaskState = {
        schema?: number;
        kind?: "share-prune";
        phase?: "scheduling" | "scheduled" | "running" | "stopped" | "interrupted" | "completed" | "cancelled" | "rejected" | "failed" | "idle";
        /**
         * Opaque scheduling identity, not an authorization token.
         */
        generation?: string;
        /**
         * At most three native cleanup attempts.
         */
        attempts?: number;
        /**
         * Earliest Unix execution time; never a deadline guarantee.
         */
        notBefore?: number;
        updatedAt?: number;
    };
    export type BackgroundTaskSupport = {
        kind: "share-prune";
        available: boolean;
        maximumAttempts: number;
        /**
         * False; Android controls execution time.
         */
        exactTiming: boolean;
        /**
         * False; the app must be launched again.
         */
        survivesForceStop: boolean;
    };
    export type BackgroundTaskStatus = {
        /**
         * Requires explicit background.enabled and generated manifest declarations.
         */
        available: boolean;
        kind: "share-prune";
        supportedKinds: string[];
        /**
         * Android currently retains the job.
         */
        pending: boolean;
        /**
         * Durable last scheduling record.
         */
        state: BackgroundTaskState;
        /**
         * False.
         */
        backgroundJavaScript: boolean;
        /**
         * False.
         */
        push: boolean;
    };
    export type BackgroundModule = {
        available: typeof available;
        register: typeof register;
        schedule: typeof schedule;
        cancel: typeof cancel;
        status: typeof status;
    };
}

oro:background/deferred#

declare module "oro:background/deferred" {
    /**
     * @typedef {object} DeferredReadOptions
     * @property {string} id Stable task identity, 1..128 letters/digits/underscores/hyphens.
     * @property {string} kind Name registered by compiled native app code.
     * @property {string} authorityRef Opaque configured server identity, never a URL or credential.
     * @property {string} accountRef Opaque account identity; authorization is rechecked at execution.
     * @property {string} targetRef Opaque resource identity.
     * @property {string} operationRef Opaque operation identity for read-only status/reconciliation.
     * @property {'any'|'unmetered'} [network='unmetered'] OS path constraint, not server availability.
     * @property {boolean} [requiresCharging=false]
     * @property {boolean} [requiresBatteryNotLow=true]
     * @property {number} [delayMs=0] Minimum delay, at most seven days. OS/process availability controls timing.
     * @property {number} [intervalMs=0] Read recurrence: 0 for one-shot, or 15 minutes through seven days. Requires delayMs=0.
     * @property {number} [flexMs] Periodic execution window: at least five minutes or 5% of intervalMs, whichever is larger. Defaults to that minimum; at most intervalMs. Omit for one-shot reads.
     */
    /**
     * @typedef {DeferredReadOptions & { schema: number, generation: string, jobId: number, mode?: 'read'|'maintenance', phase: string, attempts: number, updatedAt: number, lastOutcome?: string, completedRuns?: number }} DeferredReadState
     */
    /**
     * @typedef {object} DeferredReadSupport
     * @property {string} [platform] Present on an unavailable cross-platform support result.
     * @property {'missing'|'restricted'} [implementation] Missing runtime backend or platform API restriction; not a permission denial.
     * @property {string} [reason] Stable unavailable reason.
     * @property {boolean} available
     * @property {string[]} registeredKinds
     * @property {number} maximumTasks 32, including terminal records until explicitly released.
     * @property {number} maximumAttempts 5 with exponential backoff starting at 30 seconds.
     * @property {boolean} readOnly True for enqueue. Maintenance uses a separate explicitly registered contract.
     * @property {boolean} queuedWrites False.
     * @property {boolean} backgroundJavaScript False.
     * @property {boolean} survivesForceStop False. The app must relaunch, reconcile interrupted state and explicitly resume supported work.
     * @property {boolean} periodicReads True. Successful cycles reset their attempt budget; terminal failures suspend recurrence.
     * @property {number} minimumIntervalMs 900000.
     * @property {number} minimumFlexMs 300000.
     * @property {string[]} registeredMaintenanceKinds Explicitly registered native maintenance executors.
     * @property {Object<string, string[]>} maintenanceOperations Allowed cleanup/revoke operations per maintenance kind.
     * @property {'application-process'} [executionScope] Linux scheduling scope.
     * @property {boolean} [survivesProcessExit] False on Linux; durable records require explicit interruption reconciliation.
     */
    /** @returns {Promise<DeferredReadSupport>} */
    export function getSupport(): Promise<DeferredReadSupport>;
    /**
     * Schedules an authorized native read/reconciliation. Reusing the same task ID
     * with identical options returns its current state, without duplicate delivery.
     * Changing an existing task returns EEXIST. Each attempt has a 60-second result
     * deadline; a blocked native executor can still occupy the single worker.
     * @param {DeferredReadOptions} options
     * @returns {Promise<DeferredReadState>}
     */
    export function enqueue(options: DeferredReadOptions): Promise<DeferredReadState>;
    /**
     * @typedef {Omit<DeferredReadOptions, 'operationRef'|'intervalMs'|'flexMs'> & { operationRef: 'cleanup'|'revoke' }} DeferredMaintenanceOptions
     */
    /**
     * Schedules one registered cleanup/revocation task. Registration must explicitly
     * assert retry safety in native code. The executor reauthorizes every attempt
     * and owns idempotency, prerequisites and uncertain-outcome reconciliation.
     * General mutations, credentials, request bodies and periodic maintenance are
     * rejected. Uses the same journal, five-attempt budget and cancellation rules.
     * @param {DeferredMaintenanceOptions} options
     * @returns {Promise<DeferredReadState>}
     */
    export function enqueueMaintenance(options: DeferredMaintenanceOptions): Promise<DeferredReadState>;
    /** @returns {Promise<DeferredReadState[]>} */
    export function list(): Promise<DeferredReadState[]>;
    /**
     * Reads retained OS scheduling state and the durable last outcome. Interrupted
     * state is explicit and is never silently rescheduled.
     * @param {string} id
     * @returns {Promise<DeferredReadState>}
     */
    export function status(id: string): Promise<DeferredReadState>;
    /**
     * Explicitly resumes an interrupted task after app reconciliation. Preserves
     * the five-attempt budget and replaces its generation, so obsolete callbacks
     * cannot complete the resumed task. The native executor reauthorizes it again.
     * @param {string} id
     * @returns {Promise<DeferredReadState>}
     */
    export function resume(id: string): Promise<DeferredReadState>;
    /**
     * Cancels scheduling and signals a running native executor. An already-running
     * read can finish; its result cannot complete a cancelled or replaced task.
     * @param {string} id
     * @returns {Promise<DeferredReadState>}
     */
    export function cancel(id: string): Promise<DeferredReadState>;
    /**
     * Cancels and releases a retained task record. Preserve any required application
     * receipt before releasing. A later enqueue of this ID starts a new generation.
     * @param {string} id
     * @returns {Promise<DeferredReadState>}
     */
    export function release(id: string): Promise<DeferredReadState>;
    namespace _default {
        export { getSupport };
        export { enqueue };
        export { enqueueMaintenance };
        export { list };
        export { status };
        export { resume };
        export { cancel };
        export { release };
    }
    export default _default;
    export type DeferredReadOptions = {
        /**
         * Stable task identity, 1..128 letters/digits/underscores/hyphens.
         */
        id: string;
        /**
         * Name registered by compiled native app code.
         */
        kind: string;
        /**
         * Opaque configured server identity, never a URL or credential.
         */
        authorityRef: string;
        /**
         * Opaque account identity; authorization is rechecked at execution.
         */
        accountRef: string;
        /**
         * Opaque resource identity.
         */
        targetRef: string;
        /**
         * Opaque operation identity for read-only status/reconciliation.
         */
        operationRef: string;
        /**
         * OS path constraint, not server availability.
         */
        network?: "any" | "unmetered";
        requiresCharging?: boolean;
        requiresBatteryNotLow?: boolean;
        /**
         * Minimum delay, at most seven days. OS/process availability controls timing.
         */
        delayMs?: number;
        /**
         * Read recurrence: 0 for one-shot, or 15 minutes through seven days. Requires delayMs=0.
         */
        intervalMs?: number;
        /**
         * Periodic execution window: at least five minutes or 5% of intervalMs, whichever is larger. Defaults to that minimum; at most intervalMs. Omit for one-shot reads.
         */
        flexMs?: number;
    };
    export type DeferredReadState = DeferredReadOptions & {
        schema: number;
        generation: string;
        jobId: number;
        mode?: "read" | "maintenance";
        phase: string;
        attempts: number;
        updatedAt: number;
        lastOutcome?: string;
        completedRuns?: number;
    };
    export type DeferredReadSupport = {
        /**
         * Present on an unavailable cross-platform support result.
         */
        platform?: string;
        /**
         * Missing runtime backend or platform API restriction; not a permission denial.
         */
        implementation?: "missing" | "restricted";
        /**
         * Stable unavailable reason.
         */
        reason?: string;
        available: boolean;
        registeredKinds: string[];
        /**
         * 32, including terminal records until explicitly released.
         */
        maximumTasks: number;
        /**
         * 5 with exponential backoff starting at 30 seconds.
         */
        maximumAttempts: number;
        /**
         * True for enqueue. Maintenance uses a separate explicitly registered contract.
         */
        readOnly: boolean;
        /**
         * False.
         */
        queuedWrites: boolean;
        /**
         * False.
         */
        backgroundJavaScript: boolean;
        /**
         * False. The app must relaunch, reconcile interrupted state and explicitly resume supported work.
         */
        survivesForceStop: boolean;
        /**
         * True. Successful cycles reset their attempt budget; terminal failures suspend recurrence.
         */
        periodicReads: boolean;
        /**
         * 900000.
         */
        minimumIntervalMs: number;
        /**
         * 300000.
         */
        minimumFlexMs: number;
        /**
         * Explicitly registered native maintenance executors.
         */
        registeredMaintenanceKinds: string[];
        /**
         * Allowed cleanup/revoke operations per maintenance kind.
         */
        maintenanceOperations: {
            [x: string]: string[];
        };
        /**
         * Linux scheduling scope.
         */
        executionScope?: "application-process";
        /**
         * False on Linux; durable records require explicit interruption reconciliation.
         */
        survivesProcessExit?: boolean;
    };
    export type DeferredMaintenanceOptions = Omit<DeferredReadOptions, "operationRef" | "intervalMs" | "flexMs"> & {
        operationRef: "cleanup" | "revoke";
    };
}

See also#

Source repository · Edit this page · View Markdown

Quick links

Type to search across the site. Use the up and down arrow keys to choose a result, Enter to open it, and Escape to close.