@sfdx-falcon/task/lib/task.d.ts

Specialized abstraction of a single Listr Task. Part of the SFDX-Falcon Library.

/**
 * @author        Vivek M. Chawla <@VivekMChawla>
 * @copyright     2019, Vivek M. Chawla / Salesforce. All rights reserved.
 * @license       BSD-3-Clause For full license text, see the LICENSE file in the repo root or
 *                `https://opensource.org/licenses/BSD-3-Clause`
 * @file          packages/task/src/task.ts
 * @summary       Exports `SfdxFalconTask`, an abstraction of a single Listr Task.
 * @description   Exports `SfdxFalconTask`, an abstraction of a single Listr Task.
 */
import { ListrContext } from 'listr';
import { ListrTask } from 'listr';
import { ListrTaskWrapper } from 'listr';
import { Observable } from 'rxjs';
import { Subscriber } from 'rxjs';
import { TaskStatusMessage } from '@sfdx-falcon/status';
import { ExternalContext } from '@sfdx-falcon/builder';
import { ErrorOrResult } from '@sfdx-falcon/status';
import { TaskStatusOptions } from '@sfdx-falcon/status';
/**
 * Type. Alias for the `this` context from the caller.
 */
export declare type Context = any;
/**
 * Type. Represents an externally defined `Task` function. Extends the standard `ListrTask` function type by adding a `sharedData` parameter after the `thisTask` parameter.
 */
export declare type ExtTaskFunction<CTX = ListrContext> = (taskCtx?: CTX, taskObj?: ListrTaskWrapper<CTX>, taskStatus?: TaskStatusMessage, extCtx?: ExternalContext) => Promise<void>;
/**
 * Type. Represents an externally defined `Skip` function. Extends the standard `ListrSkip` function type by adding a `sharedData` parameter after the `listrContext` parameter.
 */
export declare type ExtSkipFunction<CTX = ListrContext> = (ctx?: CTX, extCtx?: ExternalContext) => void | boolean | string | Promise<boolean>;
/**
 * Type. Represents an externally defined `Enabled` function. Extends the standard `ListrEnabled` function type by adding a `sharedData` parameter after the `listrContext` parameter.
 */
export declare type ExtEnabledFunction<CTX = ListrContext> = (ctx?: CTX, extCtx?: ExternalContext) => boolean | Promise<boolean> | Observable<boolean>;
/**
 * Interface. Options that can be set during the construction of an `ObservableTaskResult` object.
 */
export interface ObservableTaskResultOptions {
    /** Collection of external context mechanisms. Passed directly */
    extCtx: ExternalContext;
    /** The `ListrContext` associated with the execution of a `ListrTask` at runtime. Passed as the first parameter into all `ListrTask` functions. */
    taskCtx: ListrContext;
    /** Runtime wrapper around the `ListrTask` that's being executed. Allows for runtime modification of various task properties. */
    taskObj: ListrTaskWrapper;
    /** The RxJS Subscriber that this `ObservableTaskResult` should be hooked into */
    subscriber: Subscriber<unknown>;
    /** The baseline status message for this `ObservableTaskResult`. */
    statusMsg: string;
    /** The minimum amount of time, in seconds, that this `ObservableTaskResult` should run. Useful for keeping a status message on screen long enough for the user to see it. */
    minRuntime: number;
    /** Specifies whether or not the status message shown by the `ListrTask` will be continually updated with an "elapsed seconds" counter. */
    showTimer: boolean;
}
/**
 * Interface. Specifies which elements of `ExternalContext` are required to be present to ensure
 * that an error won't be thrown upon construction of an `SfdxFalconTask` object.
 */
export interface ExternalContextRequirements {
    /** Determines whether or not the `sharedData` context item is required. Ensures that a shared data `object` must be part of the Context when a `SfdxFalconTask` is constructed. */
    sharedData?: boolean;
    /** Determines whether or not the `parentResult` context item is required. Ensures that an `SfdxFalconResult` object must be part of the Context when a `SfdxFalconTask` is constructed. */
    parentResult?: boolean;
    /** Determines whether or not the `generatorStatus` context item is required. Ensures that a `GeneratorStatus` object must be part of the Context when a `SfdxFalconTask` is constructed. */
    generatorStatus?: boolean;
}
/**
 * Interface. Options that can be set during the construction of an `SfdxFalconTask` object.
 */
