photoniq-eds-sdk v0.0.5

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:

SubConfig instance schema:

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

getId

Retrieves the connection ID:

connection.getId();

getStatus

Checks status of the connection:

connection.getStatus();

The method can return the next ConnectionType enum values:

getProperty

Get property of a connection:

connection.getProperty(name);

getProperties

Get all properties of a connection:

connection.getProperties();

querySet

Create a QuerySet instance:

connection.querySet();

disconnect

Disconnect from the Event Delivery Service:

connection.disconnect();

reconnect

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

connection.reconnect();

type

Type of connection:

connection.type();

getQueries

Get a list of all listened queries for the connection:

connection.getQueries();

getQuerySets

Get a list of all QuerySet instances for the connection:

connection.getQuerySets();

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

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
})

subscribe

Only subscribes to changes in the query:

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

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

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:

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:

EDSEventType Schema

The type property can have the next EDSEventType enum values:

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