photoniq-eds-sdk

SDK for PhotonIQ EDS

PhotonIQ offers SDK to enable you connect to and deliver event streams to your applications, services, and several other data-volatile use cases. It supports both WebSocket and Server-Sent Events (SSE) connections.

Quick Start

This section demonstrates some simple tasks to help get you started using this client SDK in two ways.

This quickstart guide will guide you through:

• Connecting to an event delivery service
• Querying and subscribing that service and receiving query results and updates

Basic Example:

Connect to Event Delivery Service, retrieve and subsribe to SQL:

let config = {
    host: "<YOUR-PHOTONIQ>.photoniq.macrometa.io",
    customerId: "<YOUR-CUSTOMER-ID>",
    apiKey: "<YOUR-API-KEY>",
    fabric: "<YOUR-FABRIC>",
};

let connection = PhotoniqEdsSdk.connect(config);

let querySet = connection.querySet();

querySet.retrieveAndSubscribe("SELECT * FROM <YOUR-COLLECTION> WHERE key=<YOUR-KEY>", (event) => {
    console.log(`Message event: `, event);
})

---

NOTE

The example uses a WebSocket connection. To switch to an SSE connection, add connectionTypes: ["sse"] to the config. For a priority connection that falls back to WebSocket in case of network issues, use connectionTypes: ["sse", "ws"].

---

Supported Methods

Connect

Create a new Connection instance and establish connection to PhotonIQ EDS server:

let connection: Connection = PhotoniqEdsSdk.connect(config);

Create

Create a new Connection instance:

let connection = PhotoniqEdsSdk.create(config);

Config instance schema:

Property	Type	Requred	Description
host	string	Yes	Host of the connection
customerId	string	Yes	Customer ID credentails
apiKey	string	Yes	ApiKey credentails
fabric	string	No	Fabric to be used. Default is _system
urlParameters	object	No	Custom URL query parameters set as key value properties
connectionTypes	(string | SubConfig)[]	No	Use type of connection and priority. Default is ["ws"]. Types: ws, sse
autoReconnect	boolean	No	Automatically reconnect in case of network issues. Default is true

SubConfig instance schema:

Property	Type	Requred	Description
type	string	Yes	Type of the connection. Value: ws or sse
customerId	string	No	Customer ID credentails. Default set from Config
apiKey	string	No	ApiKey credentails. Default set from Config
fabric	string	No	Fabric to be used. Default set from Config
urlBase	string	No	Set custom URL for connection.
urlParameters	object	No	Custom URL query parameters set as key:value properties
pingSeconds	number	No	Seconds between ping-pong messages to the WebSocket server. Default is 29. Acceptable only for ws connection.
flushTimeoutMs	number	No	Seconds between ping-pong messages to the WebSocket server. Default is 20. Acceptable only for sse connection.

Connection Instance

It maintains a WebSocket/SSE connection:

Supported methods

connect

Connects to the Event Delivery Service. This method can be used to reconnect after a disconnection, such as after using the disconnect method:

connection.connect();

getConfig

Retrieves the configuration of the connection. Returns a Config instance:

connection.getConfig();

Argument	Type	Description
return	Config	Client configuration of the connection

getId

Retrieves the connection ID:

connection.getId();

Argument	Type	Description
return	number	ID of the connection

getStatus

Checks status of the connection:

connection.getStatus();

The method can return the next ConnectionType enum values:

Type	Description
ConnectionType.Closed	Connection closed
ConnectionType.Connecting	Connection is opening
ConnectionType.Open	Connection opened
ConnectionType.Closing	Connection is closing

getProperty

Get property of a connection:

connection.getProperty(name);

Argument	Type	Description
name	string	Name of a property
return	string	Value of a property

getProperties

Get all properties of a connection:

connection.getProperties();

Argument	Type	Description
return	object	Object of all property:value pairs

querySet

Create a QuerySet instance:

connection.querySet();

Argument	Type	Description
return	QuerySet	Query set instance

disconnect

Disconnect from the Event Delivery Service:

connection.disconnect();

Argument	Type	Description
return	boolean	true if disconnected; false if it was not connected

Query Set And Batch

This abstract layer helps to manage a group of queries instead of working with each query independently. To initialize a new QuerySet instance, call the following method from the Connection instance:

let querySet = connection.querySet();

Supported methods

retrieve

Only retrieves initial data and immediately removes the query from the Event Delivery Service after the response:

querySet.retrieve("SELECT * FROM <YOUR-COLLECTION> WHERE key=<YOUR-KEY>", (event) => {
    console.log(`Message event: `, event);
})

Argument	Type	Requred	Description
query	string	Yes	SQL query to retrieve/listen
resultListener	function	Yes	Set result listener
errorListenerOrOptions	function | QueryOptions	No	Set error listener or set query options
options	QueryOptions	No	Set query options.

retrieveAndSubscribe

Retrieves initial data and subscribes to changes in the query:

querySet.retrieveAndSubscribe("SELECT * FROM <YOUR-COLLECTION> WHERE key=<YOUR-KEY>", (event) => {
    console.log(`Message event: `, event);
})

Retrieves compressed initial data and subscribes to changes in the query:

querySet.retrieveAndSubscribe("SELECT * FROM <YOUR-COLLECTION> WHERE key=<YOUR-KEY>", (event) => {
    console.log(`Message event: `, event);
}, {
    compress: true
})

