Resonate Async Await Engine Typescript

Resonate Async/Await Engine (TypeScript)

SDK version: This skill reflects @resonatehq/sdk v0.11.4 (current on npm). The async/await engine was introduced in v0.11.0.

Overview

The TypeScript SDK ships two execution engines:

Both engines connect to the same Resonate Server, share the same durable-promise substrate, and support the same patterns (fan-out, human-in-the-loop, saga, etc.). The async engine is opt-in — existing generator-engine code is unaffected.

For the generator engine, see resonate-basic-ephemeral-world-usage-typescript and resonate-basic-durable-world-usage-typescript.

When to use the async engine

• Writing new TypeScript workflows and prefer async/await over function*/yield*
• Integrating Resonate into a codebase that already uses async/await throughout
• Browser or edge environments: @resonatehq/sdk/async exports are browser-compatible

When to keep the generator engine

• Existing generator-engine code — there is no reason to migrate; the generator engine is fully supported
• You need ctx.detached() with the full bounded-replay pattern (async engine also has detach() but check the SDK changelog for your version)

Installation

npm install @resonatehq/sdk@0.11.4

Both engines are in the same package. The generator engine is the default export; the async engine is the /async sub-export.

Basic usage

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

const resonate = new Resonate({ url: "http://localhost:8001" });

// Register an async function
resonate.register("greet", async (ctx, name: string) => {
  return `Hello, ${name}!`;
});

// Start a workflow — resonate.run(id, funcOrName, ...args) → Promise<ResonateHandle<T>>
const handle = await resonate.run("greet-001", "greet", "world");

// Await the result via the durable-promise subscription
const result = await handle.result();
// result === "Hello, world!"

Key differences from the generator engine:

• Import is from "@resonatehq/sdk/async" not from "@resonatehq/sdk"
• Functions are async function not function*
• ctx.run(func, ...args) in the async engine has no id argument (ID is auto-generated); in the generator engine ctx.run(fn, ...args) is also ID-less at the context level, but the API shape differs
• No beginRun / beginRpc on the async-engine client — every run and rpc already returns a ResonateHandle<T> directly, so beginRun would be redundant

Eager ctx.run and fan-out with Promise.all

Inside an async workflow function, ctx.run(func, ...args) returns a DurablePromise<T> immediately — the child starts executing right away. Hold several and await them together for parallel fan-out:

resonate.register("processItems", async (ctx, items: string[]) => {
  // Start all children eagerly — they run in parallel
  const promises = items.map((item) =>
    ctx.run(processOne, item)
  );

  // Await all results
  const results = await Promise.all(promises);
  return results;
});

resonate.register("processOne", async (ctx, item: string) => {
  // ... durable leaf work
  return `processed: ${item}`;
});

This is the async-engine equivalent of the generator engine's ctx.beginRun + sequential yield* pattern.

Retries: Never default, Exponential opt-in

The async/await engine defaults to no retry (Never) when no retry policy is specified. To opt into retries on a specific ctx.run call, pass ctx.options({ retryPolicy: ... }):

import { Resonate, Exponential, Never } from "@resonatehq/sdk/async";

resonate.register("reliableStep", async (ctx, taskId: string) => {
  // Default: Never retry — a failure propagates immediately
  const noRetryResult = await ctx.run(fragileOp, taskId);

  // Explicit Exponential retry on a specific child
  const retryResult = await ctx.run(
    flakeyOp,
    taskId,
    ctx.options({ retryPolicy: new Exponential() }),
  );

  return { noRetryResult, retryResult };
});

Never, Exponential, Linear, and Constant are all exported from @resonatehq/sdk/async and can be used with both engines.

Tip: For saga-style compensation, let steps fail immediately with the default Never policy and catch in the outer function.

ctx.options() in the async engine

ctx.options() accepts the same fields as the generator engine:

ctx.options({
  retryPolicy: new Exponential(),   // retry policy (default: Never)
  target: "poll://any@workers",     // worker group routing
  timeout: 30_000,                  // ms; defaults to 24h
  tags: { "env": "prod" },          // arbitrary tags on the child promise
  version: 1,                       // function version pin
})

Migration from generator engine

The server-side promise structure is identical; existing generator-engine workflows on the server are unaffected by the async engine.

See the SDK README migration guide for the authoritative changelog.

External promise resolution (human-in-the-loop)

The async engine uses the same resonate.promises.resolve() API as the generator engine:

// Inside a workflow: park on an external decision
resonate.register("awaitApproval", async (ctx, orderId: string) => {
  const dp = ctx.promise<{ approved: boolean }>();
  // dp.id is available synchronously — surface it to whoever needs to approve
  console.log("Approval promise id:", dp.id);
  const decision = await dp;
  return decision;
});

// In a webhook handler: resolve the parked promise
const data = Buffer.from(JSON.stringify({ approved: true })).toString("base64");
await resonate.promises.resolve(promiseId, { data });

Full runnable example

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

const resonate = new Resonate({ url: "http://localhost:8001" });

resonate.register("summarize", async (ctx, texts: string[]) => {
  // Fan-out: summarize each text in parallel
  const summaries = await Promise.all(
    texts.map((t) =>
      ctx.run(
        summarizeOne,
        t,
        ctx.options({ retryPolicy: new Exponential() }),
      )
    )
  );
  return summaries.join("\n");
});

resonate.register("summarizeOne", async (ctx, text: string) => {
  // ... call an LLM or summarization service
  return `Summary of: ${text.slice(0, 50)}`;
});

const handle = await resonate.run("summarize-job-001", "summarize", [
  "First document ...",
  "Second document ...",
]);
console.log(await handle.result());

await resonate.stop();