@temporalio/client/lib/nexus-types.d.ts

Temporal.io SDK Client sub-package

import type { Duration, SearchAttributePair, SearchAttributeType, TypedSearchAttributes } from '@temporalio/common';
import type { TypedSearchAttributeValue } from '@temporalio/common/lib/search-attributes';
import type { temporal } from '@temporalio/proto';
import type { Replace } from '@temporalio/common/lib/type-helpers';
/**
 * Defines whether to allow re-using an operation ID from a previously *completed* Nexus operation.
 *
 * See {@link NexusOperationIdConflictPolicy} for handling ID duplication with a *running* operation.
 */
export declare const NexusOperationIdReusePolicy: {
    readonly ALLOW_DUPLICATE: "ALLOW_DUPLICATE";
    readonly ALLOW_DUPLICATE_FAILED_ONLY: "ALLOW_DUPLICATE_FAILED_ONLY";
    readonly REJECT_DUPLICATE: "REJECT_DUPLICATE";
};
export type NexusOperationIdReusePolicy = (typeof NexusOperationIdReusePolicy)[keyof typeof NexusOperationIdReusePolicy];
export declare const encodeNexusOperationIdReusePolicy: (input: "ALLOW_DUPLICATE" | "ALLOW_DUPLICATE_FAILED_ONLY" | "REJECT_DUPLICATE" | temporal.api.enums.v1.NexusOperationIdReusePolicy | "NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE" | "NEXUS_OPERATION_ID_REUSE_POLICY_ALLOW_DUPLICATE_FAILED_ONLY" | "NEXUS_OPERATION_ID_REUSE_POLICY_REJECT_DUPLICATE" | null | undefined) => temporal.api.enums.v1.NexusOperationIdReusePolicy | undefined, decodeNexusOperationIdReusePolicy: (input: temporal.api.enums.v1.NexusOperationIdReusePolicy | null | undefined) => "ALLOW_DUPLICATE" | "ALLOW_DUPLICATE_FAILED_ONLY" | "REJECT_DUPLICATE" | undefined;
/**
 * Defines how to resolve an operation ID conflict with a *running* Nexus operation.
 *
 * See {@link NexusOperationIdReusePolicy} for handling operation ID duplication with a *closed* operation.
 */
export declare const NexusOperationIdConflictPolicy: {
    readonly FAIL: "FAIL";
    readonly USE_EXISTING: "USE_EXISTING";
};
export type NexusOperationIdConflictPolicy = (typeof NexusOperationIdConflictPolicy)[keyof typeof NexusOperationIdConflictPolicy];
export declare const encodeNexusOperationIdConflictPolicy: (input: "FAIL" | "USE_EXISTING" | temporal.api.enums.v1.NexusOperationIdConflictPolicy | "NEXUS_OPERATION_ID_CONFLICT_POLICY_FAIL" | "NEXUS_OPERATION_ID_CONFLICT_POLICY_USE_EXISTING" | null | undefined) => temporal.api.enums.v1.NexusOperationIdConflictPolicy | undefined, decodeNexusOperationIdConflictPolicy: (input: temporal.api.enums.v1.NexusOperationIdConflictPolicy | null | undefined) => "FAIL" | "USE_EXISTING" | undefined;
/**
 * A general status for a Nexus operation, indicating whether it is currently running or in a terminal state.
 */
