@temporalio/client 1.2.0 → 1.3.1

package/src/connection.ts

@@ -5,7 +5,7 @@ import type { RPCImpl } from 'protobufjs';
 import { isServerErrorResponse, ServiceError } from './errors';
 import { defaultGrpcRetryOptions, makeGrpcRetryInterceptor } from './grpc-retry';
 import pkg from './pkg';
-import { CallContext, Metadata, OperatorService, WorkflowService } from './types';
+import { CallContext, HealthService, Metadata, OperatorService, WorkflowService } from './types';
 
 /**
  * gRPC and Temporal Server connection options
@@ -63,7 +63,7 @@ export interface ConnectionOptions {
    * Used either when connecting eagerly with {@link Connection.connect} or
    * calling {@link Connection.ensureConnected}.
    *
-   * @format {@link https://www.npmjs.com/package/ms | ms} formatted string
+   * @format number of milliseconds or {@link https://www.npmjs.com/package/ms | ms-formatted string}
    * @default 10 seconds
    */
   connectTimeout?: number | string;
@@ -146,7 +146,14 @@ export interface ConnectionCtorOptions {
    * **NOTE**: The namespace provided in {@link options} is **not** automatically set on requests made to the service.
    */
   readonly workflowService: WorkflowService;
+  /**
+   * Raw gRPC access to the Temporal {@link https://github.com/temporalio/api/blob/ddf07ab9933e8230309850e3c579e1ff34b03f53/temporal/api/operatorservice/v1/service.proto | operator service}.
+   */
   readonly operatorService: OperatorService;
+  /**
+   * Raw gRPC access to the standard gRPC {@link https://github.com/grpc/grpc/blob/92f58c18a8da2728f571138c37760a721c8915a2/doc/health-checking.md | health service}.
+   */
+  readonly healthService: HealthService;
   readonly callContextStorage: AsyncLocalStorage<CallContext>;
 }
 
@@ -181,6 +188,7 @@ export class Connection {
    * {@link https://github.com/temporalio/api/blob/master/temporal/api/operatorservice/v1/service.proto | Operator service}
    */
   public readonly operatorService: OperatorService;
+  public readonly healthService: HealthService;
   readonly callContextStorage: AsyncLocalStorage<CallContext>;
 
   protected static createCtorOptions(options?: ConnectionOptions): ConnectionCtorOptions {
@@ -214,12 +222,20 @@ export class Connection {
       interceptors: optionsWithDefaults?.interceptors,
     });
     const operatorService = OperatorService.create(operatorRpcImpl, false, false);
+    const healthRpcImpl = this.generateRPCImplementation({
+      serviceName: 'grpc.health.v1.Health',
+      client,
+      callContextStorage,
+      interceptors: optionsWithDefaults?.interceptors,
+    });
+    const healthService = HealthService.create(healthRpcImpl, false, false);
 
     return {
       client,
       callContextStorage,
       workflowService,
       operatorService,
+      healthService,
       options: optionsWithDefaults,
     };
   }
@@ -282,12 +298,14 @@ export class Connection {
     client,
     workflowService,
     operatorService,
+    healthService,
     callContextStorage,
   }: ConnectionCtorOptions) {
     this.options = options;
     this.client = client;
     this.workflowService = workflowService;
     this.operatorService = operatorService;
+    this.healthService = healthService;
     this.callContextStorage = callContextStorage;
   }
 

package/src/index.ts

@@ -28,6 +28,7 @@ export * from '@temporalio/internal-workflow-common/lib/errors';
 export * from '@temporalio/internal-workflow-common/lib/interfaces';
 export * from '@temporalio/internal-workflow-common/lib/workflow-handle';
 export * from './async-completion-client';
+export * from './client';
 export { Connection, ConnectionOptions, ConnectionOptionsWithDefaults, LOCAL_TARGET } from './connection';
 export * from './errors';
 export * from './grpc-retry';

package/src/interceptors.ts

@@ -112,7 +112,7 @@ export interface WorkflowClientCallsInterceptor {
   describe?: (input: WorkflowDescribeInput, next: Next<this, 'describe'>) => Promise<DescribeWorkflowExecutionResponse>;
 }
 
