docs.md

Classes

ResClient

ResClient represents a client connection to a RES API.

ResCollection

ResCollection represents a collection provided over the RES API.

ResModel

ResModel represents a model provided over the RES API.

ResError

ResError represents a RES API error.

Typedefs

eventCallback : function

Event callback

ResClient

ResClient represents a client connection to a RES API.

Kind: global class

• ResClient
  • new ResClient(hostUrlOrFactory, [opt])
  • instance
    • .supportedProtocol ⇒ string
    • .connect() ⇒ Promise
    • .disconnect()
    • .getHostUrl() ⇒ string
    • .on(events, handler)
    • .off(events, [handler])
    • .setOnConnect(onConnect) ⇒ this
    • .registerModelType(pattern, factory) ⇒ this
    • .unregisterModelType(pattern) ⇒ modelFactory
    • .registerCollectionType(pattern, factory) ⇒ this
    • .unregisterCollectionType(pattern) ⇒ collectionFactory
    • .get(rid, [collectionFactory]) ⇒ Promise.<(ResModel|ResCollection)>
    • .call(rid, method, params) ⇒ Promise.<object>
    • .authenticate(rid, method, params) ⇒ Promise.<object>
    • .create(rid, params) ⇒ Promise.<(ResModel|ResCollection)>
    • .setModel(modelId, props) ⇒ Promise.<object>
  • inner
    • ~connectCallback : function
    • ~disconnectCallback : function
    • ~errorCallback : function
    • ~websocketFactory ⇒ WebSocket
    • ~onConnectCallback ⇒ Promise
    • ~modelFactory ⇒ ResModel
    • ~collectionFactory ⇒ ResCollection

new ResClient(hostUrlOrFactory, [opt])

Creates a ResClient instance

Param	Type	Description
hostUrlOrFactory	string | websocketFactory	Websocket host path, or websocket factory function. Path may be relative to current path.
[opt]	object	Optional parameters.
[opt.onConnect]	function	On connect callback called prior resolving the connect promise and subscribing to stale resources. May return a promise.
[opt.namespace]	string	Event bus namespace. Defaults to 'resclient'.
[opt.reconnectDelay]	boolean	Milliseconds between WebSocket reconnect attempts. Defaults to 3000.
[opt.subscribeStaleDelay]	boolean	Milliseconds until a subscribe attempt is made on a stale resource. Zero means no attempt to subscribe. Defaults to 2000.
[opt.subscribeRetryDelay]	boolean	Milliseconds between subscribe attempts on a stale resource after a failed stale subscribe. Zero means no retries. Defaults to 10000.
[opt.unsubscribeDelay]	boolean	Milliseconds between stopping listening to a resource, and the resource being unsubscribed. Defaults to 5000.
[opt.debug]	boolean | function	Flag to debug log all WebSocket communication, or logging function. Defaults to false. Function has schema: (type:string,msg:string,ctx:any) => void.
[opt.eventBus]	module:modapp~EventBus	Event bus.

resClient.supportedProtocol ⇒ string

RES protocol level supported by this client version.

Kind: instance property of ResClient
Returns: string - Supported RES protocol version.

resClient.connect() ⇒ Promise

Connects the instance to the server. Can be called even if a connection is already established.

Kind: instance method of ResClient
Returns: Promise - A promise to the established connection.

resClient.disconnect()

Disconnects any current connection and stops attempts of reconnecting.

Kind: instance method of ResClient

resClient.getHostUrl() ⇒ string

Gets the host URL to the RES API

Kind: instance method of ResClient
Returns: string - Host URL

resClient.on(events, handler)

Attach an event handler function for one or more instance events. Available events are 'connect', 'disconnect', and 'error'.

Kind: instance method of ResClient

Param	Type	Description
events	string	One or more space-separated events. Null means any event.
handler	connectCallback | disconnectCallback | errorCallback	Handler function to execute when the event is emitted.

resClient.off(events, [handler])

Remove an instance event handler. Available events are 'connect', 'disconnect', and 'error'.

Kind: instance method of ResClient

Param	Type	Description
events	string	One or more space-separated events. Null means any event.
[handler]	connectCallback | disconnectCallback | errorCallback	Handler function to remove.

resClient.setOnConnect(onConnect) ⇒ this

