condux-client

0.4.4 • Public • Published

Condux Client

A client-side companion to condux, an over-the-wire unidirectional data-flow architecture utilizing Reflux as the flux pattern implementation and SockJS as the websocket implementation.

Tap into readonly streams of data (Frequencies) broadcast by the Condux server, or call actions that can be listened to by datastores on the server. Create actions Reflux-like actions with <ConduxClient>.createAction and <ConduxClient>.createActions to interact with your server stores.

All actions are transmitted to the Condux server via a main CLIENT_ACTIONS channel, ensuring the Condux server dispatch can perform its delegation in a reactive, unidirectional pattern.

Installation

npm install condux-client --save

API

ConduxClient

Kind: global class

new ConduxClient(url, persistence)

create a Condux Client instance

Param Type Default Description
url string a url of your server to pass into SockJS. Ensure the prefix http://yoururl.com:port{/prefix} is /reflux-nexus to connect to the reflux-nexus instance on your node server, or change the prefix on your server accordingly
persistence object
[persistence.enabled] boolean true should automatically try to reconnect on websocket "close" event
[persistence.attempts] number 10 how many times should attempt to reconnect after losing connection. This happens inside .reconnect, which can be called independently of the websocket "close" event if necessary
[persistence.interval] number | function 3000 how long to wait between reconnection attempts, in milliseconds. If passed a function, the function will be called with the number of reconnection attempts aleady made, and should return a number in milliseconds
[persistence.onConnecting] function noop called when begins a reconnection attempt
[persistence.onConnection] function noop called when establishes a connection to
[persistence.onDisconnect] function noop called when disconnects with a close event from websocket
[persistence.onReconnect] function noop called when re-establishes a connection to after being dropped
[persistence.onTimeout] function noop called when reconnection attempts are exhausted

conduxClient.persistence ⇒ object

Kind: instance property of ConduxClient
Returns: object - current persistence options
Read only: true
Since: 0.4.2

conduxClient.connecting ⇒ boolean

is the in the process of connecting

Kind: instance property of ConduxClient
Read only: true
Since: 0.3.1

conduxClient.connected ⇒ boolean

is the currently connected to the Server

Kind: instance property of ConduxClient
Read only: true
Since: 0.3.1

conduxClient.updatePersistence() ⇒ object

Update the current persistence options. If <ConduxClient> is connecting and the onConnecting hook was updated, it will immediately call the new onConnecting function

Kind: instance method of ConduxClient
Returns: object - updated persistence options
Since: 0.4.2

conduxClient.connect()

Set up frequency multiplexing and persistent connection (if enabled)

Kind: instance method of ConduxClient

conduxClient.reconnect()

Set up frequency multiplexing after a disconnection with existing frequencies. Will attempt the reconnection with options passed to ConduxClient constructor as persistence options attempts and interval

Kind: instance method of ConduxClient

conduxClient.createAction(actionName) ⇒ function

Create a function that sends a keyed object with actionType and payload to a ServerNexus. Use like you would use Reflux.createAction for a local store.

Kind: instance method of ConduxClient
Returns: function - An action that should be called with an object payload to be serialized and sent over the wire to the ServerNexus

Param Type Description
actionName string name of the action the ServerNexus will need to listen to

conduxClient.createActions(actionNames) ⇒ object

Create a hash of action name keys with ConduxClient actions as values

Kind: instance method of ConduxClient
Returns: object - - a hash of action functions that accept an object payload to be serialized and sent to the server

Param Type Description
actionNames Array.<string> create a hash of actions, use like you would Reflux.createActions for a local store.

conduxClient.registerFrequency(topic, options) ⇒ Frequency

Create a new Frequency to subscribe to data streams from

Kind: instance method of ConduxClient
Returns: Frequency - A Frequency instance

Param Type Default Description
topic string The Frequency's name handle
options object hash of options
[options.setInitialData] function Frequency.prototype._hydrateData handle the merging of new data into datastream
[options.updateData] function Frequency.prototype._updateData handle the updating of new data to datastream
[options.provideCredentials] function provide a function that returns a hash of credentials to the Server (if required by the Channel to connect, otherwise leave blank)

conduxClient.enablePersistence()

enable automatic reconnection on websocket "close" event, for use after persistence has been set by constructor

Kind: instance method of ConduxClient
Since: 0.3.0

conduxClient.disablePersistence()

disable automatic reconnection on websocket "close" event, for use after persistence has been set by constructor

Kind: instance method of ConduxClient
Since: 0.3.0

conduxClient.Hz() ⇒ Frequency

convenience alias for registerFrequency

Kind: instance method of ConduxClient
Returns: Frequency - A Frequency instance
Since: 0.2.4

ConduxClient.ReactConnectMixin

