Merge pull request #227228 from hossam-nasr/durable-v4-model

Add Node v4 Programming Model to Durable docs

Author: v-regandowner

.openpublishing.publish.config.json

@@ -233,7 +233,13 @@
     {
       "path_to_root": "azure-functions-durable-js",
       "url": "https://github.com/Azure/azure-functions-durable-js",
-      "branch": "main",
+      "branch": "v2.x",
+      "branch_mapping": {}
+    },
+    {
+      "path_to_root": "azure-functions-durable-js-v3",
+      "url": "https://github.com/Azure/azure-functions-durable-js",
+      "branch": "v3.x",
       "branch_mapping": {}
     },
     {

articles/azure-functions/durable/TOC.yml

@@ -26,6 +26,9 @@
   - name: Create durable function - JavaScript
     displayName: get started, chaining
     href: quickstart-js-vscode.md
+  - name: Create durable function - TypeScript
+    displayName: get started, chaining
+    href: quickstart-ts-vscode.md
   - name: Create durable function - Python
     displayName: get started, chaining
     href: quickstart-python-vscode.md

articles/azure-functions/durable/durable-functions-cloud-backup.md

@@ -2,14 +2,19 @@
 title: Fan-out/fan-in scenarios in Durable Functions - Azure
 description: Learn how to implement a fan-out-fan-in scenario in the Durable Functions extension for Azure Functions.
 ms.topic: conceptual
-ms.date: 11/02/2019
+ms.date: 02/14/2023
 ms.author: azfuncdf
 ---
 
 # Fan-out/fan-in scenario in Durable Functions - Cloud backup example
 
 *Fan-out/fan-in* refers to the pattern of executing multiple functions concurrently and then performing some aggregation on the results. This article explains a sample that uses [Durable Functions](durable-functions-overview.md) to implement a fan-in/fan-out scenario. The sample is a durable function that backs up all or some of an app's site content into Azure Storage.
 
+> [!NOTE]
+> The new programming model for authoring Functions in Node.js (V4) is currently in preview. Compared to the current model, the new experience is designed to be more idiomatic and intuitive for JavaScript and TypeScript developers. To learn more, see the Azure Functions Node.js [developer guide](../functions-reference-node.md?pivots=nodejs-model-v4).
+>
+> In the following code snippets, JavaScript (PM4) denotes programming model V4, the new experience.
+
 [!INCLUDE [durable-functions-prerequisites](../../../includes/durable-functions-prerequisites.md)]
 
 ## Scenario overview
@@ -50,7 +55,7 @@ Notice the `await Task.WhenAll(tasks);` line. All the individual calls to the `E
 
 After awaiting from `Task.WhenAll`, we know that all function calls have completed and have returned values back to us. Each call to `E2_CopyFileToBlob` returns the number of bytes uploaded, so calculating the sum total byte count is a matter of adding all those return values together.
 
-# [JavaScript](#tab/javascript)
+# [JavaScript (PM3)](#tab/javascript-v3)
 
 The function uses the standard *function.json* for orchestrator functions.
 
@@ -67,6 +72,19 @@ Notice the `yield context.df.Task.all(tasks);` line. All the individual calls to
 
 After yielding from `context.df.Task.all`, we know that all function calls have completed and have returned values back to us. Each call to `E2_CopyFileToBlob` returns the number of bytes uploaded, so calculating the sum total byte count is a matter of adding all those return values together.
 
+# [JavaScript (PM4)](#tab/javascript-v4)
+
+Here is the code that implements the orchestrator function:
+
+:::code language="javascript" source="~/azure-functions-durable-js-v3/samples-js/functions/backupSiteContent.js" range="1,4,7-35":::
+
+Notice the `yield context.df.Task.all(tasks);` line. All the individual calls to the `copyFileToBlob` function were *not* yielded, which allows them to run in parallel. When we pass this array of tasks to `context.df.Task.all`, we get back a task that won't complete *until all the copy operations have completed*. If you're familiar with [`Promise.all`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise/all) in JavaScript, then this is not new to you. The difference is that these tasks could be running on multiple virtual machines concurrently, and the Durable Functions extension ensures that the end-to-end execution is resilient to process recycling.
+
+> [!NOTE]
+> Although Tasks are conceptually similar to JavaScript promises, orchestrator functions should use `context.df.Task.all` and `context.df.Task.any` instead of `Promise.all` and `Promise.race` to manage task parallelization.
+
+After yielding from `context.df.Task.all`, we know that all function calls have completed and have returned values back to us. Each call to `copyFileToBlob` returns the number of bytes uploaded, so calculating the sum total byte count is a matter of adding all those return values together.
+
 # [Python](#tab/python)
 
 The function uses the standard *function.json* for orchestrator functions.
@@ -96,7 +114,7 @@ The helper activity functions, as with other samples, are just regular functions
 
 [!code-csharp[Main](~/samples-durable-functions/samples/precompiled/BackupSiteContent.cs?range=44-54)]
 
-# [JavaScript](#tab/javascript)
+# [JavaScript (PM3)](#tab/javascript-v3)
 
 The *function.json* file for `E2_GetFileList` looks like the following:
 
@@ -108,6 +126,14 @@ And here is the implementation:
 
 The function uses the `readdirp` module (version 2.x) to recursively read the directory structure.
 
+# [JavaScript (PM4)](#tab/javascript-v4)
+
+Here is the implementation of the `getFileList` activity function:
+
+:::code language="javascript" source="~/azure-functions-durable-js-v3/samples-js/functions/backupSiteContent.js" range="1,3,7,36-48":::
+
+The function uses the `readdirp` module (version `3.x`) to recursively read the directory structure.
+
 # [Python](#tab/python)
 
 The *function.json* file for `E2_GetFileList` looks like the following:
@@ -134,7 +160,7 @@ And here is the implementation:
 
 The function uses some advanced features of Azure Functions bindings (that is, the use of the [`Binder` parameter](../functions-dotnet-class-library.md#binding-at-runtime)), but you don't need to worry about those details for the purpose of this walkthrough.
 
-# [JavaScript](#tab/javascript)
+# [JavaScript (PM3)](#tab/javascript-v3)
 
 The *function.json* file for `E2_CopyFileToBlob` is similarly simple:
 
@@ -144,6 +170,12 @@ The JavaScript implementation uses the [Azure Storage SDK for Node](https://gith
 
 :::code language="javascript" source="~/azure-functions-durable-js/samples/E2_CopyFileToBlob/index.js":::
 
+# [JavaScript (PM4)](#tab/javascript-v4)
+
+The JavaScript implementation of `copyFileToBlob` uses an Azure Storage output binding to upload the files to Azure Blob storage.
+
+:::code language="javascript" source="~/azure-functions-durable-js-v3/samples-js/functions/backupSiteContent.js" range="1-2,5-6,8-9,50-68":::
+
 # [Python](#tab/python)
 
 The *function.json* file for `E2_CopyFileToBlob` is similarly simple:

articles/azure-functions/durable/durable-functions-error-handling.md

@@ -2,7 +2,7 @@
 title: Handling errors in Durable Functions - Azure
 description: Learn how to handle errors in the Durable Functions extension for Azure Functions.
 ms.topic: conceptual
-ms.date: 12/07/2022
+ms.date: 02/14/2023
 ms.author: azfuncdf
 ms.devlang: csharp, javascript, powershell, python, java
 ---
@@ -11,6 +11,11 @@ ms.devlang: csharp, javascript, powershell, python, java
 
 Durable Function orchestrations are implemented in code and can use the programming language's built-in error-handling features. There really aren't any new concepts you need to learn to add error handling and compensation into your orchestrations. However, there are a few behaviors that you should be aware of.
 
+> [!NOTE]
+> The new programming model for authoring Functions in Node.js (V4) is currently in preview. Compared to the current model, the new experience is designed to be more idiomatic and intuitive for JavaScript and TypeScript developers. To learn more, see the Azure Functions Node.js [developer guide](../functions-reference-node.md?pivots=nodejs-model-v4).
+>
+> In the following code snippets, JavaScript (PM4) denotes programming model V4, the new experience.
+
 ## Errors in activity functions
 
 Any exception that is thrown in an activity function is marshaled back to the orchestrator function and thrown as a `FunctionFailedException`. You can write error handling and compensation code that suits your needs in the orchestrator function.
@@ -95,41 +100,63 @@ public static async Task Run(
 }
 ```
 
-# [JavaScript](#tab/javascript)
+# [JavaScript (PM3)](#tab/javascript-v3)
 
 ```javascript
 const df = require("durable-functions");
 
-module.exports = df.orchestrator(function*(context) {
+module.exports = df.orchestrator(function* (context) {
     const transferDetails = context.df.getInput();
 
-    yield context.df.callActivity("DebitAccount",
-        {
-            account = transferDetails.sourceAccount,
-            amount = transferDetails.amount,
-        }
-    );
+    yield context.df.callActivity("DebitAccount", {
+        account: transferDetails.sourceAccount,
+        amount: transferDetails.amount,
+    });
 
     try {
-        yield context.df.callActivity("CreditAccount",
-            {
-                account = transferDetails.destinationAccount,
-                amount = transferDetails.amount,
-            }
-        );
+        yield context.df.callActivity("CreditAccount", {
+            account: transferDetails.destinationAccount,
+            amount: transferDetails.amount,
+        });
+    } catch (error) {
+        // Refund the source account.
+        // Another try/catch could be used here based on the needs of the application.
+        yield context.df.callActivity("CreditAccount", {
+            account: transferDetails.sourceAccount,
+            amount: transferDetails.amount,
+        });
     }
-    catch (error) {
+})
+```
+# [JavaScript (PM4)](#tab/javascript-v4)
+
+```javascript
+const df = require("durable-functions");
+
+df.app.orchestration("transferFunds", function* (context) {
+    const transferDetails = context.df.getInput();
+
+    yield context.df.callActivity("debitAccount", {
+        account: transferDetails.sourceAccount,
+        amount: transferDetails.amount,
+    });
+
+    try {
+        yield context.df.callActivity("creditAccount", {
+            account: transferDetails.destinationAccount,
+            amount: transferDetails.amount,
+        });
+    } catch (error) {
         // Refund the source account.
         // Another try/catch could be used here based on the needs of the application.
-        yield context.df.callActivity("CreditAccount",
-            {
-                account = transferDetails.sourceAccount,
-                amount = transferDetails.amount,
-            }
-        );
+        yield context.df.callActivity("creditAccount", {
+            account: transferDetails.sourceAccount,
+            amount: transferDetails.amount,
+        });
     }
 });
 ```
+
 # [Python](#tab/python)
 
 ```python
@@ -248,7 +275,7 @@ public static async Task Run([OrchestrationTrigger] TaskOrchestrationContext con
 }
 ```
 
-# [JavaScript](#tab/javascript)
+# [JavaScript (PM3)](#tab/javascript-v3)
 
 ```javascript
 const df = require("durable-functions");
@@ -266,6 +293,23 @@ module.exports = df.orchestrator(function*(context) {
 });
 ```
 
+# [JavaScript (PM4)](#tab/javascript-v4)
+
+```javascript
+const df = require("durable-functions");
+
+df.app.orchestration("callActivityWithRetry", function* (context) {
+    const firstRetryIntervalInMilliseconds = 5000;
+    const maxNumberOfAttempts = 3;
+
+    const retryOptions = new df.RetryOptions(firstRetryIntervalInMilliseconds, maxNumberOfAttempts);
+
+    yield context.df.callActivityWithRetry("flakyFunction", retryOptions);
+
+    // ...
+});
+```
+
 # [Python](#tab/python)
 
 ```python
@@ -372,7 +416,11 @@ catch (TaskFailedException)
 }
 ```
 
-# [JavaScript](#tab/javascript)
+# [JavaScript (PM3)](#tab/javascript-v3)
+
+JavaScript doesn't currently support custom retry handlers. However, you still have the option of implementing retry logic directly in the orchestrator function using loops, exception handling, and timers for injecting delays between retries.
+
+# [JavaScript (PM4)](#tab/javascript-v4)
 
 JavaScript doesn't currently support custom retry handlers. However, you still have the option of implementing retry logic directly in the orchestrator function using loops, exception handling, and timers for injecting delays between retries.
 
@@ -474,7 +522,7 @@ public static async Task<bool> Run([OrchestrationTrigger] TaskOrchestrationConte
 }
 ```
 
-# [JavaScript](#tab/javascript)
+# [JavaScript (PM3)](#tab/javascript-v3)
 
 ```javascript
 const df = require("durable-functions");
@@ -498,6 +546,30 @@ module.exports = df.orchestrator(function*(context) {
 });
 ```
 
+# [JavaScript (PM4)](#tab/javascript-v4)
+
+```javascript
+const df = require("durable-functions");
+const { DateTime } = require("luxon");
+
+df.app.orchestration("timerOrchestrator", function* (context) {
+    const deadline = DateTime.fromJSDate(context.df.currentUtcDateTime).plus({ seconds: 30 });
+
+    const activityTask = context.df.callActivity("flakyFunction");
+    const timeoutTask = context.df.createTimer(deadline.toJSDate());
+
+    const winner = yield context.df.Task.any([activityTask, timeoutTask]);
+    if (winner === activityTask) {
+        // success case
+        timeoutTask.cancel();
+        return true;
+    } else {
+        // timeout case
+        return false;
+    }
+});
+```
+
 # [Python](#tab/python)
 
 ```python