@temporalio/workflow 0.23.0 → 1.0.0

package/lib/workflow.d.ts

@@ -1,4 +1,4 @@
-import { ActivityFunction, ActivityInterface, ActivityOptions, LocalActivityOptions, QueryDefinition, SignalDefinition, WithWorkflowArgs, Workflow, WorkflowResultType, WorkflowReturnType } from '@temporalio/internal-workflow-common';
+import { ActivityFunction, ActivityOptions, LocalActivityOptions, QueryDefinition, SearchAttributes, SignalDefinition, UntypedActivities, WithWorkflowArgs, Workflow, WorkflowResultType, WorkflowReturnType } from '@temporalio/internal-workflow-common';
 import { ChildWorkflowOptions, ChildWorkflowOptionsWithDefaults, ContinueAsNewOptions, WorkflowInfo } from './interfaces';
 import { Sinks } from './sinks';
 import { ChildWorkflowHandle, ExternalWorkflowHandle } from './workflow-handle';
@@ -11,19 +11,10 @@ export declare function addDefaultWorkflowOptions<T extends Workflow>(opts: With
  *
  * Schedules a timer on the Temporal service.
  *
- * @param ms sleep duration - {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds. If given a negative number, value will be set to 1.
- *
+ * @param ms sleep duration - {@link https://www.npmjs.com/package/ms | ms} formatted string or number of milliseconds.
+ * If given a negative number or 0, value will be set to 1.
  */
 export declare function sleep(ms: number | string): Promise<void>;
-export interface ActivityInfo {
-    name: string;
-    type: string;
-}
-export declare type InternalActivityFunction<P extends any[], R> = ActivityFunction<P, R> & ActivityInfo;
-/**
- * @hidden
- */
-export declare function validateActivityOptions(options: ActivityOptions): void;
 /**
  * Schedule an activity and run outbound interceptors
  * @hidden
@@ -34,19 +25,52 @@ export declare function scheduleActivity<R>(activityType: string, args: any[], o
  * @hidden
  */
 export declare function scheduleLocalActivity<R>(activityType: string, args: any[], options: LocalActivityOptions): Promise<R>;
+/**
+ * Symbol used in the return type of proxy methods to mark that an attribute on the source type is not a method.
+ *
+ * @see {@link ActivityInterfaceFor}
+ * @see {@link proxyActivities}
+ * @see {@link proxyLocalActivities}
+ */
+export declare const NotAnActivityMethod: unique symbol;
+/**
+ * Type helper that takes a type `T` and transforms attributes that are not {@link ActivityFunction} to
+ * {@link NotAnActivityMethod}.
+ *
+ * @example
+ *
+ * Used by {@link proxyActivities} to get this compile-time error:
+ *
+ * ```ts
+ * interface MyActivities {
+ *   valid(input: number): Promise<number>;
+ *   invalid(input: number): number;
+ * }
+ *
+ * const act = proxyActivities<MyActivities>({ startToCloseTimeout: '5m' });
+ *
+ * await act.valid(true);
+ * await act.invalid();
+ * // ^ TS complains with:
+ * // (property) invalidDefinition: typeof NotAnActivityMethod
+ * // This expression is not callable.
+ * // Type 'Symbol' has no call signatures.(2349)
+ * ```
+ */
+export declare type ActivityInterfaceFor<T> = {
+    [K in keyof T]: T[K] extends ActivityFunction ? T[K] : typeof NotAnActivityMethod;
+};
 /**
  * Configure Activity functions with given {@link ActivityOptions}.
  *
  * This method may be called multiple times to setup Activities with different options.
  *
- * @return a [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
- *         for which each attribute is a callable Activity function
- *
- * @typeparam A An {@link ActivityInterface} - mapping of name to function
+ * @return a {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy | Proxy} for
+ *         which each attribute is a callable Activity function
  *
  * @example
  * ```ts
- * import { proxyActivities, ActivityInterface } from '@temporalio/workflow';
+ * import { proxyActivities } from '@temporalio/workflow';
  * import * as activities from '../activities';
  *
  * // Setup Activities from module exports
@@ -55,7 +79,7 @@ export declare function scheduleLocalActivity<R>(activityType: string, args: any
  * });
  *
  * // Setup Activities from an explicit interface (e.g. when defined by another SDK)
- * interface JavaActivities extends ActivityInterface {
+ * interface JavaActivities {
  *   httpGetFromJava(url: string): Promise<string>
  *   someOtherJavaActivity(arg1: number, arg2: string): Promise<string>;
  * }
@@ -74,22 +98,20 @@ export declare function scheduleLocalActivity<R>(activityType: string, args: any
  * }
  * ```
  */
-export declare function proxyActivities<A extends ActivityInterface>(options: ActivityOptions): A;
+export declare function proxyActivities<A = UntypedActivities>(options: ActivityOptions): ActivityInterfaceFor<A>;
 /**
  * Configure Local Activity functions with given {@link LocalActivityOptions}.
  *
  * This method may be called multiple times to setup Activities with different options.
  *
- * @return a [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy)
+ * @return a {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy | Proxy}
  *         for which each attribute is a callable Activity function
  *
- * @typeparam A An {@link ActivityInterface} - mapping of name to function
- *
  * @experimental
  *
- * See {@link proxyActivities} for examples
+ * @see {@link proxyActivities} for examples
  */
-export declare function proxyLocalActivities<A extends ActivityInterface>(options: LocalActivityOptions): A;
+export declare function proxyLocalActivities<A = UntypedActivities>(options: LocalActivityOptions): ActivityInterfaceFor<A>;
 /**
  * Returns a client-side handle that can be used to signal and cancel an existing Workflow execution.
  * It takes a Workflow ID and optional run ID.
@@ -182,9 +204,31 @@ export declare function executeChild<T extends () => WorkflowReturnType>(workflo
  *
  * @return The result of the child Workflow.
  */
-export declare function executeChild<T extends () => WorkflowReturnType>(workflowFunc: T): Promise<ChildWorkflowHandle<T>>;
+export declare function executeChild<T extends () => WorkflowReturnType>(workflowFunc: T): Promise<WorkflowResultType<T>>;
 /**
- * Get information about the current Workflow
+ * Get information about the current Workflow.
+ *
+ * ⚠️ We recommend calling `workflowInfo()` whenever accessing {@link WorkflowInfo} fields. Some WorkflowInfo fields
+ * change during the lifetime of an Execution—like {@link WorkflowInfo.historyLength} and
+ * {@link WorkflowInfo.searchAttributes}—and some may be changeable in the future—like {@link WorkflowInfo.taskQueue}.
+ *
+ * ```ts
+ * // GOOD
+ * function myWorkflow() {
+ *   doSomething(workflowInfo().searchAttributes)
+ *   ...
+ *   doSomethingElse(workflowInfo().searchAttributes)
+ * }
+ * ```
+ *
+ * ```ts
+ * // BAD
+ * function myWorkflow() {
+ *   const attributes = workflowInfo().searchAttributes
+ *   doSomething(attributes)
+ *   ...
+ *   doSomethingElse(attributes)
+ * }
  */
 export declare function workflowInfo(): WorkflowInfo;
 /**
@@ -225,30 +269,27 @@ export declare function proxySinks<T extends Sinks>(): T;
 /**
  * Returns a function `f` that will cause the current Workflow to ContinueAsNew when called.
  *
- * `f` takes the same arguments as the Workflow execute function supplied to typeparam `F`.
+ * `f` takes the same arguments as the Workflow function supplied to typeparam `F`.
  *
- * Once `f` is called, Workflow execution immediately completes.
+ * Once `f` is called, Workflow Execution immediately completes.
  */
 export declare function makeContinueAsNewFunc<F extends Workflow>(options?: ContinueAsNewOptions): (...args: Parameters<F>) => Promise<never>;
 /**
- * Continues current Workflow execution as new with default options.
+ * {@link https://docs.temporal.io/concepts/what-is-continue-as-new/ | Continues-As-New} the current Workflow Execution
+ * with default options.
  *
- * Shorthand for `makeContinueAsNewFunc<F>()(...args)`.
+ * Shorthand for `makeContinueAsNewFunc<F>()(...args)`. (See: {@link makeContinueAsNewFunc}.)
  *
  * @example
  *
- * ```ts
- * import { continueAsNew } from '@temporalio/workflow';
+ *```ts
+ *import { continueAsNew } from '@temporalio/workflow';
  *
- * export function myWorkflow(n: number) {
- *   return {
- *     async execute() {
- *       // ... Workflow logic
- *       await continueAsNew<typeof myWorkflow>(n + 1);
- *     }
- *   };
- * }
- * ```
+ *export async function myWorkflow(n: number): Promise<void> {
+ *  // ... Workflow logic
+ *  await continueAsNew<typeof myWorkflow>(n + 1);
+ *}
+ *```
  */
 export declare function continueAsNew<F extends Workflow>(...args: Parameters<F>): Promise<never>;
 /**
@@ -261,7 +302,7 @@ export declare function uuid4(): string;
 /**
  * Patch or upgrade workflow code by checking or stating that this workflow has a certain patch.
  *
- * See [docs page](https://docs.temporal.io/docs/typescript/versioning) for info.
+ * See {@link https://docs.temporal.io/typescript/versioning | docs page} for info.
  *
  * If the workflow is replaying an existing history, then this function returns true if that
  * history was produced by a worker which also had a `patched` call with the same `patchId`.
@@ -279,7 +320,7 @@ export declare function patched(patchId: string): boolean;
 /**
  * Indicate that a patch is being phased out.
  *
- * See [docs page](https://docs.temporal.io/docs/typescript/versioning) for info.
+ * See {@link https://docs.temporal.io/typescript/versioning | docs page} for info.
  *
  * Workflows with this call may be deployed alongside workflows with a {@link patched} call, but
  * they must *not* be deployed while any workers still exist running old code without a
@@ -333,3 +374,34 @@ export declare type Handler<Ret, Args extends any[], T extends SignalDefinition<
  * @param handler a compatible handler function for the given definition or `undefined` to unset the handler.
  */
 export declare function setHandler<Ret, Args extends any[], T extends SignalDefinition<Args> | QueryDefinition<Ret, Args>>(def: T, handler: Handler<Ret, Args, T> | undefined): void;
+/**
+ * Updates this Workflow's Search Attributes by merging the provided `searchAttributes` with the existing Search
+ * Attributes, `workflowInfo().searchAttributes`.
+ *
+ * For example, this Workflow code:
+ *
+ * ```ts
+ * upsertSearchAttributes({
+ *   CustomIntField: [1, 2, 3],
+ *   CustomBoolField: [true]
+ * });
+ * upsertSearchAttributes({
+ *   CustomIntField: [42],
+ *   CustomKeywordField: ['durable code', 'is great']
+ * });
+ * ```
+ *
+ * would result in the Workflow having these Search Attributes:
+ *
+ * ```ts
+ * {
+ *   CustomIntField: [42],
+ *   CustomBoolField: [true],
+ *   CustomKeywordField: ['durable code', 'is great']
+ * }
+ * ```
+ *
+ * @param searchAttributes The Record to merge. Use a value of `[]` to clear a Search Attribute.
+ */
+export declare function upsertSearchAttributes(searchAttributes: SearchAttributes): void;
+export declare const stackTraceQuery: QueryDefinition<string, []>;