Convenience Mixin for a React Component, giving it a tuneIn method that that allows the component to subscribe to a ConduxClient Frequency with a handler. Conveniently removes all Component handlers from the Frequency on componentWillUnmount

Kind: static mixin of ConduxClient

ConduxClient.DISCONNECTED

Kind: static property of ConduxClient
Read only: true
Since: 0.4.0

ConduxClient.CONNECTING

Kind: static constant of ConduxClient
Read only: true
Since: 0.4.0

ConduxClient.CONNECTED

Kind: static constant of ConduxClient
Read only: true
Since: 0.4.0

Frequency

Kind: global class
Access: protected

new Frequency(topic, conduxClient, options)

A read-only stream of data from the server on topic. Split from a single websocket connection. Frequencies cannot be directly instansiated with the new operator; they are created with <ConduxClient>.registerFrequency or the shorthand <ConduxClient>.Hz.

Param Type Default Description
topic string name handle of the Frequency, ex /chat
conduxClient object the ConduxClient instance that owns the Frequency
options object
[options.handleConnection] function Frequency.prototype._hydrateData handle initial data flowing into Data on connection
[options.handleMessage] function Frequency.prototype._updateData handle the updating Data from incoming message
[options.setInitialData] function (since 0.2.3) new API for bootstrapping this.Data on connection to Server. If declared, replaces options.handleConnection
[options.updateData] function (since 0.2.3) new API for handling how messages from the server are integrated into this.Data. If declared, replaces options.handleMessage
[options.provideCredentials] function provide a function that returns a hash of credentials to the Server (if required by the Channel to connect, otherwise leave you can this blank)

frequency.didConnect

A bluebird Promise fulfilled when the Frequency connects with the Condux Server

Kind: instance property of Frequency

frequency.topic

The name of the frequency, should match a Channel on the Condux server

Kind: instance property of Frequency
Read only: true

frequency.band

A hash of all the Frequencies on the ConduxClient instance that created this Frequency

Kind: instance property of Frequency
Read only: true

frequency.Data ⇒ any

getter

Kind: instance property of Frequency
Returns: any - immutable _Data state of Frequency
Read only: true

frequency.request(constraints) ⇒ Promise

The client side of Condux request API. Sends constraints to a Condux server Channel implementing the response interface, Sent with a silent, unique request token that ensures resolution of the Promise created when the Condux server responds. Adds the Promise to this._responseListeners_. When the Condux server Channel responds, the resolved Promise's thenables are called and the Promise itself is removed from the this._responseListeners_ hash.

Kind: instance method of Frequency

Param Type Description
constraints object developer-defined key:value map of constraints to send Condux server Channel

frequency.addListener(listener, handlers) ⇒ string

Add a handler for Frequency's onmessage event

Kind: instance method of Frequency
Returns: string - token - unique identifier for the registered listener

Param Type Description
listener object handlers are invoked with listener as this
handlers object a hash of callbacks to execute when the Frequency recieves an update from its server-side Channel
[handlers.connection] function called withthis.Data as single argument when the Frequency connects to its Channel
[handlers.message] function called when the Frequency receives a message. Is passed two arguments, the parsed JSON payload of the message, and this.Data
[handlers.close] function called when the connection to the server-side channel closes

frequency.removeListener(token)

Remove a handler from Frequency's onmessage event

Kind: instance method of Frequency

Param Type Description
token string the listener's unique identifier returned from addListener

frequency.close()

Shut down the Frequency, unsubscribing from Condux server's channel broadcasts on this topic

Kind: instance method of Frequency

tuneInto

exposed to React.Component via ConduxClient.ReactConnectMixin Tune into a ConduxClient Frequency and handle Frequency lifecyle events connection,message, and close

Kind: global variable

Param Type Description
frequency object a Frequency name handle
handlers object a hash of callbacks for Frequency's lifecycle events
[handlers.connection] connectionHandler
[handlers.message] messageHandler
[handlers.close] closeHandler

connectionHandler : function

A callback for the ConduxClient.Connect mixin triggered when the component initially tunes into a Frequency

Kind: global typedef

Param Type Description
hydration object | array the tuned-in Frequency's datastream when the component begins listening

messageHandler : function

A callback for the ConduxClient.Connect mixin triggered when Frequency receives server data

Kind: global typedef

Param Type Description
message object | array the tuned-in Frequency's latest message from the server
datastream object | array a copy of the Frequency's full datastream

closeHandler : function

A callback for the ConduxClient.Connect mixin triggered when Frequency receives server data

Kind: global typedef

Package Sidebar

Install

npm i condux-client

Weekly Downloads

1

Version

0.4.4

License

MIT

Last publish

Collaborators

  • epferrari