addressing pr feedback:

- symbol usage to mark if connection supports ews
- separate file for interceptor adapters, adapt wf client interceptors on wf client creation
- deprecate `start` wf client interceptor in favor of `startWithDetails`

Author: THardy98

packages/client/src/interceptor-adapters.ts

@@ -0,0 +1,42 @@
+import { WorkflowClientInterceptor, WorkflowStartInput, WorkflowStartOutput } from './interceptors';
+
+// Apply adapters to workflow client interceptor.
+export function adaptWorkflowClientInterceptor(i: WorkflowClientInterceptor): WorkflowClientInterceptor {
+  return adaptLegacyStartInterceptor(i);
+}
+
+// Adapt legacy `start` interceptors to the new `startWithDetails` interceptor.
+function adaptLegacyStartInterceptor(i: WorkflowClientInterceptor): WorkflowClientInterceptor {
+  // If it already has the new method, or doesn't have the legacy one, no adaptation is needed.
+  // eslint-disable-next-line deprecation/deprecation
+  if (i.startWithDetails || !i.start) {
+    return i;
+  }
+
+  // This interceptor has a legacy `start` but not `startWithDetails`. We'll adapt it.
+  return {
+    ...i,
+    startWithDetails: async (input, next): Promise<WorkflowStartOutput> => {
+      let downstreamOut: WorkflowStartOutput | undefined;
+
+      // Patched `next` for legacy `start` interceptors.
+      // Captures the full `WorkflowStartOutput` while returning `runId` as a string.
+      const patchedNext = async (patchedInput: WorkflowStartInput): Promise<string> => {
+        downstreamOut = await next(patchedInput);
+        return downstreamOut.runId;
+      };
+
+      const runIdFromLegacyInterceptor = await i.start!(input, patchedNext); // eslint-disable-line deprecation/deprecation
+
+      // If the interceptor short-circuited (didn't call `next`), `downstreamOut` will be undefined.
+      // In that case, we can't have an eager start.
+      if (downstreamOut === undefined) {
+        return { runId: runIdFromLegacyInterceptor, eagerlyStarted: false };
+      }
+
+      // If `next` was called, honor the `runId` from the legacy interceptor but preserve
+      // the `eagerlyStarted` status from the actual downstream call.
+      return { ...downstreamOut, runId: runIdFromLegacyInterceptor };
+    },
+  };
+}

packages/client/src/interceptors.ts