-interface WorkflowClientCallsInterceptorFactoryInput {
+export interface WorkflowClientCallsInterceptorFactoryInput {
   workflowId: string;
   runId?: string;
 }
@@ -130,3 +130,12 @@ export interface WorkflowClientCallsInterceptorFactory {
 export interface WorkflowClientInterceptors {
   calls?: WorkflowClientCallsInterceptorFactory[];
 }
+
+/**
+ * Interceptors for any high-level SDK client.
+ *
+ * NOTE: Currently only for {@link WorkflowClient}. More will be added later as needed.
+ */
+export interface ClientInterceptors {
+  workflow?: WorkflowClientInterceptors;
+}

package/src/types.ts

@@ -1,18 +1,20 @@
 import type { SearchAttributes } from '@temporalio/internal-workflow-common';
-import { temporal } from '@temporalio/proto';
+import * as proto from '@temporalio/proto';
 import type * as grpc from '@grpc/grpc-js';
-import Long from 'long';
 
 export interface WorkflowExecution {
   workflowId: string;
   runId?: string;
 }
-export type StartWorkflowExecutionRequest = temporal.api.workflowservice.v1.IStartWorkflowExecutionRequest;
-export type GetWorkflowExecutionHistoryRequest = temporal.api.workflowservice.v1.IGetWorkflowExecutionHistoryRequest;
-export type DescribeWorkflowExecutionResponse = temporal.api.workflowservice.v1.IDescribeWorkflowExecutionResponse;
-export type TerminateWorkflowExecutionResponse = temporal.api.workflowservice.v1.ITerminateWorkflowExecutionResponse;
+export type StartWorkflowExecutionRequest = proto.temporal.api.workflowservice.v1.IStartWorkflowExecutionRequest;
+export type GetWorkflowExecutionHistoryRequest =
+  proto.temporal.api.workflowservice.v1.IGetWorkflowExecutionHistoryRequest;
+export type DescribeWorkflowExecutionResponse =
+  proto.temporal.api.workflowservice.v1.IDescribeWorkflowExecutionResponse;
+export type TerminateWorkflowExecutionResponse =
+  proto.temporal.api.workflowservice.v1.ITerminateWorkflowExecutionResponse;
 export type RequestCancelWorkflowExecutionResponse =
-  temporal.api.workflowservice.v1.IRequestCancelWorkflowExecutionResponse;
+  proto.temporal.api.workflowservice.v1.IRequestCancelWorkflowExecutionResponse;
 
 export type WorkflowExecutionStatusName =
   | 'UNSPECIFIED'
@@ -30,21 +32,23 @@ export interface WorkflowExecutionDescription {
   workflowId: string;
   runId: string;
   taskQueue: string;
-  status: { code: temporal.api.enums.v1.WorkflowExecutionStatus; name: WorkflowExecutionStatusName };
-  historyLength: Long;
+  status: { code: proto.temporal.api.enums.v1.WorkflowExecutionStatus; name: WorkflowExecutionStatusName };
+  historyLength: number;
   startTime: Date;
   executionTime?: Date;
   closeTime?: Date;
   memo?: Record<string, unknown>;
   searchAttributes: SearchAttributes;
-  parentExecution?: Required<temporal.api.common.v1.IWorkflowExecution>;
+  parentExecution?: Required<proto.temporal.api.common.v1.IWorkflowExecution>;
   raw: DescribeWorkflowExecutionResponse;
 }
 
-export type WorkflowService = temporal.api.workflowservice.v1.WorkflowService;
-export const { WorkflowService } = temporal.api.workflowservice.v1;
-export type OperatorService = temporal.api.operatorservice.v1.OperatorService;
-export const { OperatorService } = temporal.api.operatorservice.v1;
+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;
+export const { OperatorService } = proto.temporal.api.operatorservice.v1;
+export type HealthService = proto.grpc.health.v1.Health;
+export const { Health: HealthService } = proto.grpc.health.v1;
 
 /**
  * Mapping of string to valid gRPC metadata value

package/src/workflow-client.ts

@@ -18,6 +18,8 @@ import {
   decodeOptionalFailureToOptionalError,
   encodeMapToPayloads,
   encodeToPayloads,
+  filterNullAndUndefined,
+  isLoadedDataConverter,
   loadDataConverter,
 } from '@temporalio/internal-non-workflow-common';
 import {
@@ -118,7 +120,17 @@ export interface WorkflowHandle<T extends Workflow = Workflow> extends BaseWorkf
   terminate(reason?: string): Promise<TerminateWorkflowExecutionResponse>;
 
   /**
-   * Cancel a running Workflow
+   * Cancel a running Workflow.
+   *
+   * When a Workflow is cancelled, the root scope throws {@link CancelledFailure} with `message: 'Workflow canceled'`.
+   * That means that all cancellable scopes will throw `CancelledFailure`.
+   *
+   * Cancellation may be propagated to Activities depending on {@link ActivityOptions#cancellationType}, after which
+   * Activity calls may throw an {@link ActivityFailure}, and `isCancellation(error)` will be true (see {@link isCancellation}).
+   *
+   * Cancellation may be propagated to Child Workflows depending on {@link ChildWorkflowOptions#cancellationType}, after
+   * which calls to {@link executeChild} and {@link ChildWorkflowHandle#result} will throw, and `isCancellation(error)`
+   * will be true (see {@link isCancellation}).
    */
   cancel(): Promise<RequestCancelWorkflowExecutionResponse>;
 
@@ -160,9 +172,9 @@ export interface WorkflowHandleWithSignaledRunId<T extends Workflow = Workflow>
 
 export interface WorkflowClientOptions {
   /**
-   * {@link DataConverter} to use for serializing and deserializing payloads
+   * {@link DataConverter} or {@link LoadedDataConverter} to use for serializing and deserializing payloads
    */
-  dataConverter?: DataConverter;
+  dataConverter?: DataConverter | LoadedDataConverter;
 
   /**
    * Used to override and extend default Connection functionality
@@ -285,7 +297,10 @@ interface WorkflowHandleOptions extends GetWorkflowHandleOptions {
 export type WorkflowStartOptions<T extends Workflow = Workflow> = WithWorkflowArgs<T, WorkflowOptions>;
 
 /**
- * Client for starting Workflow executions and creating Workflow handles
+ * Client for starting Workflow executions and creating Workflow handles.
+ *
+ * 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 {
   public readonly options: LoadedWorkflowClientOptions;
@@ -293,22 +308,29 @@ export class WorkflowClient {
 
   constructor(options?: WorkflowClientOptions) {
     this.connection = options?.connection ?? Connection.lazy();
+    const dataConverter = options?.dataConverter;
+    const loadedDataConverter = isLoadedDataConverter(dataConverter) ? dataConverter : loadDataConverter(dataConverter);
     this.options = {
       ...defaultWorkflowClientOptions(),
-      ...options,
-      loadedDataConverter: loadDataConverter(options?.dataConverter),
+      ...filterNullAndUndefined(options ?? {}),
+      loadedDataConverter,
     };
   }
 
   /**
    * Raw gRPC access to the Temporal service.
    *
-   * **NOTE**: The namespace provided in {@link options} is **not** automatically set on requests made to the service.
+   * **NOTE**: The namespace provided in {@link options} is **not** automatically set on requests made via this service
+   * object.
    */
   get workflowService(): WorkflowService {
     return this.connection.workflowService;
   }
 
+  protected get dataConverter(): LoadedDataConverter {
+    return this.options.loadedDataConverter;
+  }
+
   /**
    * Set the deadline for any service requests executed in `fn`'s scope.
    */
@@ -377,7 +399,7 @@ export class WorkflowClient {
       headers: {},
       workflowType,
       signalName: typeof signal === 'string' ? signal : signal.name,
-      signalArgs,
+      signalArgs: signalArgs ?? [],
     });
   }
 
@@ -409,15 +431,15 @@ export class WorkflowClient {
   }
 
   /**
-   * Sends a signal to a running Workflow or starts a new one if not already running and immediately signals it.
-   * Useful when you're unsure of the Workflows' run state.
+   * Sends a Signal to a running Workflow or starts a new one if not already running and immediately Signals it.
+   * Useful when you're unsure whether the Workflow has been started.
    *
-   * @returns a WorkflowHandle to the started Workflow
+   * @returns a {@link WorkflowHandle} to the started Workflow
    */
-  public async signalWithStart<T extends Workflow, SA extends any[] = []>(
-    workflowTypeOrFunc: string | T,
-    options: WithWorkflowArgs<T, WorkflowSignalWithStartOptions<SA>>
-  ): Promise<WorkflowHandleWithSignaledRunId<T>> {
+  public async signalWithStart<WorkflowFn extends Workflow, SignalArgs extends any[] = []>(
+    workflowTypeOrFunc: string | WorkflowFn,
+    options: WithWorkflowArgs<WorkflowFn, WorkflowSignalWithStartOptions<SignalArgs>>
+  ): Promise<WorkflowHandleWithSignaledRunId<WorkflowFn>> {
     const { workflowId } = options;
     const interceptors = (this.options.interceptors.calls ?? []).map((ctor) => ctor({ workflowId }));
     const runId = await this._signalWithStart(workflowTypeOrFunc, options, interceptors);
@@ -430,7 +452,7 @@ export class WorkflowClient {
       runIdForResult: runId,
       interceptors,
       followRuns: options.followRuns ?? true,
-    }) as WorkflowHandleWithSignaledRunId<T>; // Cast is safe because we know we add the signaledRunId below
+    }) as WorkflowHandleWithSignaledRunId<WorkflowFn>; // Cast is safe because we know we add the signaledRunId below
     (handle as any) /* readonly */.signaledRunId = runId;
     return handle;
   }