Argument	Type	Requred	Description
query	string	Yes	SQL query to retrieve/listen
resultListener	function	Yes	Set result listener
errorListenerOrOptions	function | QueryOptions	No	Set error listener or set query options
options	QueryOptions	No	Set query options.

subscribe

Only subscribes to changes in the query:

querySet.subscribe("SELECT * FROM <YOUR-COLLECTION> WHERE key=<YOUR-KEY>", (event) => {
    console.log(`Message event: `, event);
})

Argument	Type	Requred	Description
query	string	Yes	SQL query to retrieve/listen
resultListener	function	Yes	Set result listener
errorListenerOrOptions	function | QueryOptions	No	Set error listener or set query options
options	QueryOptions	No	Set query options.

unubscribe

Removes a subscription if the query was subscribed in the QuerySet. This applies only to the retrieveAndSubscribe and subscribe methods:

querySet.unsubscribe("SELECT * FROM <YOUR-COLLECTION> WHERE key=<YOUR-KEY>");

batch

To make requests to the Event Delivery Service more efficient, it is possible to join them into one WebSocket/SSE message. This returns a QueryBatch instance, which has the same methods (retrieve, retrieveAndSubscribe, subscribe, unsubscribe) as QuerySet. The final method should beassemble(), which builds and sends the message:

let queryBatch = querySet.batch();
queryBatch
    .retrieve("SELECT * FROM <YOUR-COLLECTION> WHERE key=<YOUR-KEY>", (event) => {
       console.log(`Message event: `, event);
    })
    .retrieveAndSubscribe("SELECT * FROM <YOUR-COLLECTION> WHERE key=<YOUR-KEY>", (event) => {
       console.log(`Message event: `, event);
    })
    .subscribe("SELECT * FROM <YOUR-COLLECTION> WHERE key=<YOUR-KEY>", (event) => {
       console.log(`Message event: `, event);
    })
    .unsubscribe("SELECT * FROM <YOUR-COLLECTION> WHERE key=<YOUR-KEY>")
    .assemble();

unubscribeAll

Removes all subscriptions in the QuerySet:

querySet.unsubscribeAll();

QueryOptions instance schema:

Property	Type	Requred	Description
compress	boolean	No	compress response data

Listeners and Error Handling

The Client has two types of event listeners: global and query.

Global Listener

The listener can be attached to the client when use connect method to Event Delivery Service

Example

let globalListener = function(event) {
    if (event.type === "open") {
        console.log('EDS connection established: ', event);
    } else if (event.type === "properties") {
        console.log("EDS assigned properties: ", event.data);
    } else if (event.type === "server-global-error") {
        console.log(`EDS replied with an Error: `, event);
    }else if (event.type === "server-query-error") {
        console.log(`EDS replied with an Error for query '${event.query}': `, event);
    } else if (event.type === "client-global-error") {
        console.log(`Client global error: `, event);
    } else if (event.type === "client-query-error") {
        console.log(`Client error for query '${event.query}': `, event);
    } else if (event.type === "message") {
        console.log('Message event: ', event);
    } else if (event.type === "close") {
        console.log('EDS connection closed: ', event);
    }
};

let connection = PhotoniqEdsSdk.connect({
host: "<YOUR-PHOTONIQ>.photoniq.macrometa.io",
customerId: "<YOUR-CUSTOMER-ID>",
apiKey: "<YOUR-API-KEY>",
fabric: "<YOUR-FABRIC>",
}, globalListener);

EDSEvent Schema

The globalListener function returns EDSEvent instance which has the next schema:

Property	Type	Requred	Description
type	EDSEventType	Yes	List of event types generated by EDS driver
connection	Connection	Yes	An instance used for the WebSocket/SSE connection
data	any	No	Present for events with data like message, cnnection-id types
code	number	No	Error code, only present for server side errors
message	string	No	Error message, only present in error's event
query	string	No	Error for a query, only present for query's errors

EDSEventType Schema

The type property can have the next EDSEventType enum values:

Type	Description
open	Openned WebSocket/SSE connection
properties	Received properties of connection
server-query-error	Server-side error related to a query
server-global-error	Server-side error not related to a query
client-query-error	Client-side error related to a query
client-global-error	Client-side error not related to a query
message	Message event
close	Closed WebSocket/SSE connection

Query Listeners

The functions listen to events related to a specific query and are divided into result and error listeners.

Result Listener

It listens only for events with event.type === "message" and is passed as the second parameter to the retrieve, retrieveAndSubscribe, and subscribe methods:

let sql = "SELECT * FROM <YOUR-COLLECTION> WHERE key=<YOUR-KEY>";
let resultListener = (event) => {
    console.log(`Message event: `, event);
};
querySet.retrieve(sql, resultListener);

Error Listener

The error listener handles error messages related to a query, which can have the types event.type === "server-query-error" or event.type === "client-query-error"

let sql = "SELECT * FROM <YOUR-COLLECTION> WHERE key=<YOUR-KEY>";
let resultListener = (event) => {
    console.log(`Message event: `, event);
};
let errorListener = (event) => {
    console.log(`Error event: `, event);
};
querySet.retrieve(sql, resultListener, errorListener);