feat(workflow): support TypeInfo for client-started workflows

Author: THardy98

CHANGELOG.md

@@ -23,7 +23,7 @@ to docs, or any other relevant information.
 
 - **Experimental**: Added `TypeInfo`, `TransferTypeConverter`, and `ConverterHint` to `@temporalio/common` for converting
   application values to and from serialization-friendly transfer types and supplying converter-specific metadata
-  during payload conversion.
+  during payload conversion, including client-started Workflow inputs and results.
 
 ## [1.21.1] - 2026-07-23
 

packages/client/src/workflow-client.ts

@@ -11,6 +11,8 @@ import type {
   WorkflowResultType,
   WorkflowIdConflictPolicy,
   WorkflowSerializationContext,
+  WorkflowTypeOptions,
+  PayloadTypeInfo,
 } from '@temporalio/common';
 import {
   CancelledFailure,
@@ -21,11 +23,11 @@ import {
   TimeoutType,
   WorkflowExecutionAlreadyStartedError,
   WorkflowNotFoundError,
-  extractWorkflowType,
   encodeWorkflowIdReusePolicy,
   decodeRetryState,
   encodeWorkflowIdConflictPolicy,
   compilePriority,
+  extractWorkflowTypeAndConfig,
 } from '@temporalio/common';
 import { encodeUserMetadata } from '@temporalio/common/lib/internal-non-workflow/codec-helpers';
 import { encodeUnifiedSearchAttributes } from '@temporalio/common/lib/converter/payload-search-attributes';
@@ -360,6 +362,16 @@ export interface WorkflowResultOptions {
    * @default true
    */
   followRuns?: boolean;
+
+  /**
+   * Type information used to decode the Workflow result.
+   *
+   * This is only needed when getting a result from an existing Workflow handle or
+   * when the Workflow definition is not available to this client.
+   *
+   * @experimental
+   */
+  typeInfo?: PayloadTypeInfo;
 }
 
 /**
@@ -550,13 +562,16 @@ export class WorkflowClient extends BaseClient {
   }
 
   protected async _start<T extends Workflow>(
-    workflowTypeOrFunc: string | T,
+    workflowTypeOptions: WorkflowTypeOptions,
     options: WorkflowStartOptions<T>,
     interceptors: WorkflowClientInterceptor[]
   ): Promise<WorkflowStartOutput> {
-    const workflowType = extractWorkflowType(workflowTypeOrFunc);
     assertRequiredWorkflowOptions(options);
-    const compiledOptions = compileWorkflowOptions(ensureArgs(options));
+    const workflowOptions = {
+      ...options,
+      typeInfo: workflowTypeOptions.typeInfo,
+    };
+    const compiledOptions = compileWorkflowOptions(ensureArgs(workflowOptions));
     const adaptedInterceptors = interceptors.map((i) => adaptWorkflowClientInterceptor(i));
 
     const startWithDetails = composeInterceptors(
@@ -568,7 +583,7 @@ export class WorkflowClient extends BaseClient {
     return startWithDetails({
       options: compiledOptions,
       headers: {},
-      workflowType,
+      workflowType: workflowTypeOptions.type,
     });
   }
 
@@ -577,10 +592,14 @@ export class WorkflowClient extends BaseClient {
     options: WithWorkflowArgs<T, WorkflowSignalWithStartOptions<SA>>,
     interceptors: WorkflowClientInterceptor[]
   ): Promise<string> {
-    const workflowType = extractWorkflowType(workflowTypeOrFunc);
     const { signal, signalArgs, ...rest } = options;
+    const { type: workflowType, typeInfo } = extractWorkflowTypeAndConfig(workflowTypeOrFunc, rest.typeInfo);
     assertRequiredWorkflowOptions(rest);
-    const compiledOptions = compileWorkflowOptions(ensureArgs(rest));
+    const workflowOptions = {
+      ...rest,
+      typeInfo,
+    };
+    const compiledOptions = compileWorkflowOptions(ensureArgs(workflowOptions));
     const signalWithStart = composeInterceptors(
       interceptors,
       'signalWithStart',
@@ -607,7 +626,8 @@ export class WorkflowClient extends BaseClient {
   ): Promise<WorkflowHandleWithStartDetails<T>> {
     const { workflowId } = options;
     const interceptors = this.getOrMakeInterceptors(workflowId);
-    const wfStartOutput = await this._start(workflowTypeOrFunc, { ...options, workflowId }, interceptors);
+    const workflowTypeOptions = extractWorkflowTypeAndConfig(workflowTypeOrFunc, options.typeInfo);
+    const wfStartOutput = await this._start(workflowTypeOptions, { ...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.
     const baseHandle = this._createWorkflowHandle({
@@ -617,6 +637,7 @@ export class WorkflowClient extends BaseClient {
       runIdForResult: wfStartOutput.runId,
       interceptors,
       followRuns: options.followRuns ?? true,
+      typeInfo: workflowTypeOptions.typeInfo,
     });
     return {
       ...baseHandle,
@@ -642,6 +663,7 @@ export class WorkflowClient extends BaseClient {
   ): Promise<WorkflowHandleWithSignaledRunId<WorkflowFn>> {
     const { workflowId } = options;
     const interceptors = this.getOrMakeInterceptors(workflowId);
+    const workflowTypeOptions = extractWorkflowTypeAndConfig(workflowTypeOrFunc, options.typeInfo);
     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.
@@ -652,6 +674,7 @@ export class WorkflowClient extends BaseClient {
       runIdForResult: runId,
       interceptors,
       followRuns: options.followRuns ?? true,
+      typeInfo: workflowTypeOptions.typeInfo,
     }) as WorkflowHandleWithSignaledRunId<WorkflowFn>; // Cast is safe because we know we add the signaledRunId below
     (handle as any) /* readonly */.signaledRunId = runId;
     return handle;
@@ -736,11 +759,16 @@ export class WorkflowClient extends BaseClient {
       throw new Error('This WithStartWorkflowOperation instance has already been executed.');
     }
     startWorkflowOperation[withStartWorkflowOperationUsed] = true;
+    const { type: workflowType, typeInfo } = extractWorkflowTypeAndConfig(workflowTypeOrFunc, workflowOptions.typeInfo);
     assertRequiredWorkflowOptions(workflowOptions);
 
+    const resolvedWorkflowOptions = {
+      ...workflowOptions,
+      typeInfo,
+    };
     const startUpdateWithStartInput: WorkflowStartUpdateWithStartInput = {
-      workflowType: extractWorkflowType(workflowTypeOrFunc),
-      workflowStartOptions: compileWorkflowOptions(ensureArgs(workflowOptions)),
+      workflowType,
+      workflowStartOptions: compileWorkflowOptions(ensureArgs(resolvedWorkflowOptions)),
       workflowStartHeaders: {},
       updateName: typeof updateDef === 'string' ? updateDef : updateDef.name,
       updateArgs: args ?? [],
@@ -757,6 +785,7 @@ export class WorkflowClient extends BaseClient {
           firstExecutionRunId: startResponse.runId ?? undefined,
           interceptors,
           followRuns: workflowOptions.followRuns ?? true,
+          typeInfo,
         })
       );
 
