Swim JavaScript Client

The Swim JavaScript client makes it easy to build web apps that connect seamlessly to ultra responsive, highly scalable Swim services running in the cloud.

To get started writing reactive Swim services, check out the SwimJS server runtime.

JavaScript Library

The Swim client library can run in any standard JavaScript environment. Use npm or bower to incorporate the library into your project.

bower install swim-cli-js --save

npm install swim-client-js --save

var swim = require('swim-client-js');

JavaScript API

Module

Swim

The exported library module is also global Client instance. Scripts can use the global swim client to keep simple things simple.

var swim = require('swim-client-js');
var users = swim.downlinkMap().node('ws://swim.example.com/chat/public').lane('chat/users').open();

new swim.Client([options])

Returns a Client object, which represents a dedicated connection pool.

• options.maxReconnectTimeout: maximum number of milliseconds to wait between reconnect attempts after exponential backoff. Defaults to 30 seconds.
• options.idleTimeout: number of milliseconds to wait before closing a connection with no active links. Defaults to 1 second.
• options.sendBufferSize: maximum number of commands to buffer while waiting for the network. Defaults to 1,024 messages.

var swim = require('swim-client-js');
var client = new swim.Client();

Client

client.downlink()

Returns a new EventDownlink prototype.

client.downlinkList()

Returns a new ListDownlink prototype.

client.downlinkMap()

Returns a new MapDownlink prototype.

client.downlinkValue()

Returns a new ValueDownlink prototype.

client.command([hostUri, ]nodeUri, laneUri, body)

Sends a command to a lane of a remote service. If provided, hostUri specifies the network endpoint of the service to command, otherwise nodeUri must itself contain a network authority component. nodeUri identifies the particular service instance to command. body is the command to send, and can be any JSON-compatible object; body is serialized as a RECON structure.

client.host(hostUri)

Returns a new HostScope object bound to the endpoint at the given hostUri.

client.node([hostUri, ]nodeUri)

Returns a new NodeScope object bound to the service at the given nodeUri. If provided, hostUri specifies the network endpoint to connect to, otherwise nodeUri must contain a network authority component.

client.lane([hostUri, ]nodeUri, laneUri)

Returns a new LaneScope object bound to the given laneUri of the service at the given nodeUri. If provided, hostUri specifies the network endpoint to connect to, otherwise nodeUri must contain a network authority component.

client.authenticate(hostUri, credentials)

Authenticates all connections to hostUri through client with the provided credentials object. credentials might contain, for example, a Google Sign-In ID token. Note that connections to public hosts may not require authorization.

client.isOnline()

Returns true if the client has an active internet connection.

client.keepOnline([keepOnline])

Watches for changes to network availability when true (default behavior).

client.close()

Unlinks all downlinks, and closes all network connections, associated with the client connection pool.

Client Callbacks

client.didAuthenticate([function (host)])

The didAuthenticate callback gets invoked when a network connection managed by the client is successfully authenticated by the remote host.

• host.hostUri: the URI of the authenticated host.

client.didDeauthenticate([function (host)])

The didDeauthenticate callback gets invoked when a network connection managed by the client is deauthorized by the remote host, or when the host rejects an authorization request.

• host.hostUri: the URI of the deauthorized host.

client.didConnect([function (host)])

The didConnect callback gets invoked when a network connection managed by the client is connected.

• host.hostUri: the URI of the host that connected.

client.didDisconnect([function (host)])

The didConnect callback gets invoked when a network connection managed by the client is disconnected.

• host.hostUri: the URI of the host that disconnected.

client.didFail([function (error, host)])

The didFail callback gets invoked when a network connection managed by the client encounters an error.

• host.hostUri: the URI of the host that disconnected.

Scope

A Scope object monitors the lifecycle of downlinks created through the scope.

• HostScope: manages a set of downlinks to a particular remote hostUri.
• NodeScope: manages a set of downlinks to a particular remote nodeUri.
• LaneScope: manages a set of downlinks to a particular laneUri of some remote nodeUri.

scope.isConnected()

Returns true if there is an active network connection to this scope's remote host.

scope.isAuthenticated()

