use-scheduler-post-task

Post prioritized tasks with the Prioritized Task Scheduling API.


Package	`@vizejs/composable/use-scheduler-post-task`
Own the source	`vize lib pull composable:use-scheduler-post-task`
Runtime exports	`useSchedulerPostTask`
Gzip budget	2816 B

Usage

import { useSchedulerPostTask } from "@vizejs/composable/use-scheduler-post-task";

Runtime contract

Utility	Category	Stability	SSR	Hydration	Cleanup	Targets	Host globals	Uses
`useSchedulerPostTask`	timing	experimental	deterministic-fallback	caller-managed	caller, reactive-scope	web, desktop	`AbortController`, `window`	`tryOnScopeDispose`

API

`useSchedulerPostTask`

Post prioritized tasks with the Prioritized Task Scheduling API. Every task gets its own controller (a TaskController when available), so setPriority re-prioritizes pending tasks and abort rejects them; pending tasks are aborted when the owning reactive scope stops (their promises reject with an AbortError; outside a scope the caller owns abort()). Fallback without scheduler: tasks run from setTimeout(delay) in timer (FIFO) order. Priorities are ignored, so a later "user-blocking" task does not overtake an earlier "background" one, and tasks do not yield to rendering or input the way native tasks do. Server rendering: nothing is scheduled, supported is false and postTask rejects.

function useSchedulerPostTask( options: UseSchedulerPostTaskOptions = {}, ): SchedulerPostTaskControls

const { postTask } = useSchedulerPostTask();
const total = await postTask(() => expensiveSum(rows), { priority: "background" });

Types

`SchedulerPostTaskInit`

Options passed to SchedulerHost.postTask.

Member	Type	Description
`priority`?	`SchedulerTaskPriority`	Fixed task priority; overrides the signal's priority.
`delay`?	`number`	Delay before the task is queued, in milliseconds.
`signal`?	`AbortSignal`	Aborts the task (a `TaskSignal` also carries a mutable priority).

`SchedulerHost`

Minimal scheduler global.

Member	Type	Description
`postTask`	`(callback: () => Result \| PromiseLike<Result>, options?: SchedulerPostTaskInit) => Promise<Result>`	Queue `callback`; resolves with its result, rejects with the abort reason.
`yield`?	`() => Promise<void>`	Yield to the event loop, continuing with inherited priority.

`TaskControllerLike`

Minimal TaskController instance.

Member	Type	Description
`signal`	`AbortSignal`	Signal handed to `postTask`.
`abort`	`(reason?: unknown) => void`	Abort every task using this controller's signal.
`setPriority`	`(priority: SchedulerTaskPriority) => void`	Change the priority of every task using this controller's signal.

`UseSchedulerPostTaskOptions`

Options for useSchedulerPostTask.

Member	Type	Description
`scheduler`?	`MaybeRefOrGetter<SchedulerHost \| null \| undefined>`	Prioritized Task Scheduling capability for alternate runtimes and tests.
`TaskController`?	`MaybeRef<TaskControllerHost \| null \| undefined>`	`TaskController` constructor. A ref (not a getter) because the host is a constructor function. Without it tasks use a plain `AbortController` and receive the priority explicitly, so `setPriority` cannot re-prioritize them.
`timers`?	`MaybeRefOrGetter<TimeoutScheduler \| null \| undefined>`	Timers used when `scheduler` is missing. Without timers (server rendering) `postTask` rejects.
`priority`?	`SchedulerTaskPriority`	Initial priority of tasks posted without an explicit priority.

`PostTaskCallOptions`

Per-call options of SchedulerPostTaskControls.postTask.

Member	Type	Description
`priority`?	`SchedulerTaskPriority`	Fixed priority for this task; `setPriority` no longer affects it.
`delay`?	`number`	Delay before the task is queued, in milliseconds.
`signal`?	`AbortSignal`	Aborts this task only.

`SchedulerPostTaskControls`

Reactive state and actions returned by useSchedulerPostTask.

Member	Type	Description
`supported`	`ComputedRef<boolean>`	Whether the native `scheduler.postTask` API is available.
`priority`	`Readonly<ShallowRef<SchedulerTaskPriority>>`	Priority applied to tasks posted without an explicit priority.
`pending`	`Readonly<ShallowRef<number>>`	Number of posted tasks that have not settled.
`postTask`	`<Result>( callback: () => Result \| PromiseLike<Result>, options?: PostTaskCallOptions, ) => Promise<Result>`	Post a task.
`setPriority`	`(priority: SchedulerTaskPriority) => void`	Re-prioritize the composable and every pending task without a fixed priority.
`abort`	`(reason?: unknown) => void`	Abort every pending task of this composable.
`yield`	`() => Promise<void>`	Yield to the event loop: `scheduler.yield()`, else a zero-delay timer, else a resolved promise.