Skip to main content


Welcome to Resonate's guide to the Resonate TypeScript SDK! This SDK makes it easy to write distributed async/await applications with TypeScript. In this guide, we will explore the minimal yet powerful API surface area the SDK offers.


To get started, simply install the SDK using npm:

npm install @resonatehq/[email protected]

Initializing Resonate

Begin by creating a top-level Resonate object:

import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate();

Registering and Running Functions

To leverage Resonate's capabilities:

  1. Register your function with the Resonate object using resonate.register(). Provide a function unique identifier (UID) and a function pointer to your local function.
  2. Once registered, you can invoke the registered function using by passing the function's UID, a UID for the specific execution, and any required arguments.
import { Resonate, Context } from "@resonatehq/sdk";

const resonate = new Resonate();

resonate.register("purchase", purchase);"purchase", uid, user, song);


With, your code executes will complete even in the presence of hardware or software failures. Remember to start the Resonate application by calling resonate.start()!

Running Functions Periodically

You can also execute your function periodically with a cron expression.

resonate.register("purchase", purchase);

// Schedule a resonate function that is already registered.
resonate.schedule("everyMinute", "* * * * *", "purchase");

// Schedule and register a resonate function in one.
resonate.schedule("everyMinute", "* * * * *", (ctx: Context) => {
console.log("every minute",;

Execution Modes

Resonate offers two execution modes: Default and Durable.

Default Mode

In the default mode, Resonate utilizes a volatile in-memory promise store. This mode provides out-of-the-box features like automatic retries, tracing, and logging without requiring any additional infrastructure.

import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate();

Durable Mode

For advanced use cases requiring recoverability, stateful reminders, and a distributed task framework, configure Resonate to use a durable promise store. To enable durable mode, run the Resonate Server locally (refer to the Resonate Server docs for setup instructions) and pass the server's address when initializing Resonate:

import { Resonate } from "@resonatehq/sdk";

const resonate = new Resonate({
url: "http://localhost:8001",

Resonate Context

Interactions with the runtime occur through the Resonate Context, which provides methods like and ctx.sleep(). These methods offer automatic retries, recoverability, task distribution, and more. All top-level functions (invoked by and intermediary functions (invoked by must accept a Resonate context as their first argument.

async function purchase(ctx: Context, user: User, song: Song): Promise<Status> {
const charged = await, user, song);
const granted = await, user, song);
return { charged, granted };

async function charge(ctx: Context, user: User, song: Song): Promise<boolean> {
console.log(`Charged user:${} $${song.price}.`);
return true;

async function access(ctx: Context, user: User, song: Song): Promise<boolean> {
console.log(`Granted user:${} access to song:${}.`);
return true;


In-process execution enables durable execution of functions within the same process by passing a function pointer to a local function followed by its arguments.

const result =, arg1, arg2, ...);



Out-process execution requires the Resonate server and proper configuration to route tasks to workers. Refer to the Resonate Server docs for more information.

Out-of-process execution allows you to dispatch the execution of multiple tasks and collect the results of those executions. Offloading tasks to dedicated workers occurs by passing a URL to an available worker along with its arguments. This approach enables you to perform the fan-out/fan-in pattern.

const result = await`/gpu/summarize/${url}`, arg);


Resonate keeps track of timers and executes them, even across failures and restarts. To sleep in a Resonate application for a whole day, do the following:

await ctx.sleep(86_400_000);


Resonate offers various configuration options to customize its behavior. If options are not provided, sensible defaults are used.

Global Configuration

Configure the SDK globally via the top-level Resonate object:

import { Resonate, Retry } from "@resonatehq/sdk";

const resonate = new Resonate({
url: "", // The remote promise store URL. If not provided, an in-memory promise store will be used.
retry: Retry.exponential(
100, // initial delay (in ms)
2, // backoff factor
Infinity, // max attempts
60000 // max delay (in ms, 1 minute)
timeout: 5000, // The default promise timeout in ms, used for every function executed by calling run. Defaults to 1000.
tags: { foo: "bar" }, // Tags to add to all durable promises.

Function-specific Configuration

When registering functions with resonate.register(), provide function-specific options:

timeout: Number.MAX_SAFE_INTEGER, // Overrides the default timeout.
retry: Retry.linear(), // Overrides the default retry policy.
tags: { bar: "baz" }, // Additional tags to add to the durable promise.

Additionally, override functions in


The options, such as timeout, cannot exceed the parent function. If it does, the minimum will take precedence., arg1, arg2, resonate.options({ ... }));


You can register multiple versions of a function with resonate.register():

// Register `downloadAndSummarize` function with a version number of 2,
// a function pointer to a local function,
// and optionals configurations.
version: 2,

You can specify which version to run as an option on run. By default the function registered with the greatest (latest) version will be chosen."downloadAndSummarize", "uid", resonate.options({ version: 2 }));

Additionally, your function has access to context.version, telling it the version this execution was started with.

async function charge(ctx: Context, user: User, song: Song): Promise<boolean> {
if (ctx.version == 1) {
console.log(`Charged user:${} $${song.price} with version 1`);
} else {
console.log(`Charged user:${} $${song.price} with version 2`);
return true;

Next Steps

We hope this guide has provided you with a solid foundation for working with the Resonate Typescript SDK. If you have any questions or need further assistance, don't hesitate to reach out to us. For next steps, consider the following: