TypeScript SDK API guidance

Welcome to the Resonate Typescript SDK guide! This SDK makes it possible to write Distributed Async Await applications with Typescript. This guide covers installation and features that the SDK offers.

API reference

Looking for the API reference?

The Resonate TypeScript SDK API reference is available here.

Installation

How to install the Resonate Typescript SDK into your project.

To install the Resonate Typescript SDK, you can use any of your favorite package managers.

Bun
npm
Yarn

bun add @resonatehq/sdk

npm install @resonatehq/sdk

yarn add @resonatehq/sdk

Initialization

How to initialize a Resonate Client.

There are two ways to initialize Resonate, local and remote.

Local initialization = zero-dependency development

Local initialization means that Resonate uses local memory for promise storage.

This is ideal for getting started quickly or for integrating Resonate into an existing application without relying on dependencies.

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

const resonate = Resonate.local();

Dead Simple incremental adoption

Temporal, Restate, and DBOS require a server or database to get started.

Resonate enables you to get started with a local worker that stores promises in memory, no server or database required. This makes it easy to incrementally adopt Resonate into your existing TypeScript application.

Remote initialization

Remote initialization means that promises are stored remotely, and that the Resonate Client receives messages from a remote source. This is how Resonate enables Durable Async RPC for building distributed applications that are reliable and scalable.

The quickest way to get started with Remote initialization is to connect to a locally running instance of a Resonate Server.

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

// default connection to local development server
const resonate = Resonate.remote();

// connection to a custom endpoint
const resonate = Resonate.remote({ url: "https://my-resonate.com" });

// declaring which group it is part of
const resonate = Resonate.remote({ group: "worker-group-x" });

The default configuration uses the Resonate Server as the promise store and uses an HTTP Long Poller as the message transport to receive messages directly from the Resonate Server.

A Resonate Client can receive messages from many different transports, such as HTTP, RabbitMQ, RedPanda, etc... The Poller is a great starting place however, as it will long-poll for messages from the Resonate Server without any additional setup.

Environment Variables

The Resonate client constructor automatically inspects a handful of environment variables when instantiating the SDK.

Resolution order

When a Resonate Client is instantiated, explicit constructor arguments always win. If an argument is not provided, the client looks for related environment variables before falling back to built-in defaults.

The following order is used when determining the remote endpoint:

url argument supplied to the constructor.
RESONATE_URL environment variable.
RESONATE_SCHEME, RESONATE_HOST, and RESONATE_PORT environment variables.
Built-in local development mode (no remote network).

Similarly, authentication credentials resolve in this order:

auth argument supplied to the constructor.
RESONATE_USERNAME and RESONATE_PASSWORD environment variables.
No authentication (anonymous requests).

No URL means local mode (zero-dependency development)

If neither an argument nor environment variable produces a URL, the client falls back to a local in-memory network. This is convenient for unit tests or quick experiments that do not require a Resonate server.

`RESONATE_URL`

Provides the full base URL (scheme, host, and port) for connecting to a remote Resonate server. Takes precedence over the individual scheme/host/port variables.

Default is unset

Compose from a single URL:

export RESONATE_URL="https://resonate.example.com"

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

const resonate = new Resonate(); // picks up RESONATE_URL automatically

Compose a URL from components:

export RESONATE_SCHEME=https
export RESONATE_HOST=resonate.example
export RESONATE_PORT=8443

const resonate = new Resonate();
// resolves to https://resonate.example:8443

`RESONATE_SCHEME`

Scheme to use when RESONATE_URL is unset and a host is supplied. Combine with RESONATE_HOST (required) and RESONATE_PORT (optional) to build the full URL. |

Default is http.

`RESONATE_HOST`

Hostname or IP address of the remote Resonate server. Must be present to use the scheme/host/port fallback path.

Default is unset.

`RESONATE_PORT`

Port number to use when building the URL from scheme/host/port. Ignored if RESONATE_URL is provided.