Returns true if the network connection to this scope's remote host has been successfully authenticated.

scope.session()

Returns the authorization parameters provided by the remote host, if the client was explicitly authenticated by the host. Returns null if the connection is closed, or if the connection is open but not authenticated.

scope.close()

Unlinks all downlinks registered with the scope.

Scope Callbacks

scope.didConnect([function (host)])

The didConnect callback gets invoked when a network connection to the scope's remote host is connected.

• host.hostUri: the URI of the host that connected.

scope.didDisconnect([function (host)])

The didConnect callback gets invoked when a network connection to the scope's remote host is disconnected.

• host.hostUri: the URI of the host that disconnected.

scope.didFail([function (host)])

The didFail callback gets invoked when a network connection to the scope's remote host encounters an error.

• host.hostUri: the URI of the host that disconnected.

scope.didAuthenticate([function (host)])

The didAuthenticate callback gets invoked when a network connection to the scope's remote host is successfully authenticated by the host.

• host.hostUri: the URI of the authenticated host.

scope.didDeauthenticate([function (host)])

The didDeauthenticate callback gets invoked when a network connection to the scope's remote host is deauthorized by the host, or when the host rejects an authorization request.

• host.hostUri: the URI of the deauthorized host.

HostScope

HostScope extends the Scope interface.

host.host()

Returns the URI of the network endpoint to which the scope is bound.

host.authenticate(credentials)

Authenticates connections to the host to which this scope is bound using the provided credentials object.

host.downlink()

Returns a new EventDownlink prototype bound to this host.

host.downlinkList()

Returns a new ListDownlink prototype bound to this host.

host.downlinkMap()

Returns a new MapDownlink prototype bound to this host.

host.downlinkValue()

Returns a new ValueDownlink prototype bound to this host.

host.command(nodeUri, laneUri, body)

Sends a command to a lane of a node on the remote host to which this scope is bound.

host.node(nodeUri)

Returns a new NodeScope object bound to the given nodeUri on the remote hostUri to which this scope is bound.

host.lane(nodeUri, laneUri)

Returns a new LaneScope object bound to the given laneUri of the given nodeUri on the remote hostUri to which this scope is bound.

host.close()

Unlinks all downlinks registered with the scope.

NodeScope

NodeScope extends the Scope interface.

node.host()

Returns the URI of the remote host to which the scope is bound.

node.node()

Returns the URI of the remote node to which the scope is bound. Returns an absolute URI resolved against the hostUri.

node.downlink()

Returns a new EventDownlink prototype bound to this node.

node.downlinkList()

Returns a new ListDownlink prototype bound to this node.

node.downlinkMap()

Returns a new MapDownlink prototype bound to this node.

node.downlinkValue()

Returns a new ValueDownlink prototype bound to this node.

node.command(laneUri, body)

Sends a command to a lane of the remote node to which this scope is bound.

node.lane(laneUri)

Returns a new LaneScope object bound to the given laneUri of the nodeUri and the hostUri to which this scope is bound.

node.close()

Unlinks all downlinks registered with the scope.

LaneScope

LaneScope extends the Scope interface.

lane.host()

Returns the URI of the remote host to which the scope is bound.

lane.node()

Returns the URI of the remote node to which the scope is bound. Returns an absolute URI resolved against the hostUri.

lane.lane()

Returns the URI of the lane to which the scope is bound.

lane.downlink()

Returns a new EventDownlink bound to this lane.

lane.downlinkList()

Returns a new ListDownlink bound to this lane.

lane.downlinkMap()

Returns a new MapDownlink bound to this lane.

lane.downlinkValue()

Returns a new ValueDownlink bound to this lane.

lane.command(body)

Sends a command to the remote lane to which this scope is bound.

lane.close()

Unlinks all downlinks registered with the scope.

Downlink

downlink.host([hostUri])

Returns the URI of the host to which downlink connects.

downlink.node([nodeUri])

Returns the URI of the remote node to which downlink connects. Returns an absolute URI resolved against the hostUri.

downlink.lane([laneUri])

Returns the URI of the lane to which downlink connects.

downlink.prio([prio])

