Skip to content

Latest commit

 

History

History
755 lines (544 loc) · 29.7 KB

docs.md

File metadata and controls

755 lines (544 loc) · 29.7 KB

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

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

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

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

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