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

Temporal.io SDK Client sub-package

import type * as nexus from 'nexus-rpc';
import type { BaseClientOptions, LoadedWithDefaults } from './base-client';
import { BaseClient } from './base-client';
import type { CancelNexusOperationInput, CountNexusOperationsInput, DescribeNexusOperationInput, GetNexusOperationResultInput, ListNexusOperationsInput, NexusClientInterceptor, StartNexusOperationInput, TerminateNexusOperationInput } from './interceptors';
import type { DescribeNexusOperationOptions, GetNexusOperationHandleOptions, ListNexusOperationsOptions, NexusOperationExecutionCount, NexusOperationExecutionDescription, NexusOperationExecution, StartNexusOperationOptions } from './nexus-types';
export interface NexusClientOptions extends BaseClientOptions {
    /**
     * Used to override and extend default client behavior.
     */
    interceptors?: NexusClientInterceptor[];
}
export type LoadedNexusClientOptions = LoadedWithDefaults<NexusClientOptions>;
/**
 * Handle to a standalone Nexus operation execution.
 *
 * Use this to poll for results, describe, cancel, or terminate the operation.
 *
 * @experimental Nexus Standalone Operations are experimental.
 */
export interface NexusOperationHandle<O = unknown> {
    readonly operationId: string;
    readonly runId?: string;
    readonly client: NexusClient;
    /**
     * Wait for the operation to complete and return its result.
     *
     * @throws {@link NexusOperationFailureError} if the operation completes with a failure outcome.
     *
     * @experimental Nexus Standalone Operations are experimental.
     */
    result(): Promise<O>;
    /**
     * Describe the Nexus operation execution.
     *
     * @experimental Nexus Standalone Operations are experimental.
     */
    describe(options?: DescribeNexusOperationOptions): Promise<NexusOperationExecutionDescription>;
    /**
     * Request cancellation of the operation.
     *
     * @param reason optional reason for the cancellation.
     *
     * @experimental Nexus Standalone Operations are experimental.
     */
    cancel(reason?: string): Promise<void>;
    /**
     * Terminate the Nexus operation execution immediately.
     *
     * @experimental Nexus Standalone Operations are experimental.
     */
    terminate(reason?: string): Promise<void>;
}
/**
 * Resolves the result type carried by a Nexus operation handle type hint.
 *
 * A NexusOperationHandle cannot infer a result type from an operation ID alone,
 * so callers may provide either the expected result type directly or a
 * Nexus operation definition type when acquiring a handle.
 * Operation definitions are unwrapped to their output type, all other types are
 * treated as the result type itself.
 */
type NexusOperationHandleResult<T> = T extends nexus.OperationDefinition<any, infer O> ? O : T;
/**
 * Typed service client for a specific Nexus service + endpoint pair.
 *
 * Created via {@link NexusClient.createServiceClient}. Provides type-safe
 * {@link startOperation} and {@link executeOperation} based on the service definition's operation types.
 *
 * @experimental Nexus Standalone Operations are experimental.
 */
export interface NexusServiceClient<T extends nexus.ServiceDefinition> {
    readonly endpoint: string;
    readonly service: T;
    /**
     * Start a Nexus operation and return a handle.
     *
     * @experimental Nexus Standalone Operations are experimental.
     */
    startOperation<Op extends T['operations'][keyof T['operations']]>(operation: Op, input: nexus.OperationInput<Op>, options: StartNexusOperationOptions): Promise<NexusOperationHandle<nexus.OperationOutput<Op>>>;
    startOperation<K extends nexus.OperationKey<T['operations']>>(op: K, input: nexus.OperationInput<T['operations'][K]>, options: StartNexusOperationOptions): Promise<NexusOperationHandle<nexus.OperationOutput<T['operations'][K]>>>;
    /**
     * Start a Nexus operation and wait for its result.
     *
     * Convenience for {@link startOperation} followed by {@link NexusOperationHandle.result}.
     *
     * @experimental Nexus Standalone Operations are experimental.
     */
    executeOperation<Op extends T['operations'][keyof T['operations']]>(operation: Op, input: nexus.OperationInput<Op>, options: StartNexusOperationOptions): Promise<nexus.OperationOutput<Op>>;
    executeOperation<K extends nexus.OperationKey<T['operations']>>(op: K, input: nexus.OperationInput<T['operations'][K]>, options: StartNexusOperationOptions): Promise<nexus.OperationOutput<T['operations'][K]>>;
}
/**
 * Client for standalone Nexus operations. Access via {@link Client.nexus}.
 *
 * Use {@link createServiceClient} to get a typed service client, or call the namespace-wide
 * {@link list}, {@link count}, and {@link getHandle} methods directly.
 *
 * @see {@link Client}
 *
 * @experimental Nexus Standalone Operations are experimental.
 */