export declare const NexusOperationExecutionStatus: {
    readonly RUNNING: "RUNNING";
    readonly COMPLETED: "COMPLETED";
    readonly FAILED: "FAILED";
    readonly CANCELED: "CANCELED";
    readonly TERMINATED: "TERMINATED";
    readonly TIMED_OUT: "TIMED_OUT";
};
export type NexusOperationExecutionStatus = (typeof NexusOperationExecutionStatus)[keyof typeof NexusOperationExecutionStatus];
export declare const encodeNexusOperationExecutionStatus: (input: "RUNNING" | "COMPLETED" | "FAILED" | "TERMINATED" | "TIMED_OUT" | "CANCELED" | temporal.api.enums.v1.NexusOperationExecutionStatus | "NEXUS_OPERATION_EXECUTION_STATUS_RUNNING" | "NEXUS_OPERATION_EXECUTION_STATUS_COMPLETED" | "NEXUS_OPERATION_EXECUTION_STATUS_FAILED" | "NEXUS_OPERATION_EXECUTION_STATUS_CANCELED" | "NEXUS_OPERATION_EXECUTION_STATUS_TERMINATED" | "NEXUS_OPERATION_EXECUTION_STATUS_TIMED_OUT" | null | undefined) => temporal.api.enums.v1.NexusOperationExecutionStatus | undefined, decodeNexusOperationExecutionStatus: (input: temporal.api.enums.v1.NexusOperationExecutionStatus | null | undefined) => "RUNNING" | "COMPLETED" | "FAILED" | "TERMINATED" | "TIMED_OUT" | "CANCELED" | undefined;
/**
 * A more detailed breakdown of {@link NexusOperationExecutionStatus.RUNNING}.
 */
export declare const PendingNexusOperationState: {
    readonly SCHEDULED: "SCHEDULED";
    readonly BACKING_OFF: "BACKING_OFF";
    readonly STARTED: "STARTED";
    readonly BLOCKED: "BLOCKED";
};
export type PendingNexusOperationState = (typeof PendingNexusOperationState)[keyof typeof PendingNexusOperationState];
export declare const encodePendingNexusOperationState: (input: "SCHEDULED" | "STARTED" | "BACKING_OFF" | "BLOCKED" | temporal.api.enums.v1.PendingNexusOperationState | "PENDING_NEXUS_OPERATION_STATE_SCHEDULED" | "PENDING_NEXUS_OPERATION_STATE_BACKING_OFF" | "PENDING_NEXUS_OPERATION_STATE_STARTED" | "PENDING_NEXUS_OPERATION_STATE_BLOCKED" | null | undefined) => temporal.api.enums.v1.PendingNexusOperationState | undefined, decodePendingNexusOperationState: (input: temporal.api.enums.v1.PendingNexusOperationState | null | undefined) => "SCHEDULED" | "STARTED" | "BACKING_OFF" | "BLOCKED" | undefined;
/**
 * State of a Nexus operation cancellation.
 */
export declare const NexusOperationCancellationState: {
    readonly SCHEDULED: "SCHEDULED";
    readonly BACKING_OFF: "BACKING_OFF";
    readonly SUCCEEDED: "SUCCEEDED";
    readonly FAILED: "FAILED";
    readonly TIMED_OUT: "TIMED_OUT";
    readonly BLOCKED: "BLOCKED";
};
export type NexusOperationCancellationState = (typeof NexusOperationCancellationState)[keyof typeof NexusOperationCancellationState];
export declare const encodeNexusOperationCancellationState: (input: "FAILED" | "TIMED_OUT" | "SCHEDULED" | "BACKING_OFF" | "BLOCKED" | "SUCCEEDED" | temporal.api.enums.v1.NexusOperationCancellationState | "NEXUS_OPERATION_CANCELLATION_STATE_SCHEDULED" | "NEXUS_OPERATION_CANCELLATION_STATE_BACKING_OFF" | "NEXUS_OPERATION_CANCELLATION_STATE_SUCCEEDED" | "NEXUS_OPERATION_CANCELLATION_STATE_FAILED" | "NEXUS_OPERATION_CANCELLATION_STATE_TIMED_OUT" | "NEXUS_OPERATION_CANCELLATION_STATE_BLOCKED" | null | undefined) => temporal.api.enums.v1.NexusOperationCancellationState | undefined, decodeNexusOperationCancellationState: (input: temporal.api.enums.v1.NexusOperationCancellationState | null | undefined) => "FAILED" | "TIMED_OUT" | "SCHEDULED" | "BACKING_OFF" | "BLOCKED" | "SUCCEEDED" | undefined;
export type RawNexusOperationExecutionInfo = temporal.api.nexus.v1.INexusOperationExecutionInfo;
export type RawNexusOperationExecutionListInfo = temporal.api.nexus.v1.INexusOperationExecutionListInfo;
export type RawNexusOperationExecutionCancellationInfo = temporal.api.nexus.v1.INexusOperationExecutionCancellationInfo;
/**
 * Cancellation state for a standalone Nexus operation.
 */