Default is 8001.

`RESONATE_USERNAME`

Username for HTTP basic authentication. When set (even without a password) it enables authenticated requests.

Default is unset.

`RESONATE_PASSWORD`

Password paired with RESONATE_USERNAME. Defaults to an empty string when the username is set but no password is supplied.

Default is an empty string.

Example:

export RESONATE_USERNAME=my-user
export RESONATE_PASSWORD=super-secret

const resonate = new Resonate();
// uses { username: "my-user", password: "super-secret" }

Troubleshooting tips

Prefer passing constructor arguments when bootstrapping in application code that owns configuration loading. Environment variables are ideal for CLI usage, tests, or infrastructure-managed settings.
Always set RESONATE_HOST if you intend to rely on the scheme/host/port combination. Without a host the client will treat the configuration as missing and default to local mode.

Client APIs

Registration

How to register a function with Resonate in the TypeScript SDK.

`.register()`

function foo(ctx: Context, ...args: any[]) {
  // ...
  return result;
}
resonate.register(foo);

// or alternatively
resonate.register("foo", (ctx: Context, ...args: any[]) => {
  // ...
  return result;
});

`.setDependency()`

Resonate's .setDependency() method allows you to set a dependency for the Application Node. You can then access the dependency in the function using the .getDependency() method.

Dependencies can only be added in the ephemeral world.

resonate.setDependency("dependency-name", dependency);

The dependency can be accessed from any function in the Call Graph on that Application Node. This is useful for things like database connections or other resources that you want to share across functions.

How to invoke a function in the ephemeral world with the Resonate Class.

To move from the ephemeral world to the durable world you use the Resonate Class to invoke functions.

There are two methods that you can use: .run() and .rpc().

`.run()`

Resonate's .run() method invokes a function in the same process and returns the result. You can think of it as a "run right here" invocation. After invocation, the function is considered durable and will recover in another process if required.

const result = await resonate.run("invocation-id", foo, ...args);

`.beginRun()`

Similar to .run() but instead of returning the result, returns a handle so the result can be awaited later.

const handle = await resonate.beginRun("invocation-id", foo, ...args);
const result = await handle.result();

`.rpc()`

Resonate's .rpc() method (Remote Procedure Call) invokes a function in a remote process and returns the result. You can think of it as a "run somewhere else" invocation (Asynchronous Remote Procedure Call). After invocation, the function is considered durable and will recover in another process if required.

// worker.ts
resonate.register("foo", (ctx: Context, ...args: any[]) => {
  // ...
  return result;
});

// client.ts
const result = await resonate.rpc(
  "invocation-id",
  "foo",
  ...args,
  resonate.options({
    target: "poll://any@workers",
  })
);

`.beginRpc()`

Similar to .rpc() but instead of returning the result, returns a handle so the result can be awaited later.

const handle = await resonate.beginRpc(
  "invocation-id",
  "foo",
  ...args,
  resonate.options({
    target: "poll://any@workers",
  })
);
const result = await handle.result();

`.schedule()`

Resonate's .schedule() method allows you to schedule a function to be invoked on a specified cron schedule. The scheduled function will be invoked until the schedule is deleted.

const schedule = await resonate.schedule(
  "scheduled-foo",
  "0 * * * *", // every hour
  foo,
  ...args
);

`.options()`

Options can be used with .run(), .beginRun(), .rpc(), .beginRpc(), and .schedule() as the final argument.

await resonate.run(
  "invocation-id",
  foo,
  ...args,
  resonate.options({
    timeout: 60_000, // 1 minute in ms
    target: "poll://any@workers",
    tags: { key: "value" },
  })
);

`.get()`

Resonate's .get() method allows you to subscribe to a function invocation. If the function invocation does not exist, an error will be thrown.

const handle = await resonate.get("invocation-id");
const result = await handle.result();

`.promises.get()`

Resonate's .promises.get() method allows you to get a promise by ID.

