Remote Resources
Return objects that stay in their owning context and explicitly manage their remote references.
A remote resource is an object that stays in its owning context while another context calls its methods. Use it for a subscription, document session, cursor, or other operation with continuing state.
Describe The Returned Object
Extend the document contract with an observation that returns a subscription. Keep these definitions in the shared module alongside the existing Token:
import type { RefWrapper } from "@nexus-js/core";
export interface DocumentChange {
title: string;
}
export type ChangeListener = (
change: DocumentChange,
) => void | PromiseLike<void>;
export interface DocumentSubscription {
stop(): void;
}
// Add to the existing DocumentService interface:
export interface DocumentService {
watch(
documentId: string,
onChange: ChangeListener,
): RefWrapper<DocumentSubscription>;
}The explicit RefWrapper result tells the remote type mapping that this object
is a reference, rather than a copied data value.
Return A Reference
The following watch method belongs to your provided document service. app is
its configured owner. The application-owned documentEvents.subscribe returns a
synchronous unsubscribe function; reportFailure records delivery failures.
import { Nexus } from "@nexus-js/core";
import type { DocumentService } from "./shared";
const watch: DocumentService["watch"] = (documentId, onChange) => {
const unsubscribe = documentEvents.subscribe(documentId, (change) => {
void Promise.resolve(onChange(change)).catch(reportFailure);
});
let stopped = false;
return app.ref({
stop() {
if (stopped) return;
stopped = true;
unsubscribe();
Nexus.release(onChange);
},
});
};Add watch to the provided service object. The returned object captures this observation’s
unsubscribe function and callback. It stays in the provider context. app.ref
marks the object for reference transfer when the response is encoded.
This is an application method excerpt, not a complete event-source implementation. A production event source also needs an application-owned shutdown path for abandoned observations and delivery failures; releasing a communication reference does not automatically unsubscribe a local event listener.
Use And Release The Subscription
import { Nexus } from "@nexus-js/core";
const subscription = await documents.watch("intro", (change) => {
panel.apply(change);
});
try {
await waitUntilPanelCloses();
} finally {
try {
await subscription.stop();
} finally {
Nexus.release(subscription);
}
}panel and waitUntilPanelCloses belong to the application. Remote methods are
awaitable even when the provider implements them synchronously.
Two different lifetimes are explicit here:
stop()ends the business observation and releases its received callback.Nexus.release(subscription)gives up the consumer’s remote reference.
Releasing a reference does not invoke stop, unsubscribe, or another business
method. Other local or remote references may keep the object alive; release does
not promise immediate garbage collection.
Scope-Based Release
With TypeScript explicit resource management enabled, refs returned through a
RefWrapper contract support using:
{
using subscription = await documents.watch("intro", onChange);
try {
await waitUntilPanelCloses();
} finally {
await subscription.stop();
}
} // Releases the reference, without another business stop call.Scope exit performs the same local, idempotent release as Nexus.release. It does
not wait for a remote business acknowledgement.
Disconnects And Ownership
Refs and callbacks are session-bound. Disconnect invalidates them and fails pending calls, but does not reverse business side effects or detach application listeners. Coordinate business cleanup with your application’s ownership model.
Ordinary root service proxies are lightweight access descriptions and do not require release. Release only remote refs and callbacks actually held by your code. See Connection lifecycle and the resource reference.