Sets the onConnect callback.

Kind: instance method of ResClient

Param	Type	Description
onConnect	onConnectCallback	On connect callback called prior resolving the connect promise and subscribing to stale resources. May return a promise.

resClient.registerModelType(pattern, factory) ⇒ this

Register a model type. The pattern may use the following wild cards:

• The asterisk (*) matches any part at any level of the resource name.
• The greater than symbol (>) matches one or more parts at the end of a resource name, and must be the last part.

Kind: instance method of ResClient

Param	Type	Description
pattern	string	Pattern of the model type.
factory	modelFactory	Model factory callback

resClient.unregisterModelType(pattern) ⇒ modelFactory

Unregister a previously registered model type pattern.

Kind: instance method of ResClient
Returns: modelFactory - Unregistered model factory callback

Param	Type	Description
pattern	string	Pattern of the model type.

resClient.registerCollectionType(pattern, factory) ⇒ this

Register a collection type. The pattern may use the following wild cards:

• The asterisk (*) matches any part at any level of the resource name.
• The greater than symbol (>) matches one or more parts at the end of a resource name, and must be the last part.

Kind: instance method of ResClient

Param	Type	Description
pattern	string	Pattern of the collection type.
factory	collectionFactory	Collection factory callback

resClient.unregisterCollectionType(pattern) ⇒ collectionFactory

Unregister a previously registered collection type pattern.

Kind: instance method of ResClient
Returns: collectionFactory - Unregistered collection factory callback

Param	Type	Description
pattern	string	Pattern of the collection type.

resClient.get(rid, [collectionFactory]) ⇒ Promise.<(ResModel|ResCollection)>

Get a resource from the API

Kind: instance method of ResClient
Returns: Promise.<(ResModel|ResCollection)> - Promise of the resource.

Param	Type	Description
rid	string	Resource ID
[collectionFactory]	function	Collection factory function.

resClient.call(rid, method, params) ⇒ Promise.<object>

Calls a method on a resource.

Kind: instance method of ResClient
Returns: Promise.<object> - Promise of the call result.

Param	Type	Description
rid	string	Resource ID.
method	string	Method name
params	*	Method parameters

resClient.authenticate(rid, method, params) ⇒ Promise.<object>

Invokes a authentication method on a resource.

Kind: instance method of ResClient
Returns: Promise.<object> - Promise of the authentication result.

Param	Type	Description
rid	string	Resource ID.
method	string	Method name
params	*	Method parameters

resClient.create(rid, params) ⇒ Promise.<(ResModel|ResCollection)>

Deprecated

Creates a new resource by calling the 'new' method.
Use call with 'new' as method parameter instead.

Kind: instance method of ResClient
Returns: Promise.<(ResModel|ResCollection)> - Promise of the resource.

Param	Type	Description
rid	*	Resource ID
params	*	Method parameters

resClient.setModel(modelId, props) ⇒ Promise.<object>

Calls the set method to update model properties.

Kind: instance method of ResClient
Returns: Promise.<object> - Promise of the call being completed.

Param	Type	Description
modelId	string	Model resource ID.
props	object	Properties. Set value to undefined to delete a property.

ResClient~connectCallback : function

Connect event emitted on connect.

Kind: inner typedef of ResClient

Param	Type	Description
event	object	WebSocket open event object

ResClient~disconnectCallback : function

Disconnect event emitted on disconnect.

Kind: inner typedef of ResClient

Param	Type	Description
event	object	WebSocket close event object

ResClient~errorCallback : function

Error event emitted on error.

Kind: inner typedef of ResClient

Param	Type	Description
err	ResError	ResError object

ResClient~websocketFactory ⇒ WebSocket

WebSocket factory function.

Kind: inner typedef of ResClient
Returns: WebSocket - WebSocket instance implementing the WebSocket API.

ResClient~onConnectCallback ⇒ Promise

OnConnect callback function.

Kind: inner typedef of ResClient
Returns: Promise - Promise for the onConnect handlers completion. Must always resolve.

Param	Type	Description
ResClient	ResClient	instance

ResClient~modelFactory ⇒ ResModel

Model factory callback

Kind: inner typedef of ResClient
Returns: ResModel - Model instance object.

Param	Type	Description
api	ResClient	ResClient instance
rid	string	Resource ID

