Skip to main content

Standalone Nexus Operations - TypeScript SDK

SUPPORT, STABILITY, and DEPENDENCY INFO

Temporal TypeScript SDK support for Standalone Nexus Operations is at Pre-release.

All APIs are experimental and may be subject to backwards-incompatible changes.

Standalone Nexus Operations let you run Nexus Operation Executions independently, without being orchestrated by a Workflow. Instead of calling a Nexus Operation from within a Workflow Definition using @temporalio/workflow's createNexusServiceClient(), you execute a Standalone Nexus Operation directly from a Nexus service client created on the Temporal Client using client.nexus.createServiceClient().

Standalone Nexus Operations use the same Nexus Service contract, Operation handlers, and Worker setup as Workflow-driven Operations — only the execution path differs. See the Nexus feature guide for details on defining a Service contract and developing Operation handlers and registering a Service in a Worker.

This page focuses on the client-side APIs that are unique to Standalone Nexus Operations:

note

This documentation uses source code from nexus-standalone-operations.

Execute a Standalone Nexus Operation​

To execute a Standalone Nexus Operation, first create a NexusServiceClient using client.nexus.createServiceClient(), bound to a specific Nexus Endpoint and Service. The endpoint must be pre-created on the server. Then call startOperation() or executeOperation() from application code (for example, a starter program), not from inside a Workflow Definition.

executeOperation waits for the Operation to complete and returns the result. Both methods require id. scheduleToCloseTimeout is optional and defaults to the maximum allowed by the Temporal server.

const nexusClient = client.nexus.createServiceClient({
  endpoint: ENDPOINT_NAME,
  service: myNexusService,
});

// Await the result of the operation immediately.
const echoResult = await nexusClient.executeOperation(
  myNexusService.operations.echo,
  { message: 'hello' },
  {
    id: `echo-${nanoid()}`,
    scheduleToCloseTimeout: '10s',
  },
);

See the full starter sample for a complete example that executes both synchronous and asynchronous Operations, gets their results, and lists and counts Operations.

Start a Standalone Nexus Operation and Wait for the Result​

startOperation returns a NexusOperationHandle. Use NexusOperationHandle.result() to wait until the Operation completes and retrieve its result. This works for both synchronous and asynchronous Operations.

// Start an operation and get a NexusOperationHandle
const handle = await nexusClient.startOperation(
  myNexusService.operations.hello,
  { name: 'World' },
  {
    id: `hello-${nanoid()}`,
    scheduleToCloseTimeout: '10s',
  },
);

// Await the result
const helloResult = await handle.result();
console.log(helloResult.greeting);

If the Operation completed successfully, the result is returned. If the Operation failed, the failure is thrown as an error.

List Standalone Nexus Operations​

Use client.nexus.list() to list Standalone Nexus Operation Executions that match a List Filter query. The result is an async iterator that yields operation metadata entries.

Note that client.nexus.list() is called on the base Client, not on the NexusServiceClient.

const query = `Endpoint = "${ENDPOINT_NAME}"`;
for await (const op of client.nexus.list({ query })) {
  console.log(
    `OperationId: ${op.operationId},`,
    `Operation: ${op.operation},`,
    `Status: ${op.status}`,
  );
}

The query parameter accepts List Filter syntax. For example, "Endpoint = 'my-endpoint' AND Status = 'Running'".

Count Standalone Nexus Operations​

Use client.nexus.count() to count Standalone Nexus Operation Executions that match a List Filter query.

Note that client.nexus.count() is called on the base Client, not on the Nexus service client.

const query = `Endpoint = "${ENDPOINT_NAME}"`;
const count = await client.nexus.count(query);
console.log(`Total Nexus operations: ${count.count}`);

Run Standalone Nexus Operations with Temporal Cloud​

The code samples referenced on this page use loadClientConnectConfig() from @temporalio/envconfig, so the same code works against Temporal Cloud — just configure the connection via environment variables or a TOML profile. No code changes are needed.

For full details on connecting to Temporal Cloud, including Namespace creation, Nexus Endpoint setup, certificate generation, and authentication options, see Make Nexus calls across Namespaces in Temporal Cloud and Connect to Temporal Cloud.