durable-execution/build/storage.d.ts

A durable task engine for running tasks durably and resiliently

import { type DurableExecutionErrorStorageObject } from './errors';
import { type Serializer } from './serializer';
import { type DurableChildTaskExecution, type DurableChildTaskExecutionErrorStorageObject, type DurableTaskExecution, type DurableTaskExecutionStatusStorageObject, type DurableTaskRetryOptions } from './task';
/**
 * A durable storage with support for transactions. Running multiple transactions in parallel
 * must be supported. If that is not possible, use {@link createTransactionMutex} to run
 * transactions sequentially.
 *
 * @category Storage
 */
export type DurableStorage = {
    withTransaction: <T>(fn: (tx: DurableStorageTx) => Promise<T>) => Promise<T>;
};
/**
 * A durable storage transaction. It is used to perform multiple operations on the storage in a
 * single transaction.
 *
 * @category Storage
 */
export type DurableStorageTx = {
    /**
     * Insert durable task executions.
     *
     * @param executions - The durable task executions to insert.
     */
    insertTaskExecutions: (executions: Array<DurableTaskExecutionStorageObject>) => void | Promise<void>;
    /**
     * Get durable task execution ids.
     *
     * @param where - The where clause to filter the durable task executions.
     * @param limit - The maximum number of durable task execution ids to return.
     * @returns The ids of the durable task executions.
     */
    getTaskExecutionIds: (where: DurableTaskExecutionStorageWhere, limit?: number) => Array<string> | Promise<Array<string>>;
    /**
     * Get durable task executions.
     *
     * @param where - The where clause to filter the durable task executions.
     * @param limit - The maximum number of durable task executions to return.
     * @returns The durable task executions.
     */
    getTaskExecutions: (where: DurableTaskExecutionStorageWhere, limit?: number) => Array<DurableTaskExecutionStorageObject> | Promise<Array<DurableTaskExecutionStorageObject>>;
    /**
     * Update durable task executions.
     *
     * @param where - The where clause to filter the durable task executions.
     * @param update - The update object.
     * @returns The ids of the durable task executions that were updated.
     */
    updateTaskExecutions: (where: DurableTaskExecutionStorageWhere, update: DurableTaskExecutionStorageObjectUpdate) => Array<string> | Promise<Array<string>>;
};
/**
 * Create a transaction mutex. Use this to run {@link DurableStorage.withTransaction} in a durable
 * storage sequentially. Only use this if the storage does not support running transactions in
 * parallel.
 *
 * @example
 * ```ts
 * const mutex = createTransactionMutex()
 *
 * function createStorage() {
 *   return {
 *     withTransaction: async (fn) => {
 *       await mutex.acquire()
 *       try {
 *         // ... run transaction logic that won't run in parallel with other transactions
 *       } finally {
 *         mutex.release()
 *       }
 *     },
 *   }
 * }
 * ```
 *
 * @category Storage
 */
export declare function createTransactionMutex(): TransactionMutex;
/**
 * A transaction mutex returned by {@link createTransactionMutex}.
 *
 * @category Storage
 */
export type TransactionMutex = {
    acquire: () => Promise<void>;
    release: () => void;
};
export declare function updateTaskExecutionsWithLimit(tx: DurableStorageTx, where: DurableTaskExecutionStorageWhere, update: DurableTaskExecutionStorageObjectUpdate, limit?: number): Promise<Array<string>>;
/**
 * A storage object for a durable task execution.
 *
 * @category Storage
 */
