or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

activity-completion.mdclient-connection.mderror-handling.mdindex.mdinterceptors.mdschedule-client.mdtask-queue-client.mdworkflow-client.md
tile.json

tessl/npm-temporalio--client

TypeScript SDK Client for communicating with Temporal workflow orchestration systems, providing workflow lifecycle management, connection handling, and durable execution patterns.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@temporalio/client@1.13.x

To install, run

npx @tessl/cli install tessl/npm-temporalio--client@1.13.0

index.mddocs/

Temporal TypeScript Client

The Temporal TypeScript Client (@temporalio/client) provides a comprehensive TypeScript/JavaScript interface for communicating with Temporal workflow orchestration systems. It enables developers to connect to Temporal services, start and manage workflows, send signals and queries, and handle durable execution patterns with strongly-typed APIs and seamless gRPC integration.

Package Information

  • Package Name: @temporalio/client
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @temporalio/client

Core Imports

import { Client, Connection, WorkflowClient } from "@temporalio/client";

For CommonJS:

const { Client, Connection, WorkflowClient } = require("@temporalio/client");

Basic Usage

import { Client, Connection } from "@temporalio/client";

// Create connection to Temporal server
const connection = await Connection.connect({
  address: 'localhost:7233', // Local Temporal server
});

// Create client with connection
const client = new Client({ connection });

// Start a workflow
const handle = await client.workflow.start('myWorkflowType', {
  args: ['argument1', 'argument2'],
  taskQueue: 'my-task-queue',
  workflowId: 'my-workflow-id-1',
});

// Wait for result
const result = await handle.result();
console.log('Workflow result:', result);

Architecture

The Temporal TypeScript Client is built around several key components:

  • Main Client: High-level Client class that aggregates specialized sub-clients
  • Connection Management: Connection class for managing gRPC connections to Temporal Server
  • Workflow Operations: WorkflowClient for starting, querying, and managing workflow lifecycles
  • Schedule Management: ScheduleClient for creating and managing scheduled workflow executions
  • Activity Completion: AsyncCompletionClient for manually completing activities outside worker processes
  • Task Queue Operations: TaskQueueClient for worker versioning and build ID management
  • Error Handling: Comprehensive error classes for different failure scenarios
  • Interceptor System: Pluggable interceptors for custom logging, metrics, and modification of client operations
  • Type System: Full TypeScript integration with generics for type-safe workflow and activity operations

Capabilities

Main Client & Connection

Core client functionality for establishing connections and accessing sub-clients for different Temporal operations.

class Client {
  constructor(options: ClientOptions);
  readonly workflow: WorkflowClient;
  readonly activity: AsyncCompletionClient;
  readonly schedule: ScheduleClient;
  readonly taskQueue: TaskQueueClient;
  readonly workflowService: WorkflowService;
  withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R>;
  withAbortSignal<R>(signal: AbortSignal, fn: () => Promise<R>): Promise<R>;
  withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R>;
}

class Connection {
  static connect(options: ConnectionOptions): Promise<Connection>;
  static lazy(options: ConnectionOptions): Connection;
  ensureConnected(): Promise<void>;
  close(): Promise<void>;
  withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R>;
  withAbortSignal<R>(signal: AbortSignal, fn: () => Promise<R>): Promise<R>;
  withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R>;
  withApiKey<R>(apiKey: string, fn: () => Promise<R>): Promise<R>;
  setApiKey(apiKey: string): void;
  readonly workflowService: WorkflowService;
  readonly operatorService: OperatorService;
  readonly testService: TestService;
  readonly healthService: HealthService;
}

interface ClientOptions {
  connection?: ConnectionLike;
  namespace?: string;
  dataConverter?: DataConverter;
  interceptors?: ClientInterceptors;
  workflow?: {
    queryRejectCondition?: QueryRejectCondition;
  };
}

interface ConnectionOptions {
  address?: string;
  tls?: TLSConfig | boolean;
  credentials?: ChannelCredentials;
  callCredentials?: CallCredentials[];
  channelArgs?: object;
  interceptors?: Interceptor[];
  metadata?: Metadata;
  apiKey?: string;
  connectTimeout?: string | number;
}

Client & Connection

Workflow Operations

Complete workflow lifecycle management including starting workflows, handling updates, sending signals and queries, and managing workflow execution.

class WorkflowClient {
  start<T extends Workflow>(
    workflowTypeOrFunc: string | T,
    options: WorkflowStartOptions<T>
  ): Promise<WorkflowHandleWithFirstExecutionRunId<T>>;
  execute<T extends Workflow>(
    workflowTypeOrFunc: string | T,
    options: WorkflowStartOptions<T>
  ): Promise<WorkflowResultType<T>>;
  getHandle<T extends Workflow>(
    workflowId: string,
    runId?: string,
    options?: GetWorkflowHandleOptions
  ): WorkflowHandle<WorkflowResultType<T>>;
  list(options?: ListOptions): AsyncWorkflowListIterable;
  count(query?: string): Promise<CountWorkflowExecution>;
}

interface WorkflowHandle<T> {
  readonly workflowId: string;
  readonly runId: string | undefined;
  readonly firstExecutionRunId: string;
  result(): Promise<T>;
  terminate(reason?: string): Promise<void>;
  cancel(): Promise<void>;
  signal<Args extends any[]>(
    def: SignalDefinition<Args> | string,
    ...args: Args
  ): Promise<void>;
  query<Ret, Args extends any[]>(
    def: QueryDefinition<Ret, Args> | string,
    ...args: Args
  ): Promise<Ret>;
  executeUpdate<Ret, Args extends any[]>(
    def: UpdateDefinition<Ret, Args> | string,
    options?: WorkflowUpdateOptions,
    ...args: Args
  ): Promise<Ret>;
}

