Backend

Connect a route to a server, over WebSocket or XHR and manage its data from there instead of purely on the client. WebSocket is the connection to reach for, XHR is the fallback for whenever WebSocket genuinely isn't possible. The wire contract is the same either way, this page covers it. See .NET Backend or Node.js Backend for an actual server implementing it.

Connecting

Set dataServerURL to your server's endpoint to open a connection. relativeDataServerURL marks that URL as relative rather than absolute. Leave dataServerURL unset to retrieve data some other way, with no built-in connection at all.

dataConnect on a route, covered on Routes, is a separate setting from the ones on this page: it only skips the automatic request a route fires on load. $bindary.dataSend()/dataSendAsync() work from that route regardless of its own dataConnect value.

useWebSocket (default true) prefers a WebSocket connection when the browser supports one. websocketSupport exposes that capability check, "WebSocket" in window, read-only. secure chooses wss/https over the insecure equivalents, defaulting to the current page's own protocol.

When WebSocket isn't available, set xhrUpdateInterval to control how often, in milliseconds, Bindary polls over XHR for anything waiting to be delivered. This is what lets a client without WebSocket still receive something pushed to it later, picked up on the next poll rather than arriving the instant it was sent.

Once connected, every client carries a clientId, sent with every request, so the server can tell one client's data apart from another's or push to a specific one directly.

Requesting data

Route loads send a request automatically. For anything else, call $bindary.dataSend() or its promise-based counterpart, $bindary.dataSendAsync(), directly:

const response = await $bindary.dataSendAsync(
    { text: 'hello' },              // the data payload
    'Namespace.ClassName.MethodName' // optional: a specific server method to invoke
);

Both use whichever connection is active, WebSocket if one's open, a fresh XHR request otherwise. Here's the shape of what gets sent:

{
    clientId, routeIndex, routePath,
    serverMethod,   // which server method to invoke, if any
    callbackId,     // matches the response back to this specific call
    initialLoad,    // true only for a route's first, automatic request
    data            // the custom payload
}

Unloading

Set dataServerUnload on a route to have Bindary send it to the server as that route unloads. Ordinary in-app navigation, one route replacing another, sends it as a completely normal request. Actual window teardown, a closing tab, uses $bindary.unload() instead: it tries the open WebSocket first, then navigator.sendBeacon, then a synchronous XHR call as a last resort.

sendBeacon is reliable during unload. The synchronous XHR fallback isn't always, modern browsers increasingly restrict synchronous XHR during page dismissal. This only matters on a browser old enough to lack sendBeacon support.

The response

A response carries clientId, callbackId, an isError flag and a data container holding whichever of appData, routeData, or viewData it's updating, each with an optional matching rules dictionary, appDataRules, routeDataRules, viewDataRules, keyed by property name. Bindary merges received data into the client's own data automatically, according to those rules.

Client-side, a rule covers: path (retarget where this specific property applies, rather than its own key), updateKey/removeByKeyValues (match array items by a field's value rather than by index), addIndex/ removeIndex/removeCount (position-based insertion and removal), update (merge onto existing data or overwrite it outright), recreate (rebuild the element rather than update it in place) and ignoreNullValues/omitKeys (skip specific fields when merging).

This is the client's view of the contract, what arrives and how it gets applied. It isn't the same shape as a specific backend's own rules class, .NET's DataRules, for instance, matches closely but adds a couple of fields of its own. Each backend page covers its own version, this is the wire format both sides agree on.

Choosing a backend

Everything above is backend-agnostic, the same contract regardless of what implements the other side. .NET Backend and Node.js Backend cover an actual server: the classes to inherit, how a client connects and gets identified server-side and how to send a response back.