universal-common/Task.d.ts

Library that provides useful missing base class library functionality.

/**
 * Represents a unit of work that can be executed asynchronously.
 *
 * The Task class provides a higher-level abstraction over JavaScript Promises,
 * with additional features like explicit state tracking and manual execution control.
 * This pattern is inspired by the Task pattern from languages like C#.
 *
 * @example
 * // Create a task that will execute later
 * const task = new Task(() => {
 *   return fetch('https://api.example.com/data');
 * });
 *
 * // Later, start the task and handle its result
 * task.start();
 * task.then(response => response.json())
 *     .then(data => console.log(data));
 */
export default class Task {
    /**
     * Represents the state of a task that has not yet completed.
     * @readonly
     * @type {string}
     */
    static readonly get STATE_PENDING(): string;
    /**
     * Represents the state of a task that has completed successfully.
     * @readonly
     * @type {string}
     */
    static readonly get STATE_FULFILLED(): string;
    /**
     * Represents the state of a task that has completed with an error.
     * @readonly
     * @type {string}
     */
    static readonly get STATE_REJECTED(): string;
    /**
     * Creates a Promise that resolves after the specified delay.
     *
     * @param {number} ms - The delay in milliseconds
     * @returns {Promise<void>} A Promise that resolves after the delay
     *
     * @example
     * // Wait for 2 seconds
     * await Task.delay(2000);
     * console.log("2 seconds have passed");
     */
    static delay(ms: number): Promise<void>;
    /**
     * Creates a new Task instance.
     *
     * @param {Function} action - The function to execute when the task starts.
     *                            This can return a value or a Promise.
     * @throws {TypeError} If action is not a function
     */
    constructor(action: Function);
    /**
     * Gets the current state of the task.
     *
     * @returns {string} The current state (Pending, Fulfilled, or Rejected)
     */
    get state(): string;
    /**
     * Registers a callback to be executed when the task completes successfully.
     * This method also implicitly starts the task if it hasn't been started yet.
     *
     * @param {Function} action - The callback function to execute with the task's result
     * @returns {Promise} A Promise that resolves with the result of the callback
     *
     * @example
     * const task = new Task(() => 42);
     * task.then(result => console.log(result)); // Outputs: 42
     */
    then(action: Function): Promise<any>;
    /**
     * Explicitly starts the task execution.
     *
     * @returns {void}
     * @throws {InvalidOperationError} If the task has already been started
     *
     * @example
     * const task = new Task(() => {
     *   console.log("Task is running");
     * });
     * task.start(); // Task begins execution
     */
    start(): void;
    /**
     * Waits synchronously for the task to complete.
     *
     * @returns {void}
     *
     * @warning This method uses a busy-wait approach which can block the JavaScript thread.
     * It should only be used in environments where blocking is acceptable (e.g., Node.js
     * with worker threads). Do not use this in browser environments as it will freeze the UI.
     *
     * @example
     * // In a non-browser environment:
     * const task = new Task(() => {
     *   return someExpensiveOperation();
     * });
     * task.start();
     * task.wait(); // Blocks until the task completes
     * console.log("Task is done!");
     */
    wait(): void;
    promise: Promise<any>;
    #private;
}