Add RawValue support for non-converted Payloads #1664

THardy98 · 2025-04-01T21:18:02Z

What was changed

Added RawValue support for non-converted Payloads - a thin wrapper around Payload.

RawValue is intended to be used for payloads that bypasses users custom payload converters in favour of the default payload converter.

TS does not include type hints or similar when converting from a payload back to its original representation. As such, the best we can do is just send the payload as is and have users convert it back to its original representation.

The existing builtin queries now return a RawValue that wraps their former returned values. The return types of the builtin queries however, maintain their existing type (this is because receivers of these queries will get the payload itself, not the RawValue). This is breaking change as consumers of these builtin queries will need to make sure they decode the builtin payloads correctly.

Closes [Feature Request] Support "RawValue" non-converted values #1629, [Feature Request] Built-in query responses should use "RawValue" #1630
How was this tested:
Added short integration test, modified the existing built-in metadata test.
Any docs updates needed?
Possibly. Maybe for the change to the built-in metadata query.

packages/workflow/src/internals.ts

mjameswh · 2025-07-10T18:49:17Z

I believe we need to return RawValue from all built-in queries, not only the user metadata query. And we should be using the default payload converter, not the payload converter provided by the user.

mjameswh · 2025-07-10T18:56:34Z

I'm really not clear how RawValue should work in TS on the inbound path, given that we don't have any form of type hint on functions that receive Payloads. Using a rawValue payload metadata set on the outbound feels totally wrong to me, as that makes RawValue a symetric thing (i.e. receiver will get a RawValue if and only if the caller sent a RawValue) whereas it seems to me that the reason to have RawPayloads is specifically to support cases where the caller and receiver would have different configurations.

For now, I'd focus on the outbound path only, simply to support return value of built-in queries. For inbound payloads, that might have to wait only we add support for type hints on receivers.

…l internal queries

THardy98 · 2025-07-24T13:15:51Z

I've written this in the PR description:

The existing builtin queries now return a RawValue that wraps their former returned values. The return types of the builtin queries however, maintain their existing type (this is because receivers of these queries will get the payload itself, not the RawValue). This is breaking change as consumers of these builtin queries will need to make sure they decode the builtin payloads correctly.

Let me know if this makes sense to you.

mjameswh · 2025-07-29T17:09:11Z

packages/test/src/workflows/stack-tracer.ts

@@ -4,6 +4,7 @@
 */
 import * as wf from '@temporalio/workflow';
 import type { EnhancedStackTrace } from '@temporalio/workflow/lib/interfaces';
+import { defaultPayloadConverter } from '@temporalio/common/lib/converter/payload-converter';


Unused import

mjameswh · 2025-07-29T17:29:51Z

packages/workflow/src/workflow.ts

@@ -22,6 +22,7 @@ import {
  WorkflowReturnType,
  WorkflowUpdateValidatorType,
  SearchAttributeUpdatePair,
+  RawValue,


Unused import

mjameswh · 2025-07-29T17:41:21Z

packages/workflow/src/internals.ts

@@ -315,14 +317,14 @@ export class Activator implements ActivationHandler {
            name,
            description: value.description,
          }));