export interface NexusOperationExecutionCancellationInfo {
    /**
     * The time when cancellation was requested.
     */
    readonly requestedTime: Date | undefined;
    /**
     * The current state of the cancellation request.
     */
    readonly state: NexusOperationCancellationState | undefined;
    /**
     * The number of attempts made to deliver the cancel operation request.
     */
    readonly attempt: number;
    /**
     * The time when the last attempt completed.
     */
    readonly lastAttemptCompleteTime: Date | undefined;
    /**
     * The time when the next attempt is scheduled.
     */
    readonly nextAttemptScheduleTime: Date | undefined;
    /**
     * The last attempt's failure, if any.
     */
    readonly lastAttemptFailure: Error | undefined;
    /**
     * Blocked reason provides additional information if the cancellation state is {@link NexusOperationCancellationState.BLOCKED}.
     */
    readonly blockedReason: string | undefined;
    /**
     * The reason specified in the cancellation request.
     */
    readonly reason: string;
    /**
     * Underlying protobuf cancellation info.
     */
    readonly raw: RawNexusOperationExecutionCancellationInfo;
}
/**
 * Info for a standalone Nexus operation execution, from list response.
 */
export interface NexusOperationExecution {
    /**
     * Unique identifier of this operation.
     */
    readonly operationId: string;
    /**
     * The run ID of the standalone Nexus operation.
     */
    readonly runId: string;
    /**
     * Endpoint name.
     */
    readonly endpoint: string;
    /**
     * Service name.
     */
    readonly service: string;
    /**
     * Operation name.
     */
    readonly operation: string;
    /**
     * The time the operation was originally scheduled.
     */
    readonly scheduleTime: Date | undefined;
    /**
     * Time the operation reached a terminal status, if closed.
     */
    readonly closeTime: Date | undefined;
    /**
     * Current status of the operation.
     */
    readonly status: NexusOperationExecutionStatus | undefined;
    /**
     * Current set of search attributes if any.
     */
    readonly searchAttributes: TypedSearchAttributes;
    /**
     * Number of state transitions.
     */
    readonly stateTransitionCount: number;
    /**
     * Duration from scheduled to close time, only populated if closed.
     */
    readonly executionDuration: number | undefined;
    /**
     * Underlying protobuf info.
     */
    readonly raw: RawNexusOperationExecutionListInfo;
}
/**
 * Detailed information about a standalone Nexus operation execution.
 */