Workflow Client

Schedule Management

Manage scheduled workflow executions with flexible calendar-based and interval-based scheduling configurations.

class ScheduleClient {
  create<A extends any[]>(options: ScheduleOptions<A>): Promise<ScheduleHandle>;
  getHandle(scheduleId: string): ScheduleHandle;
  list(options?: ListScheduleOptions): AsyncIterable<ScheduleListEntry>;
}

interface ScheduleHandle {
  readonly scheduleId: string;
  describe(): Promise<ScheduleDescription>;
  update<A extends any[]>(options: ScheduleUpdateOptions<A>): Promise<void>;
  delete(): Promise<void>;
  trigger(options?: TriggerImmediatelyOptions): Promise<void>;
  pause(note?: string): Promise<void>;
  unpause(note?: string): Promise<void>;
  backfill(backfills: Backfill[]): Promise<void>;
}

interface ScheduleOptions<A extends any[]> {
  scheduleId: string;
  spec: ScheduleSpec;
  action: ScheduleAction<A>;
  policies?: SchedulePolicies;
  state?: ScheduleState;
  memo?: Record<string, any>;
  searchAttributes?: SearchAttributes;
}

Schedule Management

Activity Completion

Manual activity completion for activities that complete outside the normal worker execution model.

class AsyncCompletionClient {
  complete<T = any>(
    taskTokenOrActivityId: Uint8Array | string,
    result?: T
  ): Promise<void>;
  complete<T = any>(fullActivityId: FullActivityId, result?: T): Promise<void>;
  fail(
    taskTokenOrActivityId: Uint8Array | string,
    err: unknown
  ): Promise<void>;
  fail(fullActivityId: FullActivityId, err: unknown): Promise<void>;
  reportCancellation(
    taskTokenOrActivityId: Uint8Array | string,
    details?: unknown
  ): Promise<void>;
  heartbeat(
    taskTokenOrActivityId: Uint8Array | string,
    details?: unknown
  ): Promise<void>;
}

interface FullActivityId {
  workflowId: string;
  runId?: string;
  activityId: string;
}

Activity Completion

Task Queue Management

Worker build ID versioning and task reachability management for gradual deployments and worker compatibility.

class TaskQueueClient {
  updateBuildIdCompatibility(
    taskQueue: string,
    operation: BuildIdOperation
  ): Promise<void>;
  getBuildIdCompatability(
    taskQueue: string
  ): Promise<WorkerBuildIdVersionSets>;
  getReachability(options: ReachabilityOptions): Promise<ReachabilityResponse>;
}

type BuildIdOperation =
  | AddNewIdInNewDefaultSet
  | AddNewCompatibleVersion
  | PromoteSetByBuildId
  | PromoteBuildIdWithinSet
  | MergeSets;

Task Queue Management

Error Handling

Comprehensive error types for different failure scenarios in Temporal operations.

class WorkflowFailedError extends Error {
  readonly cause: TemporalFailure;
  readonly workflowId: string;
  readonly workflowType: string;
  readonly runId: string;
}

class ServiceError extends Error {
  readonly code: Status;
  readonly details: string;
}

// Error checking utilities
function isGrpcServiceError(error: unknown): error is ServiceError;
function isGrpcDeadlineError(error: unknown): boolean;
function isGrpcCancelledError(error: unknown): boolean;

Error Handling

Interceptors

Pluggable system for customizing client behavior through interceptors that can modify requests, responses, and add cross-cutting concerns.

interface WorkflowClientInterceptor {
  start?(
    input: WorkflowStartInput,
    next: WorkflowClientCallsInterceptor['start']
  ): Promise<WorkflowHandle>;
  signalWithStart?(
    input: WorkflowSignalWithStartInput,
    next: WorkflowClientCallsInterceptor['signalWithStart']
  ): Promise<WorkflowHandle>;
  signal?(
    input: WorkflowSignalInput,
    next: WorkflowClientCallsInterceptor['signal']
  ): Promise<void>;
  query?(
    input: WorkflowQueryInput,
    next: WorkflowClientCallsInterceptor['query']
  ): Promise<unknown>;
}

interface ClientInterceptors {
  workflow?: WorkflowClientInterceptor[];
  schedule?: ScheduleClientInterceptor[];
}

Interceptors

Types

Core Types

interface WorkflowExecution {
  workflowId: string;
  runId: string;
}

interface WorkflowExecutionInfo {
  workflowExecution: WorkflowExecution;
  workflowType: string;
  startTime: Date;
  executionTime?: Date;
  closeTime?: Date;
  status: WorkflowExecutionStatus;
  historyLength: number;
  parentExecution?: WorkflowExecution;
  memo?: Memo;
  searchAttributes?: SearchAttributes;
  autoResetPoints?: AutoResetPoints;
  taskQueue: string;
}

type Metadata = Record<string, string | Buffer | string[] | Buffer[]>;

interface CallContext {
  deadline?: Date;
  abortSignal?: AbortSignal;
}

type WorkflowResultType<T extends Workflow> = T extends (...args: any[]) => Promise<infer R> ? R : any;

interface WorkflowHandleWithFirstExecutionRunId<T = any> extends WorkflowHandle<T> {
  readonly firstExecutionRunId: string;
}

interface CountWorkflowExecution {
  count: number;
}

// Constants
const LOCAL_TARGET = 'localhost:7233';