@temporalio/client 1.4.3 → 1.5.0

package/src/types.ts

@@ -1,6 +1,7 @@
+import type * as grpc from '@grpc/grpc-js';
 import type { SearchAttributes } from '@temporalio/common';
 import * as proto from '@temporalio/proto';
-import type * as grpc from '@grpc/grpc-js';
+import { Replace } from '@temporalio/common/lib/type-helpers';
 
 export interface WorkflowExecution {
   workflowId: string;
@@ -11,6 +12,7 @@ export type GetWorkflowExecutionHistoryRequest =
   proto.temporal.api.workflowservice.v1.IGetWorkflowExecutionHistoryRequest;
 export type DescribeWorkflowExecutionResponse =
   proto.temporal.api.workflowservice.v1.IDescribeWorkflowExecutionResponse;
+export type RawWorkflowExecutionInfo = proto.temporal.api.workflow.v1.IWorkflowExecutionInfo;
 export type TerminateWorkflowExecutionResponse =
   proto.temporal.api.workflowservice.v1.ITerminateWorkflowExecutionResponse;
 export type RequestCancelWorkflowExecutionResponse =
@@ -27,7 +29,7 @@ export type WorkflowExecutionStatusName =
   | 'TIMED_OUT'
   | 'UNKNOWN'; // UNKNOWN is reserved for future enum values
 
-export interface WorkflowExecutionDescription {
+export interface WorkflowExecutionInfo {
   type: string;
   workflowId: string;
   runId: string;
@@ -40,9 +42,16 @@ export interface WorkflowExecutionDescription {
   memo?: Record<string, unknown>;
   searchAttributes: SearchAttributes;
   parentExecution?: Required<proto.temporal.api.common.v1.IWorkflowExecution>;
-  raw: DescribeWorkflowExecutionResponse;
+  raw: RawWorkflowExecutionInfo;
 }
 
+export type WorkflowExecutionDescription = Replace<
+  WorkflowExecutionInfo,
+  {
+    raw: DescribeWorkflowExecutionResponse;
+  }
+>;
+
 export type WorkflowService = proto.temporal.api.workflowservice.v1.WorkflowService;
 export const { WorkflowService } = proto.temporal.api.workflowservice.v1;
 export type OperatorService = proto.temporal.api.operatorservice.v1.OperatorService;

package/src/workflow-client.ts

@@ -1,55 +1,39 @@
 import { status as grpcStatus } from '@grpc/grpc-js';
+import { v4 as uuid4 } from 'uuid';
 import {
+  BaseWorkflowHandle,
   CancelledFailure,
-  DataConverter,
-  LoadedDataConverter,
-  mapFromPayloads,
+  compileRetryPolicy,
   mapToPayloads,
+  HistoryAndWorkflowId,
+  QueryDefinition,
   RetryState,
   searchAttributePayloadConverter,
+  SignalDefinition,
   TerminatedFailure,
   TimeoutFailure,
   TimeoutType,
+  WithWorkflowArgs,
+  Workflow,
+  WorkflowExecutionAlreadyStartedError,
+  WorkflowNotFoundError,
+  WorkflowResultType,
 } from '@temporalio/common';
+import { composeInterceptors } from '@temporalio/common/lib/interceptors';
+import { History } from '@temporalio/common/lib/proto-utils';
 import {
   decodeArrayFromPayloads,
   decodeFromPayloadsAtIndex,
-  decodeMapFromPayloads,
   decodeOptionalFailureToOptionalError,
   encodeMapToPayloads,
   encodeToPayloads,
   filterNullAndUndefined,
-  isLoadedDataConverter,
-  loadDataConverter,
 } from '@temporalio/common/lib/internal-non-workflow';
-import {
-  BaseWorkflowHandle,
-  compileRetryPolicy,
-  QueryDefinition,
-  SearchAttributes,
-  SignalDefinition,
-  WithWorkflowArgs,
-  Workflow,
-  WorkflowNotFoundError,
-  WorkflowResultType,
-} from '@temporalio/common';
-import { optionalTsToDate, tsToDate } from '@temporalio/common/lib/time';
-import { composeInterceptors } from '@temporalio/common/lib/interceptors';
-import { Replace } from '@temporalio/common/lib/type-helpers';
 import { temporal } from '@temporalio/proto';
-import os from 'os';
-import { v4 as uuid4 } from 'uuid';
-import { Connection } from './connection';
-import {
-  isServerErrorResponse,
-  ServiceError,
-  WorkflowContinuedAsNewError,
-  WorkflowExecutionAlreadyStartedError,
-  WorkflowFailedError,
-} from './errors';
+import { isServerErrorResponse, ServiceError, WorkflowContinuedAsNewError, WorkflowFailedError } from './errors';
 import {
   WorkflowCancelInput,
-  WorkflowClientCallsInterceptor,
+  WorkflowClientInterceptor,
   WorkflowClientInterceptors,
   WorkflowDescribeInput,
   WorkflowQueryInput,
@@ -59,19 +43,31 @@ import {
   WorkflowTerminateInput,
 } from './interceptors';
 import {
-  ConnectionLike,
   DescribeWorkflowExecutionResponse,
   GetWorkflowExecutionHistoryRequest,
-  Metadata,
   RequestCancelWorkflowExecutionResponse,
   StartWorkflowExecutionRequest,
   TerminateWorkflowExecutionResponse,
   WorkflowExecution,
   WorkflowExecutionDescription,
-  WorkflowExecutionStatusName,
+  WorkflowExecutionInfo,
   WorkflowService,
 } from './types';
-import { compileWorkflowOptions, WorkflowOptions, WorkflowSignalWithStartOptions } from './workflow-options';
+import {
+  compileWorkflowOptions,
+  WorkflowOptions,
+  WorkflowSignalWithStartOptions,
+  WorkflowStartOptions,
+} from './workflow-options';
+import { executionInfoFromRaw } from './helpers';
+import {
+  BaseClient,
+  BaseClientOptions,
+  defaultBaseClientOptions,
+  LoadedWithDefaults,
+  WithDefaults,
+} from './base-client';
+import { mapAsyncIterable } from './iterators-utils';
 
 /**
  * A client side handle to a single Workflow instance.
@@ -138,6 +134,11 @@ export interface WorkflowHandle<T extends Workflow = Workflow> extends BaseWorkf
    */
   describe(): Promise<WorkflowExecutionDescription>;
 
+  /**
+   * Return a workflow execution's history
+   */
+  fetchHistory(): Promise<History>;
+
   /**
    * Readonly accessor to the underlying WorkflowClient
    */
@@ -169,41 +170,14 @@ export interface WorkflowHandleWithSignaledRunId<T extends Workflow = Workflow>
   readonly signaledRunId: string;
 }
 
-export interface WorkflowClientOptions {
-  /**
-   * {@link DataConverter} or {@link LoadedDataConverter} to use for serializing and deserializing payloads
-   */
-  dataConverter?: DataConverter | LoadedDataConverter;
-
+export interface WorkflowClientOptions extends BaseClientOptions {
   /**
    * Used to override and extend default Connection functionality
    *
    * Useful for injecting auth headers and tracing Workflow executions
    */
-  interceptors?: WorkflowClientInterceptors;
-
-  /**
-   * Identity to report to the server
-   *
-   * @default `${process.pid}@${os.hostname()}`
-   */
-  identity?: string;
-
-  /**
-   * Connection to use to communicate with the server.
-   *
-   * By default `WorkflowClient` connects to localhost.
-   *
-   * Connections are expensive to construct and should be reused.
-   */
-  connection?: ConnectionLike;
-
-  /**
-   * Server namespace
-   *
-   * @default default
-   */
-  namespace?: string;
+  // eslint-disable-next-line deprecation/deprecation
+  interceptors?: WorkflowClientInterceptors | WorkflowClientInterceptor[];
 
   /**
    * Should a query be rejected by closed and failed workflows
@@ -213,23 +187,12 @@ export interface WorkflowClientOptions {
   queryRejectCondition?: temporal.api.enums.v1.QueryRejectCondition;
 }
 
-export type WorkflowClientOptionsWithDefaults = Replace<
-  Required<WorkflowClientOptions>,
-  {
-    connection?: ConnectionLike;
-  }
->;
-export type LoadedWorkflowClientOptions = WorkflowClientOptionsWithDefaults & {
-  loadedDataConverter: LoadedDataConverter;
-};
+export type LoadedWorkflowClientOptions = LoadedWithDefaults<WorkflowClientOptions>;
 
-export function defaultWorkflowClientOptions(): WorkflowClientOptionsWithDefaults {
+function defaultWorkflowClientOptions(): WithDefaults<WorkflowClientOptions> {
   return {
-    dataConverter: {},
-    // The equivalent in Java is ManagementFactory.getRuntimeMXBean().getName()
-    identity: `${process.pid}@${os.hostname()}`,
-    interceptors: {},
-    namespace: 'default',
+    ...defaultBaseClientOptions(),
+    interceptors: [],
     queryRejectCondition: temporal.api.enums.v1.QueryRejectCondition.QUERY_REJECT_CONDITION_UNSPECIFIED,
   };
 }
@@ -279,7 +242,7 @@ export interface GetWorkflowHandleOptions extends WorkflowResultOptions {
 interface WorkflowHandleOptions extends GetWorkflowHandleOptions {
   workflowId: string;
   runId?: string;
-  interceptors: WorkflowClientCallsInterceptor[];
+  interceptors: WorkflowClientInterceptor[];
   /**
    * A runId to use for getting the workflow's result.
    *
@@ -291,9 +254,58 @@ interface WorkflowHandleOptions extends GetWorkflowHandleOptions {
 }
 
 /**
- * Options for starting a Workflow
+ * An iterable list of WorkflowExecution, as returned by {@link WorkflowClient.list}.
+ */
+interface AsyncWorkflowListIterable extends AsyncIterable<WorkflowExecutionInfo> {
+  /**
+   * Return an iterable of histories corresponding to this iterable's WorkflowExecutions.
+   * Workflow histories will be fetched concurrently.
+   *
+   * Useful in batch replaying
+   */
+  intoHistories: (intoHistoriesOptions?: IntoHistoriesOptions) => AsyncIterable<HistoryAndWorkflowId>;
+}
+
+/**
+ * Options for {@link WorkflowClient.list}
+ */
+export interface ListOptions {
+  /**
+   * Maximum number of results to fetch per page.
+   *
+   * @default depends on server config, typically 1000
+   */
+  pageSize?: number;
+  /**
+   * Query string for matching and ordering the results
+   */
+  query?: string;
+}
+
+/**
+ * Options for {@link WorkflowClient.list().intoHistories()}
  */
-export type WorkflowStartOptions<T extends Workflow = Workflow> = WithWorkflowArgs<T, WorkflowOptions>;
+export interface IntoHistoriesOptions {
+  /**
+   * Maximum number of workflow histories to download concurrently.
+   *
+   * @default 5
+   */
+  concurrency?: number;
+
+  /**
+   * Maximum number of workflow histories to buffer ahead, ready for consumption.
+   *
+   * It is recommended to set `bufferLimit` to a rasonnably low number if it is expected that the
+   * iterable may be stopped before reaching completion (for example, when implementing a fail fast
+   * bach replay test).
+   *
+   * Ignored unless `concurrency > 1`. No limit applies if set to `undefined`.
+   *
+   * @default unlimited
+   */
+  bufferLimit?: number;
+}
 
 /**
  * Client for starting Workflow executions and creating Workflow handles.
@@ -301,18 +313,15 @@ export type WorkflowStartOptions<T extends Workflow = Workflow> = WithWorkflowAr
  * Typically this client should not be instantiated directly, instead create the high level {@link Client} and use
  * {@link Client.workflow} to interact with Workflows.
  */
-export class WorkflowClient {
+export class WorkflowClient extends BaseClient {
   public readonly options: LoadedWorkflowClientOptions;
-  public readonly connection: ConnectionLike;
 
   constructor(options?: WorkflowClientOptions) {
-    this.connection = options?.connection ?? Connection.lazy();
-    const dataConverter = options?.dataConverter;
-    const loadedDataConverter = isLoadedDataConverter(dataConverter) ? dataConverter : loadDataConverter(dataConverter);
+    super(options);
     this.options = {
       ...defaultWorkflowClientOptions(),
       ...filterNullAndUndefined(options ?? {}),
-      loadedDataConverter,
+      loadedDataConverter: this.dataConverter,
     };
   }
 
@@ -326,28 +335,6 @@ export class WorkflowClient {
     return this.connection.workflowService;
   }
 
-  protected get dataConverter(): LoadedDataConverter {
-    return this.options.loadedDataConverter;
-  }
-
-  /**
-   * Set the deadline for any service requests executed in `fn`'s scope.
-   */
-  async withDeadline<R>(deadline: number | Date, fn: () => Promise<R>): Promise<R> {
-    return await this.connection.withDeadline(deadline, fn);
-  }
-
-  /**
-   * Set metadata for any service requests executed in `fn`'s scope.
-   *
-   * @returns returned value of `fn`
-   *
-   * @see {@link Connection.withMetadata}
-   */
-  async withMetadata<R>(metadata: Metadata, fn: () => Promise<R>): Promise<R> {
-    return await this.connection.withMetadata(metadata, fn);
-  }
-
   /**
    * Start a new Workflow execution.
    *
@@ -356,7 +343,7 @@ export class WorkflowClient {
   protected async _start<T extends Workflow>(
     workflowTypeOrFunc: string | T,
     options: WithWorkflowArgs<T, WorkflowOptions>,
-    interceptors: WorkflowClientCallsInterceptor[]
+    interceptors: WorkflowClientInterceptor[]
   ): Promise<string> {
     const workflowType = typeof workflowTypeOrFunc === 'string' ? workflowTypeOrFunc : workflowTypeOrFunc.name;
     assertRequiredWorkflowOptions(options);
@@ -380,7 +367,7 @@ export class WorkflowClient {
   protected async _signalWithStart<T extends Workflow, SA extends any[]>(
     workflowTypeOrFunc: string | T,
     options: WithWorkflowArgs<T, WorkflowSignalWithStartOptions<SA>>,
-    interceptors: WorkflowClientCallsInterceptor[]
+    interceptors: WorkflowClientInterceptor[]
   ): Promise<string> {
     const workflowType = typeof workflowTypeOrFunc === 'string' ? workflowTypeOrFunc : workflowTypeOrFunc.name;
     const { signal, signalArgs, ...rest } = options;
@@ -412,8 +399,7 @@ export class WorkflowClient {
     options: WorkflowStartOptions<T>
   ): Promise<WorkflowHandleWithFirstExecutionRunId<T>> {
     const { workflowId } = options;
-    // Cast is needed because it's impossible to deduce the type in this situation
-    const interceptors = (this.options.interceptors.calls ?? []).map((ctor) => ctor({ workflowId }));
+    const interceptors = this.getOrMakeInterceptors(workflowId);
     const runId = await this._start(workflowTypeOrFunc, { ...options, workflowId }, interceptors);
     // runId is not used in handles created with `start*` calls because these
     // handles should allow interacting with the workflow if it continues as new.
@@ -440,7 +426,7 @@ export class WorkflowClient {
     options: WithWorkflowArgs<WorkflowFn, WorkflowSignalWithStartOptions<SignalArgs>>
   ): Promise<WorkflowHandleWithSignaledRunId<WorkflowFn>> {
     const { workflowId } = options;
-    const interceptors = (this.options.interceptors.calls ?? []).map((ctor) => ctor({ workflowId }));
+    const interceptors = this.getOrMakeInterceptors(workflowId);
     const runId = await this._signalWithStart(workflowTypeOrFunc, options, interceptors);
     // runId is not used in handles created with `start*` calls because these
     // handles should allow interacting with the workflow if it continues as new.
@@ -466,7 +452,7 @@ export class WorkflowClient {
     options: WorkflowStartOptions<T>
   ): Promise<WorkflowResultType<T>> {
     const { workflowId } = options;
-    const interceptors = (this.options.interceptors.calls ?? []).map((ctor) => ctor({ workflowId }));
+    const interceptors = this.getOrMakeInterceptors(workflowId);
     await this._start(workflowTypeOrFunc, options, interceptors);
     return await this.result(workflowId, undefined, {
       ...options,
@@ -855,38 +841,25 @@ export class WorkflowClient {
         const raw = await fn({
           workflowExecution: { workflowId, runId },
         });
-        return {
-          /* eslint-disable @typescript-eslint/no-non-null-assertion */
-          type: raw.workflowExecutionInfo!.type!.name!,
-          workflowId: raw.workflowExecutionInfo!.execution!.workflowId!,
-          runId: raw.workflowExecutionInfo!.execution!.runId!,
-          taskQueue: raw.workflowExecutionInfo!.taskQueue!,
-          status: {
-            code: raw.workflowExecutionInfo!.status!,
-            name: workflowStatusCodeToName(raw.workflowExecutionInfo!.status!),
-          },
-          // Safe to convert to number, max history length is 50k, which is much less than Number.MAX_SAFE_INTEGER
-          historyLength: raw.workflowExecutionInfo!.historyLength!.toNumber(),
-          startTime: tsToDate(raw.workflowExecutionInfo!.startTime!),
-          executionTime: optionalTsToDate(raw.workflowExecutionInfo!.executionTime),
-          closeTime: optionalTsToDate(raw.workflowExecutionInfo!.closeTime),
-          memo: await decodeMapFromPayloads(this.client.dataConverter, raw.workflowExecutionInfo!.memo?.fields),
-          searchAttributes: Object.fromEntries(
-            Object.entries(
-              mapFromPayloads(
-                searchAttributePayloadConverter,
-                raw.workflowExecutionInfo!.searchAttributes?.indexedFields ?? {}
-              ) as SearchAttributes
-            ).filter(([_, v]) => v && v.length > 0) // Filter out empty arrays returned by pre 1.18 servers
-          ),
-          parentExecution: raw.workflowExecutionInfo?.parentExecution
-            ? {
-                workflowId: raw.workflowExecutionInfo.parentExecution.workflowId!,
-                runId: raw.workflowExecutionInfo.parentExecution.runId!,
-              }
-            : undefined,
-          raw,
-        };
+        const info = await executionInfoFromRaw(raw.workflowExecutionInfo ?? {}, this.client.dataConverter);
+        (info as unknown as WorkflowExecutionDescription).raw = raw;
+        return info;
+      },
+      async fetchHistory() {
+        let nextPageToken: Uint8Array | undefined = undefined;
+        const events = Array<temporal.api.history.v1.IHistoryEvent>();
+        for (;;) {
+          const response: temporal.api.workflowservice.v1.GetWorkflowExecutionHistoryResponse =
+            await this.client.workflowService.getWorkflowExecutionHistory({
+              nextPageToken,
+              namespace: this.client.options.namespace,
+              execution: { workflowId, runId },
+            });
+          events.push(...(response.history?.events ?? []));
+          nextPageToken = response.nextPageToken;
+          if (nextPageToken == null || nextPageToken.length === 0) break;
+        }
+        return temporal.api.history.v1.History.create({ events });
       },
       async signal<Args extends any[]>(def: SignalDefinition<Args> | string, ...args: Args): Promise<void> {
         const next = this.client._signalWorkflowHandler.bind(this.client);
@@ -935,7 +908,7 @@ export class WorkflowClient {
     runId?: string,
     options?: GetWorkflowHandleOptions
   ): WorkflowHandle<T> {
-    const interceptors = (this.options.interceptors.calls ?? []).map((ctor) => ctor({ workflowId, runId }));
+    const interceptors = this.getOrMakeInterceptors(workflowId, runId);
 
     return this._createWorkflowHandle({
       workflowId,
@@ -946,6 +919,61 @@ export class WorkflowClient {
       followRuns: options?.followRuns ?? true,
     });
   }
+
+  protected async *_list(options?: ListOptions): AsyncIterable<WorkflowExecutionInfo> {
+    let nextPageToken: Uint8Array = Buffer.alloc(0);
+    for (;;) {
+      const response = await this.workflowService.listWorkflowExecutions({
+        namespace: this.options.namespace,
+        query: options?.query,
+        nextPageToken,
+        pageSize: options?.pageSize,
+      });
+      // Not decoding memo payloads concurrently even though we could have to keep the lazy nature of this iterator.
+      // Decoding is done for `memo` fields which tend to be small.
+      // We might decide to change that based on user feedback.
+      for (const raw of response.executions) {
+        yield await executionInfoFromRaw(raw, this.dataConverter);
+      }
+      nextPageToken = response.nextPageToken;
+      if (nextPageToken == null || nextPageToken.length === 0) break;
+    }
+  }
+
+  /**
+   * List workflows by given `query`.
+   *
+   * ⚠️ To use advanced query functionality, as of the 1.18 server release, you must use Elasticsearch based visibility.
+   *
+   * More info on the concept of "visibility" and the query syntax on the Temporal documentation site:
+   * https://docs.temporal.io/visibility
+   */
+  public list(options?: ListOptions): AsyncWorkflowListIterable {
+    return {
+      [Symbol.asyncIterator]: () => this._list(options)[Symbol.asyncIterator](),
+      intoHistories: (intoHistoriesOptions?: IntoHistoriesOptions) => {
+        return mapAsyncIterable(
+          this._list(options),
+          async ({ workflowId, runId }) => ({
+            workflowId,
+            history: await this.getHandle(workflowId, runId)
+              .fetchHistory()
+              .catch((_) => undefined),
+          }),
+          { concurrency: intoHistoriesOptions?.concurrency ?? 5 }
+        );
+      },
+    };
+  }
+
+  protected getOrMakeInterceptors(workflowId: string, runId?: string): WorkflowClientInterceptor[] {
+    if (typeof this.options.interceptors === 'object' && 'calls' in this.options.interceptors) {
+      // eslint-disable-next-line deprecation/deprecation
+      const factories = (this.options.interceptors as WorkflowClientInterceptors).calls ?? [];
+      return factories.map((ctor) => ctor({ workflowId, runId }));
+    }
+    return Array.isArray(this.options.interceptors) ? (this.options.interceptors as WorkflowClientInterceptor[]) : [];
+  }
 }
 
 export class QueryRejectedError extends Error {
@@ -961,33 +989,3 @@ export class QueryNotRegisteredError extends Error {
     super(message);
   }
 }
-
-function workflowStatusCodeToName(code: temporal.api.enums.v1.WorkflowExecutionStatus): WorkflowExecutionStatusName {
-  return workflowStatusCodeToNameInternal(code) ?? 'UNKNOWN';
-}
-
-/**
- * Intentionally leave out `default` branch to get compilation errors when new values are added
- */
-function workflowStatusCodeToNameInternal(
-  code: temporal.api.enums.v1.WorkflowExecutionStatus
-): WorkflowExecutionStatusName {
-  switch (code) {
-    case temporal.api.enums.v1.WorkflowExecutionStatus.WORKFLOW_EXECUTION_STATUS_UNSPECIFIED:
-      return 'UNSPECIFIED';
-    case temporal.api.enums.v1.WorkflowExecutionStatus.WORKFLOW_EXECUTION_STATUS_RUNNING:
-      return 'RUNNING';
-    case temporal.api.enums.v1.WorkflowExecutionStatus.WORKFLOW_EXECUTION_STATUS_FAILED:
-      return 'FAILED';
-    case temporal.api.enums.v1.WorkflowExecutionStatus.WORKFLOW_EXECUTION_STATUS_TIMED_OUT:
-      return 'TIMED_OUT';
-    case temporal.api.enums.v1.WorkflowExecutionStatus.WORKFLOW_EXECUTION_STATUS_CANCELED:
-      return 'CANCELLED';
-    case temporal.api.enums.v1.WorkflowExecutionStatus.WORKFLOW_EXECUTION_STATUS_TERMINATED:
-      return 'TERMINATED';
-    case temporal.api.enums.v1.WorkflowExecutionStatus.WORKFLOW_EXECUTION_STATUS_COMPLETED:
-      return 'COMPLETED';
-    case temporal.api.enums.v1.WorkflowExecutionStatus.WORKFLOW_EXECUTION_STATUS_CONTINUED_AS_NEW:
-      return 'CONTINUED_AS_NEW';
-  }
-}

package/src/workflow-options.ts

@@ -1,4 +1,10 @@
-import { CommonWorkflowOptions, SignalDefinition, WithCompiledWorkflowOptions } from '@temporalio/common';
+import {
+  CommonWorkflowOptions,
+  SignalDefinition,
+  WithCompiledWorkflowOptions,
+  WithWorkflowArgs,
+  Workflow,
+} from '@temporalio/common';
 
 export * from '@temporalio/common/lib/workflow-options';
 
@@ -60,3 +66,8 @@ export interface WorkflowSignalWithStartOptionsWithArgs<SignalArgs extends any[]
    */
   signalArgs: SignalArgs;
 }
+
+/**
+ * Options for starting a Workflow
+ */
+export type WorkflowStartOptions<T extends Workflow = Workflow> = WithWorkflowArgs<T, WorkflowOptions>;