export interface SfdxFalconTaskOptions<CTX = ListrContext> {
    /** The title of the task. */
    title: string;
    /** Collection of external context mechanisms that this `SfdxFalconTask` can use to communicate in/out with the calling code. */
    extCtx: ExternalContext;
    /** Defines which `ExternalContext` items are required by this task. Task constructor will throw an error if required `ExternalContext` items are not present. */
    extCtxReqs?: ExternalContextRequirements;
    /** The task that the user wants to execute. Must be contained within a promise. */
    task: ExtTaskFunction<CTX>;
    /** Function that determines whether this task should be skipped. */
    skip?: ExtSkipFunction<CTX>;
    /** Function that determines whether this task should be enabled. */
    enabled?: ExtEnabledFunction<CTX>;
    /** The baseline status message for this `SfdxFalconTask`. */
    statusMsg?: string;
    /** The minimum amount of time, in seconds, that this `SfdxFalconTask` should run. Useful for keeping a status message on screen long enough for the user to see it. */
    minRuntime?: number;
    /** Specifies whether or not the status message shown by the `SfdxFalconTask` will be continually updated with an "elapsed seconds" counter. */
    showTimer?: boolean;
}
/**
 * Interface. Models the information stored as the "detail" of an `SfdxFalconResult` that's contained
 * by an `ObservableTaskResult` object.
 */
export interface TaskResultDetail {
    /** Reference to the `ExternalContext` object which may contain a variety of objects that connect back to the environment the `ObservableTaskResult` runs in. */
    extCtx: ExternalContext;
    /** Special local task execution context managed by Listr */
    taskCtx: ListrContext;
    /** Reference to the specific Listr Task that is associated with the `SfdxFalconTask` for which this detail is connected. */
    taskObj: ListrTaskWrapper;
    /** Reference to the `TaskStatusOptions` object used by the  `TaskStatus` class to power status messages for the `SfdxFalconTask` for which this detail is connected. */
    statusMsgs: TaskStatusOptions;
}
/**
 * @class       ObservableTaskResult
 * @description Creates the structure needed to wrap the output of any task as an `SfdxFalconResult`
 *              while also managing access to the Observer that Listr uses to monitor the progress
 *              of a task.
 * @public
 */
export declare class ObservableTaskResult {
    private _extCtx;
    private _taskCtx;
    private _taskObj;
    private _subscriber;
    private _minRunTime;
    private _showTimer;
    private _taskResult;
    private _taskResultDetail;
    private _taskStatusMessage;
    private _taskStatusMessages;
    private _notificationTimer;
    /** Represents the Status Message for the associated `SfdxFalconTask`. Allows external logic to read and set status messages. */
    readonly status: TaskStatusMessage;
    /**
     * @constructs  ObservableTaskResult
     * @param       {ObservableTaskResultOptions} opts  Required. Options that
     *              determine how this `ObservableTaskResult` will be constructed.
     * @description Constructs an `ObservableTaskResult` object.
     * @public
     */
    constructor(opts: ObservableTaskResultOptions);
    /**
     * @method      finalizeFailure
     * @param       {ErrorOrResult} errorOrResult Required.
     * @returns     {void}
     * @description Finalizes this `ObservableTaskResult` in a manner that
     *              indicates the associated task was NOT successful.
     * @public
     */
    finalizeFailure(errorOrResult: ErrorOrResult): void;
    /**
     * @method      finalizeSuccess
     * @returns     {void}
     * @description Finalizes this `ObservableTaskResult` in a manner that
     *              indicates the associated task was successful.
     * @public
     */
    finalizeSuccess(): void;
    /**
     * @method      remainingRuntime
     * @returns     {number}
     * @description Finds out how long it's been since the Task Result started and
     *              subtracts that value from the minimum runtime (`_minRunTime`)
     *              to compute the remaining runtime.
     * @public
     */
    remainingRuntime(): number;
}
/**
 * @class       SfdxFalconTask
 * @description Abstraction of a single Listr Task with a lot of extra functionality bundled in.
 * @public
 */
export declare class SfdxFalconTask<CTX = ListrContext> {
    private _title;
    private _extTask;
    private _extSkip;
    private _extEnabled;
    private _task;
    private _skip;
    private _enabled;
    private _extCtx;
    private _statusMsg;
    private _minRuntime;
    private _showTimer;
    private _otr;
    /**
     * @constructs  SfdxFalconTask
     * @param       {SfdxFalconTaskOptions} opts  Required. Options used to
     *              construct this instance of an `SfdxFalconTask` object.
     * @description Constructs an `SfdxFalconTask` object.
     * @public
     */
    constructor(opts: SfdxFalconTaskOptions);
    /**
     * @method      build
     * @returns     {ListrTask}
     * @description Builds an Observable `ListrTask` object based on the info
     *              that the caller provided to us when this `SfdxFalconTask`
     *              object was constructed.
     * @public
     */
    build(): ListrTask;
}