export declare class NexusClient extends BaseClient {
    readonly options: LoadedNexusClientOptions;
    protected readonly interceptors: NexusClientInterceptor[];
    constructor(options?: NexusClientOptions);
    /**
     * Create a typed service client for starting and executing Nexus operations on a specific endpoint + service.
     *
     * @experimental Nexus Standalone Operations are experimental.
     */
    createServiceClient<T extends nexus.ServiceDefinition>(options: {
        endpoint: string;
        service: T;
    }): NexusServiceClient<T>;
    /**
     * Get a handle to an existing standalone Nexus operation.
     *
     * If {@link GetNexusOperationHandleOptions.runId} is not provided, operations on the handle
     * (like {@link NexusOperationHandle.result}) will target the latest run.
     *
     * @experimental Nexus Standalone Operations are experimental.
     */
    getHandle<T>(operationId: string, options?: GetNexusOperationHandleOptions): NexusOperationHandle<NexusOperationHandleResult<T>>;
    /**
     * List standalone Nexus operations matching a visibility query.
     *
     * @experimental Nexus Standalone Operations are experimental.
     */
    list(options?: ListNexusOperationsOptions): AsyncIterable<NexusOperationExecution>;
    /**
     * Count standalone Nexus operations matching a visibility query.
     *
     * @experimental Nexus Standalone Operations are experimental.
     */
    count(query?: string): Promise<NexusOperationExecutionCount>;
    protected startNexusOperation(input: StartNexusOperationInput): Promise<NexusOperationHandle>;
    protected getNexusOperationResult(input: GetNexusOperationResultInput): Promise<unknown>;
    protected describeNexusOperation(input: DescribeNexusOperationInput): Promise<NexusOperationExecutionDescription>;
    protected cancelNexusOperation(input: CancelNexusOperationInput): Promise<void>;
    protected terminateNexusOperation(input: TerminateNexusOperationInput): Promise<void>;
    protected startNexusOperationHandler(input: StartNexusOperationInput): Promise<NexusOperationHandle>;
    protected createNexusOperationHandle<O>(opts: {
        operationId: string;
        runId?: string;
    }): NexusOperationHandle<O>;
    protected getResultHandler(input: GetNexusOperationResultInput): Promise<unknown>;
    protected describeHandler(input: DescribeNexusOperationInput): Promise<NexusOperationExecutionDescription>;
    protected cancelHandler(input: CancelNexusOperationInput): Promise<void>;
    protected terminateHandler(input: TerminateNexusOperationInput): Promise<void>;
    protected listHandler(input: ListNexusOperationsInput): AsyncIterable<NexusOperationExecution>;
    protected countHandler(input: CountNexusOperationsInput): Promise<NexusOperationExecutionCount>;
    protected rethrowGrpcError(err: unknown, fallbackMessage: string, operationId?: string, runId?: string): never;
}
/**
 * Thrown by {@link NexusOperationHandle.result} when the operation completes with a failure outcome.
 * The original failure is available on `cause`.
 */
export declare class NexusOperationFailureError extends Error {
    readonly cause: Error;
    constructor(message: string, cause: Error);
}
/**
 * Thrown by {@link NexusServiceClient.startOperation} when the server returns ALREADY_EXISTS
 * because an operation with the given ID already exists and the reuse/conflict policies disallow reuse.
 */
export declare class NexusOperationAlreadyStartedError extends Error {
    readonly operationId: string;
    readonly runId?: string | undefined;
    constructor(operationId: string, runId?: string | undefined);
}
/**
 * Thrown when a Nexus Operation with the given operationId and runId is not known by the Temporal Server.
 */
export declare class NexusOperationNotFoundError extends Error {
    readonly operationId: string;
    readonly runId?: string | undefined;
    constructor(operationId: string, runId?: string | undefined);
}
export {};