Returns the floating point priority level of the downlink.

downlink.rate([rate])

Returns the event throttle rate, in Hertz, of the downlink.

downlink.keepLinked([keepLinked])

Returns true if the link should be automatically re-established after connection failures. The keepLinked mode can be changed at any time by assigning a new value to this property.

downlink.keepSynced([keepSynced])

Returns true if the link should be synchronize its state with the remote lane.

downlink.isConnected()

Returns true if the link is currently connected.

downlink.isAuthenticated()

Returns true if the network connection carrying the link has been explicitly authenticated. Note that not all links require authorization.

downlink.session()

Returns the authorization parameters of the network connection carrying this link, if the link was explicitly authenticated by the remote host. Returns null if the link is disconnected, or if the link is connected but not authenticated.

downlink.command(body)

Sends a command to the remote lane to which this downlink is connected.

downlink.open()

Registers the downlink with the remote node so that it receives events.

downlink.close()

Unregisters the downlink so that it no longer receives events. If this was the only active link to a particular remote lane, the link will be unlinked.

Downlink Callbacks

downlink.onEvent([function (message, downlink)])

The onEvent callback gets invoked every time the downlink receives an event. message is the plain old JavaScript value of the event, decode from RECON.

downlink.willLink([function (downlink)])

The willLink callback gets invoked when the downlink is about to send a @link request to the remote host to establish a new link.

downlink.didLink([function (downlink)])

The didLink callback gets invoked when the downlink receives a @linked response from the remote host, indicating the link has been established.

downlink.willSync([function (downlink)])

The willSync callback gets invoked when the downlink is about to send a @sync request to the remote host to establish a new link and synchronize its state.

• request.nodeUri: the URI of the remote node to sync.
• request.laneUri: the URI of the lane to sync.
• request.prio: the requested priority of the link.
• request.body: an optional request body to send to the remote lane.

downlink.didSync([function (downlink)])

The didSync callback gets invoked when the downlink receives a @synced response from the remote host, indicating that the link has finished sending its initial state events.

downlink.willUnlink([function (downlink)])

The willUnlink callback gets invoked when the downlink is about to send an @unlink request to the remote host in order to teardown a previously established link. This happens when the client calls downlink.close() on the only active link to a particular remote lane.

downlink.didUnlink([function (downlink)])

The didUnlink callback gets invoked when the downlink receives an @unlinked response from the remote host. This indicates that the remote host has rejected the link. The link will now close, regardless of whether downlink.keepLinked is true or not.

downlink.didConnect([function (downlink)])

The didConnect callback gets invoked when the network connection that carries the link is connected.

downlink.didDisconnect([function (downlink)])

The didDisconnect callback gets invoked when the network connection that carries the link is disconnected.

downlink.didFail([function (error, downlink)])

The didFail callback gets invoked when the network connection that carries the link encounters an error. Unfortunately, the underlying network APIs don't provide any detail on network errors. Errors always cause the underlying network connection to close; keepLinked links will automatically reconnect after network errors.

downlink.didClose([function (downlink)])

The didClose callback gets invoked when the downlink has been disconnected and will not be reconnected. This happens when the client calls downlink.close(), or when the link is explicityly @unlinked by the remote host, or when the network connection that carries a non-keepLinked link gets disconnected.

EventDownlink

ValueDownlink

valueDownlink.get()

valueDownlink.set(value)

ValueDownlink Callbacks

valueDownlink.willSet([function (newValue, oldValue)])

valueDownlink.didSet([function (newValue, oldValue, downlink)])

MapDownlink

A MapDownlink synchronizes its state with a remote MapLane. A MapDownlink supports the full functionality of an ordinary Downlink. It also implements the behavior of a JavaScript key-value Map. All map operations are transparently synchronized with the remote lane. And all operations on the remote lane are transparently syncrhonized with the MapDownlink object. MapDownlink seamlessly supports complex key objects.

Note that the complete state of the map is not guaranteed to be available until the didSync callback has been invoked. And the downlinked map state may desync when the link's underlying network connection drops.

mapDownlink.size

Returns the number of entries in the downlinked map state.

mapDownlink.has(key)

