@temporalio/client 1.2.0 → 1.4.0

package/src/workflow-client.ts

@@ -18,23 +18,24 @@ import {
   decodeOptionalFailureToOptionalError,
   encodeMapToPayloads,
   encodeToPayloads,
+  filterNullAndUndefined,
+  isLoadedDataConverter,
   loadDataConverter,
-} from '@temporalio/internal-non-workflow-common';
+} from '@temporalio/common/lib/internal-non-workflow';
 import {
   BaseWorkflowHandle,
   compileRetryPolicy,
-  composeInterceptors,
-  optionalTsToDate,
   QueryDefinition,
-  Replace,
   SearchAttributes,
   SignalDefinition,
-  tsToDate,
   WithWorkflowArgs,
   Workflow,
   WorkflowNotFoundError,
   WorkflowResultType,
-} from '@temporalio/internal-workflow-common';
+} 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';
@@ -118,7 +119,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 +171,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 +296,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 +307,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 +398,7 @@ export class WorkflowClient {
       headers: {},
       workflowType,
       signalName: typeof signal === 'string' ? signal : signal.name,
-      signalArgs,
+      signalArgs: signalArgs ?? [],
     });
   }
 
@@ -409,15 +430,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 +451,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 +527,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 +540,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 +627,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 +647,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 +665,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 +688,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 +699,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 +729,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 +738,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 +776,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,21 +870,20 @@ 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: 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
           ),
-          searchAttributes: mapFromPayloads(
-            searchAttributePayloadConverter,
-            raw.workflowExecutionInfo!.searchAttributes?.indexedFields ?? {}
-          ) as SearchAttributes,
           parentExecution: raw.workflowExecutionInfo?.parentExecution
             ? {
                 workflowId: raw.workflowExecutionInfo.parentExecution.workflowId!,

package/src/workflow-options.ts

@@ -1,10 +1,6 @@
-import {
-  CommonWorkflowOptions,
-  SignalDefinition,
-  WithCompiledWorkflowOptions,
-} from '@temporalio/internal-workflow-common';
+import { CommonWorkflowOptions, SignalDefinition, WithCompiledWorkflowOptions } from '@temporalio/common';
 
-export * from '@temporalio/internal-workflow-common/lib/workflow-options';
+export * from '@temporalio/common/lib/workflow-options';
 
 export interface CompiledWorkflowOptions extends WithCompiledWorkflowOptions<WorkflowOptions> {
   args: unknown[];
@@ -37,40 +33,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;
+}