ResClient~collectionFactory ⇒ ResCollection

Collection factory callback

Kind: inner typedef of ResClient
Returns: ResCollection - Collection instance object.

Param	Type	Description
api	ResClient	ResClient instance
rid	string	Resource ID

ResCollection

ResCollection represents a collection provided over the RES API.

Kind: global class
Implements: module:modapp~Collection

• ResCollection
  • new ResCollection(api, rid, [opt])
  • instance
    • .length
    • .list
    • .getClient() ⇒ ResClient
    • .getResourceId() ⇒ string
    • .on([events], [handler]) ⇒ this
    • .off([events], [handler]) ⇒ this
    • .get(id) ⇒ *
    • .indexOf(item) ⇒ number
    • .atIndex(idx) ⇒ *
    • .call(method, params) ⇒ Promise.<object>
    • .auth(method, params) ⇒ Promise.<object>
    • .toArray() ⇒ Array.<*>
  • inner
    • ~addEvent : object
    • ~addCallback : function
    • ~removeEvent : object
    • ~removeCallback : function

new ResCollection(api, rid, [opt])

Creates an ResCollection instance

Param	Type	Description
api	ResClient	ResClient instance
rid	string	Resource id.
[opt]	object	Optional settings
[opt.idCallback]	function	Id callback function.

resCollection.length

Length of the collection

Kind: instance property of ResCollection

resCollection.list

Internal collection array. Do not mutate directly.

Kind: instance property of ResCollection

resCollection.getClient() ⇒ ResClient

ResClient instance.

Kind: instance method of ResCollection
Returns: ResClient - ResClient instance

resCollection.getResourceId() ⇒ string

Collection resource ID

Kind: instance method of ResCollection
Returns: string - Resource ID

resCollection.on([events], [handler]) ⇒ this

Attach a collection event handler function for one or more events. If no event or handler is provided, the collection will still be considered listened to, until a matching off call without arguments is made. Available events are 'add', 'remove', and custom events.

Kind: instance method of ResCollection

Param	Type	Description
[events]	string	One or more space-separated events. Null means any event.
[handler]	addCallback | removeCallback | eventCallback	Handler function to execute when the event is emitted.

resCollection.off([events], [handler]) ⇒ this

Remove a collection event handler function. Available events are 'add', 'remove', and custom events.

Kind: instance method of ResCollection

Param	Type	Description
[events]	string	One or more space-separated events. Null means any event.
[handler]	addCallback | removeCallback | eventCallback	Handler function to remove.

resCollection.get(id) ⇒ *

Get an item from the collection by id. Requires that id callback is defined for the collection.

Kind: instance method of ResCollection
Returns: * - Item with the id. Undefined if key doesn't exist

Param	Type	Description
id	string	Id of the item

resCollection.indexOf(item) ⇒ number

Retrieves the order index of an item.

Kind: instance method of ResCollection
Returns: number - Order index of the first matching item. -1 if the item doesn't exist.

Param	Type	Description
item	*	Item to find

resCollection.atIndex(idx) ⇒ *

Gets an item from the collection by index position

Kind: instance method of ResCollection
Returns: * - Item at the given index. Undefined if the index is out of bounds.

Param	Type	Description
idx	number	Index of the item

resCollection.call(method, params) ⇒ Promise.<object>

Calls a method on the collection.

Kind: instance method of ResCollection
Returns: Promise.<object> - Promise of the call result.

Param	Type	Description
method	string	Method name
params	*	Method parameters

resCollection.auth(method, params) ⇒ Promise.<object>

Calls an auth method on the collection.

Kind: instance method of ResCollection
Returns: Promise.<object> - Promise of the auth result.

Param	Type	Description
method	string	Auth method name
params	*	Method parameters

resCollection.toArray() ⇒ Array.<*>

Returns a shallow clone of the internal array.

Kind: instance method of ResCollection
Returns: Array.<*> - Clone of internal array

ResCollection~addEvent : object

Add event data

Kind: inner typedef of ResCollection
Properties

Name	Type	Description
item	*	Item being added to the collection.
idx	number	Index where item was added.

ResCollection~addCallback : function

Add event emitted on any item being added to the collection.

Kind: inner typedef of ResCollection

