@temporalio/workflow 1.11.8 → 1.12.0-rc.0

package/src/workflow.ts

@@ -9,10 +9,11 @@ import {
   LocalActivityOptions,
   mapToPayloads,
   QueryDefinition,
-  searchAttributePayloadConverter,
   SearchAttributes,
+  SearchAttributeValue,
   SignalDefinition,
   toPayloads,
+  TypedSearchAttributes,
   UntypedActivities,
   UpdateDefinition,
   WithWorkflowArgs,
@@ -20,7 +21,14 @@ import {
   WorkflowResultType,
   WorkflowReturnType,
   WorkflowUpdateValidatorType,
+  SearchAttributeUpdatePair,
+  compilePriority,
+  WorkflowDefinitionOptionsOrGetter,
 } from '@temporalio/common';
+import {
+  encodeUnifiedSearchAttributes,
+  searchAttributePayloadConverter,
+} from '@temporalio/common/lib/converter/payload-search-attributes';
 import { versioningIntentToProto } from '@temporalio/common/lib/versioning-intent-enum';
 import { Duration, msOptionalToTs, msToNumber, msToTs, requiredTsToMs } from '@temporalio/common/lib/time';
 import { composeInterceptors } from '@temporalio/common/lib/interceptors';
@@ -50,6 +58,8 @@ import {
   UpdateInfo,
   encodeChildWorkflowCancellationType,
   encodeParentClosePolicy,
+  DefaultUpdateHandler,
+  DefaultQueryHandler,
 } from './interfaces';
 import { LocalActivityDoBackoff } from './errors';
 import { assertInWorkflowContext, getActivator, maybeGetActivator } from './global-attributes';
@@ -186,6 +196,7 @@ function scheduleActivityNextHandler({ options, args, headers, seq, activityType
         cancellationType: encodeActivityCancellationType(options.cancellationType),
         doNotEagerlyExecute: !(options.allowEagerDispatch ?? true),
         versioningIntent: versioningIntentToProto(options.versioningIntent),
+        priority: options.priority ? compilePriority(options.priority) : undefined,
       },
     });
     activator.completions.activity.set(seq, {
@@ -380,11 +391,13 @@ function startChildWorkflowExecutionNextHandler({
         workflowIdReusePolicy: encodeWorkflowIdReusePolicy(options.workflowIdReusePolicy),
         parentClosePolicy: encodeParentClosePolicy(options.parentClosePolicy),
         cronSchedule: options.cronSchedule,
-        searchAttributes: options.searchAttributes
-          ? mapToPayloads(searchAttributePayloadConverter, options.searchAttributes)
-          : undefined,
+        searchAttributes:
+          options.searchAttributes || options.typedSearchAttributes // eslint-disable-line deprecation/deprecation
+            ? encodeUnifiedSearchAttributes(options.searchAttributes, options.typedSearchAttributes) // eslint-disable-line deprecation/deprecation
+            : undefined,
         memo: options.memo && mapToPayloads(activator.payloadConverter, options.memo),
         versioningIntent: versioningIntentToProto(options.versioningIntent),
+        priority: options.priority ? compilePriority(options.priority) : undefined,
       },
     });
     activator.completions.childWorkflowStart.set(seq, {
@@ -922,9 +935,10 @@ export function makeContinueAsNewFunc<F extends Workflow>(
         headers,
         taskQueue: options.taskQueue,
         memo: options.memo && mapToPayloads(activator.payloadConverter, options.memo),
-        searchAttributes: options.searchAttributes
-          ? mapToPayloads(searchAttributePayloadConverter, options.searchAttributes)
-          : undefined,
+        searchAttributes:
+          options.searchAttributes || options.typedSearchAttributes // eslint-disable-line deprecation/deprecation
+            ? encodeUnifiedSearchAttributes(options.searchAttributes, options.typedSearchAttributes) // eslint-disable-line deprecation/deprecation
+            : undefined,
         workflowRunTimeout: msOptionalToTs(options.workflowRunTimeout),
         workflowTaskTimeout: msOptionalToTs(options.workflowTaskTimeout),
         versioningIntent: versioningIntentToProto(options.versioningIntent),
@@ -946,14 +960,15 @@ export function makeContinueAsNewFunc<F extends Workflow>(
  *
  * @example
  *
- *```ts
+ * ```ts
  *import { continueAsNew } from '@temporalio/workflow';
+import { SearchAttributeType } from '@temporalio/common';
  *
  *export async function myWorkflow(n: number): Promise<void> {
  *  // ... Workflow logic
  *  await continueAsNew<typeof myWorkflow>(n + 1);
  *}
- *```
+ * ```
  */
 export function continueAsNew<F extends Workflow>(...args: Parameters<F>): Promise<never> {
   return makeContinueAsNewFunc()(...args);
@@ -1300,7 +1315,7 @@ export function setHandler<
  *
  * Signals are dispatched to the default signal handler in the order that they were accepted by the server.
  *
- * If this function is called multiple times for a given signal or query name the last handler will overwrite any previous calls.
+ * If this function is called multiple times for a given signal name the last handler will overwrite any previous calls.
  *
  * @param handler a function that will handle signals for non-registered signal names, or `undefined` to unset the handler.
  */
@@ -1318,24 +1333,73 @@ export function setDefaultSignalHandler(handler: DefaultSignalHandler | undefine
   }
 }
 
+/**
+ * Set a update handler function that will handle updates calls for non-registered update names.
+ *
+ * Updates are dispatched to the default update handler in the order that they were accepted by the server.
+ *
+ * If this function is called multiple times for a given update name the last handler will overwrite any previous calls.
+ *
+ * @param handler a function that will handle updates for non-registered update names, or `undefined` to unset the handler.
+ */
+export function setDefaultUpdateHandler(handler: DefaultUpdateHandler | undefined): void {
+  const activator = assertInWorkflowContext(
+    'Workflow.setDefaultUpdateHandler(...) may only be used from a Workflow Execution.'
+  );
+  if (typeof handler === 'function') {
+    activator.defaultUpdateHandler = handler;
+    activator.dispatchBufferedUpdates();
+  } else if (handler == null) {
+    activator.defaultUpdateHandler = undefined;
+  } else {
+    throw new TypeError(`Expected handler to be either a function or 'undefined'. Got: '${typeof handler}'`);
+  }
+}
+
+/**
+ * Set a query handler function that will handle query calls for non-registered query names.
+ *
+ * Queries are dispatched to the default query handler in the order that they were accepted by the server.
+ *
+ * If this function is called multiple times for a given query name the last handler will overwrite any previous calls.
+ *
+ * @param handler a function that will handle queries for non-registered query names, or `undefined` to unset the handler.
+ */
+export function setDefaultQueryHandler(handler: DefaultQueryHandler | undefined): void {
+  const activator = assertInWorkflowContext(
+    'Workflow.setDefaultQueryHandler(...) may only be used from a Workflow Execution.'
+  );
+  if (typeof handler === 'function' || handler === undefined) {
+    activator.defaultQueryHandler = handler;
+  } else {
+    throw new TypeError(`Expected handler to be either a function or 'undefined'. Got: '${typeof handler}'`);
+  }
+}
+
 /**
  * Updates this Workflow's Search Attributes by merging the provided `searchAttributes` with the existing Search
  * Attributes, `workflowInfo().searchAttributes`.
  *
- * For example, this Workflow code:
+ * Search attributes can be upserted using either SearchAttributes (deprecated) or SearchAttributeUpdatePair[] (preferred)
+ *
+ * Upserting a workflow's search attributes using SearchAttributeUpdatePair[]:
  *
  * ```ts
- * upsertSearchAttributes({
- *   CustomIntField: [1],
- *   CustomBoolField: [true]
- * });
- * upsertSearchAttributes({
- *   CustomIntField: [42],
- *   CustomKeywordField: ['durable code', 'is great']
- * });
+ * const intKey = defineSearchKey('CustomIntField', 'INT');
+ * const boolKey = defineSearchKey('CustomBoolField', 'BOOL');
+ * const keywordListKey = defineSearchKey('CustomKeywordField', 'KEYWORD_LIST');
+ *
+ * upsertSearchAttributes([
+ *  defineSearchAttribute(intKey, 1),
+ *  defineSearchAttribute(boolKey, true)
+ * ]);
+ * upsertSearchAttributes([
+ *  defineSearchAttribute(intKey, 42),
+ *  defineSearchAttribute(keywordListKey, ['durable code', 'is great'])
+ * ]);
  * ```
  *
- * would result in the Workflow having these Search Attributes:
+ * Would result in the Workflow having these Search Attributes:
  *
  * ```ts
  * {
@@ -1345,9 +1409,12 @@ export function setDefaultSignalHandler(handler: DefaultSignalHandler | undefine
  * }
  * ```
  *
- * @param searchAttributes The Record to merge. Use a value of `[]` to clear a Search Attribute.
+ * @param searchAttributes The Record to merge.
+ * If using SearchAttributeUpdatePair[] (preferred), set a value to null to remove the search attribute.
+ * If using SearchAttributes (deprecated), set a value to undefined or an empty list to remove the search attribute.
  */
-export function upsertSearchAttributes(searchAttributes: SearchAttributes): void {
+// eslint-disable-next-line deprecation/deprecation
+export function upsertSearchAttributes(searchAttributes: SearchAttributes | SearchAttributeUpdatePair[]): void {
   const activator = assertInWorkflowContext(
     'Workflow.upsertSearchAttributes(...) may only be used from a Workflow Execution.'
   );
@@ -1356,21 +1423,111 @@ export function upsertSearchAttributes(searchAttributes: SearchAttributes): void
     throw new Error('searchAttributes must be a non-null SearchAttributes');
   }
 
-  activator.pushCommand({
-    upsertWorkflowSearchAttributes: {
-      searchAttributes: mapToPayloads(searchAttributePayloadConverter, searchAttributes),
-    },
-  });
+  if (Array.isArray(searchAttributes)) {
+    // Typed search attributes
+    activator.pushCommand({
+      upsertWorkflowSearchAttributes: {
+        searchAttributes: encodeUnifiedSearchAttributes(undefined, searchAttributes),
+      },
+    });
 
-  activator.mutateWorkflowInfo((info: WorkflowInfo): WorkflowInfo => {
-    return {
-      ...info,
-      searchAttributes: {
-        ...info.searchAttributes,
-        ...searchAttributes,
+    activator.mutateWorkflowInfo((info: WorkflowInfo): WorkflowInfo => {
+      // Create a copy of the current state.
+      const newSearchAttributes: SearchAttributes = { ...info.searchAttributes }; // eslint-disable-line deprecation/deprecation
+      for (const pair of searchAttributes) {
+        if (pair.value == null) {
+          // If the value is null, remove the search attribute.
+          // We don't mutate the existing state (just the new map) so this is safe.
+          delete newSearchAttributes[pair.key.name];
+        } else {
+          newSearchAttributes[pair.key.name] = Array.isArray(pair.value)
+            ? pair.value
+            : ([pair.value] as SearchAttributeValue); // eslint-disable-line deprecation/deprecation
+        }
+      }
+      return {
+        ...info,
+        searchAttributes: newSearchAttributes,
+        // Create an empty copy and apply existing and new updates. Keep in mind the order matters here (existing first, new second - to possibly overwrite existing).
+        typedSearchAttributes: info.typedSearchAttributes.updateCopy([...searchAttributes]),
+      };
+    });
+  } else {
+    // Legacy search attributes
+    activator.pushCommand({
+      upsertWorkflowSearchAttributes: {
+        searchAttributes: mapToPayloads(searchAttributePayloadConverter, searchAttributes),
       },
-    };
-  });
+    });
+
+    activator.mutateWorkflowInfo((info: WorkflowInfo): WorkflowInfo => {
+      // Create a new copy of the current state.
+      let typedSearchAttributes = info.typedSearchAttributes.updateCopy([]);
+      const newSearchAttributes: SearchAttributes = { ...info.searchAttributes }; // eslint-disable-line deprecation/deprecation
+
+      // Upsert legacy search attributes into typedSearchAttributes.
+      for (const [k, v] of Object.entries(searchAttributes)) {
+        if (v !== undefined && !Array.isArray(v)) {
+          throw new Error(`Search attribute value must be an array or undefined, got ${v}`);
+        }
+
+        // The value is undefined or an empty list, this signifies deletion.
+        // Remove from both untyped & typed search attributes.
+        if (v == null || (Array.isArray(v) && v.length === 0)) {
+          // We cannot discern a valid key typing from these values.
+          // Instead, we do a "best effort" deletion from typed search attributes:
+          // - check if a matching key name exists, if so, remove it.
+          const matchingPair = typedSearchAttributes.getAll().find((pair) => pair.key.name === k);
+          if (matchingPair) {
+            typedSearchAttributes = typedSearchAttributes.updateCopy([
+              { key: matchingPair.key, value: null } as SearchAttributeUpdatePair,
+            ]);
+          }
+          delete newSearchAttributes[k];
+          continue;
+        }
+
+        // Attempt to discern a valid key typing for the update.
+        const typedKey = TypedSearchAttributes.getKeyFromUntyped(k, v);
+
+        // Unable to discern a valid key typing (no valid type for defined value).
+        // Skip applying this update (no-op).
+        if (typedKey === undefined) {
+          continue;
+        }
+
+        // TEXT type is inferred from a string value, but it could also be KEYWORD.
+        // If a matching pair exists with KEYWORD type, use that instead.
+        if (typedKey.type === 'TEXT') {
+          const matchingPair = typedSearchAttributes.getAll().find((pair) => pair.key.name === typedKey.name);
+          if (matchingPair) {
+            typedKey.type = matchingPair.key.type;
+          }
+        }
+
+        let newValue: unknown = v;
+        // Unpack value if it is a single-element array.
+        if (v.length === 1) {
+          newValue = v[0];
+          // Convert value back to Date.
+          if (typedKey.type === 'DATETIME') {
+            newValue = new Date(newValue as string);
+          }
+        }
+
+        // We have a defined value with valid type. Apply the update.
+        typedSearchAttributes = typedSearchAttributes.updateCopy([
+          { key: typedKey, value: newValue } as SearchAttributeUpdatePair,
+        ]);
+        newSearchAttributes[k] = v;
+      }
+      return {
+        ...info,
+        searchAttributes: newSearchAttributes,
+        typedSearchAttributes,
+      };
+    });
+  }
 }
 
 /**
@@ -1458,6 +1615,43 @@ export function allHandlersFinished(): boolean {
   return activator.inProgressSignals.size === 0 && activator.inProgressUpdates.size === 0;
 }
 
+/**
+ * Can be used to alter workflow functions with certain options specified at definition time.
+ *
+ * @example
+ * For example:
+ * ```ts
+ * setWorkflowOptions({ versioningBehavior: 'PINNED' }, myWorkflow);
+ * export async function myWorkflow(): Promise<string> {
+ *   // Workflow code here
+ *   return "hi";
+ * }
+ * ```
+ *
+ * @example
+ * To annotate a default or dynamic workflow:
+ * ```ts
+ * export default async function (): Promise<string> {
+ *   // Workflow code here
+ *   return "hi";
+ * }
+ * setWorkflowOptions({ versioningBehavior: 'PINNED' }, module.exports.default);
+ * ```
+ *
+ * @param options Options for the workflow defintion, or a function that returns options. If a
+ * function is provided, it will be called once just before the workflow function is called for the
+ * first time. It is safe to call {@link workflowInfo} inside such a function.
+ * @param fn The workflow function.
+ */
+export function setWorkflowOptions<A extends any[], RT>(
+  options: WorkflowDefinitionOptionsOrGetter,
+  fn: (...args: A) => Promise<RT>
+): void {
+  Object.assign(fn, {
+    workflowDefinitionOptions: options,
+  });
+}
+
 export const stackTraceQuery = defineQuery<string>('__stack_trace');
 export const enhancedStackTraceQuery = defineQuery<EnhancedStackTrace>('__enhanced_stack_trace');
 export const workflowMetadataQuery = defineQuery<temporal.api.sdk.v1.IWorkflowMetadata>('__temporal_workflow_metadata');