-          return {
+          return new RawValue({


It's sad we're loosing type safety check here… There's nothing ensuring that the arg to RawValue complies with the expected type definition.

See my suggestions elsewhere that adds back type safety.

mjameswh · 2025-07-29T18:02:06Z

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

+ * A payload that belongs to a RawValue is special in that it bypasses user-defined payload converters,
+ * instead using the default payload converter. The payload still undergoes codec conversion.
+ */
+export class RawValue {


For the sake of type safety, I think we should add an optional generic parameter on RawValue, and save that generic parameter using the type brand pattern. Also, we should accept passing in an optional payload converter, i.e. in cases where user want to proce a specific payload converter (not the default one, and not the one they configured on the worker or client).

export declare const rawPayloadTypeBrand: unique symbol; class RawValue<T = unknown> { private readonly _payload: Payload; // private readonly [rawPayloadTypeBrand]: T = undefined as T; constructor(value: T, payloadConverter: PayloadConverter = defaultPayloadConverter) { this._payload = payloadConverter.toPayload(value); } get payload(): Payload { return this._payload; } }

mjameswh · 2025-07-29T18:03:28Z

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

@@ -386,7 +388,7 @@ test('Query workflow metadata returns handler descriptions', async (t) => {

  await worker.runUntil(async () => {
    const handle = await startWorkflow(queryWorkflowMetadata);
-    const meta = await handle.query(workflow.workflowMetadataQuery);
+    const meta = (await handle.query(workflow.workflowMetadataQuery)) as temporal.api.sdk.v1.IWorkflowMetadata;


You should not need a cast here.

mjameswh · 2025-07-29T18:04:09Z

packages/workflow/src/internals.ts

-          return this.getStackTraces()
-            .map((s) => s.formatted)
-            .join('\n\n');
+          return new RawValue(


Suggested change

return new RawValue(

return new RawValue<string>(

mjameswh · 2025-07-29T18:04:22Z

packages/workflow/src/internals.ts

        },
        description: 'Returns a sensible stack trace.',
      },
    ],
    [
      '__enhanced_stack_trace',
      {
-        handler: (): EnhancedStackTrace => {
+        handler: (): RawValue => {


Suggested change

handler: (): RawValue => {

handler: (): RawValue<EnhancedStackTrace> => {

mjameswh · 2025-07-29T18:04:39Z

packages/workflow/src/internals.ts

        },
        description: 'Returns a stack trace annotated with source information.',
      },
    ],
    [
      '__temporal_workflow_metadata',
      {
-        handler: (): temporal.api.sdk.v1.IWorkflowMetadata => {
+        handler: (): RawValue => {


Suggested change

handler: (): RawValue => {

handler: (): RawValue<temporal.api.sdk.v1.IWorkflowMetadata> => {

mjameswh

We're almost there, but still a bit more.

Add RawValue support for non-converted Payloads

5ac2c4b

THardy98 requested a review from a team as a code owner April 1, 2025 21:18

mjameswh reviewed Jul 10, 2025

View reviewed changes

packages/workflow/src/internals.ts Outdated Show resolved Hide resolved

THardy98 added 2 commits July 22, 2025 10:24

simplify RawValue API, use default converter, return RawValue from al…

eff5009

…l internal queries

Merge branch 'main' into raw_value_support

b0acfd0

THardy98 force-pushed the raw_value_support branch from 62de924 to cec9e55 Compare July 22, 2025 21:37

update test

573c2ca

THardy98 force-pushed the raw_value_support branch from cec9e55 to 573c2ca Compare July 22, 2025 21:59

THardy98 requested a review from mjameswh July 23, 2025 15:57

mjameswh reviewed Jul 29, 2025

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add RawValue support for non-converted Payloads #1664

Add RawValue support for non-converted Payloads #1664

THardy98 commented Apr 1, 2025 •

edited

Loading

Uh oh!

Uh oh!

mjameswh commented Jul 10, 2025

Uh oh!

mjameswh commented Jul 10, 2025

Uh oh!

THardy98 commented Jul 24, 2025

Uh oh!

mjameswh Jul 29, 2025

Uh oh!

mjameswh Jul 29, 2025

Uh oh!

mjameswh Jul 29, 2025

Uh oh!

mjameswh Jul 29, 2025

Uh oh!

mjameswh Jul 29, 2025

Uh oh!

mjameswh Jul 29, 2025

Uh oh!

mjameswh Jul 29, 2025

Uh oh!

mjameswh Jul 29, 2025

Uh oh!

mjameswh Jul 29, 2025

Uh oh!

mjameswh left a comment

Uh oh!

Uh oh!

	handler: (): RawValue => {
	handler: (): RawValue<EnhancedStackTrace> => {

	handler: (): RawValue => {
	handler: (): RawValue<temporal.api.sdk.v1.IWorkflowMetadata> => {

Add RawValue support for non-converted Payloads #1664

Are you sure you want to change the base?

Add RawValue support for non-converted Payloads #1664

Conversation

THardy98 commented Apr 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What was changed

Uh oh!

Uh oh!

mjameswh commented Jul 10, 2025

Uh oh!

mjameswh commented Jul 10, 2025

Uh oh!

THardy98 commented Jul 24, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mjameswh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

THardy98 commented Apr 1, 2025 •

edited

Loading