export type NexusOperationExecutionDescription = Replace<NexusOperationExecution, {
    raw: temporal.api.nexus.v1.INexusOperationExecutionInfo;
}> & {
    /**
     * More detailed breakdown if status is {@link NexusOperationExecutionStatus.RUNNING}.
     */
    readonly state: PendingNexusOperationState | undefined;
    /**
     * Schedule-to-close timeout for this operation in milliseconds.
     */
    readonly scheduleToCloseTimeout: number | undefined;
    /**
     * Schedule-to-start timeout for this operation in milliseconds.
     */
    readonly scheduleToStartTimeout: number | undefined;
    /**
     * Start-to-close timeout for this operation in milliseconds.
     */
    readonly startToCloseTimeout: number | undefined;
    /**
     * Current attempt number.
     */
    readonly attempt: number;
    /**
     * Scheduled time plus schedule_to_close_timeout.
     */
    readonly expirationTime: Date | undefined;
    /**
     * Time when the last attempt completed.
     */
    readonly lastAttemptCompleteTime: Date | undefined;
    /**
     * Time when the next attempt will be scheduled.
     */
    readonly nextAttemptScheduleTime: Date | undefined;
    /**
     * Failure from the last failed attempt, if any.
     */
    readonly lastAttemptFailure: Error | undefined;
    /**
     * Reason the operation is blocked, if any.
     */
    readonly blockedReason: string | undefined;
    /**
     * Server-generated request ID used as an idempotency token.
     */
    readonly requestId: string;
    /**
     * operationToken is only set for asynchronous operations after a successful start_operation call.
     */
    readonly operationToken: string | undefined;
    /**
     * Identity of the client that started this operation.
     */
    readonly identity: string;
    /**
     * Cancellation info if cancellation was requested.
     */
    readonly cancellationInfo: NexusOperationExecutionCancellationInfo | undefined;
    staticSummary: () => Promise<string | undefined>;
    staticDetails: () => Promise<string | undefined>;
};
/**
 * Count of standalone Nexus operation executions, optionally grouped by a search attribute.
 */
export interface NexusOperationExecutionCount {
    readonly count: number;
    readonly groups: readonly NexusOperationExecutionCountGroup[];
}
/**
 * A group within a count aggregation.
 */
export interface NexusOperationExecutionCountGroup {
    readonly count: number;
    readonly groupValues: readonly TypedSearchAttributeValue<SearchAttributeType>[];
}
/**
 * Options for starting a standalone Nexus operation via
 * {@link NexusServiceClient.startOperation} or {@link NexusServiceClient.executeOperation}.
 */
export interface StartNexusOperationOptions {
    /**
     * Caller-side identifier for this operation. Must be unique among operations in the
     * same namespace, subject to {@link idReusePolicy} and {@link idConflictPolicy}.
     */
    id: string;
    /**
     * Schedule-to-close timeout for this operation.
     */
    scheduleToCloseTimeout?: Duration;
    /**
     * Schedule-to-start timeout for this operation.
     */
    scheduleToStartTimeout?: Duration;
    /**
     * Start-to-close timeout for this operation.
     */
    startToCloseTimeout?: Duration;
    /**
     * Single-line Temporal-markdown summary used by user interfaces to display operation metadata.
     */
    summary?: string;
    /**
     * How to handle an operation ID that was used by a previously closed operation.
     * @default {@link NexusOperationIdReusePolicy.ALLOW_DUPLICATE}
     */
    idReusePolicy?: NexusOperationIdReusePolicy;
    /**
     * How to handle an operation ID that is in use by a currently running operation.
     * @default {@link NexusOperationIdConflictPolicy.FAIL}
     */
    idConflictPolicy?: NexusOperationIdConflictPolicy;
    /**
     * Search attributes for indexing.
     */
    searchAttributes?: SearchAttributePair[] | TypedSearchAttributes;
    /**
     * Headers to attach to the Nexus request. Transmitted to the handler as-is.
     * Useful for propagating tracing information.
     */
    headers?: Record<string, string>;
}
/**
 * Options for {@link NexusClient.list}.
 */
export interface ListNexusOperationsOptions {
    /**
     * Visibility list filter query. See https://docs.temporal.io/list-filter for syntax.
     */
    query?: string;
    /**
     * Maximum number of operations to return per page.
     */
    pageSize?: number;
}
/**
 * Options for {@link NexusClient.getHandle}.
 */
export interface GetNexusOperationHandleOptions {
    /**
     * If provided, targets this specific run of the operation. If absent, targets the latest run.
     */
    runId?: string;
}
/**
 * Options for {@link NexusOperationHandle.describe}
 */
export interface DescribeNexusOperationOptions {
}