nexus

What Is Nexus?

One communication model for services, callbacks, and resources across changing JavaScript contexts.

Nexus gives multi-context JavaScript applications one model for service calls, callbacks, remote objects, and the connections they depend on.

Why Nexus

Imagine a browser extension that summarizes a page in its side panel. A content script reads the document; the panel displays the result. These contexts cannot directly share functions or objects, so they communicate through messages.

The side panel communicates with a content script in the selected tab and frame.

When Messages Split A Feature

One request is straightforward: tabs.sendMessage can address that content script and return its response. An RPC library can express the exchange as await documents.summarize(documentId).

Keeping the panel updated is a different problem. Updates must reach the right view, the observation must be stopped when it is no longer needed, and a page reload must end the old work. With raw messages, one feature grows into event handlers, subscription IDs, and cleanup logic on both sides.

Nexus keeps that relationship in functions and objects, with a session that defines how long they can communicate.

Here documents is the remote service and panel is local UI. The callback updates this panel; the returned object controls this observation:

const observation = await documents.watch(documentId, (change) => {
  panel.apply(change);
});

// Later, when this panel no longer needs updates:
await observation.stop();

The callback stays in the side panel, along with the panel it captures. The service can call it remotely and await its result. No separate event handler needs to look up which view should receive the update.

The returned ref points to an observation object in the content script. observation.stop() calls that object’s method. Nexus handles object IDs and message routing underneath; the application works with the object itself.

Calls travel both ways. The callback and observation object stay in their original contexts.

A cursor, editor session, or task handle can use the same pattern. The provider returns the object through ref(...). Stopping its business activity and releasing the remote reference are separate actions; see the resource guide for the complete cleanup pattern.

When The Peer Disappears

Extension contexts have independent lifetimes: popups close, frames unload, tabs navigate, and the background can restart. A working call or remote object can lose its peer at any moment.

Suppose our panel has an active observation and a summary request in flight when the page reloads. The panel survives, but the content script is replaced. The tab and frame IDs may stay the same, but the old observation and pending request do not belong to the replacement document.

The peer disappears without replying. Nexus rejects pending work; later calls through old refs fail locally.

The connection is a cleanup boundary for calls and references. Once Nexus observes the disconnect, the pending summary rejects with E_CONN_CLOSED without waiting for its timeout. Calls through the old service proxy or observation ref also fail instead of reaching the new page.

Explicitly disconnecting demonstrates the same effect. Here the summary is still pending and the observation has not been stopped or released:

// Start the call; observe its outcome as a Result.
const pending = Nexus.safeCall(documents.summarize(documentId));
connection.disconnect();

const summary = await pending;
if (summary.isErr()) console.log(summary.error.code); // E_CONN_CLOSED

// The old ref cannot be used after disconnect.
const stopped = await Nexus.safeCall(observation.stop());
console.log(stopped.isErr()); // true

With an ordinary await instead of safeCall, these failures throw. A peer unloading triggers the same session cleanup once its disconnection is observed.

Nexus removes the session’s pending-call records and releases its holds on callback and object references. Each feature no longer needs a separate disconnect loop over these records. This does not invoke business stop() methods or destroy objects still held elsewhere.

The application can reconnect and create a fresh observation. The old handles stay invalid: the same address does not mean the same session.

One Model Across Contexts

Chrome ports, iframe messaging, and process IPC have different APIs. Without a common layer, each integration can grow its own way to identify services, invoke callbacks, and clean up remote handles.

The business-facing structure stays the same across Nexus adapters:

const connection = await app.connect({ target });
const documents = connection.get(DocumentToken);
const observation = await documents.watch(documentId, onChange);

The application chooses target using the adapter’s target type. DocumentToken identifies the shared service contract. Calls, callbacks, and refs follow the same lifecycle rules on each adapter.

Choose the platform adapter; keep the same service and session model.

One way to address a peer, use its capabilities, and handle its disappearance. Platform setup and target discovery still vary, but each integration does not need its own RPC and resource protocol. That shared mental model is what lets a plugin-style application grow without every feature inventing new communication rules. Core concepts →

Alternatives

Already have a stable channel and a clear owner for its lifetime? Comlink’s object proxies or comctx’s Provider/Injector services may cover what you need.

Have multiple peers that come and go, with calls and resources spanning their lifetimes? Nexus combines connection management, callbacks, and remote objects in one model across adapters. The distinction is who manages these relationships, not whether the libraries can send messages through a complex topology.

Yes = built in. Custom = requires a custom transfer handler/protocol. — = no built-in API for this capability.

CapabilityNexusComlinkcomctx
Typed remote callsYesYesYes
Remote callbacksYesYes¹Yes
Callbacks over data-only transports (no port transfer)YesCustom¹Yes⁴
Await a remote callback’s resultYesYes—⁴
Explicit callback-reference releaseYesYes—⁴
Return objects by referenceYesYes¹—
Explicit remote-reference releaseYesYes—
Explicit connection/session APIYes——
Acquire and reuse a session by targetYes——
Filter sessions by peer metadataYes——
Acquire a fixed snapshot of multiple sessionsYes——
Fail pending calls and clear refs on session disconnectYes²——
Configurable per-call timeoutYes——³

Comlink wraps a supplied endpoint; comctx uses a supplied messaging adapter. Neither exposes a Connection/session-management layer. Transport lifecycle, message namespaces, and individual proxy release are not equivalent to managing all calls and references as one peer session.

  1. Comlink references use its built-in proxy transfer handler, which creates a MessageChannel and transfers a MessagePort. Native window.postMessage supports that transfer; Chrome extension runtime.sendMessage does not. Ordinary Comlink RPC accepts custom endpoints, but callbacks on a data-only transport need a custom reference protocol/handler. Nexus callbacks and object refs use the existing session without transferring a port.
  2. Nexus cleanup fails pending calls and clears session communication resources. It does not stop application-owned tasks, undo effects, or automatically reconnect.
  3. comctx heartbeat checks provider readiness; it is not a general RPC timeout.
  4. comctx callbacks encode top-level function arguments as IDs and invoke them through ordinary adapter messages. They are one-way notifications: callback return values and exceptions are not sent back to the provider. Version 1.7.5 has no per-callback release API; callback listeners remain registered until the adapter is cleaned up. Nexus callbacks use request/response calls and support explicit reference release.

Next Steps

These guides describe the Core 2.0 alpha contract under development. For an existing application, use the migration guide.

Edit this page on GitHub