@@ -506,7 +528,7 @@ export class WorkflowClient {
         // Note that we can only return one value from our workflow function in JS.
         // Ignore any other payloads in result
         const [result] = await decodeArrayFromPayloads(
-          this.options.loadedDataConverter,
+          this.dataConverter,
           ev.workflowExecutionCompletedEventAttributes.result?.payloads
         );
         return result as any;
@@ -519,14 +541,14 @@ export class WorkflowClient {
         const { failure, retryState } = ev.workflowExecutionFailedEventAttributes;
         throw new WorkflowFailedError(
           'Workflow execution failed',
-          await decodeOptionalFailureToOptionalError(this.options.loadedDataConverter, failure),
+          await decodeOptionalFailureToOptionalError(this.dataConverter, failure),
           retryState ?? RetryState.RETRY_STATE_UNSPECIFIED
         );
       } else if (ev.workflowExecutionCanceledEventAttributes) {
         const failure = new CancelledFailure(
           'Workflow canceled',
           await decodeArrayFromPayloads(
-            this.options.loadedDataConverter,
+            this.dataConverter,
             ev.workflowExecutionCanceledEventAttributes.details?.payloads
           )
         );
@@ -606,7 +628,7 @@ export class WorkflowClient {
         execution: input.workflowExecution,
         query: {
           queryType: input.queryType,
-          queryArgs: { payloads: await encodeToPayloads(this.options.loadedDataConverter, ...input.args) },
+          queryArgs: { payloads: await encodeToPayloads(this.dataConverter, ...input.args) },
           header: { fields: input.headers },
         },
       });
@@ -626,7 +648,7 @@ export class WorkflowClient {
       throw new TypeError('Invalid response from server');
     }
     // We ignore anything but the first result
-    return await decodeFromPayloadsAtIndex(this.options.loadedDataConverter, 0, response.queryResult?.payloads);
+    return await decodeFromPayloadsAtIndex(this.dataConverter, 0, response.queryResult?.payloads);
   }
 
   /**
@@ -644,7 +666,7 @@ export class WorkflowClient {
         // control is unused,
         signalName: input.signalName,
         header: { fields: input.headers },
-        input: { payloads: await encodeToPayloads(this.options.loadedDataConverter, ...input.args) },
+        input: { payloads: await encodeToPayloads(this.dataConverter, ...input.args) },
       });
     } catch (err) {
       this.rethrowGrpcError(err, input.workflowExecution, 'Failed to signal Workflow');
@@ -667,9 +689,9 @@ export class WorkflowClient {
         workflowId: options.workflowId,
         workflowIdReusePolicy: options.workflowIdReusePolicy,
         workflowType: { name: workflowType },
-        input: { payloads: await encodeToPayloads(this.options.loadedDataConverter, ...options.args) },
+        input: { payloads: await encodeToPayloads(this.dataConverter, ...options.args) },
         signalName,
-        signalInput: { payloads: await encodeToPayloads(this.options.loadedDataConverter, ...signalArgs) },
+        signalInput: { payloads: await encodeToPayloads(this.dataConverter, ...signalArgs) },
         taskQueue: {
           kind: temporal.api.enums.v1.TaskQueueKind.TASK_QUEUE_KIND_UNSPECIFIED,
           name: options.taskQueue,
@@ -678,9 +700,7 @@ export class WorkflowClient {
         workflowRunTimeout: options.workflowRunTimeout,
         workflowTaskTimeout: options.workflowTaskTimeout,
         retryPolicy: options.retry ? compileRetryPolicy(options.retry) : undefined,
-        memo: options.memo
-          ? { fields: await encodeMapToPayloads(this.options.loadedDataConverter, options.memo) }
-          : undefined,
+        memo: options.memo ? { fields: await encodeMapToPayloads(this.dataConverter, options.memo) } : undefined,
         searchAttributes: options.searchAttributes
           ? {
               indexedFields: mapToPayloads(searchAttributePayloadConverter, options.searchAttributes),
@@ -710,7 +730,7 @@ export class WorkflowClient {
       workflowId: opts.workflowId,
       workflowIdReusePolicy: opts.workflowIdReusePolicy,
       workflowType: { name: workflowType },
-      input: { payloads: await encodeToPayloads(this.options.loadedDataConverter, ...opts.args) },
+      input: { payloads: await encodeToPayloads(this.dataConverter, ...opts.args) },
       taskQueue: {
         kind: temporal.api.enums.v1.TaskQueueKind.TASK_QUEUE_KIND_UNSPECIFIED,
         name: opts.taskQueue,
@@ -719,7 +739,7 @@ export class WorkflowClient {
       workflowRunTimeout: opts.workflowRunTimeout,
       workflowTaskTimeout: opts.workflowTaskTimeout,
       retryPolicy: opts.retry ? compileRetryPolicy(opts.retry) : undefined,
-      memo: opts.memo ? { fields: await encodeMapToPayloads(this.options.loadedDataConverter, opts.memo) } : undefined,
+      memo: opts.memo ? { fields: await encodeMapToPayloads(this.dataConverter, opts.memo) } : undefined,
       searchAttributes: opts.searchAttributes
         ? {
             indexedFields: mapToPayloads(searchAttributePayloadConverter, opts.searchAttributes),
@@ -757,9 +777,7 @@ export class WorkflowClient {
         identity: this.options.identity,
         ...input,
         details: {
-          payloads: input.details
-            ? await encodeToPayloads(this.options.loadedDataConverter, ...input.details)
-            : undefined,
+          payloads: input.details ? await encodeToPayloads(this.dataConverter, ...input.details) : undefined,
         },
         firstExecutionRunId: input.firstExecutionRunId,
       });
@@ -853,17 +871,12 @@ export class WorkflowClient {
             code: raw.workflowExecutionInfo!.status!,
             name: workflowStatusCodeToName(raw.workflowExecutionInfo!.status!),
           },
-          // Technically safe to convert to number, unfortunately this was overlooked when this was originally
-          // implemented.
-          // Max history length is 50k, which is much less than Number.MAX_SAFE_INTEGER
-          historyLength: raw.workflowExecutionInfo!.historyLength!,
+          // 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.options.loadedDataConverter,
-            raw.workflowExecutionInfo!.memo?.fields
-          ),
+          memo: await decodeMapFromPayloads(this.client.dataConverter, raw.workflowExecutionInfo!.memo?.fields),
           searchAttributes: mapFromPayloads(
             searchAttributePayloadConverter,
             raw.workflowExecutionInfo!.searchAttributes?.indexedFields ?? {}

package/src/workflow-options.ts

@@ -37,40 +37,30 @@ export interface WorkflowOptions extends CommonWorkflowOptions {
   followRuns?: boolean;
 }
 
-export interface WorkflowSignalWithStartOptions<SA extends any[] = []> extends WorkflowOptions {
+export type WorkflowSignalWithStartOptions<SignalArgs extends any[] = []> = SignalArgs extends [any, ...any[]]
+  ? WorkflowSignalWithStartOptionsWithArgs<SignalArgs>
+  : WorkflowSignalWithStartOptionsWithoutArgs<SignalArgs>;
+
+export interface WorkflowSignalWithStartOptionsWithoutArgs<SignalArgs extends any[]> extends WorkflowOptions {
   /**
    * SignalDefinition or name of signal
    */
