nexus
Core guides

Remote Calls

Get a service, invoke methods, read properties, and understand when a remote call runs.

After connecting, get a service using its shared Token:

import { DocumentToken } from "./shared";

const documents = connection.get(DocumentToken);
const summary = await documents.summarize("intro");

Getting A Service

get synchronously checks that the session is connected and its current catalog contains the Token. It returns a lightweight proxy. It neither contacts another peer nor waits for a future service publication.

Use safeGet to receive the acquisition failure as a Result. A successful get describes availability at that moment; a later call can still fail or disconnect. See Errors and timeouts.

Methods And Properties

Remote methods return awaitable call results. Reading a property also produces a remote read when consumed. For a contract with a title property:

const title = await document.title;
await document.setTitle("New title");

Use methods for writes. Remote property assignment is unsupported.

Ordinary supported values are serialized; they are not shared mutable memory. Use callbacks for functions and remote resources for objects that should stay in their owning context. Supported by-value data depends on the transport’s serializer; do not assume arbitrary class instances preserve their behavior.

Binary values

Ordinary RPC arguments and results can include ArrayBuffer, Uint8Array, Node.js Buffer, and Blob, including when nested in supported containers. ArrayBuffer stays an ArrayBuffer; Uint8Array and Node Buffer arrive as a Uint8Array containing only the view’s visible bytes. A Blob arrives as a Blob with its content and MIME type. A File is transferred with Blob content semantics only; pass its name and other file metadata as separate fields.

Nexus snapshots bytes for transport and does not detach the caller’s buffer. This does not preserve object identity or shared memory and is not a zero-copy or ownership-transfer API. No per-call binary or chunk option is needed.

Large encoded messages are split into bounded frames transparently on each connection hop and reassembled before normal RPC handling. Defaults are a 64 KiB frame limit, a 16 MiB message limit, and a 64 MiB aggregate framework-buffer budget per endpoint runtime. JSON/Base64 encoding can make a message reach its limit sooner than binary encoding. The 16 MiB message ceiling is fixed; an endpoint can lower that limit but cannot raise it. Unsupported values, size limits, exhausted capacity, and transfer deadlines reject the normal call with structured errors; inspect them through await or Nexus.safeCall(...). Delivery can be uncertain if the final frame was submitted but its acknowledgment or RPC response was not received. Nexus does not retry or replay the call, so do not infer that the remote method did not run.

Calls Start When Consumed

const call = documents.summarize("intro"); // No message sent yet.

const first = await call; // Starts the operation.
const again = await call; // Observes the same result.

Calling the method again creates a new operation. The same result shares its first success or failure across all observations.

await, then, catch, finally, Promise.resolve, and native Promise helpers consume a call. Ignoring it, writing void call, or merely reading its then property does not start it.

To start work without awaiting it in the current function, consume it and handle rejection:

void documents.summarize("intro").catch(console.error);

Arguments retain their references until the first consumption encodes them. Copy mutable input yourself if you need a snapshot at declaration time.

Compose With JavaScript

const summaries = await Promise.all([
  documents.summarize("intro"),
  documents.summarize("guide"),
]);

Calls execute independently. race and any do not cancel the remaining calls or roll back effects. A call result’s connection identifies its source; then, catch, and finally return native Promises without that source field.

Session And Call Budget

The proxy stays bound to the connection from which it was obtained. After disconnect, reconnect and get a new proxy. An existing proxy does not switch to the replacement session.

Override the call budget on an acquired handle when needed:

const documents = connection.get(DocumentToken, { callTimeout: 30_000 });

The default is 5 seconds from first consumption. Returned refs inherit this handle’s budget. See Errors and timeouts for runtime defaults.

Proxy member-name constraints are listed in the resource API reference.

Next: Passing callbacks.

Edit this page on GitHub