@excentone/spfx-react/lib/hooks/usePipeline/usePipeline.types.d.ts

Contains custom ReactJs components and hooks intended to use when developing SharePoint Framework (SPFx) Web components.

import { Dispatch, SetStateAction, ReactText } from "react";
import { ActionWithoutArgs, AsyncFunc } from "@excentone/spfx-utilities";
/**
 * The status of pipeline execution.
 */
export declare type ExecutionStatus = 'Idle' | 'Pending' | 'Executing' | 'Completed';
/**
 * The result of pipeline execution.
 */
export declare type ExecutionResult = 'Unknown' | 'Success' | 'Success with errors' | 'Failed';
/**
 * The type of reducer action.
 */
export declare type ActionType = 'PREPEND' | 'APPEND' | 'INSERT' | 'UPDATE' | 'CLEAR' | 'SET' | 'SET_STATUS';
/**
 * Delegate to invoke for the job.
 */
export declare type JobHandler<TValues = any> = (values: TValues, index?: number, details?: IJobDetails<TValues>, updater?: Dispatch<SetStateAction<IJobDetails<TValues>>>) => Promise<TValues>;
/**
 * Delegate to handle error thrown by the job/pipeline.
 */
export declare type ErrorHandler<TValues = any, TError = any> = Dispatch<IPipelineError<TValues, TError>>;
/**
 * Delegate to invoke for job events (start, done, finished).
 */
export declare type JobEventHandler<TValues = any> = (details: IJobDetails<TValues>, index?: number) => void;
export interface IPipelineSharedProps<TValues = any> {
    /**
   * The name of the pipeline. This can be use when displaying the pipeline execution progress.
   */
    name?: string;
    /**
     * Jobs to be performed sequentially when the pipeline is executed/started.
     */
    jobs: IJob<TValues>[];
    /**
   * Any data to be used by the pipeline.
   */
    data?: any;
}
export interface IPipelineValuesProp<TValues = any> {
    /**
     * The current values.
     */
    values?: TValues;
}
export interface IPipelineExecutionState {
    /**
     * Status of the pipeline.
     */
    status: ExecutionStatus;
    /**
     * The current index of the job being performed.
     */
    currentIndex: number;
}
/**
 * State values of the pipeline.
 */
export interface IPipelineState<TValues = any> extends IPipelineExecutionState, IPipelineSharedProps<TValues> {
}
/**
 * The details/metadata of the job.
 */
export interface IJobDetails<TValues = any> extends IPipelineValuesProp<TValues> {
    /**
     * The key of the job details
     */
    key?: ReactText;
    /**
     * The title of the job.
     */
    title: string;
    /**
     * The descriptions of the sub-actions under the job.
     */
    subActionsTitles?: string[];
    /**
     * Whether the job has error or not.
     */
    hasError?: boolean;
    /**
     * Error message for thrown when job was executed.
     */
    errorMessage?: string;
    /**
     * Whether to ignore the error and proceed with the next job on the pipeline, or stop the execution of pipeline when error is thrown.
     */
    ignoreOnError?: boolean;
    /**
     * Whether the job was skipped or not.
     */
    skipped?: boolean;
    /**
     * Any data to be used by the job.
     */
    data?: any;
    /**
     * The current execution status of the job.
     */
    status?: ExecutionStatus;
}
export interface IJob<TValues = any> extends IJobDetails<TValues> {
    /**
     * The function to be executed for the job.
     */
    handler: JobHandler<TValues>;
    /**
     * Whether to skip the job or not.
     */
    skip?: boolean | ((values: TValues, details?: IJobDetails<TValues>) => boolean);
}
/**
 * Event callbacks for executing jobs.
 */
export interface IJobEvents<TValues = any> {
    /**
     * Callback when the job execution is starting.
     */
    onJobStart?: JobEventHandler<TValues>;
    /**
     * Callback when the job execution is finished, whether successful or not.
     */
    onJobFinished?: JobEventHandler<TValues>;
    /**
     * Callback when the job execution succeeded.
     */
    onJobSuccess?: JobEventHandler<TValues>;
    /**
     * Callback when the job execution failed.
     */
    onJobFailed?: ErrorHandler<TValues>;
}
/**
 * Information for the error thrown during pipeline execution.
 */
export interface IPipelineError<TValues = any, TError = any> extends IPipelineValuesProp<TValues> {
    /**
     * The original error object.
    */
    error: TError;
    /**
     * The current index of when the error occurred.
     */
    currentIndex: number;
    /**
     * The details of the job that threw the error.
     */
    jobDetails: IJobDetails<TValues>;
}
/**
 * Result of executing the pipeline.
 */
export interface IPipelineResult<TValues = any> extends IPipelineValuesProp<TValues> {
    /**
     * The errors throw by one or more jobs after the execution.
     */
    errors: IPipelineError<TValues>[];
    /**
     * Pipeline result.
     */
    result: ExecutionResult;
}
/**
 * Event callbacks for executing the pipeline.
 */
export interface IPipelineEvents<TValues = any> {
    /**
     * Callback when the pipeline execution is starting.
     */
    onPipelineStart?: (values: TValues, state?: IPipelineState<TValues>) => void;
    /**
     * Callback when the pipeline execution is finished, whether successful or not.
     */
    onPipelineFinished?: (result: IPipelineResult<TValues>, state?: IPipelineState<TValues>) => void;
    /**
     * Callback when the pipeline execution succeeded.
     */
    onPipelineSuccess?: Dispatch<TValues>;
    /**
     * Callback when the pipeline execution failed.
     */
    onPipelineFailed?: ErrorHandler<TValues>;
}
export interface IPipelineActionEvents<TValues = any> extends IPipelineEvents<TValues>, IJobEvents<TValues> {
}
/**
 * Options available when creating the pipeline hook.
 */
export interface IPipelineHookOptions<TValues = any> extends IPipelineActionEvents<TValues>, IPipelineSharedProps<TValues>, IPipelineValuesProp<TValues> {
    /**
     * The delay (in milliseconds) before the next job executes.
     */
    jobExecutionDelay?: number;
    /**
     * A callback for getting/extracting the error message from the error object.
     * @param error The error object.
     * @returns A {@link Promise} that resolve to string containing the error message.
     */
    getErrorMessage?: (error: any) => Promise<string>;
}
export interface IPipelineOperations<TValues = any> {
    start: ActionWithoutArgs;
    startAsync: AsyncFunc<void>;
    run: (values: TValues) => void;
    runAsync: (values: TValues) => Promise<void>;
}
export declare type PipelineHook<TValues = any> = Readonly<IPipelineOperations<TValues> & IPipelineState<TValues>>;