Services

​

Two API flavors

• Standard TypeScript and Promises use familiar async/await syntax for simple, readable code. Use this API for sequential logic, parallel individual steps, and calls to other handlers.
• Generator-based API uses TypeScript generator functions (function* and yield*) for more flexible concurrency and type-safe composition of operations, tasks, and their results. It is a good fit for coding agents or developers familiar with JavaScript and TypeScript generators. Use Durable Coroutines to run concurrent tasks with multiple durable steps in one handler, or define whole handlers as generators.

​

Prerequisites

• NodeJS >= v22 or Bun
• npm CLI >= 9.6.7

​

Getting started

​

Basic Services

import * as restate from "@restatedev/restate-sdk";

export const myService = restate.service({
  name: "MyService",
  handlers: {
    myHandler: async (ctx: restate.Context, greeting: string) => {
      return `${greeting}!`;
    },
  },
});

restate.serve({ services: [myService] });

• Define a service using restate.service.
• The service has a name and a list of handlers.
• Each handler has a name and can be called at <RESTATE_INGRESS>/myService/myHandler
• Handlers take the Context as the first argument.
• Handlers can take one optional JSON-serializable input and must return a JSON-serializable output (see custom serialization for advanced types).
• Serve the service over HTTP (port 9080 by default).

​

Virtual Objects

import * as restate from "@restatedev/restate-sdk";

export const myObject = restate.object({
  name: "MyObject",
  handlers: {
    myHandler: async (ctx: restate.ObjectContext, greeting: string) => {
      return `${greeting} ${ctx.key}!`;
    },
    myConcurrentHandler: restate.handlers.object.shared(
      async (ctx: restate.ObjectSharedContext, greeting: string) => {
        return `${greeting} ${ctx.key}!`;
      }
    ),
  },
});

restate.serve({ services: [myObject] });

• Define a Virtual Object using restate.object(...)
• Each instance is identified by a key (accessible via ctx.key).
• Virtual Objects can have exclusive and shared handlers.
• Exclusive handlers receive an ObjectContext, allowing read/write access to object state.
• Shared handlers are wrapped in handlers.object.shared(...) and use the ObjectSharedContext
• Serve the Virtual Object over HTTP (port 9080 by default).

​

Workflows

import * as restate from "@restatedev/restate-sdk";

export const myWorkflow = restate.workflow({
  name: "MyWorkflow",
  handlers: {
    run: async (ctx: restate.WorkflowContext, req: string) => {
      // implement workflow logic here

      return "success";
    },

    interactWithWorkflow: async (ctx: restate.WorkflowSharedContext) => {
      // implement interaction logic here
      // e.g. resolve a promise that the workflow is waiting on
    },
  },
});

restate.serve({ services: [myWorkflow] });

• Define a workflow with restate.workflow(...)
• Every workflow must include a run handler:
  • This is the main orchestration entry point
  • It runs exactly once per workflow execution and uses the WorkflowContext
  • Resubmission of the same workflow will fail with “Previously accepted”. The invocation ID can be found in the request header x-restate-id.
  • Use ctx.key to access the workflow’s unique ID
• Additional handlers must use the WorkflowSharedContext. They can query state or resolve workflow promises, run concurrently with the run handler, and remain callable until the retention time expires.
• Serve the Workflow over HTTP (port 9080 by default).

​

Configuring services