Param	Type	Description
event	addEvent	Add event data.
collection	ResCollection	Collection emitting event.
event	string	Event name including namespace.
action	string	Event action.

ResCollection~removeEvent : object

Remove event data

Kind: inner typedef of ResCollection
Properties

Name	Type	Description
item	*	Item being removed from the collection.
idx	number	Index from where the item was removed.

ResCollection~removeCallback : function

Remove event emitted on any item being added to the collection.

Kind: inner typedef of ResCollection

Param	Type	Description
event	removeEvent	Remove event data.
collection	ResCollection	Collection emitting event.
event	string	Event name including namespace.
action	string	Event action.

ResModel

ResModel represents a model provided over the RES API.

Kind: global class
Implements: module:modapp~Model

• ResModel
  • new ResModel(api, rid, [opt])
  • instance
    • .props ⇒ object
    • .getClient() ⇒ ResClient
    • .getResourceId() ⇒ string
    • .on([events], [handler]) ⇒ this
    • .off(events, [handler]) ⇒ this
    • .set(props) ⇒ Promise.<object>
    • .call(method, params) ⇒ Promise.<object>
    • .auth(method, params) ⇒ Promise.<object>
  • inner
    • ~changeCallback : function

new ResModel(api, rid, [opt])

Creates a ResModel instance

Param	Type	Description
api	ResClient	ResClient instance
rid	string	Resource id.
[opt]	object	Optional parameters.
[opt.definition]	object	Object definition. If not provided, any value will be allowed.

resModel.props ⇒ object

Model properties.

Kind: instance property of ResModel
Returns: object - Anonymous object with all model properties.

resModel.getClient() ⇒ ResClient

ResClient instance.

Kind: instance method of ResModel
Returns: ResClient - ResClient instance

resModel.getResourceId() ⇒ string

Model resource ID

Kind: instance method of ResModel
Returns: string - Resource ID

resModel.on([events], [handler]) ⇒ this

Attach a model event handler function for one or more events. If no event or handler is provided, the model will still be considered listened to, until a matching off call without arguments is made. Available events are 'change', or custom events.

Kind: instance method of ResModel

Param	Type	Description
[events]	string	One or more space-separated events. Null means any event.
[handler]	changeCallback | eventCallback	Handler function to execute when the event is emitted.

resModel.off(events, [handler]) ⇒ this

Remove a model event handler function. Available events are 'change', or custom events.

Kind: instance method of ResModel

Param	Type	Description
events	string	One or more space-separated events. Null means any event.
[handler]	changeCallback | eventCallback	Handler function to remove.

resModel.set(props) ⇒ Promise.<object>

Calls the set method to update model properties.

Kind: instance method of ResModel
Returns: Promise.<object> - Promise of the call being completed.

Param	Type	Description
props	object	Properties. Set value to undefined to delete a property.

resModel.call(method, params) ⇒ Promise.<object>

Calls a method on the model.

Kind: instance method of ResModel
Returns: Promise.<object> - Promise of the call result.

Param	Type	Description
method	string	Method name
params	*	Method parameters

resModel.auth(method, params) ⇒ Promise.<object>

Calls an auth method on the model.

Kind: instance method of ResModel
Returns: Promise.<object> - Promise of the auth result.

Param	Type	Description
method	string	Auth method name
params	*	Method parameters

ResModel~changeCallback : function

Change event emitted on any change to one or more public (non-underscore) properties.

Kind: inner typedef of ResModel

Param	Type	Description
changed	Object.<string, *>	Changed key/value object where key is the changed property, and value is the old property value.
model	Model	ResModel emitting the event.
event	string	Event name including namespace.
action	string	Event action.

ResError

ResError represents a RES API error.

Kind: global class

• ResError
  • .code : string
  • .message : string
  • .data : *
  • .getResourceId() ⇒ string

resError.code : string

Error code

Kind: instance property of ResError

resError.message : string

Error message

Kind: instance property of ResError

resError.data : *

Error data object

Kind: instance property of ResError

resError.getResourceId() ⇒ string

Error resource ID

Kind: instance method of ResError
Returns: string - Resource ID

eventCallback : function

Event callback

Kind: global typedef

Param	Type	Description
data	object	Event data object
resource	object	Resource emitting the event
event	string	Event name including namespace
action	string	Event action