Merge pull request #3896 from hhunter-ms/issue_3869

[Workflow] Update for JavaScript SDK

daprdocs/content/en/developing-applications/building-blocks/workflow/howto-author-workflow.md

@@ -34,7 +34,7 @@ The Dapr sidecar doesn’t load any workflow definitions. Rather, the sidecar si
 
 [Workflow activities]({{< ref "workflow-features-concepts.md#workflow-activites" >}}) are the basic unit of work in a workflow and are the tasks that get orchestrated in the business process.
 
-{{< tabs Python ".NET" Java >}}
+{{< tabs Python JavaScript ".NET" Java >}}
 
 {{% codetab %}}
 
@@ -52,6 +52,37 @@ def hello_act(ctx: WorkflowActivityContext, input):
 [See the `hello_act` workflow activity in context.](https://github.com/dapr/python-sdk/blob/master/examples/demo_workflow/app.py#LL40C1-L43C59)
 
 
+{{% /codetab %}}
+
+{{% codetab %}}
+
+<!--javascript-->
+
+Define the workflow activities you'd like your workflow to perform. Activities are wrapped in the `WorkflowActivityContext` class, which implements the workflow activities. 
+
+```javascript
+export default class WorkflowActivityContext {
+  private readonly _innerContext: ActivityContext;
+  constructor(innerContext: ActivityContext) {
+    if (!innerContext) {
+      throw new Error("ActivityContext cannot be undefined");
+    }
+    this._innerContext = innerContext;
+  }
+
+  public getWorkflowInstanceId(): string {
+    return this._innerContext.orchestrationId;
+  }
+
+  public getWorkflowActivityId(): number {
+    return this._innerContext.taskId;
+  }
+}
+```
+
+[See the workflow activity in context.](https://github.com/dapr/js-sdk/blob/main/src/workflow/runtime/WorkflowActivityContext.ts)
+
+
 {{% /codetab %}}
 
 {{% codetab %}}
@@ -172,7 +203,7 @@ public class DemoWorkflowActivity implements WorkflowActivity {
 
 Next, register and call the activites in a workflow. 
 
-{{< tabs Python ".NET" Java >}}
+{{< tabs Python JavaScript ".NET" Java >}}
 
 {{% codetab %}}
 
@@ -193,6 +224,51 @@ def hello_world_wf(ctx: DaprWorkflowContext, input):
 [See the `hello_world_wf` workflow in context.](https://github.com/dapr/python-sdk/blob/master/examples/demo_workflow/app.py#LL32C1-L38C51)
 
 
+{{% /codetab %}}
+
+{{% codetab %}}
+
+<!--javascript-->
+
+Next, register the workflow with the `WorkflowRuntime` class and start the workflow runtime.
+
+```javascript
+export default class WorkflowRuntime {
+
+  //..
+  // Register workflow implementation for handling orchestrations
+  public registerWorkflow(workflow: TWorkflow): WorkflowRuntime {
+    const name = getFunctionName(workflow);
+    const workflowWrapper = (ctx: OrchestrationContext, input: any): any => {
+      const workflowContext = new WorkflowContext(ctx);
+      return workflow(workflowContext, input);
+    };
+    this.worker.addNamedOrchestrator(name, workflowWrapper);
+    return this;
+  }
+
+  // Register workflow activities
+  public registerActivity(fn: TWorkflowActivity<TInput, TOutput>): WorkflowRuntime {
+    const name = getFunctionName(fn);
+    const activityWrapper = (ctx: ActivityContext, intput: TInput): TOutput => {
+      const wfActivityContext = new WorkflowActivityContext(ctx);
+      return fn(wfActivityContext, intput);
+    };
+    this.worker.addNamedActivity(name, activityWrapper);
+    return this;
+  }
+
+  // Start the workflow runtime processing items and block.
+  public async start() {
+    await this.worker.start();
+  }
+
+}
+```
+
+[See the `WorkflowRuntime` in context.](https://github.com/dapr/js-sdk/blob/main/src/workflow/runtime/WorkflowRuntime.ts)
+
+
 {{% /codetab %}}
 
 {{% codetab %}}
@@ -275,7 +351,7 @@ public class DemoWorkflowWorker {
 
 Finally, compose the application using the workflow.
 
-{{< tabs Python ".NET" Java >}}
+{{< tabs Python JavaScript ".NET" Java >}}
 
 {{% codetab %}}
 
@@ -364,6 +440,153 @@ if __name__ == '__main__':
 ```
 
 
+{{% /codetab %}}
+
+{{% codetab %}}
+
+<!--javascript-->
+
+[The following example](https://github.com/dapr/js-sdk/blob/main/src/workflow/client/DaprWorkflowClient.ts) is a basic JavaScript application using the JavaScript SDK. As in this example, your project code would include:
+
+- A builder with extensions called:
+  - `WorkflowRuntime`: Allows you to register workflows and workflow activities
+  - `DaprWorkflowContext`: Allows you to [create workflows]({{< ref "#write-the-workflow" >}})
+  - `WorkflowActivityContext`: Allows you to [create workflow activities]({{< ref "#write-the-workflow-activities" >}})
+- API calls. In the example below, these calls start, terminate, get status, pause, resume, raise event, and purge the workflow.
+
+```javascript
+import { TaskHubGrpcClient } from "@microsoft/durabletask-js";
+import { WorkflowState } from "./WorkflowState";
+import { generateApiTokenClientInterceptors, generateEndpoint, getDaprApiToken } from "../internal/index";
+import { TWorkflow } from "../../types/workflow/Workflow.type";
+import { getFunctionName } from "../internal";
+import { WorkflowClientOptions } from "../../types/workflow/WorkflowClientOption";
+
+/** DaprWorkflowClient class defines client operations for managing workflow instances. */
+
+export default class DaprWorkflowClient {
+  private readonly _innerClient: TaskHubGrpcClient;
+
+  /** Initialize a new instance of the DaprWorkflowClient.
+   */
+  constructor(options: Partial<WorkflowClientOptions> = {}) {
+    const grpcEndpoint = generateEndpoint(options);
+    options.daprApiToken = getDaprApiToken(options);
+    this._innerClient = this.buildInnerClient(grpcEndpoint.endpoint, options);
+  }
+
+  private buildInnerClient(hostAddress: string, options: Partial<WorkflowClientOptions>): TaskHubGrpcClient {
+    let innerOptions = options?.grpcOptions;
+    if (options.daprApiToken !== undefined && options.daprApiToken !== "") {
+      innerOptions = {
+        ...innerOptions,
+        interceptors: [generateApiTokenClientInterceptors(options), ...(innerOptions?.interceptors ?? [])],
+      };
+    }
+    return new TaskHubGrpcClient(hostAddress, innerOptions);
+  }
+
+  /**
+   * Schedule a new workflow using the DurableTask client.
+   */
+  public async scheduleNewWorkflow(
+    workflow: TWorkflow | string,
+    input?: any,
+    instanceId?: string,
+    startAt?: Date,
+  ): Promise<string> {
+    if (typeof workflow === "string") {
+      return await this._innerClient.scheduleNewOrchestration(workflow, input, instanceId, startAt);
+    }
+    return await this._innerClient.scheduleNewOrchestration(getFunctionName(workflow), input, instanceId, startAt);
+  }
+
+  /**
+   * Terminate the workflow associated with the provided instance id.
+   *
+   * @param {string} workflowInstanceId - Workflow instance id to terminate.
+   * @param {any} output - The optional output to set for the terminated workflow instance.
+   */
+  public async terminateWorkflow(workflowInstanceId: string, output: any) {
+    await this._innerClient.terminateOrchestration(workflowInstanceId, output);
+  }
+
+  /**
+   * Fetch workflow instance metadata from the configured durable store.
+   */
+  public async getWorkflowState(
+    workflowInstanceId: string,
+    getInputsAndOutputs: boolean,
+  ): Promise<WorkflowState | undefined> {
+    const state = await this._innerClient.getOrchestrationState(workflowInstanceId, getInputsAndOutputs);
+    if (state !== undefined) {
+      return new WorkflowState(state);
+    }
+  }
+
+  /**
+   * Waits for a workflow to start running
+   */
+  public async waitForWorkflowStart(
+    workflowInstanceId: string,
+    fetchPayloads = true,
+    timeoutInSeconds = 60,
+  ): Promise<WorkflowState | undefined> {
+    const state = await this._innerClient.waitForOrchestrationStart(
+      workflowInstanceId,
+      fetchPayloads,
+      timeoutInSeconds,
+    );
+    if (state !== undefined) {
+      return new WorkflowState(state);
+    }
+  }
+
+  /**
+   * Waits for a workflow to complete running
+   */
+  public async waitForWorkflowCompletion(
+    workflowInstanceId: string,
+    fetchPayloads = true,
+    timeoutInSeconds = 60,
+  ): Promise<WorkflowState | undefined> {
+    const state = await this._innerClient.waitForOrchestrationCompletion(
+      workflowInstanceId,
+      fetchPayloads,
+      timeoutInSeconds,
+    );
+    if (state != undefined) {
+      return new WorkflowState(state);
+    }
+  }
+
+  /**
+   * Sends an event notification message to an awaiting workflow instance
+   */
+  public async raiseEvent(workflowInstanceId: string, eventName: string, eventPayload?: any) {
+    this._innerClient.raiseOrchestrationEvent(workflowInstanceId, eventName, eventPayload);
+  }
+
+  /**
+   * Purges the workflow instance state from the workflow state store.
+   */
+  public async purgeWorkflow(workflowInstanceId: string): Promise<boolean> {
+    const purgeResult = await this._innerClient.purgeOrchestration(workflowInstanceId);
+    if (purgeResult !== undefined) {
+      return purgeResult.deletedInstanceCount > 0;
+    }
+    return false;
+  }
+
+  /**
+   * Closes the inner DurableTask client and shutdown the GRPC channel.
+   */
+  public async stop() {
+    await this._innerClient.stop();
+  }
+}
+```
+
 {{% /codetab %}}
 
 {{% codetab %}}
@@ -504,5 +727,6 @@ Now that you've authored a workflow, learn how to manage it.
 - [Workflow API reference]({{< ref workflow_api.md >}})
 - Try out the full SDK examples:
   - [Python example](https://github.com/dapr/python-sdk/tree/master/examples/demo_workflow)
+  - [JavaScript example](https://github.com/dapr/js-sdk/tree/main/examples/workflow)
   - [.NET example](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow)
   - [Java example](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/workflows)

daprdocs/content/en/developing-applications/building-blocks/workflow/howto-manage-workflow.md

@@ -12,7 +12,7 @@ Dapr Workflow is currently in beta. [See known limitations for {{% dapr-latest-v
 
 Now that you've [authored the workflow and its activities in your application]({{< ref howto-author-workflow.md >}}), you can start, terminate, and get information about the workflow using HTTP API calls. For more information, read the [workflow API reference]({{< ref workflow_api.md >}}).
 
-{{< tabs Python ".NET" Java HTTP >}}
+{{< tabs Python JavaScript ".NET" Java HTTP >}}
 
 <!--Python-->
 {{% codetab %}}
@@ -63,6 +63,77 @@ d.terminate_workflow(instance_id=instanceId, workflow_component=workflowComponen
 
 {{% /codetab %}}
 
+<!--JavaScript-->
+{{% codetab %}}
+
+Manage your workflow within your code. In the workflow example from the [Author a workflow]({{< ref "howto-author-workflow.md#write-the-application" >}}) guide, the workflow is registered in the code using the following APIs:
+- **client.workflow.start**: Start an instance of a workflow
+- **client.workflow.get**: Get information on the status of the workflow
+- **client.workflow.pause**: Pauses or suspends a workflow instance that can later be resumed
+- **client.workflow.resume**: Resumes a paused workflow instance
+- **client.workflow.purge**: Removes all metadata related to a specific workflow instance
+- **client.workflow.terminate**: Terminate or stop a particular instance of a workflow
+
+```javascript
+import { DaprClient } from "@dapr/dapr";
+
+async function printWorkflowStatus(client: DaprClient, instanceId: string) {
+  const workflow = await client.workflow.get(instanceId);
+  console.log(
+    `Workflow ${workflow.workflowName}, created at ${workflow.createdAt.toUTCString()}, has status ${
+      workflow.runtimeStatus
+    }`,
+  );
+  console.log(`Additional properties: ${JSON.stringify(workflow.properties)}`);
+  console.log("--------------------------------------------------\n\n");
+}
+
+async function start() {
+  const client = new DaprClient();
+
+  // Start a new workflow instance
+  const instanceId = await client.workflow.start("OrderProcessingWorkflow", {
+    Name: "Paperclips",
+    TotalCost: 99.95,
+    Quantity: 4,
+  });
+  console.log(`Started workflow instance ${instanceId}`);
+  await printWorkflowStatus(client, instanceId);
+
+  // Pause a workflow instance
+  await client.workflow.pause(instanceId);
+  console.log(`Paused workflow instance ${instanceId}`);
+  await printWorkflowStatus(client, instanceId);
+
+  // Resume a workflow instance
+  await client.workflow.resume(instanceId);
+  console.log(`Resumed workflow instance ${instanceId}`);
+  await printWorkflowStatus(client, instanceId);
+
+  // Terminate a workflow instance
+  await client.workflow.terminate(instanceId);
+  console.log(`Terminated workflow instance ${instanceId}`);
+  await printWorkflowStatus(client, instanceId);
+
+  // Wait for the workflow to complete, 30 seconds!
+  await new Promise((resolve) => setTimeout(resolve, 30000));
+  await printWorkflowStatus(client, instanceId);
+
+  // Purge a workflow instance
+  await client.workflow.purge(instanceId);
+  console.log(`Purged workflow instance ${instanceId}`);
+  // This will throw an error because the workflow instance no longer exists.
+  await printWorkflowStatus(client, instanceId);
+}
+
+start().catch((e) => {
+  console.error(e);
+  process.exit(1);
+});
+```
+
+{{% /codetab %}}
+
 <!--NET-->
 {{% codetab %}}
 
@@ -242,6 +313,7 @@ Learn more about these HTTP calls in the [workflow API reference guide]({{< ref
 - [Try out the Workflow quickstart]({{< ref workflow-quickstart.md >}})
 - Try out the full SDK examples:
   - [Python example](https://github.com/dapr/python-sdk/blob/master/examples/demo_workflow/app.py)
+  - [JavaScript example](https://github.com/dapr/js-sdk/tree/main/examples/workflow)
   - [.NET example](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow)
   - [Java example](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/workflows)
 

daprdocs/content/en/developing-applications/building-blocks/workflow/workflow-architecture.md

@@ -195,5 +195,6 @@ See the [Reminder usage and execution guarantees section]({{< ref "workflow-arch
 - [Try out the Workflow quickstart]({{< ref workflow-quickstart.md >}})
 - Try out the following examples: 
    - [Python](https://github.com/dapr/python-sdk/tree/master/examples/demo_workflow)
+   - [JavaScript example](https://github.com/dapr/js-sdk/tree/main/examples/workflow)
    - [.NET](https://github.com/dapr/dotnet-sdk/tree/master/examples/Workflow)
    - [Java](https://github.com/dapr/java-sdk/tree/master/examples/src/main/java/io/dapr/examples/workflows)