move user metadata encoding/decoding to user-metadata.ts, add deepMerge to merge/override nested fields in objects (used to override activity options with activities' executeWithOptions), add metadata to child workflows and condition calls

Author: THardy98

packages/client/src/schedule-helpers.ts

@@ -6,6 +6,8 @@ import {
   decompileRetryPolicy,
   extractWorkflowType,
   LoadedDataConverter,
+  encodeUserMetadata,
+  decodeUserMetadata,
 } from '@temporalio/common';
 import {
   encodeUnifiedSearchAttributes,
@@ -16,9 +18,7 @@ import { Headers } from '@temporalio/common/lib/interceptors';
 import {
   decodeArrayFromPayloads,
   decodeMapFromPayloads,
-  decodeOptionalSinglePayload,
   encodeMapToPayloads,
-  encodeOptionalToPayload,
   encodeToPayloads,
 } from '@temporalio/common/lib/internal-non-workflow';
 import { temporal } from '@temporalio/proto';
@@ -271,10 +271,7 @@ export async function encodeScheduleAction(
             }
           : undefined,
       header: { fields: headers },
-      userMetadata: {
-        summary: await encodeOptionalToPayload(dataConverter, action?.staticSummary),
-        details: await encodeOptionalToPayload(dataConverter, action?.staticDetails),
-      },
+      userMetadata: await encodeUserMetadata(dataConverter, action.staticSummary, action.staticDetails),
       priority: action.priority ? compilePriority(action.priority) : undefined,
     },
   };
