feat: Add a meta Client class (#870)

Co-authored-by: Loren ☺️ <251288+lorensr@users.noreply.github.com>

Author: bergundy

packages/activity/src/index.ts

@@ -63,7 +63,7 @@ export {
  * Throw this error from an Activity in order to make the Worker forget about this Activity.
  *
  * The Activity can then be completed asynchronously (from anywhere—usually outside the Worker) using
- * {@link AsyncCompletionClient}.
+ * {@link Client.activity}.
  *
  * @example
  *

packages/client/src/async-completion-client.ts

@@ -4,6 +4,7 @@ import {
   encodeErrorToFailure,
   encodeToPayloads,
   filterNullAndUndefined,
+  isLoadedDataConverter,
   loadDataConverter,
 } from '@temporalio/internal-non-workflow-common';
 import { Replace } from '@temporalio/internal-workflow-common';
@@ -41,9 +42,9 @@ export class ActivityCancelledError extends Error {
  */
 export interface AsyncCompletionClientOptions {
   /**
-   * {@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;
 
   /**
    * Identity to report to the server
@@ -69,6 +70,10 @@ export type AsyncCompletionClientOptionsWithDefaults = Replace<
   }
 >;
 
+export type LoadedAsyncCompletionClientOptions = AsyncCompletionClientOptionsWithDefaults & {
+  loadedDataConverter: LoadedDataConverter;
+};
+
 export function defaultAsyncCompletionClientOptions(): AsyncCompletionClientOptionsWithDefaults {
   return {
     dataConverter: {},
@@ -92,22 +97,38 @@ export interface FullActivityId {
 
 /**
  * A client for asynchronous completion and heartbeating of Activities.
+ *
+ * Typically this client should not be instantiated directly, instead create the high level {@link Client} and use
+ * {@link Client.activity} to complete async activities.
  */
 export class AsyncCompletionClient {
-  public readonly options: AsyncCompletionClientOptionsWithDefaults;
-  protected readonly dataConverter: LoadedDataConverter;
+  public readonly options: LoadedAsyncCompletionClientOptions;
   public readonly connection: ConnectionLike;
 
   constructor(options?: AsyncCompletionClientOptions) {
     this.connection = options?.connection ?? Connection.lazy();
-    this.dataConverter = loadDataConverter(options?.dataConverter);
-    this.options = { ...defaultAsyncCompletionClientOptions(), ...filterNullAndUndefined(options ?? {}) };
+    const dataConverter = options?.dataConverter;
+    const loadedDataConverter = isLoadedDataConverter(dataConverter) ? dataConverter : loadDataConverter(dataConverter);
+    this.options = {
+      ...defaultAsyncCompletionClientOptions(),
+      ...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.
+   */
   get workflowService(): WorkflowService {
     return this.connection.workflowService;
   }
 
+  protected get dataConverter(): LoadedDataConverter {
+    return this.options.loadedDataConverter;
+  }
+
   /**
    * Transforms grpc errors into well defined TS errors.
    */

packages/client/src/client.ts

@@ -0,0 +1,152 @@
+import { DataConverter, LoadedDataConverter } from '@temporalio/common';
+import { filterNullAndUndefined, loadDataConverter } from '@temporalio/internal-non-workflow-common';
+import { Replace } from '@temporalio/internal-workflow-common';
+import { temporal } from '@temporalio/proto';
+import os from 'os';
+import { AsyncCompletionClient } from './async-completion-client';
+import { Connection } from './connection';
+import { ClientInterceptors } from './interceptors';
+import { ConnectionLike, Metadata, WorkflowService } from './types';
+import { WorkflowClient } from './workflow-client';
+
+export interface ClientOptions {
+  /**
+   * {@link DataConverter} to use for serializing and deserializing payloads
+   */
+  dataConverter?: DataConverter;
+
+  /**
+   * Used to override and extend default Connection functionality
+   *
+   * Useful for injecting auth headers and tracing Workflow executions
+   */
+  interceptors?: ClientInterceptors;
+
+  /**
+   * 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;
+
+  workflow?: {
+    /**
+     * Should a query be rejected by closed and failed workflows
+     *
+     * @default QUERY_REJECT_CONDITION_UNSPECIFIED which means that closed and failed workflows are still queryable
+     */
+    queryRejectCondition?: temporal.api.enums.v1.QueryRejectCondition;
+  };
+}
+
+export type ClientOptionsWithDefaults = Replace<
+  Required<ClientOptions>,
+  {
+    connection?: ConnectionLike;
+  }
+>;
+
+export type LoadedClientOptions = ClientOptionsWithDefaults & {
+  loadedDataConverter: LoadedDataConverter;
+};
+
+export function defaultClientOptions(): ClientOptionsWithDefaults {
+  return {
+    dataConverter: {},
+    identity: `${process.pid}@${os.hostname()}`,
+    interceptors: {},
+    namespace: 'default',
+    workflow: {
+      queryRejectCondition: temporal.api.enums.v1.QueryRejectCondition.QUERY_REJECT_CONDITION_UNSPECIFIED,
+    },
+  };
+}
+
+/**
+ * High level SDK client.
+ *
+ *
+ */
+export class Client {
+  /**
+   * Underlying gRPC connection to the Temporal service
+   */
+  public readonly connection: ConnectionLike;
+  public readonly options: LoadedClientOptions;
+  /**
+   * Workflow sub-client - use to start and interact with Workflows
+   */
+  public readonly workflow: WorkflowClient;
+  /**
+   * (Async) Activity completion sub-client - use to manually manage Activities
+   */
+  public readonly activity: AsyncCompletionClient;
+
+  constructor(options?: ClientOptions) {
+    this.connection = options?.connection ?? Connection.lazy();
+    this.options = {
+      ...defaultClientOptions(),
+      ...filterNullAndUndefined(options ?? {}),
+      loadedDataConverter: loadDataConverter(options?.dataConverter),
+    };
+
+    const { workflow, loadedDataConverter, interceptors, ...base } = this.options;
+
+    this.workflow = new WorkflowClient({
+      ...base,
+      ...workflow,
+      connection: this.connection,
+      dataConverter: loadedDataConverter,
+      interceptors: interceptors.workflow,
+    });
+
+    this.activity = new AsyncCompletionClient({
+      ...base,
+      connection: this.connection,
+      dataConverter: 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.
+   */
+  get workflowService(): WorkflowService {
+    return this.connection.workflowService;
+  }
+
+  /**
+   * 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);
+  }
+}

packages/client/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';

packages/client/src/interceptors.ts

@@ -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;
+}