Subscriptions

Subscriptions control which paths a client materializes and receives during sync. They are a visibility/bandwidth mechanism, not an authority mechanism.

Why subscriptions exist

Large rooms often contain more state than one client view needs. Subscriptions help by:

Reducing client-side materialization scope
Reducing relayed traffic for non-matching paths
Keeping UI selectors focused on relevant data

Initial subscription

Set subscription patterns at document creation:

const doc = await createDoc({
  serverUrl,
  room,
  subscribe: ["world/**", "notes/welcome"]
});

Default is broad (["**"]) when no subscription is provided.

Runtime subscription updates

Update patterns dynamically:

doc.subscribe(["world/**"]);
doc.onSubscriptionChange(({ patterns }) => {
  rerender(patterns);
});

Use runtime updates for route/view changes in single-page apps.

Path checks

Use helper checks before expensive reads:

doc.isSubscribed("world/player1"); // true/false

This is useful for conditional data access and UI guardrails.

Glob semantics (practical)

Typical pattern behavior:

** matches everything
foo/** matches foo and descendants
* matches one path segment

Keep patterns simple and intentional; over-broad patterns defeat subscription benefits.

What subscriptions affect

Subscriptions affect client materialization and relay filtering behavior. They do not replace write authority enforcement. Authority remains governed by policy/capability rules.

Design pattern: route-scoped subscriptions

In UI apps:

Map each route/view to a small set of patterns
Apply doc.subscribe(...) on route activation
Expand only when user workflows demand wider context

This keeps bandwidth and memory pressure predictable.

Debugging subscription issues

If expected updates are missing:

Confirm path actually matches active patterns
Check runtime subscription updates are applied
Verify view code is not reading outside subscribed scope
Confirm issue is visibility-scope related, not authority rejection

Common mistakes

Treating subscription as access control
Leaving stale narrow patterns active after navigation
Using complex overlapping patterns without tests
Assuming doc.onChange always implies subscribed materialized changes

Runtime SDK event subscriptions

The runtime SDK (createNodalMergeSdk) uses a separate event subscription model via sdk.on(event, handler). These are process-level lifecycle and protocol events, not path-pattern subscriptions.

const stop = sdk.on("connected", () => {
  console.log("room connected");
});

// Unsubscribe by calling the returned function
stop();

`NodalMergeSdkEvent` reference

Event	Payload	When it fires
`"connected"`	none	WebSocket session opened and `welcome` received
`"disconnected"`	none	WebSocket connection closed (clean or error)
`"reconnect"`	`{ attempt: number }`	Reconnect attempt starting (with backoff)
`"state"`	`{ state: "connecting" \| "connected" \| "disconnected" }`	Any connection state transition
`"message"`	raw WebSocket message string	Every inbound WebSocket frame (low-level)
`"error"`	`{ msg: string }`	Server-sent `error` envelope received
`"presence"`	presence envelope object	Presence update received from server
`"signal"`	WebRTC signal envelope	`webrtc-offer`, `webrtc-answer`, or `webrtc-ice` received
`"runtime-message"`	`NodalMergeRuntimeMessage`	Any parsed server message that passes `parseRuntimeMessage`
`"transport"`	`{ active: "ws-only" \| "ws+webrtc" }`	Active transport layer changes

Common patterns

Connection lifecycle:

sdk.on("state", ({ state }) => {
  setConnectionState(state); // "connecting" | "connected" | "disconnected"
});

Error and rejection handling:

sdk.on("error", ({ msg }) => {
  console.error("server error:", msg);
  // msg may be "reject.control_plane_forbidden: ...", "auth: ...", etc.
});

Observing all runtime messages:

sdk.on("runtime-message", (msg) => {
  // msg.type is a NodalMergeRuntimeMessageType, e.g.:
  // "projection.build.completed", "replay.read-range.result", "pack", etc.
  if (msg.type === "projection.build.completed") {
    handleProjectionReady(msg);
  }
});

Presence updates:

sdk.on("presence", (envelope) => {
  updateCursorLayer(envelope);
});

WebRTC signaling:

sdk.on("signal", (signal) => {
  if (signal.type === "webrtc-offer") {
    handleOffer(signal.from, signal.sdp);
  }
});

NodalMergeRuntimeMessage.type values are exhaustively typed in NodalMergeRuntimeMessageType. Use a switch or type-narrowed handler rather than string comparison against arbitrary values.

​Subscriptions

​Why subscriptions exist

​Initial subscription

​Runtime subscription updates

​Path checks

​Glob semantics (practical)

​What subscriptions affect

​Design pattern: route-scoped subscriptions

​Debugging subscription issues

​Common mistakes

​Runtime SDK event subscriptions

​NodalMergeSdkEvent reference

​Common patterns

​Related pages