# Temporal Operation Handler - TypeScript SDK

> For the complete documentation index, see [llms.txt](https://docs.temporal.io/llms.txt).
> Any documentation page is available as raw Markdown by appending `.md` to its URL.

> How to implement Nexus Operations with TemporalOperationHandler in the TypeScript SDK.

> **⚠️ Caution:**
>
> The Temporal Operation Handler is pre-release.
> `TemporalOperationHandler` is marked experimental in the SDKs and may change in backwards-incompatible ways.
>

A [Nexus Service](/nexus/services) publishes Operations that other teams call across [Namespace](/namespaces) boundaries.
`TemporalOperationHandler` is how you implement those Operations.

For the conceptual model, see [Temporal Operation Handler](/nexus/temporal-operation-handler).
This page shows how to write handlers in the TypeScript SDK, migrate from earlier APIs, and compose Workflow, Update, Signal, and Activity backings.

## What you can do with it

**Back an Operation with whichever primitive fits the work.** A multi-step process is a Workflow. A single durable step is an [Activity](/activities), with no Workflow wrapped around it. A change to something already running is an Update. The caller sees the same Operation contract either way, and you can change your choice later without touching callers.

**Combine messaging and a backing in one handler.** A handler can Signal a running Workflow to unblock it and then return a different Execution's result for the caller to await. These are not separate handler types you pick between; they compose inside one start handler.

**Get observability across the Namespace boundary without wiring it.** The Client handed to your handler propagates [bidirectional links](/nexus/execution-debugging#bi-directional-linking) and request Ids on every call it makes. The caller-side and handler-side Executions are connected in the UI and in [Event History](/encyclopedia/event-history), so a single trace crosses the boundary between two teams' Namespaces.

**Stay idempotent through retries.** The server retries Nexus start requests, and the request Id travels with them. Deriving the backing Execution's Id from it means a retry targets the same Execution rather than starting a second one.

**Cancel through the same handler.** The Operation token records which kind of Execution backs the Operation, so a cancellation request reaches the right place. The default behavior is usually what you want, and each kind can be overridden when it is not.

**Grow a handler without rewriting it.** An Operation that starts out completing inline can later gain an async backing, or send a Signal, without changing handler type or breaking its contract.

## The Nexus-aware Client

A `TemporalOperationHandler` start handler receives three things: a context, a Client, and the Operation input.

The Client is what makes the linking automatic, so prefer it over constructing your own inside a handler.
Reaching for your own Client still works, but messages sent that way are not connected back to the caller.

The Client exposes two kinds of call, and the distinction shapes how you write the handler.
The examples below use the TypeScript SDK APIs.

**Async backings — at most one per Operation invocation.** These determine what the Operation *is*, and their result is delivered to the caller through the Nexus completion callback when the underlying Execution finishes.

- Start a Workflow — the Operation completes when the Workflow returns
- Update a Workflow — the Operation completes when the Update completes
- Start an Activity — the Operation completes when the Activity returns; see [Nexus Standalone Activity](/develop/typescript/nexus/activity-backed-operations)

**Sync messaging — as many as you need.** Reach these through the underlying Temporal Client that the Nexus-aware Client exposes.
They take effect during the handler call, still get link propagation, and do not require an async backing.

- Signal — delivered during the handler call to a Workflow that is already running
- Signal-with-Start — delivers the Signal, starting the Workflow first if it is not already running

A handler that only sends messages returns a synchronous result, and the Operation completes immediately.

## Write an Operation handler

The examples below use a Nexus Service with a `startGreeting` Operation backed by a Workflow, an `updateShippingAddress` Operation backed by an Update, a `cancelOrder` Operation that sends a Signal, and a `greet` Operation backed by an Activity.

### Back an Operation with a Workflow

Call `startWorkflow` on the Client and return its result. The Operation completes when the Workflow returns, delivering the Workflow's return value to the caller.

```typescript
const startGreeting = new temporalnexus.TemporalOperationHandler<GreetingInput, GreetingOutput>({
  async start(ctx, client, input) {
    return await client.startWorkflow(greetingWorkflow, {
      args: [input],
      workflowId: `greeting-${input.name}`,
    });
  },
});
```

### Back an Operation with an Update

Back an Operation with an Update when it changes something already running. The target Workflow has to exist already, and the Operation completes when the Update completes.

```typescript
const updateShippingAddressOp = new temporalnexus.TemporalOperationHandler<
  UpdateAddressInput,
  AddressOutput
>({
  async start(ctx, client, input) {
    return await client
      .getWorkflowHandle<typeof orderWorkflow>(`order-${input.orderId}`)
      .update(shippingAddressUpdate, { args: [input] });
  },
});
```

Three constraints apply to Update-backed Operations, and the first two fail the Operation rather than degrading:

- **Only the accepted stage is supported.** A Nexus Operation can only back an asynchronous Update, so the wait-for-stage must be "accepted".
- **The Update Id defaults to the Nexus request Id.** Leaving it unset is what you usually want: a retried start request carries the same request Id, so it targets the same Update rather than running a second one.

The result is async in the normal case, carrying an update-workflow Operation token. If the Update has already completed by the time it is accepted — a retried request with the same Update Id, or an Update that completes immediately — you get a synchronous result instead.

### Send a Signal from an Operation

Reach the Workflow Client through the injected Client, send the message, and return a synchronous result. The Operation completes during the handler call, and the Signal is linked back to the caller.

```typescript
const cancelOrder = new temporalnexus.TemporalOperationHandler<CancelOrderInput, void>({
  async start(ctx, client, input) {
    await client.getWorkflowHandle(`order-${input.orderId}`).signal(requestCancellation, input);
    return temporalnexus.TemporalOperationResult.sync(undefined);
  },
});
```

The same Client also offers Signal-with-Start, and a handler may send several messages before returning.

### Back an Operation with an Activity

Call `startActivity` when the work is a single durable step. The Activity runs with no parent Workflow, so the options require an Activity Id and at least one timeout. See [Nexus Standalone Activity](/develop/typescript/nexus/activity-backed-operations).

```typescript
const greet = new temporalnexus.TemporalOperationHandler<GreetingInput, GreetingOutput>({
  async start(ctx, client, input) {
    return await client.typedActivity<typeof activities>().startActivity('greet', {
      id: `greet-${ctx.requestId}`,
      args: [input],
      taskQueue: TASK_QUEUE_NAME,
      startToCloseTimeout: '10s',
    });
  },
});
```

## Coming from the earlier handler APIs

Skip this section if you are new to Nexus.

Earlier SDK versions had a separate helper per pattern. Existing handlers will keep working, there is no forced migration.

Operations already in progress are not a concern either. If you need to cancel one, for example, a Workflow-backed Operation started by one of the earlier APIs is cancelled by `TemporalOperationHandler` just as it would have been before.

| If you used | Use instead |
| --- | --- |
| The Workflow-run helper (`WorkflowRunOperation`, `NewWorkflowRunOperation`, `@workflow_run_operation`) | `TemporalOperationHandler` with a Workflow backing |
| The synchronous handler (`OperationHandler.sync`, `nexus.NewSyncOperation`, `@sync_operation`) | `TemporalOperationHandler` returning a sync result |
| A Workflow wrapping a single Activity | `TemporalOperationHandler` with an Activity backing |
| A Temporal Client fetched inside a handler | The Client injected into the start handler |

Two things improve when you migrate. Messages and Executions get [bidirectional linking](/nexus/execution-debugging#bi-directional-linking), which hand-fetched Clients do not produce. And one handler type covers every case, so an Operation can change what backs it without changing shape.

### Migrating a Workflow-backed Operation

The earlier helper reached the Client through the Operation context and returned a Workflow handle or method reference, rather than being handed a Client and returning an Operation result:

```typescript
const startGreeting = new temporalnexus.WorkflowRunOperationHandler(
  async (ctx, input: GreetingInput) =>
    await temporalnexus.startWorkflow(ctx, greetingWorkflow, {
      args: [input],
      workflowId: `greeting-${input.name}`,
    }),
);
```

Replace it with [Back an Operation with a Workflow](#back-an-operation-with-a-workflow).

### Migrating a synchronous Operation

A messaging Operation used to be a synchronous handler that fetched its own Client, which is why those messages produced no links:

```typescript
nexus.serviceHandler(orderService, {
  async cancelOrder(ctx, input) {
    await temporalnexus
      .getClient()
      .workflow.getHandle(`order-${input.orderId}`)
      .signal(requestCancellation, input);
  },
});
```

Replace it with [Send a Signal from an Operation](#send-a-signal-from-an-operation).

> **💡 Tip:**
> RESOURCES
>
> - [Temporal Operation Handler](/nexus/temporal-operation-handler) for the conceptual model.
> - [Nexus Services](/nexus/services) and [Nexus Operations](/nexus/operations) for the underlying concepts.
> - [Nexus Client Code Generator](/develop/typescript/nexus/client-code-generator) to generate Service contracts and typed models from one schema.
> - [Activity-backed Nexus Operations](/develop/typescript/nexus/activity-backed-operations) for Activity-backed Operations.
> - [Bidirectional linking](/nexus/execution-debugging#bi-directional-linking) for what the Nexus-aware Client gives you.
> - [TypeScript Nexus feature guide](/develop/typescript/nexus/feature-guide)