Skip to content

Latest commit

 

History

History
151 lines (103 loc) · 10.7 KB

README.md

File metadata and controls

151 lines (103 loc) · 10.7 KB
Raw
Branch Status Support level Programming model Node.js versions
v3.x (Default) Build Status GA (Recommended) V4 18.x+
v2.x Build Status GA V3 14.x+

Durable Functions for Node.js

The durable-functions npm package allows you to write Durable Functions for Node.js. Durable Functions is an extension of Azure Functions that lets you write stateful functions and workflows in a serverless environment. The extension manages state, checkpoints, and restarts for you. Durable Functions' advantages include:

  • Define workflows in code. No JSON schemas or designers are needed.
  • Call other functions synchronously and asynchronously. Output from called functions can be saved to local variables.
  • Automatically checkpoint progress whenever the function schedules async work. Local state is never lost if the process recycles or the VM reboots.

You can find more information at the following links:

A durable function, or orchestration, is a solution made up of different types of Azure Functions:

  • Activity: the functions and tasks being orchestrated by your workflow.
  • Orchestrator: a function that describes the way and order actions are executed in code.
  • Client: the entry point for creating an instance of a durable orchestration.

Durable Functions' function types and features are documented in-depth here.

Version v3.x of the Durable Functions package supports the new v4 Node.js programming model for Azure Functions, which is now generally available! Compared to the v3 model, the v4 model is designed to have a more idiomatic and intuitive experience for JavaScript and TypeScript developers. You can learn more about the v4 programming model at the following links:

Getting Started

You can follow the Visual Studio Code quickstart in JavaScript or TypeScript to get started with a function chaining example, or follow the general checklist below:

  1. Install prerequisites:

  2. Create an Azure Functions app. Visual Studio Code's Azure Functions extension is recommended (version 1.10.4 or above is needed for the v4 programming model).

  3. Install the Durable Functions extension

We recommend using Azure Functions extension bundles to install the Durable Functions extension. Version 3.15 or higher of extension bundles is required for the v4 programming model. Make sure you add the following in your host.json file:

"extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle",
    "version": "[3.15.0, 4.0.0)"
}
  1. Install the durable-functions npm package (preview version) at the root of your function app:
npm install durable-functions
  1. Write an activity function (see sample in JavaScript/TypeScript):
const df = require("durable-functions");
df.app.activity("myActivity", {
    handler: async function (input, context) {
        // your code here
    },
});
  1. Write an orchestrator function (see sample in JavaScript/TypeScript):
const df = require("durable-functions");
df.app.orchestration("myOrchestration", function* (context) {
    // your code here
});

Note: Orchestrator functions must follow certain code constraints.

  1. Write your client function (see sample in JavaScript/TypeScript):
const df = require("durable-functions");

df.app.client.http("httpStart", {
    route: "orchestrators/{orchestratorName}",
    handler: async (request, client, context) => {
        const body = await request.json();
        const instanceId = await client.startNew(request.params.orchestratorName, { input: body });

        context.log(`Started orchestration with ID = '${instanceId}'.`);

        return client.createCheckStatusResponse(request, instanceId);
    },
});

Note: Client functions can be started by any trigger binding supported in the Azure Functions runtime version 2.x+. Node.js v4 programming model apps require at least version 4.25 of the Azure Functions runtime. Read more about trigger bindings and 2.x-supported bindings.

Samples

The Durable Functions samples demonstrate several common use cases. They are located in the samples directories (JavaScript/TypeScript). Descriptive documentation is also available:

const df = require("durable-functions");

const helloActivity = df.app.activity("hello", {
    handler: async function (input) {
        return `Hello, ${input}`;
    },
});

df.app.orchestration("helloSequence", function* (context) {
    context.log("Starting chain sample");

    const output = [];
    output.push(yield helloActivity("Tokyo"));
    output.push(yield helloActivity("Seattle"));
    output.push(yield helloActivity("Cairo"));

    return output;
});

How it works

Durable Functions

One of the key attributes of Durable Functions is reliable execution. Orchestrator functions and activity functions may be running on different VMs within a data center, and those VMs or the underlying networking infrastructure is not 100% reliable.

In spite of this, Durable Functions ensures reliable execution of orchestrations. It does so by using storage queues to drive function invocation and by periodically checkpointing execution history into storage tables (using a cloud design pattern known as Event Sourcing). That history can then be replayed to automatically rebuild the in-memory state of an orchestrator function.

Read more about Durable Functions' reliable execution.

Durable Functions JS

The durable-functions shim lets you express a workflow in code as a generator function wrapped by a call to the app.orchestration method. The Durable Functions SDK treats yield-ed calls, such as yield helloActivity("Tokyo"), as points where you want to schedule an asynchronous unit of work and wait for it to complete.

Calling helloActivity("Tokyo") returns a Task object signifying the outstanding work. Task objects can also be obtained by APIs on the context.df object, such as context.df.callHttp(). Only Task objects can be yielded. The SDK appends the action(s) of the Task object to a list which it passes back to the Functions runtime, plus whether the function is completed, and any output or errors.

The Azure Functions extension schedules the desired actions. When the actions complete, the extension triggers the orchestrator function to replay up to the next incomplete asynchronous unit of work or its end, whichever comes first.