@temporalio/workflow/lib/nexus.d.ts

Temporal.io SDK Workflow sub-package

import type * as nexus from 'nexus-rpc';
import type { StartNexusOperationOptions } from './interceptors';
/**
 * A Nexus client for invoking Nexus Operations for a specific service from a Workflow.
 *
 * @experimental Nexus support in Temporal SDK is experimental.
 */
export interface NexusServiceClient<T extends nexus.ServiceDefinition> {
    /**
     * Start a Nexus Operation and wait for its completion taking a {@link nexus.operation}.
     * Returns the operation's result.
     *
     * @experimental Nexus support in Temporal SDK is experimental.
     */
    executeOperation<O extends T['operations'][keyof T['operations']]>(op: O, input: nexus.OperationInput<O>, options?: Partial<StartNexusOperationOptions>): Promise<nexus.OperationOutput<O>>;
    /**
     * Start a Nexus Operation and wait for its completion, taking an Operation's _property name_.
     * Returns the operation's result.
     *
     * An Operation's _property name_ is the name of the property used to define that Operation in
     * the {@link nexus.ServiceDefinition} object; it may differ from the value of the `name` property
     * if one was explicitly specified on the {@link nexus.OperationDefinition} object.
     *
     * @experimental Nexus support in Temporal SDK is experimental.
     */
    executeOperation<K extends nexus.OperationKey<T['operations']>>(op: K, input: nexus.OperationInput<T['operations'][K]>, options?: Partial<StartNexusOperationOptions>): Promise<nexus.OperationOutput<T['operations'][K]>>;
    /**
     * Start a Nexus Operation taking a {@link nexus.operation}.
     *
     * Returns a handle that can be used to wait for the Operation's result.
     *
     * @experimental Nexus support in Temporal SDK is experimental.
     */
    startOperation<O extends T['operations'][keyof T['operations']]>(op: O, input: nexus.OperationInput<O>, options?: Partial<StartNexusOperationOptions>): Promise<NexusOperationHandle<nexus.OperationOutput<O>>>;
    /**
     * Start a Nexus Operation, taking an Operation's _property name_.
     * Returns a handle that can be used to wait for the Operation's result.
     *
     * An Operation's _property name_ is the name of the property used to define that Operation in
     * the {@link nexus.ServiceDefinition} object; it may differ from the value of the `name` property
     * if one was explicitly specified on the {@link nexus.OperationDefinition} object.
     *
     * @experimental Nexus support in Temporal SDK is experimental.
     */
    startOperation<K extends nexus.OperationKey<T['operations']>>(op: K, input: nexus.OperationInput<T['operations'][K]>, options?: Partial<StartNexusOperationOptions>): Promise<NexusOperationHandle<nexus.OperationOutput<T['operations'][K]>>>;
}
/**
 * A handle to a Nexus Operation.
 *
 * @experimental Nexus support in Temporal SDK is experimental.
 */
export interface NexusOperationHandle<T> {
    /**
     * The Operation's service name.
     */
    readonly service: string;
    /**
     * The name of the Operation.
     */
    readonly operation: string;
    /**
     * Operation token as set by the Operation's handler. May be empty if the Operation completed synchronously.
     */
    readonly token?: string;
    /**
     * Wait for Operation completion and get its result.
     */
    result(): Promise<T>;
}
/**
 * Options for {@link createNexusServiceClient}.
 */
export interface NexusServiceClientOptions<T> {
    endpoint: string;
    service: T;
}
/**
 * Create a Nexus client for invoking Nexus Operations from a Workflow.
 *
 * @experimental Nexus support in Temporal SDK is experimental.
 */
export declare function createNexusServiceClient<T extends nexus.ServiceDefinition>(options: NexusServiceClientOptions<T>): NexusServiceClient<T>;
/**
 * Determines:
 * - whether cancellation requests should be propagated from the Workflow to the Nexus Operation
 * - whether and when should the Operation's cancellation be reported back to the Workflow
 *   (i.e. at which moment should the operation's result promise fail with a `NexusOperationFailure`,
 *   with `cause` set to a `CancelledFailure`).
 *
 * Note that this setting only applies to cancellation originating from an external request for the
 * Workflow itself, or from internal cancellation of the `CancellationScope` in which the
 * Operation call was made.
 *
 * @experimental Nexus support in Temporal SDK is experimental.
 */
export declare const NexusOperationCancellationType: {
    /**
     * Do not propagate cancellation requests to the Nexus Operation, and immediately report
     * cancellation to the caller.
     */
    readonly ABANDON: "ABANDON";
    /**
     * Initiate a cancellation request for the Nexus operation and immediately report cancellation to
     * the caller. Note that it doesn't guarantee that cancellation is delivered to the operation if
     * calling workflow exits before the delivery is done. If you want to ensure that cancellation is
     * delivered to the operation, use {@link WAIT_CANCELLATION_REQUESTED}.
     *
     * Propagate cancellation request from the Workflow to the Operation, yet _immediately_ report
     * cancellation to the caller, i.e. without waiting for the server to confirm the cancellation
     * request.
     *
     * Note that this cancellation type provides no guarantee, from the Workflow-side, that the
     * cancellation request will be delivered to the Operation Handler. In particular, either the
     * Operation or the Workflow may complete (either successfully or uncessfully) before the
     * cancellation request is delivered, resulting in a situation where the Operation completed
     * successfully, but the Workflow thinks it was cancelled.
     *
     * To guarantee that the Operation will eventually be notified of the cancellation request,
     * use {@link WAIT_CANCELLATION_REQUESTED}.
     */
    readonly TRY_CANCEL: "TRY_CANCEL";
    /**
     * Propagate cancellation request from the Workflow to the Operation, then wait for the server
     * to confirm that the Operation cancellation request was delivered to the Operation Handler.
     */
    readonly WAIT_CANCELLATION_REQUESTED: "WAIT_CANCELLATION_REQUESTED";
    /**
     * Propagate cancellation request from the Workflow to the Operation, then wait for completion
     * of the Operation.
     */
    readonly WAIT_CANCELLATION_COMPLETED: "WAIT_CANCELLATION_COMPLETED";
};
export type NexusOperationCancellationType = (typeof NexusOperationCancellationType)[keyof typeof NexusOperationCancellationType];