@@ -798,10 +827,12 @@ export class WorkflowClient extends BaseClient {
   ): Promise<WorkflowResultType<T>> {
     const { workflowId } = options;
     const interceptors = this.getOrMakeInterceptors(workflowId);
-    await this._start(workflowTypeOrFunc, options, interceptors);
+    const workflowTypeOptions = extractWorkflowTypeAndConfig(workflowTypeOrFunc, options.typeInfo);
+    await this._start(workflowTypeOptions, options, interceptors);
     return await this.result(workflowId, undefined, {
       ...options,
       followRuns: options.followRuns ?? true,
+      typeInfo: workflowTypeOptions.typeInfo,
     });
   }
 
@@ -857,12 +888,14 @@ export class WorkflowClient extends BaseClient {
         }
         // Note that we can only return one value from our workflow function in JS.
         // Ignore any other payloads in result
-        const [result] = await decodeArrayFromPayloads(
+        const result = await decodeFromPayloadsAtIndex<WorkflowResultType<T>>(
           dataConverter,
+          0,
           ev.workflowExecutionCompletedEventAttributes.result?.payloads,
-          context
+          context,
+          opts?.typeInfo?.outputType
         );
-        return result as any;
+        return result;
       } else if (ev.workflowExecutionFailedEventAttributes) {
         if (followRuns && ev.workflowExecutionFailedEventAttributes.newExecutionRunId) {
           execution.runId = ev.workflowExecutionFailedEventAttributes.newExecutionRunId;
@@ -1335,7 +1368,9 @@ export class WorkflowClient extends BaseClient {
       workflowIdReusePolicy: encodeWorkflowIdReusePolicy(options.workflowIdReusePolicy),
       workflowIdConflictPolicy: encodeWorkflowIdConflictPolicy(options.workflowIdConflictPolicy),
       workflowType: { name: workflowType },
-      input: { payloads: await encodeToPayloadsWithContext(dataConverter, context, options.args) },
+      input: {
+        payloads: await encodeToPayloadsWithContext(dataConverter, context, options.args, options.typeInfo?.inputTypes),
+      },
       signalName,
       signalInput: { payloads: await encodeToPayloadsWithContext(dataConverter, context, signalArgs) },
       taskQueue: {
@@ -1465,7 +1500,9 @@ export class WorkflowClient extends BaseClient {
       workflowIdReusePolicy: encodeWorkflowIdReusePolicy(opts.workflowIdReusePolicy),
       workflowIdConflictPolicy: encodeWorkflowIdConflictPolicy(opts.workflowIdConflictPolicy),
       workflowType: { name: workflowType },
-      input: { payloads: await encodeToPayloadsWithContext(dataConverter, context, opts.args) },
+      input: {
+        payloads: await encodeToPayloadsWithContext(dataConverter, context, opts.args, opts.typeInfo?.inputTypes),
+      },
       taskQueue: {
         kind: temporal.api.enums.v1.TaskQueueKind.TASK_QUEUE_KIND_NORMAL,
         name: opts.taskQueue,
@@ -1752,6 +1789,7 @@ export class WorkflowClient extends BaseClient {
       runIdForResult: runId ?? options?.firstExecutionRunId,
       interceptors,
       followRuns: options?.followRuns ?? true,
+      typeInfo: options?.typeInfo,
     });
   }
 

packages/client/src/workflow-options.ts

@@ -4,6 +4,7 @@ import type {
   WithWorkflowArgs,
   Workflow,
   VersioningOverride,
+  PayloadTypeInfo,
 } from '@temporalio/common';
 import { toCanonicalString } from '@temporalio/common';
 import type { Duration } from '@temporalio/common/lib/time';
@@ -60,6 +61,13 @@ export interface WorkflowOptions extends CommonWorkflowOptions {
    * start it on a local worker running with this same client.
    */
   requestEagerStart?: boolean;
+
+  /**
+   * Type information used to encode and decode Workflow input and output.
+   *
+   * @experimental
+   */
+  typeInfo?: PayloadTypeInfo;
 }
 
 export type WithCompiledWorkflowOptions<T extends WorkflowOptions> = Replace<

packages/common/src/__tests__/test-workflow-type-info.ts

@@ -0,0 +1,47 @@
+import test from 'ava';
+import type { PayloadTypeInfo } from '../type-info';
+import { extractWorkflowType, extractWorkflowTypeAndConfig } from '../workflow-options';
+
+const typeInfo: PayloadTypeInfo = {
+  inputTypes: [{}],
+  outputType: {},
+};
+
+test('resolves call-site type information for a string Workflow type', (t) => {
+  t.deepEqual(extractWorkflowTypeAndConfig('workflow', typeInfo), {
+    type: 'workflow',
+    typeInfo,
+  });
+});
+
+test('resolves definition-supplied type information for a Workflow function', (t) => {
+  const workflow = Object.assign(async function workflow(): Promise<void> {}, {
+    staticOptions: { typeInfo },
+  });
+
+  t.deepEqual(extractWorkflowTypeAndConfig(workflow), {
+    type: 'workflow',
+    typeInfo,
+  });
+  t.is(extractWorkflowType(workflow), 'workflow');
+});
+
+test('rejects call-site type information for a Workflow function', (t) => {
+  async function workflow(): Promise<void> {}
+
+  t.throws(() => extractWorkflowTypeAndConfig(workflow, typeInfo), {
+    instanceOf: TypeError,
+    message: /Workflow type information cannot be supplied at the call site/,
+  });
+});
+
+test('ignores explicitly undefined static options', (t) => {
+  const workflow = Object.assign(async function workflow(): Promise<void> {}, {
+    staticOptions: undefined,
+  });
+
+  t.deepEqual(extractWorkflowTypeAndConfig(workflow), {
+    type: 'workflow',
+    typeInfo: undefined,
+  });
+});

packages/common/src/converter/payload-converter.ts

@@ -118,7 +118,7 @@ export function fromPayloadsAtIndex<T>(
   index: number,
   payloads?: Payload[] | null,
   context?: SerializationContext,
-  valueTypeInfo?: TypeInfo<T>
+  valueTypeInfo?: TypeInfo
 ): T {
   // To make adding arguments a backwards compatible change
   if (payloads === undefined || payloads === null || index >= payloads.length) {

packages/common/src/converter/type-info-aware-payload-converter.ts

@@ -35,12 +35,13 @@ export class TypeInfoAwarePayloadConverter implements PayloadConverter {
   public fromPayloadWithTypeInfo<T>(
     payload: Payload,
     context: SerializationContext | undefined,
-    typeInfo: TypeInfo<T> | undefined
+    typeInfo: TypeInfo | undefined
   ): T {
     const transferValue = this.payloadConverter.fromPayload<unknown>(payload, context, typeInfo?.hint);
-    return typeInfo?.transferTypeConverter
+    const value = typeInfo?.transferTypeConverter
       ? typeInfo.transferTypeConverter.fromTransferType(transferValue)
-      : (transferValue as T);
+      : transferValue;
+    return value as T;
   }
 }
 

packages/common/src/index.ts

@@ -31,7 +31,7 @@ export * from './priority';
 export * from './metrics';
 export * from './retry-policy';
 export type { Timestamp, Duration, StringValue } from './time';
-export { ConverterHint, TransferTypeConverter, TypeInfo, valueTypeBrand } from './type-info';
+export { ConverterHint, PayloadTypeInfo, TransferTypeConverter, TypeInfo, valueTypeBrand } from './type-info';
 export * from './worker-deployments';
 export * from './workflow-definition-options';
 export * from './workflow-handle';

packages/common/src/internal-non-workflow/codec-helpers.ts

@@ -148,7 +148,7 @@ export async function decodeFromPayloadsAtIndex<T>(
   index: number,
   payloads?: Payload[] | null,
   context?: SerializationContext,
-  valueTypeInfo?: TypeInfo<T>
+  valueTypeInfo?: TypeInfo
 ): Promise<T> {
   const { payloadConverter, payloadCodecs } = converter;
   return await fromPayloadsAtIndex(

packages/common/src/type-info.ts

@@ -25,3 +25,9 @@ export interface ConverterHint<T = unknown> {
   converter: string;
   [valueTypeBrand]?: T;
 }
+
+/** @experimental */
+export interface PayloadTypeInfo {
+  inputTypes?: readonly TypeInfo[];
+  outputType?: TypeInfo;
+}