@@ -124,6 +124,8 @@ export interface WorkflowClientInterceptor {
    *
    * If you implement this method,
    * {@link signalWithStart} most likely needs to be implemented too
+   *
+   * @deprecated in favour of {@link startWithDetails}
    */
   start?: (input: WorkflowStartInput, next: Next<this, 'start'>) => Promise<string /* runId */>;
 

packages/client/src/types.ts

@@ -163,14 +163,19 @@ export interface ConnectionLike {
    * @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
    */
   withAbortSignal<R>(abortSignal: AbortSignal, fn: () => Promise<R>): Promise<R>;
-
-  /**
-   * Capability flag that determines whether the connection supports eager workflow start.
-   * This will only be true if the underlying connection is a {@link NativeConnection}.
-   */
-  readonly supportsEagerStart?: boolean;
 }
 
+export const InternalConnectionLikeSymbol = Symbol('__temporal_internal_connection_like');
+export type InternalConnectionLike = ConnectionLike & {
+  [InternalConnectionLikeSymbol]?: {
+    /**
+     * Capability flag that determines whether the connection supports eager workflow start.
+     * This will only be true if the underlying connection is a {@link NativeConnection}.
+     */
+    readonly supportsEagerStart?: boolean;
+  };
+};
+
 export const QueryRejectCondition = {
   NONE: 'NONE',
   NOT_OPEN: 'NOT_OPEN',

packages/client/src/workflow-client.ts

@@ -68,6 +68,8 @@ import {
   DescribeWorkflowExecutionResponse,
   encodeQueryRejectCondition,
   GetWorkflowExecutionHistoryRequest,
+  InternalConnectionLike,
+  InternalConnectionLikeSymbol,
   QueryRejectCondition,
   RequestCancelWorkflowExecutionResponse,
   StartWorkflowExecutionRequest,
@@ -94,6 +96,7 @@ import {
 } from './base-client';
 import { mapAsyncIterable } from './iterators-utils';
 import { WorkflowUpdateStage, encodeWorkflowUpdateStage } from './workflow-update-stage';
+import { adaptWorkflowClientInterceptor } from './interceptor-adapters';
 
 const UpdateWorkflowExecutionLifecycleStage = temporal.api.enums.v1.UpdateWorkflowExecutionLifecycleStage;
 
@@ -528,43 +531,8 @@ export class WorkflowClient extends BaseClient {
     assertRequiredWorkflowOptions(options);
     const compiledOptions = compileWorkflowOptions(ensureArgs(options));
 
-    // Adapt legacy `start` interceptors to the new `startWithDetails` interface.
-    const adaptedInterceptors: WorkflowClientInterceptor[] = interceptors.map((i) => {
-      // If it already has the new method, or doesn't have the legacy one, no adaptation is needed.
-      if (i.startWithDetails || !i.start) {
-        return i;
-      }
-
-      // This interceptor has a legacy `start` but not `startWithDetails`. We'll adapt it.
-      return {
-        ...i,
-        startWithDetails: async (input, next): Promise<WorkflowStartOutput> => {
-          let downstreamOut: WorkflowStartOutput | undefined;
-
-          // Patched `next` for legacy `start` interceptors.
-          // Captures the full `WorkflowStartOutput` while returning `runId` as a string.
-          const patchedNext = async (patchedInput: WorkflowStartInput): Promise<string> => {
-            downstreamOut = await next(patchedInput);
-            return downstreamOut.runId;
-          };
-
-          const runIdFromLegacyInterceptor = await i.start!(input, patchedNext);
-
-          // If the interceptor short-circuited (didn't call `next`), `downstreamOut` will be undefined.
-          // In that case, we can't have an eager start.
-          if (downstreamOut === undefined) {
-            return { runId: runIdFromLegacyInterceptor, eagerlyStarted: false };
-          }
-
-          // If `next` was called, honor the `runId` from the legacy interceptor but preserve
-          // the `eagerlyStarted` status from the actual downstream call.
-          return { ...downstreamOut, runId: runIdFromLegacyInterceptor };
-        },
-      };
-    });
-
     const startWithDetails = composeInterceptors(
-      adaptedInterceptors,
+      interceptors,
       'startWithDetails',
       this._startWorkflowHandler.bind(this)
     );
@@ -1320,8 +1288,10 @@ export class WorkflowClient extends BaseClient {
   protected async createStartWorkflowRequest(input: WorkflowStartInput): Promise<StartWorkflowExecutionRequest> {
     const { options: opts, workflowType, headers } = input;
     const { identity, namespace } = this.options;
+    const supportsEagerStart = (this.connection as InternalConnectionLike)?.[InternalConnectionLikeSymbol]
+      ?.supportsEagerStart;
 
-    if (opts.requestEagerStart && !('supportsEagerStart' in this.connection && this.connection.supportsEagerStart)) {
+    if (opts.requestEagerStart && !supportsEagerStart) {
       throw new Error(
         'Eager workflow start requires a NativeConnection shared between client and worker. ' +
           'Pass a NativeConnection via ClientOptions.connection, or disable requestEagerStart.'
@@ -1674,7 +1644,11 @@ export class WorkflowClient extends BaseClient {
       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[]) : [];
+    const interceptors = Array.isArray(this.options.interceptors)
+      ? (this.options.interceptors as WorkflowClientInterceptor[])
+      : [];
+    // Apply adapters to workflow client interceptors.
+    return interceptors.map((i) => adaptWorkflowClientInterceptor(i));
   }
 }
 

packages/test/src/test-integration-workflows.ts

@@ -3,7 +3,7 @@ import { randomUUID } from 'crypto';
 import asyncRetry from 'async-retry';
 import { ExecutionContext } from 'ava';
 import { firstValueFrom, Subject } from 'rxjs';
-import { Client, Connection, WorkflowClient, WorkflowFailedError, WorkflowHandle } from '@temporalio/client';
+import { Client, WorkflowClient, WorkflowFailedError, WorkflowHandle } from '@temporalio/client';
 import * as activity from '@temporalio/activity';
 import { msToNumber, tsToMs } from '@temporalio/common/lib/time';
 import { TestWorkflowEnvironment } from '@temporalio/testing';

packages/worker/src/connection.ts

@@ -3,7 +3,13 @@ import * as grpc from '@grpc/grpc-js';
 import * as proto from 'protobufjs';
 import { IllegalStateError } from '@temporalio/common';
 import { native } from '@temporalio/core-bridge';
-import { ConnectionLike, Metadata, CallContext, WorkflowService } from '@temporalio/client';
+import {
+  ConnectionLike,
+  Metadata,
+  CallContext,
+  WorkflowService,
+  InternalConnectionLikeSymbol,
+} from '@temporalio/client';
 import { TransportError } from './errors';
 import { NativeConnectionOptions } from './connection-options';
 import { Runtime } from './runtime';
@@ -16,7 +22,6 @@ import { Runtime } from './runtime';
  * This class can be used to power `@temporalio/client`'s Client objects.
  */
 export class NativeConnection implements ConnectionLike {
-  public readonly supportsEagerStart = true;
   /**
    * referenceHolders is used internally by the framework, it can be accessed with `extractReferenceHolders` (below)
    */
@@ -33,6 +38,14 @@ export class NativeConnection implements ConnectionLike {
     private readonly nativeClient: native.Client
   ) {
     this.workflowService = WorkflowService.create(this.sendRequest.bind(this), false, false);
+
+    // Set internal capability flag - not part of public API
+    Object.defineProperty(this, InternalConnectionLikeSymbol, {
+      value: { supportsEagerStart: true },
+      writable: false,
+      enumerable: false,
+      configurable: false,
+    });
   }
 
   /**