nexus
Migrations

Core 2.0 Alpha Migration

Migrate service acquisition and targeting to the connection-resource API.

Core 2.0 alpha makes connections explicit. The old service-acquisition APIs are removed rather than retained as compatibility aliases. This page describes the migration from Core 1.2 to the current alpha line. Check the release notes for the exact alpha version you install; new changes may appear here before release.

Removed entries are create, safeCreate, select, safeSelect, createMulticast, safeCreateMulticast, selectMulticast, and safeSelectMulticast.

The associated CreateOptions, SelectOptions, multicast option types, RuntimeCreateTokenParam, and default-target option types are removed too. Use ConnectOptions, ConnectMulticastOptions, and per-handle ResourceOptions. State also uses ConnectOptions directly; ConnectNexusStoreOptions is removed. Mock call records retain their object shape without standalone MockNexus*Call exports. Derive record types from MockNexus["calls"] when an annotation is needed. The obsolete NexusTargetingError and provider-wait/default-target error codes are removed; connection acquisition now reports its concrete connection errors.

Ordinary proxy lifecycle APIs are removed too: Nexus.getProxyStatus, Nexus.subscribeProxyStatus, Nexus.inspectProxy, ProxyStatus, ProxyDebugSnapshot, and React’s useProxyStatus. Keep the Connection returned by connect and observe it with onDisconnected or subscribeIdentity. useStoreStatus remains the React lifecycle observer for Nexus State handles.

State Validation

State validation.state and validation.actionResults now accept synchronous Standard Schema validators. Existing Zod 4 validators remain supported; Valibot and Zod Mini validators use the same entry point. Nexus no longer requires Zod as a production dependency, so applications using Zod should declare their own dependency.

Validation preserves the original snapshot and action result. Do not depend on schema defaults, coercions, or transforms to normalize shared values. Async validators are not supported. See State validation schemas.

Internal protocol validation now uses Valibot and rejects malformed message fields before dispatch. Existing valid wire formats and legacy invocation packet layouts remain supported.

Replace Service Acquisition

Replace a one-step service acquisition:

const service = await nexus.create(SettingsToken, { target });

with an explicit connection followed by a synchronous catalog lookup:

const connection = await nexus.connect({ target });
const service = connection.get(SettingsToken);

The safe form separates the two failure boundaries:

const connected = await nexus.safeConnect({ target });
if (connected.isErr()) {
  report(connected.error);
} else {
  const service = connected.value.safeGet(SettingsToken);
  if (service.isErr()) report(service.error);
  else await service.value.read();
}

get and safeGet do not dial, wait for a provider, or create a remote business object. They check the provider catalog of the already-ready connection.

The existing Asyncified<T> type remains the type-level mapping for lazy remote service values. RemoteValue<T, M> remains a structural thenable with connection provenance; neither type adds cancellation or connection ownership.

Passive Connection Acquisition

connect({ where, timeout, signal }) without a target waits for exactly one existing matching ready connection. It never discovers a provider and never derives a target from a Token, TokenSpace, endpoint, or adapter default. Multiple matches are ambiguous; a timeout or abort ends only this caller’s wait.

where(contextMeta, connectionMeta) is an acquisition constraint. It is not re-evaluated for every RPC and cannot replace authorization policy:

  • policy.canConnect authorizes logical connection establishment.
  • where chooses an acquired connection that matches application constraints.
  • policy.canCall authorizes each service or resource operation.

If a peer publishes a service after the initial session, publish the provider before changing the peer’s application readiness marker. The peer that waits for that marker can then pass it in where; it should still use get or safeGet to check the actual catalog.

Replace Multicast APIs

Use connectMulticast for a fixed connection snapshot:

const collection = await nexus.connectMulticast({
  targets,
  where: matchesWorker,
});

const resources = collection.get(TaskToken);
const results = await Promise.all(
  resources.map(async ({ connection, result }) => ({
    connection,
    result: result.isErr()
      ? result
      : await Nexus.safeCall(result.value.run(input)),
  })),
);

With explicit targets, every target must be acquired. Without targets, the operation snapshots current matching ready connections and may return an empty collection. The collection never changes membership. Each get item retains its source connection and its own acquisition Result; failed members are not silently filtered.

The removed createMulticast, safeCreateMulticast, selectMulticast, and safeSelectMulticast APIs have no direct compatibility replacement. Use (await nexus.connectMulticast(...)).get(Token) and ordinary Promise helpers.

Remove Default Targets And Provider Wait

Remove defaultTarget from:

  • Token and TokenSpace definitions
  • endpoint configuration and decorators
  • adapter helper options
  • State tokens and State connection options

Pass exact adapter targets to connect or connectMulticast. Use an endpoint’s explicit connectTo startup list only when the application wants one-shot startup dialing independent of service acquisition. It does not wait for a provider and does not make ready() wait for the dial.

There is no replacement for provider-level wait configuration. To wait for a connection, use passive connect with a positive timeout and optional signal. To wait for a late service, publish it before the peer’s ready marker, then acquire the connection and call get.

State Options

connectNexusStore and safeConnectNexusStore remain available. Their options follow ConnectOptions: use an exact target, an acquisition where, a positive timeout, and an optional signal. They do not accept Token or endpoint default targets, provider wait settings, or a separate State targeting model. State action calls retain their own Core resource-call timeout behavior. State still observes its selected peer’s identity after acquisition: if its where predicate stops matching, that State handle becomes stale. This is State lifecycle behavior, not a predicate retained by the shared Connection or an authorization check applied to ordinary service calls.

Resource And Call Rules

RemoteValue<T, M> is a structural thenable type with a read-only connection provenance field. Declaring a method call or reading a remote property is lazy; consumption starts the operation. Use Nexus.safeCall for one call when a Result is required. Use business methods instead of remote property assignment.

The migration does not remove the existing Asyncified<T> type mapping, instance release/safeRelease methods, or top-level Expose/Endpoint decorator shorthand. These APIs remain available; the removal is limited to the old acquisition families, default-target configuration, and provider wait configuration described above.

Connections, service proxies, refs, callbacks, and State handles are session-bound. After disconnect, reload, restart, or session replacement, connect again and get fresh handles. release and safeRelease remain the explicit release operations for remote references; they do not close shared connections or invoke application cleanup.

Bootstrap declarations

Register @nexus.Expose and @nexus.Endpoint classes before bootstrap begins. Late decorator application now fails explicitly; use provide(...) for live service registration after ready(). Duplicate provider IDs within a submission, or between the final configured providers and decorated classes, fail before service factories run. Separate configuration layers retain last-wins behavior. Factories receive the effective endpoint metadata, including decorator-defined metadata. safeReady() returns the same startup failure across subsequent calls; it does not retry initialization.

Edit this page on GitHub