-  signal: SignalDefinition<SA> | string;
+  signal: SignalDefinition | string;
+
   /**
    * Arguments to invoke the signal handler with
    */
-  signalArgs: SA;
+  signalArgs?: SignalArgs;
 }
 
-// export interface WorkflowOptionsWithDefaults<T extends Workflow> extends CommonWorkflowOptionsWithDefaults<T> {
-//   /**
-//    * If set to true, instructs the client to follow the chain of execution before returning a Workflow's result.
-//    *
-//    * Workflow execution is chained if the Workflow has a cron schedule or continues-as-new or configured to retry
-//    * after failure or timeout.
-//    *
-//    * @default true
-//    */
-//   followRuns: boolean;
-// }
-//
-// /**
-//  * Adds default values to `workflowId` and `workflowIdReusePolicy` to given workflow options.
-//  */
-// export function addDefaults<T extends Workflow>(
-//   opts: WithWorkflowArgs<T, WorkflowOptions>
-// ): WorkflowOptionsWithDefaults<T> {
-//   const { workflowId, args, ...rest } = opts;
-//   return {
-//     followRuns: true,
-//     args: args ?? [],
-//     workflowId: workflowId ?? uuid4(),
-//     ...rest,
-//   };
-// }
+export interface WorkflowSignalWithStartOptionsWithArgs<SignalArgs extends any[]> extends WorkflowOptions {
+  /**
+   * SignalDefinition or name of signal
+   */
+  signal: SignalDefinition<SignalArgs> | string;
+
+  /**
+   * Arguments to invoke the signal handler with
+   */
+  signalArgs: SignalArgs;
+}