durable-execution/build/cancel.d.ts

A durable task engine for running tasks durably and resiliently

import { type Logger } from './logger';
/**
 * A cancel signal is similar to an AbortSignal. It allows you to check for cancellation and
 * register a callback that will be called when the signal is cancelled.
 *
 * @example
 * ```ts
 * async function doSomething() {
 *   const onCancel = () => {
 *     throw new DurableExecutionCancelledError()
 *   }
 *   cancelSignal.onCancelled(onCancel)
 *
 *   try {
 *     ...doWork()
 *   } finally {
 *     cancelSignal.clearOnCancelled(onCancel)
 *   }
 * }
 * ```
 *
 * @category Cancel
 */
export type CancelSignal = {
    /**
     * Register a callback that will be called when the signal is cancelled.
     *
     * @param fn - The callback to register.
     */
    onCancelled: (fn: () => void) => void;
    /**
     * Clear a callback that was registered with `onCancelled`.
     *
     * @param fn - The callback to clear. Should be the same function that was registered with
     * `onCancelled`.
     */
    clearOnCancelled: (fn: () => void) => void;
    /**
     * Check if the signal is cancelled.
     *
     * @returns `true` if the signal is cancelled, `false` otherwise.
     */
    isCancelled: () => boolean;
};
/**
 * Create a cancel signal.
 *
 * @example
 * ```ts
 * const [cancelSignal, cancel] = createCancelSignal()
 * ```
 *
 * @param options - The options for the cancel signal.
 * @param options.abortSignal - An optional abort signal. If provided, the cancel signal will be
 * cancelled when the abort signal is aborted.
 * @param options.logger - The logger to use for the cancel signal. If not provided, a console
 * logger will be created with the default settings.
 *
 * @returns A tuple containing the cancel signal and a function to cancel the signal.
 *
 * @category Cancel
 */
export declare function createCancelSignal({ abortSignal, logger, }?: {
    abortSignal?: AbortSignal;
    logger?: Logger;
}): [CancelSignal, () => void];
/**
 * Create a cancel signal that will be cancelled after a timeout.
 *
 * @param timeoutMs - The timeout in milliseconds.
 * @param options - The options for the cancel signal.
 * @param options.logger - The logger to use for the cancel signal. If not provided, a console
 * logger will be created with the default settings.
 *
 * @returns A cancel signal.
 *
 * @category Cancel
 */
export declare function createTimeoutCancelSignal(timeoutMs: number, { logger }?: {
    logger?: Logger;
}): CancelSignal;
/**
 * Create a cancellable promise. If a signal is provided, the promise will be rejected with a
 * {@link DurableExecutionCancelledError} if the signal is cancelled.
 *
 * @example
 * ```ts
 * const [cancelSignal, cancel] = createCancelSignal()
 * const promise = createCancellablePromise(doSomething(), cancelSignal)
 *
 * cancel() // Cancels the promise if it is not already resolved
 * ```
 *
 * @param promise - The promise to cancel.
 * @param signal - A signal to cancel the promise.
 * @param cancelledError - An optional error to use when the promise is cancelled. If not provided,
 * a `DurableExecutionCancelledError` will be used. If the error is a `DurableExecutionError`, it
 * will be returned as is, otherwise a `DurableExecutionCancelledError` will be created with the
 * error message.
 *
 * @returns A promise that will be rejected with a `DurableExecutionCancelledError` if the signal
 * is cancelled.
 *
 * @category Cancel
 */
export declare function createCancellablePromise<T>(promise: Promise<T>, signal?: CancelSignal, cancelledError?: Error): Promise<T>;
//# sourceMappingURL=cancel.d.ts.map