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

• ConduxClient
  • new ConduxClient(url, persistence)
  • instance
    • .persistence ⇒ object
    • .connecting ⇒ boolean
    • .connected ⇒ boolean
    • .updatePersistence() ⇒ object
    • .connect()
    • .reconnect()
    • .createAction(actionName) ⇒ function
    • .createActions(actionNames) ⇒ object
    • .registerFrequency(topic, options) ⇒ Frequency
    • .enablePersistence()
    • .disablePersistence()
    • .Hz() ⇒ Frequency
  • static
    • .ReactConnectMixin
    • .DISCONNECTED
    • .CONNECTING
    • .CONNECTED

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

• Frequency
  • new Frequency(topic, conduxClient, options)
  • .didConnect
  • .topic
  • .band
  • .Data ⇒ any
  • .request(constraints) ⇒ Promise
  • .addListener(listener, handlers) ⇒ string
  • .removeListener(token)
  • .close()

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