Nexus TypeScript SDK

This SDK is currently at an experimental release stage. Backwards-incompatible changes are anticipated until a stable release is announced.

TypeScript SDK for working with Nexus RPC. See API documentation.

What is Nexus?

Nexus is a synchronous RPC protocol. Arbitrary duration operations are modeled on top of a set of pre-defined synchronous RPCs.

A Nexus caller calls a handler. The handler may respond inline (synchronous response) or return a token referencing the ongoing operation (asynchronous response). The caller can cancel an asynchronous operation, check for its outcome, or fetch its current state. The caller can also specify a callback URL, which the handler uses to deliver the result of an asynchronous operation when it is ready.

This SDK provides the core primitives for defining and implementing Nexus services in TypeScript.

Protocol Implementations

• Temporal — builds on this SDK to provide a full implementation of the Nexus protocol, backed by Durable Execution.

Installation

npm install nexus-rpc

Usage

Define a Service

Use the service and operation helpers to define a typed service contract. Operations are generic in their input and output types.

import { service, operation } from "nexus-rpc";

interface MyInput {
  name: string;
}

interface MyOutput {
  greeting: string;
}

const myService = service("my-service", {
  sayHello: operation<MyInput, MyOutput>(),
});

Implement a Sync Operation

A sync operation handler is a function that receives a context and an input, and returns the output directly.

import { serviceHandler } from "nexus-rpc";

const handler = serviceHandler(myService, {
  async sayHello(ctx, input) {
    return { greeting: `Hello, ${input.name}!` };
  },
});

Implement an Async Operation

For operations that may take an arbitrary amount of time, return a HandlerStartOperationResult.async with a token that can be used to track, cancel, or deliver the result of the operation later.

import { HandlerStartOperationResult, serviceHandler } from "nexus-rpc";

const handler = serviceHandler(myService, {
  sayHello: {
    async start(ctx, input) {
      const token = await startBackgroundWork(input);
      return HandlerStartOperationResult.async(token);
    },
    async cancel(ctx, token) {
      await cancelBackgroundWork(token);
    },
  },
});

Resolve an Operation as Failed

Throw an OperationError from a start handler to indicate that the operation completed unsuccessfully.

import { OperationError } from "nexus-rpc";

// Failed operation
throw new OperationError("failed", "Not enough inventory");

// Canceled operation
throw new OperationError("canceled", "User canceled the operation");

Fail a Handler Request

Throw a HandlerError to fail a request with a specific error type. Returning an unrecognized error from any handler method will result in a generic internal server error response.

import { HandlerError } from "nexus-rpc";

// Bad request
throw new HandlerError("BAD_REQUEST", "Invalid input");

// Retryable internal error
throw new HandlerError("INTERNAL", "Database unavailable", {
  retryableOverride: true,
});

Contributing

Prerequisites

• Node.js >= 20

Build

pnpm install --frozen-lockfile
pnpm run build

Test

pnpm test

Lint

pnpm run lint

Format

pnpm run format