@@ -325,7 +322,7 @@ export async function decodeScheduleAction(
   pb: temporal.api.schedule.v1.IScheduleAction
 ): Promise<ScheduleDescriptionAction> {
   if (pb.startWorkflow) {
-    const userMetadata = pb.startWorkflow?.userMetadata;
+    const { staticSummary, staticDetails } = await decodeUserMetadata(dataConverter, pb.startWorkflow?.userMetadata);
     return {
       type: 'startWorkflow',
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
@@ -342,8 +339,8 @@ export async function decodeScheduleAction(
       workflowExecutionTimeout: optionalTsToMs(pb.startWorkflow.workflowExecutionTimeout),
       workflowRunTimeout: optionalTsToMs(pb.startWorkflow.workflowRunTimeout),
       workflowTaskTimeout: optionalTsToMs(pb.startWorkflow.workflowTaskTimeout),
-      staticSummary: (await decodeOptionalSinglePayload(dataConverter, userMetadata?.summary)) ?? undefined,
-      staticDetails: (await decodeOptionalSinglePayload(dataConverter, userMetadata?.details)) ?? undefined,
+      staticSummary,
+      staticDetails,
       priority: decodePriority(pb.startWorkflow.priority),
     };
   }

packages/client/src/workflow-client.ts

@@ -23,6 +23,7 @@ import {
   encodeWorkflowIdConflictPolicy,
   WorkflowIdConflictPolicy,
   compilePriority,
+  encodeUserMetadata,
 } from '@temporalio/common';
 import { encodeUnifiedSearchAttributes } from '@temporalio/common/lib/converter/payload-search-attributes';
 import { composeInterceptors } from '@temporalio/common/lib/interceptors';
@@ -34,7 +35,6 @@ import {
   decodeOptionalFailureToOptionalError,
   decodeOptionalSinglePayload,
   encodeMapToPayloads,
-  encodeOptionalToPayload,
   encodeToPayloads,
 } from '@temporalio/common/lib/internal-non-workflow';
 import { filterNullAndUndefined } from '@temporalio/common/lib/internal-workflow';
@@ -1228,10 +1228,7 @@ export class WorkflowClient extends BaseClient {
           : undefined,
       cronSchedule: options.cronSchedule,
       header: { fields: headers },
-      userMetadata: {
-        summary: await encodeOptionalToPayload(this.dataConverter, options?.staticSummary),
-        details: await encodeOptionalToPayload(this.dataConverter, options?.staticDetails),
-      },
+      userMetadata: await encodeUserMetadata(this.dataConverter, options.staticSummary, options.staticDetails),
       priority: options.priority ? compilePriority(options.priority) : undefined,
       versioningOverride: options.versioningOverride ?? undefined,
     };
@@ -1301,10 +1298,7 @@ export class WorkflowClient extends BaseClient {
           : undefined,
       cronSchedule: opts.cronSchedule,
       header: { fields: headers },
-      userMetadata: {
-        summary: await encodeOptionalToPayload(this.dataConverter, opts?.staticSummary),
-        details: await encodeOptionalToPayload(this.dataConverter, opts?.staticDetails),
-      },
+      userMetadata: await encodeUserMetadata(this.dataConverter, opts.staticSummary, opts.staticDetails),
       priority: opts.priority ? compilePriority(opts.priority) : undefined,
       versioningOverride: opts.versioningOverride ?? undefined,
     };

packages/common/src/activity-options.ts

@@ -125,12 +125,12 @@ export interface ActivityOptions {
   versioningIntent?: VersioningIntent;
 
   /**
-   * A single-line fixed summary for this workflow execution that may appear in the UI/CLI.
+   * A fixed, single-line fixed summary for this workflow execution that may appear in the UI/CLI.
    * This can be in single-line Temporal markdown format.
    *
    * @experimental User metadata is a new API and suspectible to change.
    */
-  staticSummary?: string;
+  summary?: string;
 
   /**
    * Priority of this activity
@@ -202,10 +202,10 @@ export interface LocalActivityOptions {
   cancellationType?: ActivityCancellationType;
 
   /**
-   * A single-line fixed summary for this workflow execution that may appear in the UI/CLI.
+   * A fixed, single-line fixed summary for this workflow execution that may appear in the UI/CLI.
    * This can be in single-line Temporal markdown format.
    *
    * @experimental User metadata is a new API and suspectible to change.
    */
-  staticSummary?: string;
+  summary?: string;
 }

packages/common/src/index.ts

@@ -37,6 +37,7 @@ export {
   TypedSearchAttributes,
   defineSearchAttributeKey,
 } from './search-attributes';
+export * from './user-metadata';
 
 /**
  * Encode a UTF-8 string into a Uint8Array

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

@@ -1,5 +1,5 @@
 import { Payload } from '../interfaces';
-import { arrayFromPayloads, fromPayloadsAtIndex, toPayloads } from '../converter/payload-converter';
+import { arrayFromPayloads, fromPayloadsAtIndex, PayloadConverter, toPayloads } from '../converter/payload-converter';
 import { PayloadConverterError } from '../errors';
 import { PayloadCodec } from '../converter/payload-codec';
 import { ProtoFailure } from '../failure';
@@ -77,7 +77,7 @@ export async function decodeOptionalSinglePayload<T>(
   dataConverter: LoadedDataConverter,
   payload?: Payload | null | undefined
 ): Promise<T | null | undefined> {
-  const { payloadCodecs, payloadConverter } = dataConverter;
+  const { payloadConverter, payloadCodecs } = dataConverter;
   const decoded = await decodeOptionalSingle(payloadCodecs, payload);
   if (decoded == null) return decoded;
   return payloadConverter.fromPayload(decoded);
@@ -94,15 +94,13 @@ export async function encodeToPayload(converter: LoadedDataConverter, value: unk
 /**
  * Run {@link PayloadConverter.toPayload} on an optional value, and then encode it.
  */
-export async function encodeOptionalToPayload(
-  converter: LoadedDataConverter,
+export function encodeOptionalToPayload(
+  payloadConverter: PayloadConverter,
   value: unknown
-): Promise<Payload | null | undefined> {
+): Payload | null | undefined {
   if (value == null) return value;
 
-  const { payloadConverter, payloadCodecs } = converter;
-  const payload = payloadConverter.toPayload(value);
-  return await encodeSingle(payloadCodecs, payload);
+  return payloadConverter.toPayload(value);
 }
 
 /**

packages/common/src/internal-workflow/objects-helpers.ts

@@ -35,3 +35,33 @@ export function mergeObjects<T extends Record<string, any>>(
 
   return changed ? (merged as T) : original;
 }
+
+function isObject(item: any): item is Record<string, any> {
+  return item && typeof item === 'object' && !Array.isArray(item);
+}
+
+/**
+ * Recursively merges two objects, returning a new object.
+ *
+ * Properties from `source` will overwrite properties on `target`.
+ * Nested objects are merged recursively.
+ *
+ * Object fields in the returned object are references, as in,
+ * the returned object is not completely fresh.
+ */
+export function deepMerge<T extends Record<string, any>>(target: T, source: Partial<T>): T {
+  const output = { ...target };
+
+  if (isObject(target) && isObject(source)) {
+    for (const key of Object.keys(source)) {
+      const sourceValue = source[key];
+      if (isObject(sourceValue) && key in target && isObject(target[key] as any)) {
+        output[key as keyof T] = deepMerge(target[key], sourceValue);
+      } else {
+        (output as any)[key] = sourceValue;
+      }
+    }
+  }
+
+  return output;
+}

packages/common/src/user-metadata.ts

@@ -0,0 +1,66 @@
+import { temporal } from '@temporalio/proto';
+import { PayloadConverter } from './converter/payload-converter';
+import { LoadedDataConverter } from './converter/data-converter';
+import { encodeOptionalToPayload, decodeOptionalSinglePayload, encodeOptionalSingle } from './internal-non-workflow';
+
+/**
+ * User metadata that can be attached to workflow commands.
+ */
+export interface UserMetadata {
+  /** @experimental A fixed, single line summary of the command's purpose */
+  staticSummary?: string;
+  /** @experimental Fixed additional details about the command for longer-text description, can span multiple lines */
+  staticDetails?: string;
+}
+
+export function userMetadataToPayload(
+  payloadConverter: PayloadConverter,
+  staticSummary: string | undefined,
+  staticDetails: string | undefined
+): temporal.api.sdk.v1.IUserMetadata | undefined {
+  if (staticSummary == null && staticDetails == null) return undefined;
+
+  const summary = encodeOptionalToPayload(payloadConverter, staticSummary);
+  const details = encodeOptionalToPayload(payloadConverter, staticDetails);
+
+  if (summary == null && details == null) return undefined;
+
+  return { summary, details };
+}
+
+export async function encodeUserMetadata(
+  dataConverter: LoadedDataConverter,
+  staticSummary: string | undefined,
+  staticDetails: string | undefined
+): Promise<temporal.api.sdk.v1.IUserMetadata | undefined> {
+  if (staticSummary == null && staticDetails == null) return undefined;
+
+  const { payloadConverter, payloadCodecs } = dataConverter;
+  const summary = await encodeOptionalSingle(
+    payloadCodecs,
+    await encodeOptionalToPayload(payloadConverter, staticSummary)
+  );
+  const details = await encodeOptionalSingle(
+    payloadCodecs,
+    await encodeOptionalToPayload(payloadConverter, staticDetails)
+  );
+
+  if (summary == null && details == null) return undefined;
+
+  return { summary, details };
+}
+
+export async function decodeUserMetadata(
+  dataConverter: LoadedDataConverter,
+  metadata: temporal.api.sdk.v1.IUserMetadata | undefined | null
+): Promise<UserMetadata> {
+  const res = { staticSummary: undefined, staticDetails: undefined };
+  if (metadata == null) return res;
+
+  const staticSummary = (await decodeOptionalSinglePayload<string>(dataConverter, metadata.summary)) ?? undefined;
+  const staticDetails = (await decodeOptionalSinglePayload<string>(dataConverter, metadata.details)) ?? undefined;
+
+  if (staticSummary == null && staticDetails == null) return res;
+
+  return { staticSummary, staticDetails };
+}