export type DurableTaskExecutionStorageObject = {
    /**
     * The root task of the execution.
     */
    rootTask?: {
        taskId: string;
        executionId: string;
    };
    /**
     * The parent task of the execution.
     */
    parentTask?: {
        taskId: string;
        executionId: string;
        isFinalizeTask?: boolean;
    };
    /**
     * The id of the task.
     */
    taskId: string;
    /**
     * The id of the execution.
     */
    executionId: string;
    /**
     * The retry options of the task execution.
     */
    retryOptions: DurableTaskRetryOptions;
    /**
     * The sleep ms before run of the task execution.
     */
    sleepMsBeforeRun: number;
    /**
     * The timeout ms of the task execution.
     */
    timeoutMs: number;
    /**
     * The run input of the task execution.
     */
    runInput: string;
    /**
     * The run output of the task execution.
     */
    runOutput?: string;
    /**
     * The output of the task execution.
     */
    output?: string;
    /**
     * The number of children tasks that have been completed.
     */
    childrenTasksCompletedCount: number;
    /**
     * The children tasks of the execution. It is only present for waiting_for_children_tasks status.
     */
    childrenTasks?: Array<DurableChildTaskExecution>;
    /**
     * The errors of the children tasks. It is only present for children_tasks_failed status. In case
     * of multiple errors, the order of errors is not defined.
     */
    childrenTasksErrors?: Array<DurableChildTaskExecutionErrorStorageObject>;
    /**
     * The finalize task child execution of the execution.
     */
    finalizeTask?: DurableChildTaskExecution;
    /**
     * The error of the finalize task execution. It is only present for finalize_task_failed status.
     */
    finalizeTaskError?: DurableExecutionErrorStorageObject;
    /**
     * The error of the execution.
     */
    error?: DurableExecutionErrorStorageObject;
    /**
     * The status of the execution.
     */
    status: DurableTaskExecutionStatusStorageObject;
    /**
     * Whether the execution is closed. Once the execution is finished, a background process
     * will update the status of its parent task if present and children if present.
     */
    isClosed: boolean;
    /**
     * Whether the execution needs a promise cancellation.
     */
    needsPromiseCancellation: boolean;
    /**
     * The number of attempts the execution has been retried.
     */
    retryAttempts: number;
    /**
     * The start time of the task execution. Used for delaying the execution. Set on enqueue.
     */
    startAt: Date;
    /**
     * The time the task execution started. Set on start.
     */
    startedAt?: Date;
    /**
     * The time the task execution finished. Set on finish.
     */
    finishedAt?: Date;
    /**
     * The time the task execution expires. It is used to recover from process failures. Set on
     * start.
     */
    expiresAt?: Date;
    /**
     * The time the task execution was created.
     */
    createdAt: Date;
    /**
     * The time the task execution was updated.
     */
    updatedAt: Date;
};
export declare function createDurableTaskExecutionStorageObject({ now, rootTask, parentTask, taskId, executionId, retryOptions, sleepMsBeforeRun, timeoutMs, runInput, }: {
    now: Date;
    rootTask?: {
        taskId: string;
        executionId: string;
    };
    parentTask?: {
        taskId: string;
        executionId: string;
        isFinalizeTask?: boolean;
    };
    taskId: string;
    executionId: string;
    retryOptions: DurableTaskRetryOptions;
    sleepMsBeforeRun: number;
    timeoutMs: number;
    runInput: string;
}): DurableTaskExecutionStorageObject;
/**
 * The where clause for durable task execution storage. Storage objects are filtered by the where
 * clause before being returned.
 *
 * Storage implementations should index based on these clauses to optimize the performance of
 * the storage operations. Suggested indexes:
 * - uniqueIndex(execution_id)
 * - index(status, isClosed, expiresAt)
 * - index(status, startAt)
 *
 * @category Storage
 */
export type DurableTaskExecutionStorageWhere = {
    type: 'by_execution_ids';
    executionIds: Array<string>;
    statuses?: Array<DurableTaskExecutionStatusStorageObject>;
    needsPromiseCancellation?: boolean;
} | {
    type: 'by_statuses';
    statuses: Array<DurableTaskExecutionStatusStorageObject>;
    isClosed?: boolean;
    expiresAtLessThan?: Date;
} | {
    type: 'by_start_at_less_than';
    statuses: Array<DurableTaskExecutionStatusStorageObject>;
    startAtLessThan: Date;
};
/**
 * The update object for a durable task execution. See {@link DurableTaskExecutionStorageObject}
 * for more details about the fields.
 *
 * @category Storage
 */
export type DurableTaskExecutionStorageObjectUpdate = {
    runOutput?: string;
    output?: string;
    childrenTasksCompletedCount?: number;
    childrenTasks?: Array<DurableChildTaskExecution>;
    childrenTasksErrors?: Array<DurableChildTaskExecutionErrorStorageObject>;
    finalizeTask?: DurableChildTaskExecution;
    finalizeTaskError?: DurableExecutionErrorStorageObject;
    error?: DurableExecutionErrorStorageObject;
    unsetError?: boolean;
    status?: DurableTaskExecutionStatusStorageObject;
    isClosed?: boolean;
    needsPromiseCancellation?: boolean;
    retryAttempts?: number;
    startAt?: Date;
    startedAt?: Date;
    finishedAt?: Date;
    expiresAt?: Date;
    unsetExpiresAt?: boolean;
    updatedAt: Date;
};
/**
 * Convert a durable task execution storage object to a durable task execution.
 *
 * @category Storage
 */
export declare function convertTaskExecutionStorageObjectToTaskExecution<TOutput>(execution: DurableTaskExecutionStorageObject, serializer: Serializer): DurableTaskExecution<TOutput>;
export declare function getDurableTaskExecutionStorageObjectParentError(execution: DurableTaskExecutionStorageObject): DurableExecutionErrorStorageObject;
/**
 * Create a durable storage that stores the task executions in memory. This is useful for testing
 * and for simple use cases. Do not use this for production. It is not durable or resilient.
 *
 * @category Storage
 */
export declare function createInMemoryStorage({ enableDebug, }?: {
    enableDebug?: boolean;
}): DurableStorage & {
    save: (saveFn: (s: string) => Promise<void>) => Promise<void>;
    load: (loadFn: () => Promise<string>) => Promise<void>;
    logAllTaskExecutions: () => void;
};
//# sourceMappingURL=storage.d.ts.map