const p = await resonate.promises.get("promise-id");

`.promises.create()`

Resonate's .promises.create() method allows you to create a promise.

await resonate.promises.create(
  "promise-id",
  Date.now() + 30000 // 30 seconds in the future
);

`.promises.get()`

Resonate's .promises.get() method allows you to get a promise by ID.

const p = await resonate.promises.get("promise-id");

`.promises.resolve()`

Resonate's .promises.resolve() method allows you to resolve a promise by ID.

This is useful for HITL use cases where you want to wait for a human to approve or reject a function execution. It works well in conjunction with the .promise() method.

await resonate.promises.resolve("promise-id");

`.promises.reject()`

Resonate's .promises.reject() method allows you to reject a promise by ID.

await resonate.promises.reject("promise-id");

Context APIs

How to use the Resonate Context object in the TypeScript SDK.

Resonate's Context object enables you to invoke functions from inside a Durable Function. This is how you extend the Call Graph and create a world of Durable Functions. Inside a Durable Function you use the yield* keyword to interact with the Context object.

`.getDependency()`

Context's .getDependency() method allows you to get a dependency that was set in the ephemeral world using the .setDependency() method and use it the Durable World.

resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const dependency = ctx.getDependency("dependency-name");
  // do something with the dependency
  // ...
});

`.run()`

Context's .run() method invokes a function in the same process in a synchronous manner. That is — the calling function blocks until the invoked function returns.

resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const result = yield* ctx.run(bar, ...args);
  // do more stuff
  // ...
});

function bar(ctx: Context, ...args: any[]) {
  // ...
  return;
}

`.beginRun()`

Context's .beginRun() method invokes a function in the same process in an asynchronous manner. That is — the invocation returns a promise which can be awaited later.

resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const promise = yield* ctx.beginRun(bar, ...args);
  // do more stuff
  const result = yield* promise;
  // ...
});

function bar(ctx: Context, ...args: any[]) {
  // ...
  return;
}

`.rpc()`

Context's .rpc() method invokes a function in a remote process in a synchronous manner. That is — the calling function blocks until the invoked function returns.

// process a
resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const result = yield* ctx.rpc(
    "bar",
    ...args,
    ctx.options({ target: "poll://any@workers" })
  );
  // do more stuff
  // ...
});

// process b
resonate.register("bar", function (ctx: Context, ...args: any[]) {
  // ...
  return;
});

`.beginRpc()`

Context's .beginRpc() method invokes a function in a remote process in an asynchronous manner. That is — the invocation returns a promise which can be awaited on later.

// process a
resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const promise = yield* ctx.beginRpc(
    "bar",
    ...args,
    ctx.options({ target: "poll://any@workers" })
  );
  // do more stuff
  const result = yield* promise;
  // ...
});

// process b
resonate.register("bar", function (ctx: Context, ...args: any[]) {
  // ...
  return;
});

`.detached()`

Context's .detached() method invokes a function in a remote process in an asynchronous manner but unlike .beginRpc(), the promise is not implictly awaited. Use .detached() when you want to fire-and-forget a function invocation.

resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  yield* ctx.detached("bar", ...args);
  // do more stuff
});

`.options()`

Options can be used with .run(), .beginRun(), .rpc(), .beginRpc(), and .detached() as the final argument.

resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  yield* ctx.run(
    bar,
    ...args,
    ctx.options({
      id: "custom-id",
      timeout: 60_000, // 1 minute in ms
      target: "poll://any@workers",
      tags: { key: "value" },
    })
  );
});

`.promise()`

Context's .promise() method allows you to get or create a promise that can be awaited on.

If no ID is provided, one is generated and a new promise is created. If an ID is provided and a promise already exists with that ID, then the existing promise is returned.

This is very useful for HITL (Human-In-The-Loop) use cases where you want to block progress until a human has taken an action or provided data. It works well in conjunction with the .promises.resolve() method.

resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const promise = yield* ctx.promise({ id: "promise-id" });
  // do more stuff
  const result = yield* promise;
  // ...
});

You can also pass custom data into the promise.

resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const promise = yield* ctx.promise({ data: { key: "value" } });
  // do more stuff
  const result = yield* promise;
  // ...
});

`.sleep()`

There is no limit to how long the function can sleep.

This API accepts either a millisecond duration or an options object. The options object can specify a duration with the for property or an absolute wake-up time with the until property.

ctx.sleep(5_000); // wait 5 seconds
ctx.sleep({ for: 5_000 }); // identical to passing the number
ctx.sleep({ until: new Date() });

Passing a number or for value always measures the delay in milliseconds from "now". until expects a JavaScript Date instance representing the exact time when the workflow should resume.

The options object is useful when you want to build the wake-up time conditionally before calling sleep.

Sleep for a fixed duration.

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

const resonate = Resonate.local();

resonate.register("send-reminder", function* (ctx: Context, userId: string) {
  // Pause for five seconds without blocking the worker
  yield* ctx.sleep(5_000);

  yield* ctx.rfc("notify-user", userId);
});

Sleep until a calendar time.

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

const resonate = Resonate.local();

resonate.register("schedule-digest", function* (ctx: Context, userId: string) {
  const nextEightAm = new Date();
  nextEightAm.setHours(8, 0, 0, 0);

  // If it is already past 8am today, schedule for tomorrow
  if (nextEightAm.getTime() <= Date.now()) {
    nextEightAm.setDate(nextEightAm.getDate() + 1);
  }

  // Resume exactly at 8am
  yield* ctx.sleep({ until: nextEightAm });

  yield* ctx.rfc("send-digest", userId);
});

`.date.now()`

Context's .date.now() method allows you to deterministically get the time in milliseconds since the epoch. If your function execution is recovered after the time has been retrieved, the same time will be returned. This is helpful for ensuring the same code path is taken in the event of a recovery.

resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const time = yield* ctx.date.now();
  // do something with time
  // ...
});

`.math.random()`

Context's .math.random() method allows you to generate a deterministic random number. If your function execution is recovered after the random number has been generated, the same number will be returned. This is helpful for ensuring the same code path is taken in the event of a recovery.

resonate.register("foo", function* (ctx: Context, ...args: any[]) {
  // ...
  const rand = yield* ctx.math.random();
  // do something with rand
  // ...
});

Installation​

Initialization​

Environment Variables​

RESONATE_URL​

RESONATE_SCHEME​

RESONATE_HOST​

RESONATE_PORT​

RESONATE_USERNAME​

RESONATE_PASSWORD​

Client APIs​

.register()​

.setDependency()​

.run()​

.beginRun()​

.rpc()​

.beginRpc()​

.schedule()​

.options()​

.get()​

.promises.get()​

.promises.create()​

.promises.get()​

.promises.resolve()​

.promises.reject()​

Context APIs​

.getDependency()​

.run()​

.beginRun()​

.rpc()​

.beginRpc()​

.detached()​

.options()​

.promise()​

.sleep()​

.date.now()​

.math.random()​

Installation

Initialization

Environment Variables

`RESONATE_URL`

`RESONATE_SCHEME`

`RESONATE_HOST`

`RESONATE_PORT`

`RESONATE_USERNAME`

`RESONATE_PASSWORD`

Client APIs

`.register()`

`.setDependency()`

`.run()`

`.beginRun()`

`.rpc()`

`.beginRpc()`

`.schedule()`

`.options()`

`.get()`

`.promises.get()`

`.promises.create()`

`.promises.get()`

`.promises.resolve()`

`.promises.reject()`

Context APIs

`.getDependency()`

`.run()`

`.beginRun()`

`.rpc()`

`.beginRpc()`

`.detached()`

`.options()`

`.promise()`

`.sleep()`

`.date.now()`

`.math.random()`