Returns true if the downlinked map state contains a given key.

mapDownlink.get(key)

Returns the value associated with a given key in the downlinked map state.

mapDownlink.set(key, value)

Associates a value with a given key in the downlinked map state. Pushes the change to the remote lane. Returns this.

mapDownlink.delete(key)

Removes an entry with key from the downlinked map state, pushing any change to the remote map lane. Returns true if an entry was removed, otherwise returns false.

mapDownlink.clear()

Removes all entries from the downlinked map state, as well as the remote map lane. Returns this.

mapDownlink.keys()

Returns an array of all keys in the downlinked map state.

mapDownlink.values()

Returns an array of all values in the downlinked map state.

mapDownlink.forEach(callback[, thisArg])

Invokes callback for every value in the downlinked map state. If provided, thisArg will be passed to each invocation of callback for use as its this value.

callback is invoked with three arguments:

• the map value
• the map key
• the mapDownlink being traversed

mapDownlink.state

Returns the internal downlinked map state as a record.

MapDownlink Callbacks

mapDownlink.willUpdate([function (key, newValue, downlink)])

mapDownlink.didUpdate([function (key, newValue, oldValue, downlink)])

mapDownlink.willRemove([function (key, downlink)])

mapDownlink.didRemove([function (key, oldValue, downlink)])

mapDownlink.willClear([function (downlink)])

mapDownlink.didClear([function (downlink)])

ListDownlink

A ListDownlink synchronizes its state with a remote ordered ListLane. A ListDownlink supports the full functionality of an ordinary Downlink. It also implements array-like methods. All list operations are transparently synchronized with the remote lane. And all operations on the remote lane are transparently synchronized with the ListDownlink object.

Note that the complete state of the list is not gauranteed to be available until the didSync callback has been invoked. And the downlinked list state may desync when the link's underlying network connection drops.

listDownlink.length

Returns the number of values in the downlinked list state.

listDownlink.get(index)

Returns the value at index in the downlinked list state.

listDownlink.set(index, value)

Sets value at index of the downlinked list state, and pushes the change to the remote lane.

listDownlink.push(value1, ..., valueN)

Appends one or more values to the end of the downlinked list state, and pushes the changes to the remote lane. Returns the new length of the list.

listDownlink.pop()

Removes and returns the last value of the downlinked list state, pushing any change to the remote lane. Returns undefined if the list is empty.

listDownlink.unshift(value1, ..., valueN)

Prepends one or more values to the beginning of the downlinked list state, and pushes the changes to the remote lane. Returns the new length of the list.

listDownlink.shift()

Removes and returns the first value of the downlinked list state, pushing any change to the remote lane. Returns undefined if the list is empty.

listDownlink.move(fromIndex, toIndex)

Moves that value at index fromIndex to index toIndex, pushing the change to the remote lane.

listDownlink.splice(startIndex, deleteCount[, value1, ..., valueN])

Removes deleteCount elements from the downlinked list state, starting at index start, and inserts zero or more new values at startIndex. Pushes all changes to the remote lane.

listDownlink.clear()

Removes all values from the downlinked list state, as well as the remote list lane. Returns this.

listDownlink.forEach(callback[, thisArg])

Invokes callback for every value in the downlinked list state. If provided, thisArg will be passed to each invocation of callback for use as its this value.

callback is invoked with three arguments:

• the current list value
• the index of the current list value
• the listDownlink being traversed

listDownlink.state

Returns the internal downlinked list state as an array.

ListDownlink Callbacks

listDownlink.willInsert([function (index, newValue, downlink)])

listDownlink.didInsert([function (index, newValue, downlink)])

listDownlink.willUpdate([function (index, newValue, downlink)])

listDownlink.didUpdate([function (index, newValue, oldValue, downlink)])

listDownlink.willMove([function (fromIndex, toIndex, value, downlink)])

listDownlink.didMove([function (fromIndex, toIndex, value, downlink)])

listDownlink.willRemove([function (index, downlink)])

listDownlink.didRemove([function (index, oldValue, downlink)])

listDownlink.willClear([function (downlink)])

listDownlink.didClear([function (downlink)])