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:

import { connect } from 'photoniq-eds-sdk';

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

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 Initial Methods

Connect

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

import { connect } from 'photoniq-eds-sdk';

let connection: Connection = connect(config);

Create

Create a new Connection instance:

import { create } from 'photoniq-eds-sdk';

let connection = create(config);

Create

Returns version of the instance:

import { version } from 'photoniq-eds-sdk';

console.log(version());

`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

reconnect

Forcefully disconnects from the WebSocket/SSE connection to immediately connect to the next configuration if it exists:

connection.reconnect();

Argument	Type	Description
return	`boolean`	`true` if disconnect triggered; `false` if it was not connected or `autoReconnect` is `false`

type

Type of connection:

connection.type();

Argument	Type	Description
return	`string`	Possible values: `sse`, `ws`

getQueries

Get a list of all listened queries for the connection:

connection.getQueries();

Argument	Type	Description
return	`string[]`	List of all listened queries for the `connection`

getQuerySets

Get a list of all QuerySet instances for the connection:

connection.getQuerySets();

Argument	Type	Description
return	`QuerySet[]`	List of all `QuerySet` instances for the `connection`

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>");

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>");

unubscribeAll

Removes all subscriptions in the QuerySet:

querySet.unsubscribeAll();

getQueries

Get a list of all listened queries for the QuerySet:

querySet.getQueries();

Argument	Type	Description
return	`string[]`	List of all listened queries for the `QuerySet`

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();

`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 = 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);

Name		Name	Last commit message	Last commit date
Latest commit History 48 Commits
.github/workflows		.github/workflows
src		src
test		test
.gitignore		.gitignore
DEVELOPMENT.md		DEVELOPMENT.md
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
webpack.dev.config.js		webpack.dev.config.js
webpack.prod.config.js		webpack.prod.config.js

Uh oh!

Folders and files

Latest commit

History

Repository files navigation

SDK for PhotonIQ EDS

Quick Start

Basic Example:

Supported Initial Methods

Connect

Create

Create

Config instance schema:

SubConfig instance schema:

Connection Instance

Supported methods

connect

getConfig

getId

getStatus

getProperty

getProperties

querySet

disconnect

reconnect

type

getQueries

getQuerySets

Query Set And Batch

Supported methods

retrieve

retrieveAndSubscribe

subscribe

unubscribe

unubscribe

unubscribeAll

getQueries

batch

QueryOptions instance schema:

Listeners and Error Handling

Global Listener

Example

EDSEvent Schema

EDSEventType Schema

Query Listeners

Result Listener

Error Listener

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

`Config` instance schema:

`SubConfig` instance schema:

`QueryOptions` instance schema: