Skip to content

MicroTask

Jump to bottom
Eugene Lazutkin edited this page May 7, 2026 · 9 revisions

Description

The MicroTask class is a utility designed to encapsulate a function (fn) that can be executed later. It allows for the creation of tasks that can be queued for execution in the microtask queue, ensuring they run after the current operation completes but before the next rendering.

Usually MicroTask is used as a base class for other classes that need to schedule tasks for execution in the microtask queue.

Key features

  • Encapsulation: Wraps a function for deferred execution.
  • Microtask Scheduling: Can be used to schedule tasks that need to run immediately after the current script but before any rendering.
  • Promise Support: Supports creating and resolving promises for asynchronous task completion.

Technical specifications

MicroTask is available as a named and default export.

const task = new MicroTask(fn);

Constructor parameters

  • fn: The function to be executed later. It will be called with queue-specific arguments, and its return value will be ignored by enqueue(), but it can be used by schedule() to resolve the task's promise.

Instance properties

  • fn: The function to be executed later. It will be called with queue-specific arguments, and its return value will be ignored by enqueue(), but it can be used by schedule() to resolve the task's promise.
  • isCanceled: A boolean indicating whether the task has been canceled.

Instance getters

  • promise: A promise that resolves when the task is executed, or null if makePromise() hasn't been called yet.
  • settled: A boolean indicating whether the task has been settled (resolved or rejected).
  • cancelError: The error supplied to the first cancel(error) call, or null. Useful for inspecting why a non-promised task was canceled when there's no rejection to carry the cause.

Instance methods

  • makePromise(): Creates the promise lazily. Idempotent — repeat calls return this without changing state. If cancel() was called before makePromise(), the freshly-created promise is settled immediately as a CancelTaskError rejection, carrying any stored cancelError as cause. Returns the task instance.
  • resolve(value): Resolves the task's promise with the specified value. Returns the task instance. Throws if makePromise() hasn't been called — without a promise to resolve, the value would be silently dropped (and any later await task.makePromise().promise would hang).
  • cancel(error): Cancels the task. Always sets isCanceled = true so queues skip the task. If makePromise() has been called, also rejects the promise with a CancelTaskError. The first error passed is stored on the instance and accessible via cancelError; if cancel(error) runs before makePromise(), the stored error is replayed when the promise is later created. Returns the task instance.

Usage instructions

To use the MicroTask class, import it into your project and create an instance with the desired function:

import MicroTask from 'time-queues/MicroTask.js';

const logTask = new MicroTask(() => console.log('Task executed!'));

// Execute the task
logTask.fn(); // Will log 'Task executed!'
logTask.promise; // null
logTask.isCanceled; // false

Troubleshooting

  • Function Not Executing: Ensure that the function passed to MicroTask is defined and can be executed without errors.
  • Microtask Queue Issues: If tasks are not executing as expected, ensure that the microtask queue is being processed correctly in your environment.
  • resolve() throws: Call makePromise() first, or use schedule() (which makes the promise eagerly).
  • cancel(error) reason lost: If you cancel a task without a promise and inspect later, read task.cancelError. If you call makePromise() after cancellation, the stored error is replayed as cause on the rejection automatically.

See Also

Clone this wiki locally